@cjhyy/code-shell-core 0.8.8 → 0.8.10

package/dist/session/file-history.js

@@ -4,12 +4,15 @@
  * Stores snapshots in the session directory under file-history/.
  * Supports restoring files to a previous state.
  */
-import { mkdirSync, existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, } from "node:fs";
-import { join, resolve } from "node:path";
-import { createHash } from "node:crypto";
-import { earliestSnapshotsPerFile } from "./undo-target.js";
+import { mkdirSync, existsSync, readFileSync, copyFileSync, chmodSync, lstatSync, realpathSync, rmSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { earliestSnapshotsPerFile, latestRedoTargets } from "./undo-target.js";
+import { acquireFileLock, writeFileAtomic } from "../utils/file-mutex.js";
+const LEGACY_TURN = Number.MIN_SAFE_INTEGER;
 export class FileHistory {
     historyDir;
+    lockDepth = 0;
     snapshots = [];
     /**
      * Redo material for undone turns, kept SEPARATE from `snapshots` so it never
@@ -19,8 +22,10 @@ export class FileHistory {
     /** Per-turn "this file was created" markers (see CreatedMarker). */
     created = [];
     constructor(sessionDir) {
-        this.historyDir = join(sessionDir, "file-history");
-        mkdirSync(this.historyDir, { recursive: true });
+        this.historyDir = resolve(sessionDir, "file-history");
+        mkdirSync(this.historyDir, { recursive: true, mode: 0o700 });
+        if (process.platform !== "win32")
+            chmodSync(this.historyDir, 0o700);
     }
     /**
      * Save a snapshot of a file before it is modified.
@@ -31,10 +36,19 @@ export class FileHistory {
      * latestTurnUndoTargets). Omit it for callers without turn context.
      */
     saveSnapshot(filePath, turnSeq) {
+        return this.withCurrentIndex(() => this.saveSnapshotUnlocked(filePath, turnSeq));
+    }
+    saveSnapshotUnlocked(filePath, turnSeq) {
+        if (turnSeq !== undefined && !isFiniteTurn(turnSeq))
+            return null;
         const absPath = resolve(filePath);
         if (!existsSync(absPath))
             return null;
         try {
+            const sourceInfo = lstatSync(absPath);
+            if (!sourceInfo.isFile() || sourceInfo.isSymbolicLink())
+                return null;
+            const realPath = realpathSync(absPath);
             const content = readFileSync(absPath);
             const hash = createHash("md5").update(content).digest("hex");
             // Check if we already have this exact (path, content) for this turn. Dedup
@@ -43,7 +57,7 @@ export class FileHistory {
             // miss it. Within a turn, re-snapshotting unchanged content is a no-op.
             const existing = this.snapshots.find((s) => s.filePath === absPath && s.hash === hash && s.turnSeq === turnSeq);
             if (existing)
-                return existing;
+                return { ...existing };
             // Create backup. The filename must uniquely identify (path, content): a
             // bare 100-char tail of the path can collide for two different files
             // whose tails coincide, and with the same ms timestamp the second
@@ -56,18 +70,30 @@ export class FileHistory {
             const safeName = absPath.replace(/[/\\:]/g, "_").slice(-80);
             const backupPath = join(this.historyDir, `${timestamp}_${pathHash}_${hash.slice(0, 8)}_${safeName}`);
             copyFileSync(absPath, backupPath);
+            if (process.platform !== "win32")
+                chmodSync(backupPath, 0o600);
             const snapshot = {
                 filePath: absPath,
                 timestamp,
                 backupPath,
                 hash,
                 size: content.length,
+                mode: sourceInfo.mode & 0o7777,
+                realPath,
                 ...(turnSeq === undefined ? {} : { turnSeq }),
             };
             this.snapshots.push(snapshot);
-            // Write index
-            this.saveIndex();
-            return snapshot;
+            if (!this.saveIndex()) {
+                this.snapshots.pop();
+                try {
+                    rmSync(backupPath, { force: true });
+                }
+                catch {
+                    // The unreferenced private backup is harmless; preserve the write failure result.
+                }
+                return null;
+            }
+            return { ...snapshot };
         }
         catch {
             return null;
@@ -82,16 +108,101 @@ export class FileHistory {
      * re-armed) — only fresh turns create new markers.
      */
     recordCreated(filePath, turnSeq) {
+        this.withCurrentIndex(() => this.recordCreatedUnlocked(filePath, turnSeq));
+    }
+    recordCreatedUnlocked(filePath, turnSeq) {
+        if (!isFiniteTurn(turnSeq))
+            return;
         const absPath = resolve(filePath);
         const existing = this.created.find((c) => c.filePath === absPath && c.turnSeq === turnSeq);
         if (existing)
             return;
-        this.created.push({ filePath: absPath, turnSeq });
-        this.saveIndex();
+        const realPath = this.canonicalizeNewPath(absPath);
+        const marker = {
+            filePath: absPath,
+            turnSeq,
+            ...(realPath ? { realPath } : {}),
+        };
+        this.created.push(marker);
+        if (!this.saveIndex())
+            this.created.pop();
+    }
+    /**
+     * Capture a create marker before the tool runs, but do not persist it yet.
+     * `lstat` (rather than `existsSync`) deliberately treats dangling symlinks as
+     * existing: a failed/no-follow Write must never turn such a path into a
+     * create marker that a later undo would remove.
+     */
+    prepareCreated(filePath, turnSeq) {
+        if (!isFiniteTurn(turnSeq))
+            return null;
+        const absPath = resolve(filePath);
+        try {
+            lstatSync(absPath);
+            return null;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                return null;
+        }
+        const realPath = this.canonicalizeNewPath(absPath);
+        return {
+            filePath: absPath,
+            turnSeq,
+            ...(realPath ? { realPath } : {}),
+        };
+    }
+    /** Persist a marker previously returned by prepareCreated after tool success. */
+    commitCreated(marker) {
+        this.withCurrentIndex(() => this.commitCreatedUnlocked(marker));
+    }
+    commitCreatedUnlocked(marker) {
+        if (!isCreatedMarker(marker))
+            return;
+        const existing = this.created.find((candidate) => candidate.filePath === marker.filePath && candidate.turnSeq === marker.turnSeq);
+        if (existing)
+            return;
+        this.created.push({ ...marker, undone: undefined });
+        if (!this.saveIndex())
+            this.created.pop();
     }
     /** Redo material captured by past undos (see RedoRecord). Returns a copy. */
     getRedoRecords() {
-        return [...this.redoRecords];
+        return this.redoRecords.map((record) => ({ ...record }));
+    }
+    /** Latest redo records after accounting for create-only live turns. */
+    getLatestRedoRecords() {
+        const records = latestRedoTargets(this.redoRecords, this.snapshots);
+        if (records.length === 0)
+            return [];
+        const redoTurn = records[0].turnSeq;
+        const snapshots = this.snapshots.filter((snapshot) => this.turnKey(snapshot.turnSeq) === redoTurn);
+        const markers = this.created.filter((marker) => marker.turnSeq === redoTurn);
+        if (snapshots.length + markers.length === 0 ||
+            snapshots.some((snapshot) => !snapshot.undone) ||
+            markers.some((marker) => !marker.undone)) {
+            return [];
+        }
+        if (this.created.some((marker) => !marker.undone && marker.turnSeq > redoTurn)) {
+            return [];
+        }
+        return records.map((record) => ({ ...record }));
+    }
+    /**
+     * Authoritative latest-turn plan, including turns that only created files.
+     * Keeping this decision in FileHistory prevents UI callers from accidentally
+     * selecting an older snapshot-only turn.
+     */
+    getLatestTurnUndoPlan() {
+        const plan = this.latestTurnUndoPlanInternal();
+        if (!plan)
+            return null;
+        return {
+            turnSeq: plan.turnSeq,
+            snapshots: plan.snapshots.map((snapshot) => ({ ...snapshot })),
+            createdPaths: [...plan.createdPaths],
+            filePaths: [...plan.filePaths],
+        };
     }
     /**
      * Get all snapshots for a specific file.
@@ -100,32 +211,28 @@ export class FileHistory {
         const absPath = resolve(filePath);
         return this.snapshots
             .filter((s) => s.filePath === absPath)
+            .map((snapshot) => ({ ...snapshot }))
             .sort((a, b) => b.timestamp - a.timestamp);
     }
     /**
      * Restore a file to a specific snapshot.
      */
     restore(snapshot) {
-        try {
-            if (!existsSync(snapshot.backupPath))
-                return false;
-            // Save current state before restoring
-            this.saveSnapshot(snapshot.filePath);
-            copyFileSync(snapshot.backupPath, snapshot.filePath);
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return this.withCurrentIndex(() => {
+            const authoritative = this.findSnapshot(snapshot);
+            return authoritative ? this.restoreSnapshot(authoritative, true) : false;
+        });
     }
     /**
      * Restore a file to its most recent snapshot.
      */
     restoreLatest(filePath) {
-        const snapshots = this.getSnapshots(filePath);
-        if (snapshots.length === 0)
-            return false;
-        return this.restore(snapshots[0]);
+        return this.withCurrentIndex(() => {
+            const snapshots = this.getSnapshots(filePath);
+            if (snapshots.length === 0)
+                return false;
+            return this.restore(snapshots[0]);
+        });
     }
     /**
      * Get all tracked files.
@@ -141,8 +248,10 @@ export class FileHistory {
      * hide which files reverted.
      */
     restoreAllToEarliest() {
-        const targets = earliestSnapshotsPerFile(this.snapshots);
-        return targets.map((snap) => ({ filePath: snap.filePath, ok: this.restore(snap) }));
+        return this.withCurrentIndex(() => {
+            const targets = earliestSnapshotsPerFile(this.snapshots);
+            return targets.map((snap) => ({ filePath: snap.filePath, ok: this.restore(snap) }));
+        });
     }
     /**
      * Capture the file's CURRENT on-disk content into a fresh redo backup and
@@ -152,16 +261,44 @@ export class FileHistory {
      */
     captureRedoBackup(filePath, turnSeq, existedBefore) {
         try {
-            if (!existsSync(filePath))
+            if (this.redoRecords.some((record) => record.filePath === filePath && record.turnSeq === turnSeq)) {
+                return true;
+            }
+            if (!existsSync(filePath)) {
+                const snapshot = this.snapshots.find((candidate) => candidate.filePath === filePath && this.turnKey(candidate.turnSeq) === turnSeq);
+                const backupPath = join(this.historyDir, `redo_absent_${Date.now()}_${randomUUID()}`);
+                writeFileAtomic(backupPath, "", 0o600);
+                this.redoRecords.push({
+                    filePath,
+                    turnSeq,
+                    backupPath,
+                    existedBefore,
+                    existedAfter: false,
+                    ...(snapshot?.realPath ? { realPath: snapshot.realPath } : {}),
+                });
+                return true;
+            }
+            const sourceInfo = lstatSync(filePath);
+            if (!sourceInfo.isFile() || sourceInfo.isSymbolicLink())
                 return false;
             const content = readFileSync(filePath);
             const hash = createHash("md5").update(content).digest("hex");
             const timestamp = Date.now();
             const pathHash = createHash("md5").update(filePath).digest("hex").slice(0, 8);
             const safeName = filePath.replace(/[/\\:]/g, "_").slice(-80);
-            const backupPath = join(this.historyDir, `redo_${timestamp}_${pathHash}_${hash.slice(0, 8)}_${safeName}`);
+            const backupPath = join(this.historyDir, `redo_${timestamp}_${pathHash}_${hash.slice(0, 8)}_${randomUUID()}_${safeName}`);
             copyFileSync(filePath, backupPath);
-            this.redoRecords.push({ filePath, turnSeq, backupPath, existedBefore });
+            if (process.platform !== "win32")
+                chmodSync(backupPath, 0o600);
+            this.redoRecords.push({
+                filePath,
+                turnSeq,
+                backupPath,
+                existedBefore,
+                existedAfter: true,
+                mode: sourceInfo.mode & 0o7777,
+                realPath: realpathSync(filePath),
+            });
             return true;
         }
         catch {
@@ -181,20 +318,76 @@ export class FileHistory {
      * latestTurnUndoTargets so preview and restore agree. Returns per-file results.
      */
     undoLatestTurn(targets) {
-        // The turn being undone = the turnSeq shared by the targets (all from the
-        // same latest live turn). Created-only turns may have no snapshot targets, so
-        // fall back to the created markers' turn.
-        const undoneTurn = targets[0]?.turnSeq ?? this.latestLiveCreatedTurn();
-        if (undoneTurn === undefined)
+        return this.withCurrentIndex(() => this.undoLatestTurnUnlocked(targets));
+    }
+    undoLatestTurnUnlocked(targets) {
+        const plan = this.latestTurnUndoPlanInternal();
+        if (!plan)
             return [];
+        if (!this.isExactSnapshotSet(targets, plan.snapshots)) {
+            return plan.filePaths.map((filePath) => ({ filePath, ok: false }));
+        }
+        const undoneTurn = plan.turnKey;
         const results = [];
         // Files created this turn: delete them (after stashing redo material). Skip
         // files that are also a restore target — created wins (the file didn't exist
         // pre-turn, so its "pre-turn state" is "absent" → delete, not restore).
         const createdThisTurn = this.created.filter((c) => !c.undone && c.turnSeq === undoneTurn);
         const createdPaths = new Set(createdThisTurn.map((c) => c.filePath));
+        // Validate every destination against the location recorded BEFORE the
+        // creating/editing tool ran. Redo backups describe the current location,
+        // so comparing only against them is tautological and would miss a parent
+        // directory swapped to a symlink after the edit.
+        const safeToCapture = plan.filePaths.every((filePath) => {
+            if (!this.isSafeDestination(filePath))
+                return false;
+            const marker = createdThisTurn.find((candidate) => candidate.filePath === filePath);
+            const snapshot = plan.snapshots.find((candidate) => candidate.filePath === filePath);
+            const expectedRealPath = marker?.realPath ?? snapshot?.realPath;
+            if (!this.matchesRecordedLocation(filePath, expectedRealPath))
+                return false;
+            return !snapshot || this.isSafeBackup(snapshot.backupPath);
+        });
+        if (!safeToCapture) {
+            return plan.filePaths.map((filePath) => ({ filePath, ok: false }));
+        }
+        // Capture every post-turn state before mutating any file. A missing file is
+        // a legitimate post-turn state (delete), represented by an absence marker.
+        // If any capture fails, leave all working files untouched and keep the turn
+        // live so the user can retry.
+        const captured = plan.filePaths.map((filePath) => this.captureRedoBackup(filePath, undoneTurn, !createdPaths.has(filePath)));
+        if (captured.some((ok) => !ok)) {
+            this.discardRedoTurn(undoneTurn);
+            this.saveIndex();
+            return plan.filePaths.map((filePath) => ({ filePath, ok: false }));
+        }
+        const redoForTurn = new Map(this.redoRecords
+            .filter((record) => record.turnSeq === undoneTurn)
+            .map((record) => [record.filePath, record]));
+        const canApply = plan.filePaths.every((filePath) => {
+            const redo = redoForTurn.get(filePath);
+            if (!redo || !this.isSafeBackup(redo.backupPath))
+                return false;
+            if (!this.isSafeDestination(filePath))
+                return false;
+            if (!this.matchesRecordedLocation(filePath, redo.realPath))
+                return false;
+            const snapshot = plan.snapshots.find((candidate) => candidate.filePath === filePath);
+            return !snapshot || this.isSafeBackup(snapshot.backupPath);
+        });
+        if (!canApply) {
+            this.discardRedoTurn(undoneTurn);
+            this.saveIndex();
+            return plan.filePaths.map((filePath) => ({ filePath, ok: false }));
+        }
+        // Commit the complete recovery plan before touching working files. If the
+        // process crashes during a restore, the next load still has the original
+        // post-turn material and can safely retry the idempotent operation.
+        if (!this.saveIndex()) {
+            this.discardRedoTurn(undoneTurn);
+            return plan.filePaths.map((filePath) => ({ filePath, ok: false }));
+        }
         for (const c of createdThisTurn) {
-            this.captureRedoBackup(c.filePath, undoneTurn, false);
             let ok = true;
             try {
                 if (existsSync(c.filePath))
@@ -207,35 +400,37 @@ export class FileHistory {
         }
         // Modified (pre-existing) files: stash the current result as redo material,
         // then restore the pre-turn content.
-        for (const snap of targets) {
+        for (const snap of plan.snapshots) {
             if (createdPaths.has(snap.filePath))
                 continue;
-            this.captureRedoBackup(snap.filePath, undoneTurn, true);
-            results.push({ filePath: snap.filePath, ok: this.restore(snap) });
+            results.push({ filePath: snap.filePath, ok: this.restoreSnapshot(snap, false) });
+        }
+        if (results.some((result) => !result.ok)) {
+            this.saveIndex();
+            return results;
         }
         // Mark the turn undone (snapshots + created markers) — keep them on disk so
         // redo has material and the turn is re-applyable.
         for (const s of this.snapshots) {
-            if (s.turnSeq === undoneTurn)
+            if (this.turnKey(s.turnSeq) === undoneTurn)
                 s.undone = true;
         }
         for (const c of this.created) {
             if (c.turnSeq === undoneTurn)
                 c.undone = true;
         }
-        this.saveIndex();
-        return results;
-    }
-    /** Greatest turnSeq among not-yet-undone created markers, or undefined. */
-    latestLiveCreatedTurn() {
-        let max;
-        for (const c of this.created) {
-            if (c.undone)
-                continue;
-            if (max === undefined || c.turnSeq > max)
-                max = c.turnSeq;
+        if (!this.saveIndex()) {
+            for (const s of this.snapshots) {
+                if (this.turnKey(s.turnSeq) === undoneTurn)
+                    s.undone = false;
+            }
+            for (const c of this.created) {
+                if (c.turnSeq === undoneTurn)
+                    c.undone = false;
+            }
+            return results.map((result) => ({ ...result, ok: false }));
         }
-        return max;
+        return results;
     }
     /**
      * Turn-level redo: re-apply a previously undone turn. For each redo target,
@@ -247,14 +442,40 @@ export class FileHistory {
      * latest still-undone turn). Returns per-file results.
      */
     redoLatestTurn(redoTargets) {
+        return this.withCurrentIndex(() => this.redoLatestTurnUnlocked(redoTargets));
+    }
+    redoLatestTurnUnlocked(redoTargets) {
         if (redoTargets.length === 0)
             return [];
-        const turn = redoTargets[0].turnSeq;
-        const results = redoTargets.map((rec) => {
+        const expected = this.getLatestRedoRecords();
+        const authoritative = redoTargets.map((record) => this.findRedoRecord(record));
+        const expectedBackups = new Set(expected.map((record) => record.backupPath));
+        const suppliedBackups = new Set(authoritative.flatMap((record) => (record ? [record.backupPath] : [])));
+        const exactCurrentSet = authoritative.every((record) => record !== undefined) &&
+            suppliedBackups.size === authoritative.length &&
+            suppliedBackups.size === expectedBackups.size &&
+            [...suppliedBackups].every((backupPath) => expectedBackups.has(backupPath));
+        // Treat caller-provided records as untrusted values. Besides protecting the
+        // destination path, this prevents a stale preview from consuming a newer
+        // turn's only redo material.
+        if (!exactCurrentSet) {
+            return redoTargets.map((record) => ({ filePath: record.filePath, ok: false }));
+        }
+        const turn = authoritative[0].turnSeq;
+        const results = authoritative.map((rec) => {
             let ok = false;
             try {
-                if (existsSync(rec.backupPath)) {
-                    copyFileSync(rec.backupPath, rec.filePath);
+                if (this.isSafeBackup(rec.backupPath) &&
+                    this.isSafeDestination(rec.filePath) &&
+                    this.matchesRecordedLocation(rec.filePath, rec.realPath)) {
+                    if (rec.existedAfter === false) {
+                        if (existsSync(rec.filePath))
+                            rmSync(rec.filePath, { force: true });
+                    }
+                    else {
+                        copyFileSync(rec.backupPath, rec.filePath);
+                        this.restoreMode(rec.filePath, rec.mode);
+                    }
                     ok = true;
                 }
             }
@@ -263,31 +484,48 @@ export class FileHistory {
             }
             return { filePath: rec.filePath, ok };
         });
-        // Un-mark the turn: it is live again, so undo can re-target it.
+        // A partial filesystem failure must not consume redo history. Successful
+        // copies are safe to repeat when the user retries after fixing the failed
+        // path, while deleting the records here would make recovery impossible.
+        if (results.some((result) => !result.ok)) {
+            return results;
+        }
+        // Un-mark the turn and remove redo references in the index first. Backup
+        // files are deleted only after that commit succeeds; deleting them first
+        // creates a crash window where the durable index points at missing redo.
+        const previousRedoRecords = this.redoRecords;
         for (const s of this.snapshots) {
-            if (s.turnSeq === turn)
+            if (this.turnKey(s.turnSeq) === turn)
                 s.undone = false;
         }
         for (const c of this.created) {
             if (c.turnSeq === turn)
                 c.undone = false;
         }
-        // Consume the redo records for this turn (and remove their backups).
-        const consumed = new Set(redoTargets);
-        this.redoRecords = this.redoRecords.filter((r) => {
-            if (consumed.has(r) || r.turnSeq === turn) {
-                try {
-                    if (existsSync(r.backupPath))
-                        rmSync(r.backupPath, { force: true });
-                }
-                catch {
-                    // best-effort cleanup
-                }
-                return false;
+        const consumedBackups = new Set(authoritative.map((record) => record.backupPath));
+        const consumedRecords = this.redoRecords.filter((record) => consumedBackups.has(record.backupPath) || record.turnSeq === turn);
+        this.redoRecords = this.redoRecords.filter((record) => !consumedBackups.has(record.backupPath) && record.turnSeq !== turn);
+        if (!this.saveIndex()) {
+            for (const s of this.snapshots) {
+                if (this.turnKey(s.turnSeq) === turn)
+                    s.undone = true;
             }
-            return true;
-        });
-        this.saveIndex();
+            for (const c of this.created) {
+                if (c.turnSeq === turn)
+                    c.undone = true;
+            }
+            this.redoRecords = previousRedoRecords;
+            return results.map((result) => ({ ...result, ok: false }));
+        }
+        for (const record of consumedRecords) {
+            try {
+                if (this.isSafeBackup(record.backupPath))
+                    rmSync(record.backupPath, { force: true });
+            }
+            catch {
+                // The index no longer references this file; cleanup remains best effort.
+            }
+        }
         return results;
     }
     /**
@@ -296,7 +534,7 @@ export class FileHistory {
      * Returns a copy so callers can't mutate the internal list.
      */
     getAllSnapshots() {
-        return [...this.snapshots];
+        return this.snapshots.map((snapshot) => ({ ...snapshot }));
     }
     saveIndex() {
         try {
@@ -306,33 +544,302 @@ export class FileHistory {
                 redoRecords: this.redoRecords,
                 created: this.created,
             };
-            writeFileSync(indexPath, JSON.stringify(index, null, 2), "utf-8");
+            writeFileAtomic(indexPath, `${JSON.stringify(index, null, 2)}\n`, 0o600);
+            return true;
         }
         catch {
-            // Silent fail
+            return false;
         }
     }
     static loadFromDir(sessionDir) {
         const history = new FileHistory(sessionDir);
-        const indexPath = join(history.historyDir, "index.json");
+        history.reloadIndex(false);
+        return history;
+    }
+    /** Serialize every read-modify-write and refresh after taking the lock. */
+    withCurrentIndex(operation) {
+        if (this.lockDepth > 0)
+            return operation();
+        const indexPath = join(this.historyDir, "index.json");
+        const release = acquireFileLock(indexPath);
+        this.lockDepth = 1;
+        try {
+            this.reloadIndex(true);
+            return operation();
+        }
+        finally {
+            this.lockDepth = 0;
+            release();
+        }
+    }
+    reloadIndex(throwOnInvalid) {
+        const indexPath = join(this.historyDir, "index.json");
+        this.snapshots = [];
+        this.redoRecords = [];
+        this.created = [];
         if (existsSync(indexPath)) {
             try {
                 const parsed = JSON.parse(readFileSync(indexPath, "utf-8"));
                 if (Array.isArray(parsed)) {
                     // Legacy v1: bare FileSnapshot[]. No redo/created material existed yet.
-                    history.snapshots = parsed;
+                    this.snapshots = parsed.filter((value) => this.isSnapshot(value));
                 }
                 else {
                     const index = parsed;
-                    history.snapshots = index.snapshots ?? [];
-                    history.redoRecords = index.redoRecords ?? [];
-                    history.created = index.created ?? [];
+                    this.snapshots = Array.isArray(index.snapshots)
+                        ? index.snapshots.filter((value) => this.isSnapshot(value))
+                        : [];
+                    this.redoRecords = Array.isArray(index.redoRecords)
+                        ? index.redoRecords.filter((value) => this.isRedoRecord(value))
+                        : [];
+                    this.created = Array.isArray(index.created)
+                        ? index.created.filter(isCreatedMarker)
+                        : [];
                 }
             }
+            catch (err) {
+                if (throwOnInvalid)
+                    throw err;
+                // Read-only load keeps the historical recovery behavior. A later
+                // mutation reloads under lock and fails closed instead of overwriting
+                // the malformed index with an empty one.
+            }
+        }
+    }
+    isSafeBackup(backupPath) {
+        if (!this.isContainedBackupPath(backupPath))
+            return false;
+        try {
+            const info = lstatSync(backupPath);
+            return info.isFile() && !info.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
+    isContainedBackupPath(backupPath) {
+        if (typeof backupPath !== "string" || !isAbsolute(backupPath))
+            return false;
+        const rel = relative(this.historyDir, resolve(backupPath));
+        return Boolean(rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    }
+    /** Never follow a destination symlink while restoring an old file version. */
+    isSafeDestination(filePath) {
+        if (typeof filePath !== "string" || !isAbsolute(filePath))
+            return false;
+        if (!existsSync(filePath))
+            return true;
+        try {
+            const info = lstatSync(filePath);
+            return info.isFile() && !info.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
+    canonicalizeNewPath(filePath) {
+        const absPath = resolve(filePath);
+        let candidate = absPath;
+        const missingSegments = [];
+        for (let depth = 0; depth < 256; depth += 1) {
+            try {
+                return join(realpathSync(candidate), ...missingSegments.reverse());
+            }
             catch {
-                // Start fresh
+                const parent = dirname(candidate);
+                if (parent === candidate)
+                    return undefined;
+                missingSegments.push(basename(candidate));
+                candidate = parent;
             }
         }
-        return history;
+        return undefined;
+    }
+    matchesRecordedLocation(filePath, realPath) {
+        if (!realPath)
+            return true; // Legacy index written before canonical metadata.
+        try {
+            const current = existsSync(filePath) ? realpathSync(filePath) : this.canonicalizeNewPath(filePath);
+            return current === realPath;
+        }
+        catch {
+            return false;
+        }
+    }
+    restoreSnapshot(snapshot, saveCurrent) {
+        try {
+            if (!this.isSafeBackup(snapshot.backupPath))
+                return false;
+            if (!this.isSafeDestination(snapshot.filePath))
+                return false;
+            if (!this.matchesRecordedLocation(snapshot.filePath, snapshot.realPath))
+                return false;
+            const currentMode = this.readMode(snapshot.filePath);
+            if (saveCurrent && existsSync(snapshot.filePath) && !this.saveSnapshot(snapshot.filePath)) {
+                return false;
+            }
+            copyFileSync(snapshot.backupPath, snapshot.filePath);
+            this.restoreMode(snapshot.filePath, snapshot.mode ?? currentMode);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
+    readMode(filePath) {
+        if (process.platform === "win32" || !existsSync(filePath))
+            return undefined;
+        try {
+            return lstatSync(filePath).mode & 0o7777;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    restoreMode(filePath, mode) {
+        if (process.platform === "win32" || mode === undefined)
+            return;
+        chmodSync(filePath, mode);
+    }
+    discardRedoTurn(turnSeq) {
+        this.redoRecords = this.redoRecords.filter((record) => {
+            if (record.turnSeq !== turnSeq)
+                return true;
+            try {
+                if (this.isSafeBackup(record.backupPath))
+                    rmSync(record.backupPath, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; dropping the index reference is the safety boundary.
+            }
+            return false;
+        });
+    }
+    turnKey(turnSeq) {
+        return turnSeq ?? LEGACY_TURN;
+    }
+    latestTurnUndoPlanInternal() {
+        let latest = -Infinity;
+        let found = false;
+        for (const snapshot of this.snapshots) {
+            if (snapshot.undone)
+                continue;
+            latest = Math.max(latest, this.turnKey(snapshot.turnSeq));
+            found = true;
+        }
+        for (const marker of this.created) {
+            if (marker.undone)
+                continue;
+            latest = Math.max(latest, marker.turnSeq);
+            found = true;
+        }
+        if (!found)
+            return null;
+        const earliest = new Map();
+        for (const snapshot of this.snapshots) {
+            if (snapshot.undone || this.turnKey(snapshot.turnSeq) !== latest)
+                continue;
+            const current = earliest.get(snapshot.filePath);
+            if (!current || snapshot.timestamp < current.timestamp) {
+                earliest.set(snapshot.filePath, snapshot);
+            }
+        }
+        const snapshots = [...earliest.values()].sort((a, b) => a.timestamp - b.timestamp);
+        const createdPaths = this.created
+            .filter((marker) => !marker.undone && marker.turnSeq === latest)
+            .map((marker) => marker.filePath);
+        const filePaths = [...new Set([...createdPaths, ...snapshots.map((item) => item.filePath)])];
+        return {
+            turnKey: latest,
+            ...(latest === LEGACY_TURN ? {} : { turnSeq: latest }),
+            snapshots,
+            createdPaths,
+            filePaths,
+        };
+    }
+    isExactSnapshotSet(candidates, expected) {
+        if (candidates.length !== expected.length)
+            return false;
+        const remaining = [...expected];
+        for (const candidate of candidates) {
+            const index = remaining.findIndex((snapshot) => this.sameSnapshot(snapshot, candidate));
+            if (index < 0)
+                return false;
+            remaining.splice(index, 1);
+        }
+        return remaining.length === 0;
+    }
+    sameSnapshot(a, b) {
+        return (a.filePath === b.filePath &&
+            a.timestamp === b.timestamp &&
+            a.backupPath === b.backupPath &&
+            a.hash === b.hash &&
+            a.size === b.size &&
+            a.turnSeq === b.turnSeq &&
+            a.undone === b.undone);
+    }
+    findSnapshot(candidate) {
+        return this.snapshots.find((snapshot) => this.sameSnapshot(snapshot, candidate));
+    }
+    findRedoRecord(candidate) {
+        return this.redoRecords.find((record) => record.filePath === candidate.filePath &&
+            record.turnSeq === candidate.turnSeq &&
+            record.backupPath === candidate.backupPath &&
+            record.existedBefore === candidate.existedBefore &&
+            record.existedAfter === candidate.existedAfter);
+    }
+    isSnapshot(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        const snapshot = value;
+        return (typeof snapshot.filePath === "string" &&
+            isAbsolute(snapshot.filePath) &&
+            typeof snapshot.timestamp === "number" &&
+            Number.isFinite(snapshot.timestamp) &&
+            typeof snapshot.hash === "string" &&
+            typeof snapshot.size === "number" &&
+            Number.isFinite(snapshot.size) &&
+            (snapshot.mode === undefined || isFileMode(snapshot.mode)) &&
+            (snapshot.realPath === undefined ||
+                (typeof snapshot.realPath === "string" && isAbsolute(snapshot.realPath))) &&
+            (snapshot.turnSeq === undefined || isFiniteTurn(snapshot.turnSeq)) &&
+            (snapshot.undone === undefined || typeof snapshot.undone === "boolean") &&
+            this.isSafeBackup(snapshot.backupPath));
+    }
+    isRedoRecord(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        const record = value;
+        return (typeof record.filePath === "string" &&
+            isAbsolute(record.filePath) &&
+            typeof record.turnSeq === "number" &&
+            isHistoryTurn(record.turnSeq) &&
+            typeof record.existedBefore === "boolean" &&
+            (record.existedAfter === undefined || typeof record.existedAfter === "boolean") &&
+            (record.mode === undefined || isFileMode(record.mode)) &&
+            (record.realPath === undefined ||
+                (typeof record.realPath === "string" && isAbsolute(record.realPath))) &&
+            this.isContainedBackupPath(record.backupPath));
+    }
+}
+function isCreatedMarker(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const marker = value;
+    return (typeof marker.filePath === "string" &&
+        isAbsolute(marker.filePath) &&
+        typeof marker.turnSeq === "number" &&
+        isFiniteTurn(marker.turnSeq) &&
+        (marker.realPath === undefined ||
+            (typeof marker.realPath === "string" && isAbsolute(marker.realPath))) &&
+        (marker.undone === undefined || typeof marker.undone === "boolean"));
+}
+function isFiniteTurn(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isHistoryTurn(value) {
+    return value === LEGACY_TURN || isFiniteTurn(value);
+}
+function isFileMode(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0o7777;
 }