dsh-rewind-plugin 0.11.0 → 0.12.0

package/lib/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { unlink } from "node:fs/promises";
+import { copyFile as copyFile2, rm as rm2, stat as stat2, unlink } from "node:fs/promises";
 import "@deepseek-ai/schemastery";
 
 // src/locales.ts
@@ -25,8 +25,9 @@ var en = {
   "failed": "Rewind failed: {error}. The session is unchanged.",
   "restore.count": "restored {count} file(s)",
   "delete.count": "deleted {count} file(s)",
-  "skip.count": "skipped {count} link(s)",
+  "skip.count": "skipped {count} path(s)",
   "noRestorable": "; no restorable write-class changes after the target",
+  "storeUnsupported": "file restore unavailable: these snapshots use a newer store format (v{version}) than this plugin understands; nothing was changed. Update the plugin or clear this session's snapshots.",
   "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",
@@ -73,8 +74,9 @@ var zh = {
   "failed": "\u56DE\u9000\u5931\u8D25\uFF1A{error}\u3002\u4F1A\u8BDD\u672A\u6539\u53D8\u3002",
   "restore.count": "\u8FD8\u539F {count} \u4E2A\u6587\u4EF6",
   "delete.count": "\u5220\u9664 {count} \u4E2A\u6587\u4EF6",
-  "skip.count": "\u8DF3\u8FC7 {count} \u4E2A\u94FE\u63A5",
+  "skip.count": "\u8DF3\u8FC7 {count} \u4E2A\u8DEF\u5F84",
   "noRestorable": "\uFF1B\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u53EF\u8FD8\u539F\u7684\u5199\u7C7B\u53D8\u66F4",
+  "storeUnsupported": "\u6587\u4EF6\u8FD8\u539F\u4E0D\u53EF\u7528\uFF1A\u8FD9\u4E9B\u5FEB\u7167\u4F7F\u7528\u4E86\u6BD4\u672C\u63D2\u4EF6\u66F4\u65B0\u7684\u5B58\u50A8\u683C\u5F0F\uFF08v{version}\uFF09\uFF1B\u5DE5\u4F5C\u533A\u672A\u505A\u4EFB\u4F55\u6539\u52A8\u3002\u8BF7\u66F4\u65B0\u63D2\u4EF6\uFF0C\u6216\u6E05\u9664\u8BE5\u4F1A\u8BDD\u7684\u5FEB\u7167\u3002",
   "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",
@@ -218,23 +220,104 @@ function execSessionCwd(exec, requestedPath) {
 
 // src/snapshot.ts
 import { createHash } from "node:crypto";
-import { lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 var SNAPSHOT_DIR_NAME = "rewind-snapshots";
+var SIDECAR_SUFFIX = ".before";
+var PENDING_DIR = ".pending";
+var RESCUE_DIR = "rescue";
+var JOURNAL_PREFIX = "journal-";
+var LEGACY_JOURNAL_PREFIX = "restore-journal-";
+var PENDING_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var COMPARE_CHUNK_BYTES = 64 * 1024;
+var REPLACEMENT_CHAR = "\uFFFD";
 var DEFAULT_SNAPSHOT_ROOT = join(resolveDshHome(), SNAPSHOT_DIR_NAME);
 var SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
 var MAX_ANCHOR_GROUPS = 100;
+var CURRENT_STORE_VERSION = 2;
+var UnknownStoreVersionError = class extends Error {
+  constructor(version, source) {
+    super(`snapshot store version ${version} is newer than this plugin understands (${source})`);
+    this.version = version;
+    this.source = source;
+    this.name = "UnknownStoreVersionError";
+  }
+  version;
+  source;
+};
+function textSourceOf(text) {
+  return text.includes(REPLACEMENT_CHAR) ? { kind: "lossyText", text } : { kind: "text", bytes: Buffer.from(text, "utf8") };
+}
 function isLinkEntry(entry) {
   return "ref" in entry;
 }
+async function sameFileBytes(aPath, bPath) {
+  const sizes = await Promise.all([stat(aPath), stat(bPath)]);
+  if (sizes[0].size !== sizes[1].size) return false;
+  const [a, b] = await Promise.all([open(aPath, "r"), open(bPath, "r")]);
+  try {
+    const aChunk = Buffer.allocUnsafe(COMPARE_CHUNK_BYTES);
+    const bChunk = Buffer.allocUnsafe(COMPARE_CHUNK_BYTES);
+    for (; ; ) {
+      const [ra, rb] = await Promise.all([
+        a.read(aChunk, 0, COMPARE_CHUNK_BYTES, null),
+        b.read(bChunk, 0, COMPARE_CHUNK_BYTES, null)
+      ]);
+      if (ra.bytesRead !== rb.bytesRead) return false;
+      if (ra.bytesRead === 0) return true;
+      if (!aChunk.subarray(0, ra.bytesRead).equals(bChunk.subarray(0, rb.bytesRead))) return false;
+    }
+  } finally {
+    await Promise.all([a.close(), b.close()]);
+  }
+}
+async function sameFileBuffer(path, bytes) {
+  const st = await stat(path);
+  if (st.size !== bytes.length) return false;
+  const handle = await open(path, "r");
+  try {
+    const chunk = Buffer.allocUnsafe(COMPARE_CHUNK_BYTES);
+    let offset = 0;
+    for (; ; ) {
+      const read = await handle.read(chunk, 0, Math.min(COMPARE_CHUNK_BYTES, bytes.length - offset), offset);
+      if (read.bytesRead === 0) return offset === bytes.length;
+      if (!chunk.subarray(0, read.bytesRead).equals(bytes.subarray(offset, offset + read.bytesRead))) return false;
+      offset += read.bytesRead;
+    }
+  } finally {
+    await handle.close();
+  }
+}
+function isEnoent(error) {
+  return error?.code === "ENOENT";
+}
 var defaultProbe = {
-  async readText(path) {
+  async matches(source, path) {
     try {
-      return await readFile(path, "utf8");
+      if (source === null) {
+        await stat(path);
+        return false;
+      }
+      if (source.kind === "blob") return await sameFileBytes(path, source.path);
+      if (source.kind === "text") return await sameFileBuffer(path, source.bytes);
+      return (await readFile(path)).toString("utf8") === source.text;
     } catch (error) {
-      if (error.code === "ENOENT") return void 0;
-      throw error;
+      if (isEnoent(error)) return source === null ? true : false;
+      return void 0;
+    }
+  },
+  async copy(path, dest) {
+    try {
+      await copyFile(path, dest);
+      const st = await stat(dest);
+      return { kind: "copied", size: st.size };
+    } catch (error) {
+      if (isEnoent(error)) {
+        const source = await stat(path).catch(() => void 0);
+        if (source === void 0) return { kind: "absent" };
+      }
+      return { kind: "failed", message: error instanceof Error ? error.message : String(error) };
     }
   },
   isLink: isLinkPath
@@ -253,43 +336,253 @@ async function writeJsonAtomic(file, data, afterTempWrite) {
   await rename(tmp, file);
 }
 var RESTORE_JOURNAL_STATES = /* @__PURE__ */ new Set(["running", "rollback-running", "completed", "rolled-back", "recovery-required"]);
+function isRawJournalRef(value) {
+  if (value === null) return true;
+  if (typeof value === "string") return true;
+  if (typeof value !== "object") return false;
+  const ref = value;
+  return typeof ref.blob === "string" || typeof ref.text === "string";
+}
 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 (v.version !== void 0 && v.version !== 1 && v.version !== 2) 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";
+    if (typeof a.path !== "string" || a.action !== "restore" && a.action !== "delete") return false;
+    if (typeof a.done !== "boolean") return false;
+    if (!isRawJournalRef(a.before) || !isRawJournalRef(a.rescue)) return false;
+    if (a.action === "restore" && a.before === null) return false;
+    return true;
   });
 }
-async function readEntry(file) {
+function refToSource(raw, sessionDir) {
+  if (raw === null) return null;
+  if (typeof raw === "string") return textSourceOf(raw);
+  if (typeof raw !== "object") return void 0;
+  const ref = raw;
+  if (typeof ref.blob === "string") {
+    if (!isSafeBackupRef(ref.blob)) return void 0;
+    return { kind: "blob", path: join(sessionDir, ref.blob) };
+  }
+  if (typeof ref.text === "string") return textSourceOf(ref.text);
+  return void 0;
+}
+function sourceToRef(source, sessionDir, entryPath) {
+  if (source === null) return null;
+  if (source.kind === "blob") {
+    const blob = relative(sessionDir, source.path);
+    if (!isSafeBackupRef(blob)) throw new Error(`unsafe backup ref ${blob} for ${entryPath}`);
+    return { blob };
+  }
+  return { text: source.kind === "text" ? source.bytes.toString("utf8") : source.text };
+}
+function journalToJson(journal, sessionDir) {
+  return {
+    version: 2,
+    id: journal.id,
+    sessionId: journal.sessionId,
+    targetSeq: journal.targetSeq,
+    startedAt: journal.startedAt,
+    ...journal.finishedAt !== void 0 ? { finishedAt: journal.finishedAt } : {},
+    state: journal.state,
+    actions: journal.actions.map((action) => ({
+      path: action.path,
+      action: action.action,
+      before: sourceToRef(action.before, sessionDir, action.path),
+      rescue: sourceToRef(action.rescue, sessionDir, action.path),
+      ...action.rescueError !== void 0 ? { rescueError: action.rescueError } : {},
+      ...action.mode !== void 0 ? { mode: action.mode } : {},
+      ...action.rescueMode !== void 0 ? { rescueMode: action.rescueMode } : {},
+      ...action.parent !== void 0 ? { parent: action.parent } : {},
+      done: action.done,
+      ...action.failed !== void 0 ? { failed: action.failed } : {}
+    })),
+    ...journal.rollbackError !== void 0 ? { rollbackError: journal.rollbackError } : {}
+  };
+}
+function journalFromJson(raw, sessionDir) {
+  const actions = [];
+  for (const value of raw.actions) {
+    const before = refToSource(value.before, sessionDir);
+    const rescue = refToSource(value.rescue, sessionDir);
+    if (before === void 0 || rescue === void 0) return void 0;
+    actions.push({
+      path: value.path,
+      action: value.action,
+      before: value.action === "delete" ? null : before,
+      rescue,
+      ...typeof value.rescueError === "string" ? { rescueError: value.rescueError } : {},
+      ...typeof value.mode === "number" ? { mode: value.mode } : {},
+      ...typeof value.rescueMode === "number" ? { rescueMode: value.rescueMode } : {},
+      ...typeof value.parent === "string" && value.parent.length > 0 ? { parent: value.parent } : {},
+      done: value.done,
+      ...typeof value.failed === "string" ? { failed: value.failed } : {}
+    });
+  }
+  const version = raw.version === 1 ? 1 : 2;
+  return {
+    version,
+    id: raw.id,
+    sessionId: raw.sessionId,
+    targetSeq: raw.targetSeq,
+    startedAt: typeof raw.startedAt === "number" ? raw.startedAt : 0,
+    ...typeof raw.finishedAt === "number" ? { finishedAt: raw.finishedAt } : {},
+    state: raw.state,
+    actions,
+    ...typeof raw.rollbackError === "string" ? { rollbackError: raw.rollbackError } : {}
+  };
+}
+function isJournalName(name2) {
+  if (!name2.endsWith(".json")) return false;
+  return name2.startsWith(JOURNAL_PREFIX) || name2.startsWith(LEGACY_JOURNAL_PREFIX);
+}
+function journalOpIdOf(name2) {
+  const prefix = name2.startsWith(LEGACY_JOURNAL_PREFIX) ? LEGACY_JOURNAL_PREFIX : JOURNAL_PREFIX;
+  return name2.slice(prefix.length, -".json".length);
+}
+function entryFileName(callId) {
+  return `${safeFileId(callId)}-${shortHash(callId)}.json`;
+}
+function shortHash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+function sidecarName(entryFile) {
+  return `${entryFile.slice(0, -".json".length)}${SIDECAR_SUFFIX}`;
+}
+function refAnchorOf(ref) {
+  const slash = ref.indexOf("/");
+  return slash === -1 ? Number.NaN : Number(ref.slice(0, slash));
+}
+function entryToJson(entry) {
+  const base = {
+    store: 2,
+    callId: entry.callId,
+    file: entry.path,
+    time: entry.time,
+    ...entry.parent !== void 0 ? { parent: entry.parent } : {},
+    ...entry.mode !== void 0 ? { mode: entry.mode } : {},
+    ...entry.lossy === true ? { lossy: true } : {}
+  };
+  if (entry.before === null) return { ...base, blob: null, size: 0 };
+  if (entry.before.kind !== "blob") throw new Error(`entry for ${entry.path} is not blob-backed`);
+  return { ...base, blob: basename(entry.before.path), size: entry.size };
+}
+function linkToJson(link) {
+  return {
+    store: 2,
+    callId: link.callId,
+    file: link.path,
+    ref: link.ref,
+    time: link.time,
+    ...link.parent !== void 0 ? { parent: link.parent } : {}
+  };
+}
+async function readEntry(file, anchorSeq) {
+  let parsed;
   try {
-    const parsed = JSON.parse(await readFile(file, "utf8"));
-    if (typeof parsed.path !== "string" || typeof parsed.anchorSeq !== "number") return void 0;
-    const base = {
-      callId: String(parsed.callId ?? ""),
-      anchorSeq: parsed.anchorSeq,
-      path: parsed.path,
-      time: typeof parsed.time === "number" ? parsed.time : 0
-    };
-    if (typeof parsed.ref === "string") {
-      return { ...base, ref: parsed.ref };
+    const value = JSON.parse(await readFile(file, "utf8"));
+    if (typeof value !== "object" || value === null) return void 0;
+    parsed = value;
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed.store === "number" && parsed.store > CURRENT_STORE_VERSION) {
+    throw new UnknownStoreVersionError(parsed.store, file);
+  }
+  const callId = String(parsed.callId ?? "");
+  const time = typeof parsed.time === "number" ? parsed.time : 0;
+  const origin = { file };
+  if (parsed.store === 2) {
+    if (typeof parsed.file !== "string") return void 0;
+    const parent = typeof parsed.parent === "string" && parsed.parent.length > 0 ? parsed.parent : void 0;
+    const base2 = { callId, anchorSeq, path: parsed.file, time, ...parent !== void 0 ? { parent } : {}, ...origin };
+    if (typeof parsed.ref === "string") return { ...base2, ref: parsed.ref };
+    if (parsed.blob === null) {
+      if (parsed.lossy === true) return void 0;
+      if (typeof parsed.size === "number" && parsed.size !== 0) return void 0;
+      return { ...base2, before: null, size: 0 };
+    }
+    if (typeof parsed.blob !== "string") return void 0;
+    if (parsed.blob !== sidecarName(basename(file))) return void 0;
+    const size = typeof parsed.size === "number" && parsed.size >= 0 ? parsed.size : 0;
+    const mode = typeof parsed.mode === "number" ? parsed.mode : void 0;
+    if (parsed.lossy === true) {
+      try {
+        const text = await readFile(join(dirname(file), parsed.blob), "utf8");
+        return { ...base2, before: { kind: "lossyText", text }, size, lossy: true, ...mode !== void 0 ? { mode } : {} };
+      } catch {
+        return void 0;
+      }
     }
     return {
-      ...base,
-      before: typeof parsed.before === "string" ? parsed.before : null
+      ...base2,
+      before: { kind: "blob", path: join(dirname(file), parsed.blob) },
+      size,
+      ...mode !== void 0 ? { mode } : {}
     };
+  }
+  if (typeof parsed.path !== "string" || typeof parsed.anchorSeq !== "number") return void 0;
+  const base = { callId, anchorSeq: parsed.anchorSeq, path: parsed.path, time, ...origin };
+  if (typeof parsed.ref === "string") return { ...base, ref: parsed.ref };
+  if (parsed.before !== null && typeof parsed.before !== "string") return void 0;
+  if (parsed.before === null) return { ...base, before: null, size: 0 };
+  return { ...base, before: textSourceOf(parsed.before), size: Buffer.byteLength(parsed.before, "utf8") };
+}
+async function dirBytes(dir) {
+  let names;
+  try {
+    names = await readdir(dir);
   } catch {
-    return void 0;
+    return 0;
+  }
+  let total = 0;
+  for (const name2 of names) {
+    const full = join(dir, name2);
+    const st = await lstat(full).catch(() => void 0);
+    if (st === void 0) continue;
+    if (st.isDirectory()) total += await dirBytes(full);
+    else if (st.isFile()) total += st.size;
   }
+  return total;
 }
 async function isLinkPath(path) {
   try {
-    const stat2 = await lstat(path);
-    return stat2.isSymbolicLink() || stat2.nlink > 1;
+    const stat3 = await lstat(path);
+    return stat3.isSymbolicLink() || stat3.nlink > 1;
+  } catch {
+    return false;
+  }
+}
+async function nearestExistingAncestor(dir) {
+  let current = dir;
+  for (; ; ) {
+    const st = await lstat(current).catch(() => void 0);
+    if (st !== void 0) return current;
+    const parent = dirname(current);
+    if (parent === current) return void 0;
+    current = parent;
+  }
+}
+async function parentStillMatches(path, recorded) {
+  if (recorded === void 0) return true;
+  const dir = dirname(path);
+  try {
+    return await realpath(dir) === recorded;
+  } catch (error) {
+    if (!isEnoent(error)) return false;
+  }
+  const ancestor = await nearestExistingAncestor(dir);
+  if (ancestor === void 0) return false;
+  try {
+    const real = await realpath(ancestor);
+    const inside = relative(real, recorded);
+    const escapes = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
+    return inside !== "" && !escapes;
   } catch {
     return false;
   }
@@ -297,6 +590,13 @@ async function isLinkPath(path) {
 function isSafeLinkRef(ref) {
   return /^[0-9]+\/[a-zA-Z0-9._-]+\.json$/.test(ref);
 }
+function isSafeBackupRef(ref) {
+  if (ref.length === 0 || ref.startsWith("/") || ref.includes("\\")) return false;
+  const segments = ref.split("/");
+  if (segments.length !== 2 && segments.length !== 3) return false;
+  if (segments.length === 3 && segments[0] !== RESCUE_DIR) return false;
+  return segments.every((segment) => segment !== "." && segment !== ".." && /^[a-zA-Z0-9._-]+$/.test(segment));
+}
 async function dirSizeAndLastActive(dir) {
   let size = 0;
   let lastActiveMs = 0;
@@ -319,7 +619,7 @@ async function dirSizeAndLastActive(dir) {
       return;
     }
     for (const name2 of names) {
-      if (name2.startsWith(".")) continue;
+      if (name2.startsWith(".") && name2 !== PENDING_DIR) continue;
       await visit(join(current, name2));
     }
   };
@@ -329,6 +629,10 @@ async function dirSizeAndLastActive(dir) {
 var SnapshotStore = class _SnapshotStore {
   /** Debounce window for the per-commit prune (keeps the readdir+sort off the hot path). */
   static PRUNE_INTERVAL_MS = 1e3;
+  /** Session-format-version marker file inside the session dir. Non-`.json`, so it never counts as a checkpoint entry. */
+  static FORMAT_FILE = "format";
+  /** Plugin STORE-format marker file inside the session dir (non-`.json`, same reasoning). */
+  static STORE_FILE = "store";
   lastPruneAt = 0;
   /**
    * Monotonic entry clock. Date.now() has 1ms precision, so back-to-back
@@ -349,14 +653,18 @@ var SnapshotStore = class _SnapshotStore {
   root;
   /**
    * 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.
+   * `<sessionId>\0<path>`. Each value holds the entry's effective byte source
+   * (a handle, not a copy) 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. A handle whose bytes vanished (pruned out of band) is treated as
+   * "never recorded" — dedup then stores MORE, never less.
    */
   lastEntry = /* @__PURE__ */ new Map();
   /** Sessions whose dedup state has been seeded from disk this process. */
   seededSessions = /* @__PURE__ */ new Set();
+  /** Sessions whose store-format marker this process has already stamped. */
+  storeStamped = /* @__PURE__ */ new Set();
   /**
    * Session-format version snapshots are anchored under, stamped into each
    * session's `format` marker when an entry is recorded. `null` until the host
@@ -378,7 +686,54 @@ var SnapshotStore = class _SnapshotStore {
   }
   /** Absolute file ref (relative to the session dir) of an entry. */
   entryRefOf(sessionId, callId, anchorSeq) {
-    return `${anchorSeq}/${safeFileId(callId)}.json`;
+    return `${anchorSeq}/${entryFileName(callId)}`;
+  }
+  /**
+   * The session-relative ref of an entry READ from disk: the file that really
+   * holds it. A v1 entry keeps its released name, so recomputing the name from
+   * the call id would produce a dangling reference.
+   */
+  refOfRead(sessionId, entry) {
+    if (entry.file !== void 0) return relative(this.sessionDir(sessionId), entry.file);
+    return this.entryRefOf(sessionId, entry.callId, entry.anchorSeq);
+  }
+  /** Drop every in-memory trace of one session (its directory is gone). */
+  forgetSession(sessionId) {
+    this.seededSessions.delete(sessionId);
+    this.storeStamped.delete(sessionId);
+    for (const key of [...this.lastEntry.keys()]) {
+      if (key.startsWith(`${sessionId}\0`)) this.lastEntry.delete(key);
+    }
+  }
+  /**
+   * Forget in-memory state for sessions whose directory no longer exists —
+   * after a sweep, or after the user removed a session dir out of band. A
+   * stale handle is SAFE (dedup and the boundary both fail toward storing
+   * more), but keeping it means the store holds state for a session it deleted
+   * and skips re-stamping that session's `format`/`store` markers.
+   */
+  async forgetMissingSessions() {
+    const known = /* @__PURE__ */ new Set([...this.seededSessions, ...this.storeStamped]);
+    for (const key of this.lastEntry.keys()) {
+      const separator = key.indexOf("\0");
+      if (separator !== -1) known.add(key.slice(0, separator));
+    }
+    for (const sessionId of known) {
+      const present = await this.exists(this.sessionDir(sessionId)).catch(() => true);
+      if (!present) this.forgetSession(sessionId);
+    }
+  }
+  /**
+   * Stage a capture slot for one tool call: create the session's `.pending/`
+   * area and return the absolute path the caller copies the before-bytes into
+   * (never through memory). The slot lives inside the session dir so the
+   * commit can `rename` it into the anchor group atomically; a slot that is
+   * never committed is either unlinked by its caller or collected by `prune`.
+   */
+  async stageCapture(sessionId, key) {
+    const dir = join(this.sessionDir(sessionId), PENDING_DIR);
+    await mkdir(dir, { recursive: true });
+    return join(dir, `${safeFileId(key)}-${shortHash(key)}${SIDECAR_SUFFIX}`);
   }
   /**
    * Seed a session's dedup state from the existing (bounded) on-disk window:
@@ -393,8 +748,8 @@ var SnapshotStore = class _SnapshotStore {
       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) });
+        const source = await this.resolveBefore(sessionId, entry);
+        this.lastEntry.set(key, { source, ref: this.refOfRead(sessionId, entry) });
       }
     } catch {
       this.seededSessions.delete(sessionId);
@@ -408,44 +763,135 @@ var SnapshotStore = class _SnapshotStore {
    * path from a restore).
    */
   async resolveBefore(sessionId, entry, seen = /* @__PURE__ */ new Set()) {
-    if (!isLinkEntry(entry)) return entry.before;
+    if (!isLinkEntry(entry)) return this.validatedSource(entry);
     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));
+    const referenced = await readEntry(join(this.sessionDir(sessionId), entry.ref), refAnchorOf(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) {
+  /**
+   * Validate a real entry's byte source against the store's own files: a
+   * sidecar that is missing, not a regular file, or a different size than the
+   * metadata records is an INTEGRITY failure (thrown), never a silent skip and
+   * never a fallback to "the file was created" — a restore must not delete a
+   * file whose backup it cannot read.
+   */
+  async validatedSource(entry) {
+    const source = entry.before;
+    if (source === null || source.kind !== "blob") return source;
+    const st = await stat(source.path).catch((error) => {
+      if (isEnoent(error)) throw new Error(`missing backup sidecar ${source.path} for ${entry.path}`);
+      throw error;
+    });
+    if (!st.isFile()) throw new Error(`backup sidecar is not a file: ${source.path}`);
+    if (st.size !== entry.size) {
+      throw new Error(`backup sidecar size mismatch for ${entry.path} (recorded ${entry.size}, found ${st.size})`);
+    }
+    return source;
+  }
+  /**
+   * True when two recorded byte sources are the same content. Comparison is
+   * STREAMING (size first, then chunks) so large files never enter memory.
+   * Any unreadable handle — or any legacy lossy source, whose original bytes
+   * are unknowable — answers `false`: dedup must fail toward storing more,
+   * never toward claiming "unchanged".
+   */
+  async sourcesMatch(a, b) {
+    if (a === null || b === null) return a === null && b === null;
+    try {
+      if (a.kind === "blob" && b.kind === "blob") return await sameFileBytes(a.path, b.path);
+      if (a.kind === "text" && b.kind === "text") return a.bytes.equals(b.bytes);
+      if (a.kind === "blob" && b.kind === "text") return await sameFileBuffer(a.path, b.bytes);
+      if (a.kind === "text" && b.kind === "blob") return await sameFileBuffer(b.path, a.bytes);
+      return false;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Write raw bytes to a sidecar path atomically (temp + rename): a crash
+   * between the steps leaves only a `.tmp` that no reader picks up.
+   */
+  async writeSidecar(dest, source) {
+    const tmp = `${dest}.tmp`;
+    if (source.kind === "blob") await copyFile(source.path, tmp);
+    else if (source.kind === "text") await writeFile(tmp, source.bytes);
+    else await writeFile(tmp, Buffer.from(source.text, "utf8"));
+    await rename(tmp, dest);
+  }
+  /**
+   * Place one entry's sidecar next to its entry file: MOVE a staged capture
+   * (same filesystem, atomic) or write the bytes from a source. Returns the
+   * blob source and its size, or null for a created file. The sidecar is
+   * always complete before the entry JSON is written.
+   */
+  async placeSidecar(entryFile, content) {
+    if (content.source === null) return null;
+    const dest = join(dirname(entryFile), sidecarName(basename(entryFile)));
+    if (content.staged !== void 0) await rename(content.staged.file, dest);
+    else await this.writeSidecar(dest, content.source);
+    const st = await stat(dest);
+    return { source: { kind: "blob", path: dest }, size: st.size };
+  }
+  /**
+   * Commit one entry (a full before-backup or an in-place dedup link) under
+   * its anchor group.
+   */
+  async commit(sessionId, entry, content, opts) {
     const time = Math.max(Date.now(), this.lastEntryTime + 1);
     this.lastEntryTime = time;
+    const parent = await realpath(dirname(entry.path)).catch(() => void 0);
     await this.ensureDedupSeeded(sessionId);
+    await this.assertKnownStoreVersion(sessionId);
     const dir = this.anchorDir(sessionId, entry.anchorSeq);
     await mkdir(dir, { recursive: true });
-    const file = join(dir, `${safeFileId(entry.callId)}.json`);
+    const file = join(dir, entryFileName(entry.callId));
     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 incoming = content.source === null ? null : content.staged !== void 0 ? { kind: "blob", path: content.staged.file } : content.source;
+    const link = this.dedup && opts?.dedup !== false && prior !== void 0 && await this.sourcesMatch(prior.source, incoming);
+    if (link) {
       const committed = {
         callId: entry.callId,
         anchorSeq: entry.anchorSeq,
         path: entry.path,
         ref: prior.ref,
+        ...parent !== void 0 ? { parent } : {},
         time
       };
-      await writeJsonAtomic(file, committed, () => opts?.crash?.("after-temp-write"));
-      this.lastEntry.set(key, { content: prior.content, ref: selfRef });
+      if (content.staged !== void 0) await rm(content.staged.file, { force: true });
+      await writeJsonAtomic(file, linkToJson(committed), () => opts?.crash?.("after-temp-write"));
+      this.lastEntry.set(key, { source: prior.source, 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 placed = await this.placeSidecar(file, content);
+      const committed = {
+        callId: entry.callId,
+        anchorSeq: entry.anchorSeq,
+        path: entry.path,
+        before: placed?.source ?? null,
+        size: placed?.size ?? 0,
+        // Content that was already lossy when it reached the store (a v1
+        // string, or a materialized link to one) stays marked, so a later
+        // reader cannot mistake its re-encoded bytes for a faithful backup.
+        ...incoming?.kind === "lossyText" ? { lossy: true } : {},
+        ...content.mode !== void 0 ? { mode: content.mode } : {},
+        ...parent !== void 0 ? { parent } : {},
+        time
+      };
+      await writeJsonAtomic(file, entryToJson(committed), () => opts?.crash?.("after-temp-write"));
+      this.lastEntry.set(key, { source: committed.before, ref: selfRef });
     }
     if (this.formatVersion !== null) {
       await this.markFormatVersion(sessionId, this.formatVersion);
     }
+    if (!this.storeStamped.has(sessionId)) {
+      await this.markStoreVersion(sessionId, CURRENT_STORE_VERSION);
+      this.storeStamped.add(sessionId);
+    }
     const now = Date.now();
     if (now - this.lastPruneAt >= _SnapshotStore.PRUNE_INTERVAL_MS) {
       this.lastPruneAt = now;
@@ -453,16 +899,39 @@ var SnapshotStore = class _SnapshotStore {
     }
   }
   /**
-   * 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).
+   * Commit one before-backup whose content the caller already holds as raw
+   * text (the boundary-friendly API: tests, synthetic records). The bytes are
+   * encoded UTF-8, exactly as the released v1 build did for text content.
+   */
+  async recordEntry(sessionId, entry, opts) {
+    await this.commit(sessionId, entry, {
+      source: entry.before === null ? null : textSourceOf(entry.before)
+    }, opts);
+  }
+  /**
+   * Commit one before-backup whose content is an existing byte file (the
+   * capture and boundary paths): `backup.file` is MOVED into the anchor group
+   * (same filesystem, so this is atomic), or `null` when the file did not
+   * exist — a creation.
+   */
+  async recordBackup(sessionId, entry, backup, opts) {
+    await this.commit(sessionId, entry, {
+      source: backup === null ? null : { kind: "blob", path: backup.file },
+      ...backup !== null ? { staged: { file: backup.file } } : {},
+      ...backup?.mode !== void 0 ? { mode: backup.mode } : {}
+    }, opts);
+  }
+  /**
+   * The byte source 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 compares the disk
+   * against — the same source `recordEntry` dedups against, so there is one
+   * handle 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;
+    return this.lastEntry.get(`${sessionId}\0${path}`)?.source;
   }
   /**
    * All committed entries anchored at or after `targetSeq`, newest first (for
@@ -487,7 +956,7 @@ var SnapshotStore = class _SnapshotStore {
       const files = await readdir(this.anchorDir(sessionId, anchorSeq)).catch(() => []);
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const entry = await readEntry(join(this.anchorDir(sessionId, anchorSeq), file));
+        const entry = await readEntry(join(this.anchorDir(sessionId, anchorSeq), file), anchorSeq);
         if (entry !== void 0) entries.push(entry);
       }
     }
@@ -521,9 +990,15 @@ var SnapshotStore = class _SnapshotStore {
    *   `delete` ONLY when the file currently exists; an already-absent file
    *   is a no-op — this kills the "ghost impact" of replaying an entry a
    *   previous rewind already consumed.
-   * - `before === 'X'` plans a `restore` ONLY when the current content
-   *   differs from X (or the file is missing); identical content is a no-op
-   *   — this keeps repeated rewinds idempotent.
+   * - a recorded byte source plans a `restore` ONLY when the current bytes
+   *   differ from it (or the file is missing); identical bytes are a no-op —
+   *   this keeps repeated rewinds idempotent.
+   * - A released-v1 record that lost bytes to a lossy decode (`lossyText`) is
+   *   compared with the same lossy decode but NEVER written back: a skip is
+   *   reported instead of destroying live bytes with U+FFFD content.
+   * - An unreadable / unresolvable record is a per-file FAILURE, never a
+   *   delete: planning a delete for a file we cannot restore is the one
+   *   mistake that loses data.
    * - Symlinked / hard-linked paths are never planned (they are reported as
    *   skipped by the restore pass, never written through).
    * - A probe failure (e.g. a permission error reading the file) plans the
@@ -536,40 +1011,54 @@ var SnapshotStore = class _SnapshotStore {
    * @returns the planned actions, the link paths skipped, and per-file failures.
    */
   async planRestore(sessionId, targetSeq, probe) {
+    await this.assertKnownStoreVersion(sessionId);
     const actions = [];
     const skipped = [];
     const failed = [];
     for (const entry of (await this.earliestEntries(sessionId, targetSeq)).values()) {
+      let source;
+      try {
+        source = await this.resolveBefore(sessionId, entry);
+      } catch (error) {
+        failed.push({ path: entry.path, message: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
       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) });
+        if (!await parentStillMatches(entry.path, entry.parent)) {
+          skipped.push(entry.path);
           continue;
         }
-        const current = await probe.readText(entry.path);
-        if (before === null) {
-          if (current !== void 0) actions.push({ path: entry.path, action: "delete" });
-        } else if (current !== before) {
-          actions.push({ path: entry.path, action: "restore", before });
+        if (source !== null && source.kind === "lossyText") {
+          const same2 = await probe.matches(source, entry.path);
+          if (same2 !== true) skipped.push(entry.path);
+          continue;
         }
-      } catch (error) {
-        let before;
-        try {
-          before = await this.resolveBefore(sessionId, entry);
-        } catch {
-          before = null;
+        const same = await probe.matches(source, entry.path);
+        if (same === true) continue;
+        const pin = entry.parent !== void 0 ? { parent: entry.parent } : {};
+        if (source === null) actions.push({ path: entry.path, action: "delete", ...pin });
+        else {
+          const mode = isLinkEntry(entry) ? void 0 : entry.mode;
+          actions.push({
+            path: entry.path,
+            action: "restore",
+            before: source,
+            ...mode !== void 0 ? { mode } : {},
+            ...pin
+          });
         }
-        if (before === null) {
-          actions.push({ path: entry.path, action: "delete" });
-        } else {
-          actions.push({ path: entry.path, action: "restore", before });
+      } catch {
+        if (source !== null && source.kind === "lossyText") {
+          skipped.push(entry.path);
+          continue;
         }
+        const pin = entry.parent !== void 0 ? { parent: entry.parent } : {};
+        if (source === null) actions.push({ path: entry.path, action: "delete", ...pin });
+        else actions.push({ path: entry.path, action: "restore", before: source, ...pin });
       }
     }
     return { actions, skipped, failed };
@@ -615,7 +1104,22 @@ var SnapshotStore = class _SnapshotStore {
       const journalAction = journal.actions[i];
       let applied;
       try {
-        applied = await this.applyActionToDisk(action.action, action.path, action.action === "restore" ? action.before : null, deleteFile);
+        applied = await this.applyActionToDisk(
+          action.action,
+          action.path,
+          action.action === "restore" ? action.before : null,
+          deleteFile,
+          {
+            ...action.action === "restore" && action.mode !== void 0 ? { mode: action.mode } : {},
+            ...action.parent !== void 0 ? { parent: action.parent } : {}
+          }
+        );
+        if (applied === "skipped") {
+          journalAction.failed = `parent directory moved or repointed: ${dirname(action.path)}`;
+          await this.saveJournal(journal);
+          failed.push({ path: action.path, message: journalAction.failed });
+          continue;
+        }
         if (applied === "enoent") {
           journalAction.done = true;
           await this.saveJournal(journal);
@@ -640,61 +1144,95 @@ var SnapshotStore = class _SnapshotStore {
     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-";
-  /** Session-format-version marker file inside the session dir. Non-`.json`, so it never counts as a checkpoint entry. */
-  static FORMAT_FILE = "format";
-  /** Absolute path of one restore-op journal file. */
+  /** Absolute path of one restore-op journal file (the current prefix). */
   journalPath(sessionId, opId) {
-    return join(this.sessionDir(sessionId), `${_SnapshotStore.JOURNAL_PREFIX}${safeFileId(opId)}.json`);
+    return join(this.sessionDir(sessionId), `${JOURNAL_PREFIX}${safeFileId(opId)}.json`);
+  }
+  /**
+   * Locate an existing journal file for an op: the current prefix first, then
+   * the prefix the released v1 build wrote (a restore interrupted before the
+   * upgrade must still be continuable / rollbackable).
+   */
+  async findJournalFile(sessionId, opId) {
+    const dir = this.sessionDir(sessionId);
+    for (const name2 of [`${JOURNAL_PREFIX}${safeFileId(opId)}.json`, `${LEGACY_JOURNAL_PREFIX}${safeFileId(opId)}.json`]) {
+      const file = join(dir, name2);
+      try {
+        await stat(file);
+        return file;
+      } catch {
+        continue;
+      }
+    }
+    return void 0;
   }
   /**
    * 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.
+   *
+   * A journal read back from a legacy file is rewritten IN PLACE (same file),
+   * so a redo / rollback of a pre-upgrade op never leaves two divergent
+   * versions of the same op on disk.
    */
   async saveJournal(journal) {
     try {
-      await writeJsonAtomic(this.journalPath(journal.sessionId, journal.id), journal);
+      const file = journal.sourceFile ?? this.journalPath(journal.sessionId, journal.id);
+      await writeJsonAtomic(file, journalToJson(journal, this.sessionDir(journal.sessionId)));
     } 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}).
+   * (pre-restore) state of every planned path as a raw byte copy and persist
+   * the intent (references only) 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;
+      if (!isEnoent(error)) throw error;
     }
+    const id = `op-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const rescueDir = join(sessionDir, RESCUE_DIR, safeFileId(id));
+    let rescueDirReady = false;
     const journalActions = [];
-    for (const action of actions) {
+    for (const [index, action] of actions.entries()) {
       let rescue = null;
       let rescueError;
+      const dest = join(rescueDir, `${index}${SIDECAR_SUFFIX}`);
       try {
-        rescue = await probe.readText(action.path) ?? null;
+        if (!rescueDirReady) {
+          await mkdir(rescueDir, { recursive: true });
+          rescueDirReady = true;
+        }
+        const copied = await probe.copy(action.path, dest);
+        if (copied.kind === "copied") rescue = { kind: "blob", path: dest };
+        else if (copied.kind === "failed") rescueError = copied.message;
       } catch (error) {
         rescueError = error instanceof Error ? error.message : String(error);
       }
+      const rescueMode = (await stat(action.path).catch(() => void 0))?.mode;
       const journalAction = {
         path: action.path,
         action: action.action,
         before: action.action === "restore" ? action.before : null,
         rescue,
+        ...action.action === "restore" && action.mode !== void 0 ? { mode: action.mode } : {},
+        ...action.parent !== void 0 ? { parent: action.parent } : {},
+        ...rescueMode !== void 0 ? { rescueMode: rescueMode & 4095 } : {},
         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)}`,
+      version: 2,
+      id,
       sessionId,
       targetSeq,
       startedAt: Date.now(),
@@ -710,26 +1248,24 @@ var SnapshotStore = class _SnapshotStore {
    * 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;
-    }
+    const file = await this.findJournalFile(sessionId, opId);
+    if (file === void 0) return void 0;
     let parsed;
     try {
-      parsed = JSON.parse(text);
+      parsed = JSON.parse(await readFile(file, "utf8"));
     } 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;
+    const journal = journalFromJson(parsed, this.sessionDir(sessionId));
+    if (journal === void 0) throw new Error(`restore journal ${file} failed schema validation`);
+    journal.sourceFile = file;
+    return journal;
   }
   /**
-   * Every journal file of a session — valid ones plus corrupt ones with their
-   * error — so reconciliation can report corruption instead of dropping it.
+   * Every journal file of a session (both prefixes) — 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);
@@ -737,20 +1273,26 @@ var SnapshotStore = class _SnapshotStore {
     try {
       names = await readdir(sessionDir);
     } catch (error) {
-      if (error.code === "ENOENT") return { journals: [], corrupt: [] };
+      if (isEnoent(error)) return { journals: [], corrupt: [] };
       throw error;
     }
     const journals = [];
     const corrupt = [];
     for (const name2 of names) {
-      if (!name2.startsWith(_SnapshotStore.JOURNAL_PREFIX) || !name2.endsWith(".json")) continue;
+      if (!isJournalName(name2)) 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);
+        const journal = journalFromJson(parsed, sessionDir);
+        if (journal === void 0) {
+          corrupt.push({ file: name2, message: "journal references are invalid" });
+          continue;
+        }
+        journal.sourceFile = join(sessionDir, name2);
+        journals.push(journal);
       } catch (error) {
         corrupt.push({ file: name2, message: error instanceof Error ? error.message : String(error) });
       }
@@ -760,29 +1302,54 @@ var SnapshotStore = class _SnapshotStore {
   /**
    * 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.
+   * already absent, i.e. the target state is reached), a restore copies the
+   * recorded bytes back over the file (creating the parent if needed).
    *
    * This is the only place the store writes restored content to the real FS,
-   * and it is deliberately a raw `writeFile`/`unlink` rather than the fs
-   * service: the caller only ever hands it a path from `planRestore` — one the
-   * session's own write-class tool call recorded and resolved (never a
+   * and it is deliberately raw `copyFile`/`writeFile`/`unlink` rather than the
+   * fs service: the caller only ever hands it a path from `planRestore` — one
+   * the session's own write-class tool call recorded and resolved (never a
    * symlink/hard link) and only when it differs from the live disk. So no
    * arbitrary path, no model input, never automatic.
+   *
+   * The write is IN PLACE (no temp + rename): it keeps the file's inode and
+   * thus its xattrs/ACL, and crash safety is provided by the journal plus disk
+   * reconciliation instead (a half-written file simply does not match the
+   * goal, so a redo rewrites it).
+   *
+   * Permissions are best-effort (ADR-9/R3): the mode is only ever applied as
+   * part of a CONTENT restore (never as a reason to plan one), and a chmod
+   * failure never fails the restore.
    */
-  async applyActionToDisk(kind, path, content, deleteFile) {
+  async applyActionToDisk(kind, path, content, deleteFile, opts) {
+    if (!await parentStillMatches(path, opts?.parent)) return "skipped";
     if (kind === "delete") {
       try {
         await deleteFile(path);
         return "deleted";
       } catch (error) {
-        if (error.code !== "ENOENT") throw error;
+        if (!isEnoent(error)) throw error;
         return "enoent";
       }
     }
+    if (content === null) throw new Error(`restore of ${path} has no recorded content`);
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, content, "utf8");
+    const current = (await stat(path).catch(() => void 0))?.mode;
+    let widened = false;
+    if (current !== void 0 && (current & 128) === 0) {
+      await chmod(path, current | 128).catch(() => void 0);
+      widened = true;
+    }
+    try {
+      if (content.kind === "blob") await copyFile(content.path, path);
+      else if (content.kind === "text") await writeFile(path, content.bytes);
+      else await writeFile(path, Buffer.from(content.text, "utf8"));
+    } catch (error) {
+      if (widened && current !== void 0) await chmod(path, current).catch(() => void 0);
+      throw error;
+    }
+    if (opts?.mode !== void 0) await chmod(path, opts.mode).catch(() => void 0);
+    else if (widened && current !== void 0) await chmod(path, current).catch(() => void 0);
     return "restored";
   }
   /**
@@ -794,6 +1361,13 @@ var SnapshotStore = class _SnapshotStore {
    * terminal state and not reported. A corrupt journal is reported
    * `recovery-required` — never silently dropped.
    *
+   * Deliberately NOT gated on the session's `store` marker: a journal is fully
+   * self-describing (`version` plus byte references), and refusing to finish an
+   * interrupted op merely because the SESSION marker looks newer would strand a
+   * half-restored workspace — the outcome the legacy-journal support exists to
+   * prevent. A reference the newer build moved shows up as a per-file failure,
+   * never as a silent write.
+   *
    * @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.
@@ -803,7 +1377,7 @@ var SnapshotStore = class _SnapshotStore {
     const reports = [];
     for (const bad of corrupt) {
       reports.push({
-        opId: bad.file.slice(_SnapshotStore.JOURNAL_PREFIX.length, -".json".length),
+        opId: journalOpIdOf(bad.file),
         state: "recovery-required",
         journalState: "recovery-required",
         targetSeq: 0,
@@ -843,9 +1417,8 @@ var SnapshotStore = class _SnapshotStore {
       }
       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;
+        reached = await probe.matches(goal, action.path) === true;
       } catch {
         reached = false;
       }
@@ -873,7 +1446,7 @@ var SnapshotStore = class _SnapshotStore {
     };
   }
   /**
-   * 补做 (redo) an interrupted restore: finish the op by applying every action
+   * Continue (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
@@ -896,8 +1469,8 @@ var SnapshotStore = class _SnapshotStore {
       opts?.crash?.("before-action", i);
       let reached;
       try {
-        const state = await probe.readText(action.path) ?? null;
-        reached = state === (action.action === "delete" ? null : action.before);
+        const goal = action.action === "delete" ? null : action.before;
+        reached = await probe.matches(goal, action.path) === true;
       } catch {
         reached = false;
       }
@@ -909,7 +1482,22 @@ var SnapshotStore = class _SnapshotStore {
       }
       let applied;
       try {
-        applied = await this.applyActionToDisk(action.action, action.path, action.action === "restore" ? action.before : null, deleteFile);
+        applied = await this.applyActionToDisk(
+          action.action,
+          action.path,
+          action.action === "restore" ? action.before : null,
+          deleteFile,
+          {
+            ...action.action === "restore" && action.mode !== void 0 ? { mode: action.mode } : {},
+            ...action.parent !== void 0 ? { parent: action.parent } : {}
+          }
+        );
+        if (applied === "skipped") {
+          action.failed = `parent directory moved or repointed: ${dirname(action.path)}`;
+          await this.saveJournal(journal);
+          failed.push({ path: action.path, message: action.failed });
+          continue;
+        }
         if (applied === "enoent") {
           action.done = true;
           await this.saveJournal(journal);
@@ -936,7 +1524,7 @@ var SnapshotStore = class _SnapshotStore {
     return { restored, deleted, skipped: [], failed };
   }
   /**
-   * 回滚 (roll back) an interrupted restore: undo every action whose disk
+   * 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
@@ -973,8 +1561,7 @@ var SnapshotStore = class _SnapshotStore {
       opts?.crash?.("before-action", i);
       let reached;
       try {
-        const state = await probe.readText(action.path) ?? null;
-        reached = state === action.rescue;
+        reached = await probe.matches(action.rescue, action.path) === true;
       } catch {
         reached = false;
       }
@@ -985,7 +1572,24 @@ var SnapshotStore = class _SnapshotStore {
       }
       let applied;
       try {
-        applied = await this.applyActionToDisk(action.rescue === null ? "delete" : "restore", action.path, action.rescue, deleteFile);
+        applied = await this.applyActionToDisk(
+          action.rescue === null ? "delete" : "restore",
+          action.path,
+          action.rescue,
+          deleteFile,
+          {
+            ...action.rescueMode !== void 0 ? { mode: action.rescueMode } : {},
+            ...action.parent !== void 0 ? { parent: action.parent } : {}
+          }
+        );
+        if (applied === "skipped") {
+          journal.rollbackError = `parent directory moved or repointed: ${action.path}`;
+          journal.state = "recovery-required";
+          await this.saveJournal(journal);
+          failed.push({ path: action.path, message: journal.rollbackError });
+          rollbackFailed = true;
+          continue;
+        }
         if (applied === "enoent") {
           action.done = false;
           await this.saveJournal(journal);
@@ -1038,60 +1642,147 @@ var SnapshotStore = class _SnapshotStore {
     try {
       names = await readdir(sessionDir);
     } catch (error) {
-      if (error.code === "ENOENT") return;
+      if (isEnoent(error)) return;
       throw error;
     }
     await this.pruneTerminalJournals(sessionDir, names);
+    await this.prunePendingCaptures(join(sessionDir, PENDING_DIR));
     const seqs = names.map(Number).filter((seq) => Number.isSafeInteger(seq)).sort((a, b) => a - b);
     const excess = seqs.length - keep;
     if (excess <= 0) return;
     const doomed = new Set(seqs.slice(0, excess));
+    for (const seq of await this.pinnedAnchors(sessionDir, names)) doomed.delete(seq);
+    if (doomed.size === 0) return;
     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));
+        const entryFile = join(this.anchorDir(sessionId, seq), file);
+        let entry;
+        try {
+          entry = await readEntry(entryFile, seq);
+        } catch {
+          continue;
+        }
         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));
+        const refAnchor = refAnchorOf(entry.ref);
         if (!Number.isSafeInteger(refAnchor) || !doomed.has(refAnchor)) continue;
-        let before;
+        let source;
         try {
-          before = await this.resolveBefore(sessionId, entry);
-        } catch {
+          source = await this.resolveBefore(sessionId, entry);
+        } catch (error) {
+          if (error instanceof UnknownStoreVersionError) throw error;
           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"));
+        const pin = entry.parent !== void 0 ? { parent: entry.parent } : {};
+        let real;
+        if (source === null) {
+          real = {
+            callId: entry.callId,
+            anchorSeq: entry.anchorSeq,
+            path: entry.path,
+            before: null,
+            size: 0,
+            ...pin,
+            time: entry.time
+          };
+        } else {
+          const dest = join(dirname(entryFile), sidecarName(basename(entryFile)));
+          await this.writeSidecar(dest, source);
+          const st = await stat(dest);
+          real = {
+            callId: entry.callId,
+            anchorSeq: entry.anchorSeq,
+            path: entry.path,
+            before: { kind: "blob", path: dest },
+            size: st.size,
+            ...source.kind === "lossyText" ? { lossy: true } : {},
+            ...pin,
+            time: entry.time
+          };
+        }
+        await writeJsonAtomic(entryFile, entryToJson(real), () => opts?.crash?.("after-temp-write"));
       }
     }
     for (const seq of doomed) {
       await rm(this.anchorDir(sessionId, seq), { recursive: true, force: true });
     }
+    this.seededSessions.delete(sessionId);
+    for (const key of [...this.lastEntry.keys()]) {
+      if (key.startsWith(`${sessionId}\0`)) this.lastEntry.delete(key);
+    }
+  }
+  /**
+   * Collect staged captures that were never committed and are older than
+   * {@link PENDING_MAX_AGE_MS}: a crash between `tools/execute` and
+   * `tools/post-execute` can leak one, and the process that would have
+   * unlinked it is gone.
+   */
+  async prunePendingCaptures(pendingDir) {
+    let names;
+    try {
+      names = await readdir(pendingDir);
+    } catch {
+      return;
+    }
+    const cutoff = Date.now() - PENDING_MAX_AGE_MS;
+    for (const name2 of names) {
+      const file = join(pendingDir, name2);
+      const st = await lstat(file).catch(() => void 0);
+      if (st === void 0 || !st.isFile() || st.mtimeMs >= cutoff) continue;
+      await rm(file, { force: true });
+    }
+  }
+  /**
+   * Anchor groups a NON-TERMINAL journal still depends on — the groups holding
+   * the sidecars its actions restore from. `prune` must not evict them while
+   * the op can still be finished. Rescue copies live under `rescue/`, never in
+   * an anchor group, so only `before` references matter; a group is pinned only
+   * for a well-formed, safe reference (a corrupt journal pins nothing).
+   */
+  async pinnedAnchors(sessionDir, names) {
+    const pinned = /* @__PURE__ */ new Set();
+    for (const name2 of names) {
+      if (!isJournalName(name2)) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(await readFile(join(sessionDir, name2), "utf8"));
+      } catch {
+        continue;
+      }
+      if (!isRestoreJournal(parsed)) continue;
+      const journal = journalFromJson(parsed, sessionDir);
+      if (journal === void 0) continue;
+      if (journal.state === "completed" || journal.state === "rolled-back") continue;
+      for (const action of journal.actions) {
+        const source = action.before;
+        if (source === null || source.kind !== "blob") continue;
+        const ref = relative(sessionDir, source.path);
+        if (!isSafeBackupRef(ref)) continue;
+        const anchor = refAnchorOf(ref);
+        if (Number.isSafeInteger(anchor)) pinned.add(anchor);
+      }
+    }
+    return pinned;
   }
   /**
    * 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.
+   * op finished, its journal and its rescue bytes are 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;
+      if (!isJournalName(name2)) 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 });
+          await rm(join(sessionDir, RESCUE_DIR, safeFileId(journalOpIdOf(name2))), { recursive: true, force: true });
         }
       } catch {
       }
@@ -1103,7 +1794,7 @@ var SnapshotStore = class _SnapshotStore {
       await stat(path);
       return true;
     } catch (error) {
-      if (error.code === "ENOENT") return false;
+      if (isEnoent(error)) return false;
       throw error;
     }
   }
@@ -1124,7 +1815,9 @@ var SnapshotStore = class _SnapshotStore {
    *  - 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.
+   *    temp left overs — except the real `.pending/` area, whose staged bytes
+   *    are content and whose freshness is activity — 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.
@@ -1176,6 +1869,7 @@ var SnapshotStore = class _SnapshotStore {
         remainingBytes += size;
       }
     }
+    if (!dryRun) await this.forgetMissingSessions();
     return report();
   }
   /**
@@ -1193,11 +1887,16 @@ var SnapshotStore = class _SnapshotStore {
   }
   /**
    * Summarize a session's on-disk footprint for a clear dry-run: anchor-group
-   * count, committed checkpoint-entry count, restore-journal count, and total
-   * bytes. Walks with `lstat` (never follows a symlink, so a hostile symlink
-   * cannot escape the store root or inflate the measurement) and skips
-   * dot-prefixed temp leftovers and non-`.json` members — they are never
-   * checkpoint entries.
+   * count, committed checkpoint-entry count (one per `.json` in an anchor
+   * group), restore-journal count (both journal prefixes), and the total bytes
+   * the session dir occupies — entry JSONs, raw byte sidecars, `rescue/**` and
+   * the staged `.pending/**` copies alike, so the number matches what a `du` of
+   * that directory reports.
+   *
+   * Walks with `lstat` (never follows a symlink, so a hostile symlink cannot
+   * escape the store root or inflate the measurement) and skips dot-prefixed
+   * temp leftovers (the one exception is `.pending/`, whose staged bytes are
+   * real store content).
    */
   async sessionStats(sessionId) {
     const sessionDir = this.sessionDir(sessionId);
@@ -1205,7 +1904,7 @@ var SnapshotStore = class _SnapshotStore {
     try {
       names = await readdir(sessionDir);
     } catch (error) {
-      if (error.code === "ENOENT") return { anchorGroups: 0, entries: 0, journals: 0, bytes: 0 };
+      if (isEnoent(error)) return { anchorGroups: 0, entries: 0, journals: 0, bytes: 0 };
       throw error;
     }
     let anchorGroups = 0;
@@ -1213,33 +1912,26 @@ var SnapshotStore = class _SnapshotStore {
     let journals = 0;
     let bytes = 0;
     for (const name2 of names) {
-      if (name2.startsWith(".")) continue;
+      if (name2.startsWith(".") && name2 !== PENDING_DIR) continue;
       const full = join(sessionDir, name2);
-      let st;
-      try {
-        st = await lstat(full);
-      } catch {
-        continue;
-      }
+      const st = await lstat(full).catch(() => void 0);
+      if (st === void 0) continue;
       if (st.isDirectory()) {
-        if (!Number.isSafeInteger(Number(name2))) continue;
-        anchorGroups++;
-        let files;
-        try {
-          files = await readdir(full);
-        } catch {
+        if (name2 === PENDING_DIR || name2 === RESCUE_DIR) {
+          bytes += await dirBytes(full);
           continue;
         }
-        for (const file of files) {
-          if (!file.endsWith(".json")) continue;
-          entries++;
-          const fileSt = await lstat(join(full, file)).catch(() => void 0);
-          if (fileSt !== void 0) bytes += fileSt.size;
+        if (!Number.isSafeInteger(Number(name2))) continue;
+        anchorGroups++;
+        for (const file of await readdir(full).catch(() => [])) {
+          if (file.endsWith(".json")) entries++;
         }
-      } else if (name2.startsWith(_SnapshotStore.JOURNAL_PREFIX) && name2.endsWith(".json")) {
-        journals++;
-        bytes += st.size;
+        bytes += await dirBytes(full);
+        continue;
       }
+      if (!st.isFile()) continue;
+      if (isJournalName(name2)) journals++;
+      bytes += st.size;
     }
     return { anchorGroups, entries, journals, bytes };
   }
@@ -1278,13 +1970,10 @@ var SnapshotStore = class _SnapshotStore {
     const dryRun = opts?.dryRun ?? false;
     const stats = await this.sessionStats(sessionId);
     if (!dryRun) {
-      if (stats.anchorGroups > 0 || stats.journals > 0) {
+      if (stats.anchorGroups > 0 || stats.journals > 0 || stats.bytes > 0) {
         await rm(this.sessionDir(sessionId), { recursive: true, force: true });
       }
-      this.seededSessions.delete(sessionId);
-      for (const key of this.lastEntry.keys()) {
-        if (key.startsWith(`${sessionId}\0`)) this.lastEntry.delete(key);
-      }
+      this.forgetSession(sessionId);
     }
     return { sessionId, ...stats, dryRun };
   }
@@ -1328,6 +2017,48 @@ var SnapshotStore = class _SnapshotStore {
   setFormatVersion(sessionVersion) {
     this.formatVersion = sessionVersion;
   }
+  /**
+   * Read the plugin's STORE-format marker for a session, or null when there is
+   * none (a released-v1 dir, or a session that never recorded a snapshot). The
+   * marker is a quick session-level signal; every entry and journal is also
+   * self-describing (`store` / `version`), so a missing marker never changes
+   * how an entry is read.
+   */
+  async readStoreVersion(sessionId) {
+    try {
+      const raw = await readFile(join(this.sessionDir(sessionId), _SnapshotStore.STORE_FILE), "utf8");
+      const parsed = Number(raw.trim());
+      return Number.isFinite(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Stamp the store-format marker (atomically, like `format`). Written
+   * alongside every byte-format entry, so a session that only ever holds the
+   * released string format keeps no marker and is read as v1.
+   */
+  async markStoreVersion(sessionId, storeVersion) {
+    const dir = this.sessionDir(sessionId);
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, _SnapshotStore.STORE_FILE);
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${storeVersion}`, "utf8");
+    await rename(tmp, file);
+  }
+  /**
+   * Refuse to plan against (or write into) a session whose store format is
+   * NEWER than this build understands (ADR-10): the caller reports it and
+   * changes nothing — no partial restore, no clear, no v2 entry written into a
+   * v3 store. Checked before any entry is read, so the marker alone is enough
+   * to fail closed.
+   */
+  async assertKnownStoreVersion(sessionId) {
+    const version = await this.readStoreVersion(sessionId);
+    if (version !== null && version > CURRENT_STORE_VERSION) {
+      throw new UnknownStoreVersionError(version, join(this.sessionDir(sessionId), _SnapshotStore.STORE_FILE));
+    }
+  }
   /**
    * Session-format-version guard: clear a session's snapshot dir when the
    * format its snapshots were anchored under differs from the current session
@@ -1359,25 +2090,37 @@ var SnapshotStore = class _SnapshotStore {
   }
 };
 function hashPath(path) {
-  return createHash("sha256").update(path).digest("hex").slice(0, 8);
+  return shortHash(path);
 }
 async function reconcileTracked(store, sessionId, anchorSeq, tracked, probe = defaultProbe) {
+  try {
+    await store.assertKnownStoreVersion(sessionId);
+  } catch {
+    return 0;
+  }
   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 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
-        }, { dedup: false });
-        recorded++;
+      if (last !== void 0 && last !== null && last.kind !== "lossyText") {
+        const same = await probe.matches(last, path);
+        if (same === void 0 || same) continue;
+      }
+      const callId = `recheck-${anchorSeq}-${hashPath(path)}`;
+      const staged = await store.stageCapture(sessionId, callId);
+      const copied = await probe.copy(path, staged);
+      if (copied.kind === "failed") {
+        await rm(staged, { force: true });
+        continue;
       }
+      await store.recordBackup(
+        sessionId,
+        { callId, anchorSeq, path },
+        copied.kind === "absent" ? null : { file: staged, size: copied.size },
+        { dedup: false }
+      );
+      recorded++;
     } catch {
     }
   }
@@ -1518,6 +2261,13 @@ function usage() {
     t("usage.blocked")
   ].join("\n");
 }
+async function discardCapture(capture) {
+  if (capture === void 0 || capture.backup === null) return;
+  try {
+    await rm2(capture.backup.file, { force: true });
+  } catch {
+  }
+}
 function mutationPathOf(exec) {
   const args = exec.arguments;
   if (exec.name === "write" || exec.name === "edit") {
@@ -1549,43 +2299,72 @@ async function resolveTarget(fs, path, cwd, signal) {
     return void 0;
   }
 }
-async function readTextOrUndefined(fs, target, signal) {
-  try {
-    return await fs.readText(target, signal);
-  } catch (error) {
-    const code = error?.code;
-    if (code === "ENOENT" || code === "FS_NOT_FOUND") return void 0;
-    throw error;
-  }
+function isNotFoundError(error) {
+  const code = error?.code;
+  return code === "ENOENT" || code === "FS_NOT_FOUND";
 }
-async function captureBefore(fs, exec, pending) {
+async function captureBefore(fs, store, exec, pending) {
   if (!TRACKED_TOOLS.has(exec.name)) return;
-  const header = exec.agent?.session.header;
+  const session = exec.agent?.session;
+  const header = session?.header;
   if (header !== void 0 && (header.origin === "subagent" || (header.delegationDepth ?? 0) > 0)) return;
   const path = mutationPathOf(exec);
   if (path === void 0) return;
   const cwd = execSessionCwd(exec, path);
   const target = await resolveTarget(fs, path, cwd, exec.signal);
   if (target === void 0) return;
-  const before = await readTextOrUndefined(fs, target, exec.signal);
-  pending.set(`${exec.agent?.id ?? "anon"}:${exec.callId}`, { path: target.displayPath, before });
+  const info = await fs.stat(target, exec.signal).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  if (session === void 0) return;
+  if (info !== void 0 && info.type !== "file") return;
+  const key = `${exec.agent?.id ?? "anon"}:${exec.callId}`;
+  if (info === void 0) {
+    pending.set(key, { path: target.displayPath, backup: null });
+    return;
+  }
+  const staged = await store.stageCapture(session.id, key);
+  let backup;
+  try {
+    await copyFile2(target.displayPath, staged);
+    const st = await stat2(staged);
+    const source = await stat2(target.displayPath).catch(() => void 0);
+    backup = {
+      file: staged,
+      size: st.size,
+      ...source !== void 0 ? { mode: source.mode & 4095 } : {}
+    };
+  } catch (error) {
+    await rm2(staged, { force: true });
+    throw error;
+  }
+  pending.set(key, { path: target.displayPath, backup });
 }
 async function commitEntry(store, pending, anchorCache, trackedBySession, exec, result) {
   const key = `${exec.agent?.id ?? "anon"}:${exec.callId}`;
   const capture = pending.get(key);
   if (capture === void 0) return;
   pending.delete(key);
-  if (result.isError) return;
+  if (result.isError) {
+    await discardCapture(capture);
+    return;
+  }
   const agent = exec.agent;
-  if (agent === void 0) return;
+  if (agent === void 0) {
+    await discardCapture(capture);
+    return;
+  }
   const anchorSeq = anchorSeqOf(agent.session, anchorCache);
-  if (anchorSeq === void 0) return;
-  await store.recordEntry(agent.session.id, {
+  if (anchorSeq === void 0) {
+    await discardCapture(capture);
+    return;
+  }
+  await store.recordBackup(agent.session.id, {
     callId: exec.callId,
     anchorSeq,
-    path: capture.path,
-    before: capture.before ?? null
-  });
+    path: capture.path
+  }, capture.backup);
   let tracked = trackedBySession.get(agent.session.id);
   if (tracked === void 0) {
     tracked = /* @__PURE__ */ new Set();
@@ -1724,14 +2503,23 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
     }
     let restore = "";
     if (mode === "both") {
-      const outcome = await store.restoreAfter(agent.session.id, plan.targetSeq, (path) => unlink(path));
-      await syncRestoreObservations(ctx, fs, agent, outcome);
-      const parts = [];
-      if (outcome.restored.length > 0) parts.push(t("restore.count", { count: outcome.restored.length }));
-      if (outcome.deleted.length > 0) parts.push(t("delete.count", { count: outcome.deleted.length }));
-      if (outcome.skipped.length > 0) parts.push(t("skip.count", { count: outcome.skipped.length }));
-      restore = parts.length > 0 ? `\uFF1B${parts.join("\u3001")}` : t("noRestorable");
-      restore += renderFailures(outcome.failed);
+      let outcome;
+      try {
+        outcome = await store.restoreAfter(agent.session.id, plan.targetSeq, (path) => unlink(path));
+      } catch (error) {
+        if (!(error instanceof UnknownStoreVersionError)) throw error;
+        const version = await store.readStoreVersion(agent.session.id);
+        restore = `\uFF1B${t("storeUnsupported", { version: version ?? error.version })}`;
+      }
+      if (outcome !== void 0) {
+        await syncRestoreObservations(ctx, fs, agent, outcome);
+        const parts = [];
+        if (outcome.restored.length > 0) parts.push(t("restore.count", { count: outcome.restored.length }));
+        if (outcome.deleted.length > 0) parts.push(t("delete.count", { count: outcome.deleted.length }));
+        if (outcome.skipped.length > 0) parts.push(t("skip.count", { count: outcome.skipped.length }));
+        restore = parts.length > 0 ? `\uFF1B${parts.join("\u3001")}` : t("noRestorable");
+        restore += renderFailures(outcome.failed);
+      }
     }
     return {
       kind: "success",
@@ -1774,7 +2562,13 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
     } catch (error) {
       return rewindErrorResult(error);
     }
-    const impacts = await store.impactsAfter(session.id, plan.targetSeq);
+    const impacts = await store.impactsAfter(session.id, plan.targetSeq).catch((error) => {
+      if (error instanceof UnknownStoreVersionError) return void 0;
+      throw error;
+    });
+    if (impacts === void 0) {
+      return { kind: "error", text: t("storeUnsupported", { version: await store.readStoreVersion(session.id) ?? 0 }) };
+    }
     return { kind: "success", text: formatPlan(plan, impacts) };
   }
   if (parts[0] === "__candidates") {
@@ -1961,6 +2755,12 @@ function apply(ctx, config) {
     void (async () => {
       try {
         store.setFormatVersion(session.header.version);
+        try {
+          await store.assertKnownStoreVersion(session.id);
+        } catch (error) {
+          ctx.logger.warn(`[dsh-rewind] file restore disabled for ${session.id}: ${error instanceof Error ? error.message : String(error)}`);
+          return;
+        }
         const result = await store.reconcileFormatVersion(session.id, session.header.version);
         if (result.cleared) {
           ctx.logger.warn(`[dsh-rewind] cleared snapshots for ${session.id}: session format changed (v${session.header.version})`);
@@ -1995,7 +2795,7 @@ function apply(ctx, config) {
     fsService = fs;
     scope.on("tools/execute", async (exec, next) => {
       try {
-        await captureBefore(fs, exec, pending);
+        await captureBefore(fs, store, exec, pending);
       } catch (error) {
         ctx.logger.warn(`[dsh-rewind] before-capture failed for ${exec.name}: ${error instanceof Error ? error.message : String(error)}`);
       }
@@ -2011,7 +2811,10 @@ function apply(ctx, config) {
       return next();
     });
     scope.on("tools/result", (exec) => {
-      pending.delete(`${exec.agent?.id ?? "anon"}:${exec.callId}`);
+      const key = `${exec.agent?.id ?? "anon"}:${exec.callId}`;
+      const capture = pending.get(key);
+      pending.delete(key);
+      void discardCapture(capture);
       return void 0;
     });
   });