@rljson/fs-agent 0.0.12 → 0.0.15

package/dist/fs-agent.js

@@ -1,8 +1,8 @@
 import { BsMem } from "@rljson/bs";
 import { Route, createTreesTableCfg } from "@rljson/rljson";
 import { watch, appendFileSync } from "fs";
-import { stat, readFile, mkdir, writeFile, readdir, utimes, rm } from "fs/promises";
-import { dirname, join, sep } from "path";
+import { stat, readFile, mkdir, writeFile, readdir, rename, unlink, utimes, rm } from "fs/promises";
+import { dirname, join } from "path";
 import { hip } from "@rljson/hash";
 import { Db } from "@rljson/db";
 import { IoMem, createSocketPair } from "@rljson/io";
@@ -112,6 +112,248 @@ class FsBlobAdapter {
     return new FsBlobAdapter();
   }
 }
+const DIR_MARKER = "<dir>";
+function fsTreeToContentMap(tree) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [, node] of tree.trees) {
+    const meta = node.meta;
+    if (meta?.type === "file") {
+      map.set(
+        meta.relativePath,
+        meta.blobId ?? ""
+      );
+    } else if (meta?.type === "directory" && meta.relativePath !== ".") {
+      map.set(meta.relativePath, DIR_MARKER);
+    }
+  }
+  return map;
+}
+function compareTips(a, b) {
+  if (a.timestamp !== b.timestamp) {
+    return a.timestamp - b.timestamp;
+  }
+  if (a.clientId !== b.clientId) {
+    return a.clientId > b.clientId ? 1 : -1;
+  }
+  if (a.ref !== b.ref) {
+    return a.ref > b.ref ? 1 : -1;
+  }
+  return 0;
+}
+function decideWinner(a, b) {
+  return compareTips(a, b) >= 0 ? { winner: a, loser: b } : { winner: b, loser: a };
+}
+function findCommonAncestor(rows, tipA, tipB) {
+  const prevOf = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    prevOf.set(row.timeId, row.previous ?? []);
+  }
+  const ancestorsOfA = /* @__PURE__ */ new Set();
+  const stack = [tipA];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (ancestorsOfA.has(id)) {
+      continue;
+    }
+    ancestorsOfA.add(id);
+    for (const p of prevOf.get(id) ?? []) {
+      stack.push(p);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  let frontier = [tipB];
+  while (frontier.length > 0) {
+    const next = [];
+    for (const id of frontier) {
+      if (ancestorsOfA.has(id)) {
+        return id;
+      }
+      if (visited.has(id)) {
+        continue;
+      }
+      visited.add(id);
+      for (const p of prevOf.get(id) ?? []) {
+        next.push(p);
+      }
+    }
+    frontier = next;
+  }
+  return null;
+}
+function formatConflictTimestamp(ms) {
+  const d = new Date(ms);
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  const date = `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}`;
+  const time = `${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`;
+  return `${date} ${time}`;
+}
+function conflictCopyName(relativePath, clientId, timestamp, taken) {
+  const slash = relativePath.lastIndexOf("/");
+  const dir = slash >= 0 ? relativePath.slice(0, slash + 1) : "";
+  const base = slash >= 0 ? relativePath.slice(slash + 1) : relativePath;
+  const dot = base.lastIndexOf(".");
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  const ext = dot > 0 ? base.slice(dot) : "";
+  const ts = formatConflictTimestamp(timestamp);
+  const marker = `(conflicted copy ${clientId} ${ts})`;
+  let candidate = `${dir}${stem} ${marker}${ext}`;
+  let n = 1;
+  while (taken.has(candidate)) {
+    candidate = `${dir}${stem} ${marker} (${n})${ext}`;
+    n++;
+  }
+  taken.add(candidate);
+  return candidate;
+}
+function threeWayMerge(o, ours, theirs, winnerSide, loserClientId, loserTimestamp) {
+  const merged = /* @__PURE__ */ new Map();
+  const copies = [];
+  const conflictPaths = [];
+  const taken = /* @__PURE__ */ new Set([...o.keys(), ...ours.keys(), ...theirs.keys()]);
+  const allPaths = new Set(taken);
+  for (const path of [...allPaths].sort()) {
+    const a = o.get(path);
+    const b = ours.get(path);
+    const c = theirs.get(path);
+    if (b === c) {
+      if (b !== void 0) {
+        merged.set(path, b);
+      }
+      continue;
+    }
+    if (b === a) {
+      if (c !== void 0) {
+        merged.set(path, c);
+      }
+      continue;
+    }
+    if (c === a) {
+      if (b !== void 0) {
+        merged.set(path, b);
+      }
+      continue;
+    }
+    conflictPaths.push(path);
+    const winnerVal = winnerSide === "ours" ? b : c;
+    const loserVal = winnerSide === "ours" ? c : b;
+    if (winnerVal !== void 0) {
+      merged.set(path, winnerVal);
+    }
+    if (loserVal !== void 0 && loserVal !== DIR_MARKER) {
+      const copyPath = conflictCopyName(
+        path,
+        loserClientId,
+        loserTimestamp,
+        taken
+      );
+      copies.push({ path: copyPath, blobId: loserVal });
+    }
+  }
+  return { merged, copies, conflictPaths };
+}
+class FsConflictResolver {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  _log(level, msg) {
+    this.deps.log?.(level, `[FsConflictResolver] ${msg}`);
+  }
+  /**
+   * Resolves the conflict, returning the stored merge ref, or null when the
+   * conflict is not ours / not actionable.
+   * @param conflict - The detected DAG-branch conflict
+   * @returns The stored merge revision's root ref, or null
+   */
+  async resolve(conflict) {
+    const { treeKey } = this.deps;
+    if (conflict.table !== treeKey) {
+      return null;
+    }
+    const tips = conflict.branches ?? [];
+    if (tips.length < 2) {
+      return null;
+    }
+    const rows = await this.deps.getInsertHistory(treeKey);
+    const rowByTimeId = new Map(
+      rows.map((r) => [r.timeId, r])
+    );
+    const branchTips = [];
+    for (const timeId of tips) {
+      const row = rowByTimeId.get(timeId);
+      const ref2 = await this.deps.getRefOfTimeId(treeKey, timeId);
+      branchTips.push({
+        timeId,
+        ref: ref2 ?? "",
+        clientId: row?.origin ?? "",
+        timestamp: row?.clientTimestamp ?? 0
+      });
+    }
+    const ordered = [...branchTips].sort((x, y) => compareTips(x, y));
+    const loserTip = ordered[0];
+    const winnerTip = ordered[1];
+    if (!loserTip.ref || !winnerTip.ref) {
+      this._log(
+        "warn",
+        `missing tree ref for a tip (loser=${loserTip.ref}, winner=${winnerTip.ref})`
+      );
+      return null;
+    }
+    const loserTipId = loserTip.timeId;
+    const winnerTipId = winnerTip.timeId;
+    const loserTree = await this.deps.fetchTree(loserTip.ref);
+    const winnerTree = await this.deps.fetchTree(winnerTip.ref);
+    const loserMap = fsTreeToContentMap(loserTree);
+    const winnerMap = fsTreeToContentMap(winnerTree);
+    const ancestorTimeId = findCommonAncestor(rows, loserTipId, winnerTipId);
+    let ancestorMap = /* @__PURE__ */ new Map();
+    if (ancestorTimeId) {
+      const ancRef = await this.deps.getRefOfTimeId(treeKey, ancestorTimeId);
+      if (ancRef) {
+        ancestorMap = fsTreeToContentMap(await this.deps.fetchTree(ancRef));
+      }
+    }
+    const plan = threeWayMerge(
+      ancestorMap,
+      loserMap,
+      winnerMap,
+      "theirs",
+      loserTip.clientId,
+      loserTip.timestamp
+    );
+    await this.deps.restoreTree(winnerTree);
+    for (const [path, blobId] of plan.merged) {
+      if (blobId === DIR_MARKER) {
+        continue;
+      }
+      if (winnerMap.get(path) === blobId) {
+        continue;
+      }
+      await this.deps.writeFileAt(path, await this.deps.getBlobContent(blobId));
+    }
+    for (const [path, blobId] of winnerMap) {
+      if (blobId === DIR_MARKER) {
+        continue;
+      }
+      if (!plan.merged.has(path)) {
+        await this.deps.deleteFileAt(path);
+      }
+    }
+    for (const copy of plan.copies) {
+      await this.deps.writeFileAt(
+        copy.path,
+        await this.deps.getBlobContent(copy.blobId)
+      );
+    }
+    const mergedTree = await this.deps.scan();
+    const ref = await this.deps.storeMerge(mergedTree, [loserTipId, winnerTipId]);
+    this.deps.onMergeStored?.(ref);
+    this._log(
+      "info",
+      `resolved fork ${loserTipId.slice(0, 6)}…/${winnerTipId.slice(0, 6)}… → ${ref.slice(0, 8)}… (${plan.conflictPaths.length} conflict(s), ${plan.copies.length} copy/ies)`
+    );
+    return ref;
+  }
+}
 class FsDbAdapter {
   constructor(db, treeKey) {
     this.db = db;
@@ -153,7 +395,8 @@ class FsDbAdapter {
     );
     trees.push(rootTree);
     const results = await this.db.insertTrees(this.treeKey, trees, {
-      skipNotification: options.skipNotification
+      skipNotification: options.skipNotification,
+      previous: options.previous
     });
     return results[0][`${this.treeKey}Ref`];
   }
@@ -179,6 +422,10 @@ class FsScanner {
   _bs;
   _paused = false;
   _missedChangesDuringPause = false;
+  /** Periodic full-rescan timer that catches events the native watcher drops. */
+  _safetyTimer = null;
+  /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
+  _stopRequested = false;
   constructor(rootPath, options = {}) {
     this._rootPath = rootPath;
     this._options = {
@@ -240,7 +487,6 @@ class FsScanner {
     return this._tree;
   }
   async _scanDirectory(absolutePath, relativePath, depth, trees) {
-    const stats = await stat(absolutePath);
     const entries = await readdir(absolutePath, { withFileTypes: true });
     const childRefs = [];
     for (const entry of entries) {
@@ -292,9 +538,12 @@ class FsScanner {
         const fileMeta = {
           name: entry.name,
           type: "file",
-          path: childPath,
           relativePath: childRelPath,
           size: childStats.size,
+          // mtime is kept for files (restore preserves it, so it round-trips to
+          // the same ref on every client) but NOT for directories (a folder's
+          // mtime is per-machine and does not round-trip). The absolute `path`
+          // is excluded everywhere — it is folder-specific.
           mtime: childStats.mtime.getTime(),
           blobId: blobProps.blobId
           // Link to content in Bs
@@ -311,19 +560,14 @@ class FsScanner {
         childRefs.push(fileTreeHashStr);
       }
     }
-    const dirName = relativePath === "." ? (
-      /* v8 ignore next -- @preserve */
-      this._rootPath.split(sep).pop() || ""
-    ) : (
+    const dirName = relativePath === "." ? "." : (
       /* v8 ignore next -- @preserve */
       relativePath.split("/").pop() || ""
     );
     const dirMeta = {
       name: dirName,
       type: "directory",
-      path: absolutePath,
-      relativePath,
-      mtime: stats.mtime.getTime()
+      relativePath
     };
     const dirTree = {
       id: dirName,
@@ -351,18 +595,102 @@ class FsScanner {
     if (!this._tree) {
       await this.scan();
     }
-    this._watcher = watch(
-      this._rootPath,
-      { recursive: true },
-      /* v8 ignore next -- @preserve */
-      async (eventType, filename) => {
-        if (!filename) return;
-        if (this._shouldIgnore(filename)) {
-          return;
+    const onEvent = async (eventType, filename) => {
+      if (!filename) return;
+      if (this._shouldIgnore(filename)) {
+        return;
+      }
+      await this._handleFileChange(eventType, filename);
+    };
+    const onError = (err) => {
+      console.warn(
+        `[fs-scanner] watcher error: ${FsScanner._errMessage(err)} — reinstalling`
+      );
+      try {
+        this._watcher?.close();
+      } catch {
+      }
+      this._watcher = null;
+      setTimeout(() => {
+        if (this._stopRequested) return;
+        try {
+          this._watcher = watch(this._rootPath, { recursive: true }, onEvent);
+          if (FsScanner._isWindows) this._watcher.on("error", onError);
+        } catch (e) {
+          console.warn(
+            `[fs-scanner] watcher reinstall failed: ${FsScanner._errMessage(e)}`
+          );
         }
-        await this._handleFileChange(eventType, filename);
+      }, 500);
+    };
+    this._stopRequested = false;
+    this._watcher = watch(this._rootPath, { recursive: true }, onEvent);
+    if (FsScanner._isWindows) this._watcher.on("error", onError);
+    if (!this._safetyTimer) {
+      this._safetyTimer = setInterval(() => {
+        void this._runSafetyRescan();
+      }, 3e4);
+      this._safetyTimer.unref?.();
+    }
+  }
+  /**
+   * One safety-rescan pass: rescans the tree and, if its content differs from
+   * the previous scan (the native watcher dropped an event), emits a sync
+   * notification so syncToDb reconciles the drift. Paused/stopped scanners and
+   * scan failures are no-ops.
+   */
+  async _runSafetyRescan() {
+    if (this._paused || this._stopRequested) return;
+    const prevKey = this._tree ? this._safetyContentKey(this._tree) : null;
+    try {
+      await this.scan();
+    } catch (err) {
+      console.warn(
+        `[fs-scanner] safety rescan failed: ${FsScanner._errMessage(err)}`
+      );
+      return;
+    }
+    if (this._paused || this._stopRequested) return;
+    const nextKey = this._tree ? this._safetyContentKey(this._tree) : null;
+    if (prevKey !== nextKey) {
+      console.warn(
+        `[fs-scanner] safety rescan detected drift on ${this._rootPath} — notifying`
+      );
+      await this._notifyChange({ type: "safety-rescan", path: "." });
+    }
+  }
+  /**
+   * Path+blobId content fingerprint used by the safety rescan to detect drift
+   * the native watcher missed (mtime-independent, same idea as the agent's
+   * content key but local to the scanner).
+   * @param tree - The tree to fingerprint
+   * @returns A stable content key
+   */
+  _safetyContentKey(tree) {
+    const parts = [];
+    for (const [, node] of tree.trees) {
+      const meta = node.meta;
+      if (!meta) continue;
+      if (meta.type === "file") {
+        parts.push(`${meta.relativePath}:${meta.blobId ?? ""}`);
+      } else if (meta.type === "directory" && meta.relativePath !== ".") {
+        parts.push(`d:${meta.relativePath}`);
       }
-    );
+    }
+    parts.sort();
+    return parts.join("\n");
+  }
+  /**
+   * Extracts a readable message from a thrown value.
+   * @param err - The caught value
+   * @returns A message string
+   */
+  static _errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  /** Whether the host is Windows — gates Windows-specific watcher hardening. */
+  static get _isWindows() {
+    return process.platform === "win32";
   }
   async _handleFileChange(_eventType, filename) {
     if (this._paused) {
@@ -370,23 +698,35 @@ class FsScanner {
       return;
     }
     const relativePath = filename.replace(/\\/g, "/");
+    const fullPath = join(this._rootPath, filename);
+    let exists = false;
+    if (FsScanner._isWindows) {
+      for (let i = 0; i < 4; i++) {
+        try {
+          await stat(fullPath);
+          exists = true;
+          break;
+        } catch {
+          if (i < 3) await new Promise((r) => setTimeout(r, 80 + i * 80));
+        }
+      }
+    } else {
+      try {
+        await stat(fullPath);
+        exists = true;
+      } catch {
+      }
+    }
     try {
-      await stat(join(this._rootPath, filename));
-      const existingTree = this._findTreeByPath(relativePath);
-      if (!existingTree) {
-        await this.scan();
-        await this._notifyChange({
-          type: "added",
-          path: relativePath
-        });
-      } else {
+      if (exists) {
+        const existingTree = this._findTreeByPath(relativePath);
         await this.scan();
         await this._notifyChange({
-          type: "modified",
+          type: existingTree ? "modified" : "added",
           path: relativePath
         });
+        return;
       }
-    } catch {
       let rootExists = false;
       try {
         await stat(this._rootPath);
@@ -395,15 +735,10 @@ class FsScanner {
         this.stopWatch();
       }
       if (rootExists) {
-        try {
-          await this.scan();
-          await this._notifyChange({
-            type: "deleted",
-            path: relativePath
-          });
-        } catch {
-        }
+        await this.scan();
+        await this._notifyChange({ type: "deleted", path: relativePath });
       }
+    } catch {
     }
   }
   _findTreeByPath(relativePath) {
@@ -433,6 +768,11 @@ class FsScanner {
     );
   }
   stopWatch() {
+    this._stopRequested = true;
+    if (this._safetyTimer) {
+      clearInterval(this._safetyTimer);
+      this._safetyTimer = null;
+    }
     if (this._watcher) {
       this._watcher.close();
       this._watcher = null;
@@ -510,9 +850,11 @@ const DEFAULT_TIMEOUTS = {
   syncCallback: 25e3,
   debounceMs: 300,
   processRefRetries: 3,
-  processRefRetryDelayMs: 5e3
+  processRefRetryDelayMs: 5e3,
+  recoveryRetries: 10
 };
 const SYNC_ERROR_FILE = ".sync-errors.log";
+const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 class FsAgent {
   _scanner;
   _adapter;
@@ -526,15 +868,25 @@ class FsAgent {
   /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
   _lastSentContentKey;
   _timeouts;
+  /** Client-only: resolve DAG-branch conflicts into merge revisions. */
+  _resolveConflicts;
+  /**
+   * Ancestry head: the content ref of the revision currently representing the
+   * filesystem state. New local revisions descend from it; received revisions
+   * advance it. Only tracked when `resolveConflicts` is enabled, so the
+   * InsertHistory predecessor DAG forms only where conflict resolution is on.
+   */
+  _currentRef;
   constructor(rootPath, bs, options = {}) {
     this._rootPath = rootPath;
     this._bs = bs || new BsMem();
     this._db = options.db;
     this._treeKey = options.treeKey;
     this._timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
+    this._resolveConflicts = options.resolveConflicts ?? false;
     this._scanner = new FsScanner(rootPath, {
       ...options,
-      ignore: [...options.ignore || [], SYNC_ERROR_FILE],
+      ignore: [...options.ignore || [], SYNC_ERROR_FILE, ATOMIC_TMP_PREFIX],
       bs: this._bs
     });
     this._adapter = new FsBlobAdapter(this._bs);
@@ -592,6 +944,77 @@ ${err.stack}` : String(err);
     } catch {
     }
   }
+  /**
+   * Extracts a human-readable message from a thrown value. The non-`Error`
+   * branch is defensive (the DB/transport always throw `Error`s).
+   * @param err - The caught value.
+   * @returns A message string.
+   */
+  static _errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  /**
+   * Retries an async operation up to `attempts` times with exponential backoff
+   * (each delay doubles from `baseDelayMs`). For transient failures — a file
+   * briefly locked by antivirus or a save-and-rename editor, a peer briefly
+   * unreachable. Non-final failures are logged once at warn level so retry
+   * pressure is visible without log-spam.
+   * @param fn - The operation to run
+   * @param attempts - Maximum number of attempts
+   * @param baseDelayMs - Initial backoff delay (doubles each retry)
+   * @param label - Human-readable label for log messages
+   * @returns The operation's resolved value
+   */
+  static async _withRetry(fn, attempts, baseDelayMs, label) {
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastErr = err;
+        if (i === attempts - 1) {
+          break;
+        }
+        const delay = baseDelayMs * Math.pow(2, i);
+        console.warn(
+          `[FsAgent] ${label} attempt ${i + 1}/${attempts} failed: ${FsAgent._errMessage(err)} — retry in ${delay}ms`
+        );
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+    throw lastErr;
+  }
+  /**
+   * Atomically writes a file: stages the content in a sibling `.<rand>.tmp`,
+   * then renames over the target. The rename is atomic, so a crash mid-write
+   * leaves only the temp behind — never a half-written target file. (We do not
+   * `fsync` the temp: it adds significant per-file latency under bursty
+   * restores, and durability-on-power-loss is secondary here since the content
+   * is replicated and re-synced.) The random suffix keeps concurrent restores
+   * of the same path from trampling each other.
+   * @param filePath - Destination path
+   * @param content - Bytes to write
+   */
+  static async _atomicWriteFile(filePath, content) {
+    if (process.platform !== "win32") {
+      await writeFile(filePath, content);
+      return;
+    }
+    const rnd = `${Date.now().toString(36)}-${Math.floor(
+      Math.random() * 1e9
+    ).toString(36)}`;
+    const tmp = join(dirname(filePath), `${ATOMIC_TMP_PREFIX}${rnd}`);
+    try {
+      await writeFile(tmp, content);
+      await rename(tmp, filePath);
+    } catch (err) {
+      try {
+        await unlink(tmp);
+      } catch {
+      }
+      throw err;
+    }
+  }
   /**
    * Wraps a promise with a timeout.
    * Rejects with a descriptive error if the promise does not settle
@@ -623,13 +1046,26 @@ ${err.stack}` : String(err);
    * otherwise falls back to fire-and-forget `send()`.
    * @param connector - The Connector to send through
    * @param ref - The ref to broadcast
+   * @param predecessorRefs - Causal predecessor content refs to attach (for
+   *   conflict ancestry); set explicitly here because the FsAgent broadcasts
+   *   via an explicit send, which pre-empts the Connector's db-observer path.
    */
-  async _sendRef(connector, ref) {
-    if (connector.syncConfig?.requireAck) {
-      await connector.sendWithAck(ref);
-    } else {
-      connector.send(ref);
+  async _sendRef(connector, ref, predecessorRefs) {
+    if (this._resolveConflicts) {
+      connector.setPredecessors(predecessorRefs ?? []);
     }
+    await FsAgent._withRetry(
+      async () => {
+        if (connector.syncConfig?.requireAck) {
+          await connector.sendWithAck(ref);
+        } else {
+          connector.send(ref);
+        }
+      },
+      3,
+      100,
+      `sendRef(${ref.slice(0, 12)}…)`
+    );
   }
   /**
    * Starts automatic syncing to database
@@ -692,10 +1128,41 @@ ${err.stack}` : String(err);
       tree,
       target
     );
+    const preRestore = options?.cleanTarget ? await this._collectAllFiles(target) : /* @__PURE__ */ new Set();
     await this._restoreTree(tree.rootHash, tree.trees, target);
     if (options?.cleanTarget) {
-      await this._pruneExtraneous(target, expectedDirs, expectedFiles);
+      await this._pruneExtraneous(
+        target,
+        expectedDirs,
+        expectedFiles,
+        preRestore
+      );
+    }
+  }
+  /**
+   * Recursively collects the absolute paths of all files under `currentDir`.
+   * Used to snapshot the pre-restore file set for prune race-protection.
+   * @param currentDir - Directory to walk
+   * @param out - Accumulator set (created if omitted)
+   * @returns The set of absolute file paths
+   */
+  async _collectAllFiles(currentDir, out) {
+    const result = out ?? /* @__PURE__ */ new Set();
+    let entries;
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return result;
+    }
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await this._collectAllFiles(fullPath, result);
+      } else {
+        result.add(fullPath);
+      }
     }
+    return result;
   }
   /**
    * Recursively restores a tree node and its children
@@ -729,7 +1196,7 @@ ${err.stack}` : String(err);
           );
         }
         await mkdir(dirname(filePath), { recursive: true });
-        await writeFile(filePath, fileBlob.content);
+        await FsAgent._atomicWriteFile(filePath, fileBlob.content);
         if (meta.mtime) {
           const mtime = new Date(meta.mtime);
           await utimes(filePath, mtime, mtime);
@@ -923,25 +1390,38 @@ ${err.stack}` : String(err);
     return { expectedDirs, expectedFiles };
   }
   /**
-   * Remove files/dirs not present in the expected sets
+   * Remove files/dirs not present in the expected sets, preserving any file
+   * that appeared *during* the restore (not in `preRestore`) — a fresh user
+   * write that must not be clobbered.
    * @param currentDir - Directory currently being inspected
    * @param expectedDirs - Allowed directory paths
    * @param expectedFiles - Allowed file paths
+   * @param preRestore - Files present before the restore (prune candidates)
    */
-  async _pruneExtraneous(currentDir, expectedDirs, expectedFiles) {
-    const entries = await readdir(currentDir, { withFileTypes: true });
+  async _pruneExtraneous(currentDir, expectedDirs, expectedFiles, preRestore) {
+    let entries;
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
     for (const entry of entries) {
       const fullPath = join(currentDir, entry.name);
       if (entry.isDirectory()) {
+        await this._pruneExtraneous(
+          fullPath,
+          expectedDirs,
+          expectedFiles,
+          preRestore
+        );
         if (!expectedDirs.has(fullPath)) {
-          await rm(fullPath, { recursive: true, force: true });
-          continue;
-        }
-        await this._pruneExtraneous(fullPath, expectedDirs, expectedFiles);
-      } else {
-        if (!expectedFiles.has(fullPath)) {
-          await rm(fullPath, { force: true });
+          const remaining = await readdir(fullPath);
+          if (remaining.length === 0) {
+            await rm(fullPath, { recursive: true, force: true });
+          }
         }
+      } else if (!expectedFiles.has(fullPath) && preRestore.has(fullPath)) {
+        await rm(fullPath, { force: true });
       }
     }
   }
@@ -955,18 +1435,31 @@ ${err.stack}` : String(err);
    * @returns Function to stop watching
    */
   async syncToDb(db, connector, treeKey, options) {
+    const initialParentRef = this._currentRef;
+    const initialTree = await FsAgent._withTimeout(
+      this.extract(),
+      this._timeouts.extract,
+      `syncToDb → initial extract(${treeKey})`
+    );
+    const initialIsNew = initialParentRef !== void 0 && initialTree.rootHash !== initialParentRef;
+    const initialPrevious = initialIsNew ? await this._ancestryPrevious(db, treeKey, [initialParentRef]) : void 0;
     const initialRef = await FsAgent._withTimeout(
-      this.storeInDb(db, treeKey, options),
+      new FsDbAdapter(db, treeKey).storeFsTree(initialTree, {
+        ...options,
+        previous: initialPrevious
+      }),
       this._timeouts.fetchTree,
-      `syncToDb → initial storeInDb(${treeKey})`
+      `syncToDb → initial storeFsTree(${treeKey})`
     );
     if (initialRef) {
       this._lastSentRef = initialRef;
-      const currentTree = this._scanner.tree;
-      if (currentTree) {
-        this._lastSentContentKey = this._contentKeyFromTree(currentTree);
-      }
-      await this._sendRef(connector, initialRef);
+      this._currentRef = initialRef;
+      this._lastSentContentKey = this._contentKeyFromTree(initialTree);
+      await this._sendRef(
+        connector,
+        initialRef,
+        initialIsNew ? [initialParentRef] : void 0
+      );
     }
     let debounceTimer = null;
     const debouncedSync = () => {
@@ -981,18 +1474,34 @@ ${err.stack}` : String(err);
               return;
             }
             const dbAdapter = new FsDbAdapter(db, treeKey);
-            const ref = await FsAgent._withTimeout(
-              dbAdapter.storeFsTree(tree, options),
-              this._timeouts.fetchTree,
-              `syncToDb → storeFsTree(${treeKey})`
+            const parentRef = this._currentRef;
+            const previous = await this._ancestryPrevious(
+              db,
+              treeKey,
+              parentRef ? [parentRef] : void 0
+            );
+            const ref = await FsAgent._withRetry(
+              () => FsAgent._withTimeout(
+                dbAdapter.storeFsTree(tree, { ...options, previous }),
+                this._timeouts.fetchTree,
+                `syncToDb → storeFsTree(${treeKey})`
+              ),
+              3,
+              200,
+              `syncToDb storeFsTree(${treeKey})`
             );
+            this._currentRef = ref;
             if (ref === this._lastSentRef) {
               return;
             }
             this._lastSentRef = ref;
             this._lastSentContentKey = contentKey;
             if (ref) {
-              await this._sendRef(connector, ref);
+              await this._sendRef(
+                connector,
+                ref,
+                parentRef ? [parentRef] : void 0
+              );
             }
           } catch (err) {
             console.error("[FsAgent] syncToDb failed:", err);
@@ -1009,6 +1518,110 @@ ${err.stack}` : String(err);
       this._scanner.stopWatch();
     };
   }
+  /**
+   * Resolves the `previous` (InsertHistory predecessor timeIds) for a new
+   * revision from the parent's shared content refs. timeIds are per-db, so we
+   * map each shared parent ref to *this* db's local timeId(s). Returns undefined
+   * when ancestry tracking is off (default) or no parent is known — in which
+   * case the store behaves exactly as before.
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   * @param parentRefs - Parent content refs (local head, or received predecessors)
+   */
+  async _ancestryPrevious(db, treeKey, parentRefs) {
+    if (!this._resolveConflicts || !parentRefs || parentRefs.length === 0) {
+      return void 0;
+    }
+    const timeIds = [];
+    for (const ref of parentRefs) {
+      timeIds.push(...await db.getTimeIdsForRef(treeKey, ref));
+    }
+    return timeIds.length > 0 ? timeIds : void 0;
+  }
+  /**
+   * Classifies an incoming revision relative to our current head using the
+   * local InsertHistory DAG (keyed on shared content refs):
+   *  - `behind`   → incoming descends from our head → fast-forward (restore).
+   *  - `ahead`    → our head descends from incoming (e.g. a reconnect bootstrap
+   *                 re-sending an older ancestor) → ignore; we are newer.
+   *  - `diverged` → siblings produced by concurrent edits → resolve the fork.
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   * @param currentRef - Our current head's content ref
+   * @param incomingRef - The incoming revision's content ref
+   * @param incomingPredecessorRefs - The incoming revision's predecessor refs
+   */
+  async _ancestryRelation(db, treeKey, currentRef, incomingRef, incomingPredecessorRefs) {
+    const dump = await db.getInsertHistory(treeKey);
+    const rows = dump[`${treeKey}InsertHistory`]?._data ?? [];
+    const refKey = `${treeKey}Ref`;
+    const refOfTimeId = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      refOfTimeId.set(r.timeId, r[refKey]);
+    }
+    const prevRefsOf = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      const prev = (r.previous ?? []).map((t) => refOfTimeId.get(t)).filter((x) => x !== void 0);
+      prevRefsOf.set(r[refKey], prev);
+    }
+    const ancestorsOf = (startRefs) => {
+      const seen = /* @__PURE__ */ new Set();
+      const stack = [...startRefs];
+      while (stack.length > 0) {
+        const ref = stack.pop();
+        if (seen.has(ref)) {
+          continue;
+        }
+        seen.add(ref);
+        for (const p of prevRefsOf.get(ref) ?? []) {
+          stack.push(p);
+        }
+      }
+      return seen;
+    };
+    if (ancestorsOf(incomingPredecessorRefs).has(currentRef)) {
+      return "behind";
+    }
+    if (ancestorsOf([currentRef]).has(incomingRef)) {
+      return "ahead";
+    }
+    return "diverged";
+  }
+  /**
+   * Resolves a divergent incoming revision inline (called from `processRef`
+   * with the watcher paused, so resolution cannot race the sync loop). Records
+   * the incoming revision as a fork tip without clobbering local content, then
+   * merges our head and the incoming tip into a single merge revision D that is
+   * materialised to disk and broadcast.
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   * @param incomingRef - The incoming revision's content ref
+   * @param incomingTree - The fetched incoming tree
+   * @param predecessorRefs - The incoming revision's predecessor content refs
+   */
+  async _resolveConflictInline(db, treeKey, incomingRef, incomingTree, predecessorRefs) {
+    const dbAdapter = new FsDbAdapter(db, treeKey);
+    const incomingPrevious = await this._ancestryPrevious(
+      db,
+      treeKey,
+      predecessorRefs
+    );
+    await dbAdapter.storeFsTree(incomingTree, {
+      skipNotification: true,
+      previous: incomingPrevious
+    });
+    const headTimeIds = await db.getTimeIdsForRef(treeKey, this._currentRef);
+    const incomingTimeIds = await db.getTimeIdsForRef(treeKey, incomingRef);
+    const resolver = new FsConflictResolver(
+      this._buildConflictResolverDeps(db, treeKey)
+    );
+    await resolver.resolve({
+      table: treeKey,
+      type: "dagBranch",
+      detectedAt: Date.now(),
+      branches: [...headTimeIds, ...incomingTimeIds]
+    });
+  }
   /**
    * Builds a map of relativePath → blobId for all files in a tree.
    * Used to compare trees by content rather than by hash (which includes mtime).
@@ -1062,6 +1675,51 @@ ${err.stack}` : String(err);
     }
     return true;
   }
+  /**
+   * Builds the dependency surface a {@link FsConflictResolver} needs, wiring it
+   * to this agent's db, blob store, scanner, and working directory.
+   *
+   * The merge store records the merged ref/content key as the last-sent state,
+   * so the watcher-driven re-scan that follows the on-disk materialisation
+   * settles to a no-op instead of re-broadcasting.
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   */
+  _buildConflictResolverDeps(db, treeKey) {
+    return {
+      treeKey,
+      getInsertHistory: async (table) => {
+        const dump = await db.getInsertHistory(table);
+        const rows = dump[`${table}InsertHistory`]?._data ?? [];
+        return rows;
+      },
+      getRefOfTimeId: (table, timeId) => db.getRefOfTimeId(table, timeId),
+      fetchTree: (rootRef) => this._fetchTreeFromDb(db, treeKey, rootRef),
+      getBlobContent: (blobId) => this._adapter.getFileContent(blobId),
+      restoreTree: (tree) => this.restore(tree, void 0, { cleanTarget: true }),
+      writeFileAt: async (relativePath, content) => {
+        const filePath = join(this._rootPath, relativePath);
+        await mkdir(dirname(filePath), { recursive: true });
+        await FsAgent._atomicWriteFile(filePath, content);
+      },
+      deleteFileAt: async (relativePath) => {
+        await rm(join(this._rootPath, relativePath), {
+          force: true,
+          recursive: true
+        });
+      },
+      scan: () => this._scanner.scan(),
+      storeMerge: async (tree, previous) => {
+        const dbAdapter = new FsDbAdapter(db, treeKey);
+        const ref = await dbAdapter.storeFsTree(tree, { previous });
+        this._lastSentRef = ref;
+        this._lastSentContentKey = this._contentKeyFromTree(tree);
+        this._currentRef = ref;
+        return ref;
+      }
+      // Resolution failures are surfaced by `_onConflict`; success is silent.
+    };
+  }
   /**
    * Watches database for tree changes and syncs to filesystem
    * Uses Connector for socket-based notifications
@@ -1077,7 +1735,9 @@ ${err.stack}` : String(err);
     }
     let pendingRef = null;
     let fromDbTimer = null;
-    const processRef = async (treeRef) => {
+    let pendingRecoveryAttempt = 0;
+    let pendingPredecessorRefs;
+    const processRef = async (treeRef, recoveryAttempt = 0, predecessorRefs) => {
       const maxAttempts = this._timeouts.processRefRetries + 1;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         this._scanner.pauseWatch();
@@ -1104,6 +1764,28 @@ ${err.stack}` : String(err);
             );
             return;
           }
+          if (this._resolveConflicts && this._currentRef && predecessorRefs && predecessorRefs.length > 0) {
+            const relation = await this._ancestryRelation(
+              db,
+              treeKey,
+              this._currentRef,
+              treeRef,
+              predecessorRefs
+            );
+            if (relation === "ahead") {
+              return;
+            }
+            if (relation === "diverged") {
+              await this._resolveConflictInline(
+                db,
+                treeKey,
+                treeRef,
+                incomingTree,
+                predecessorRefs
+              );
+              return;
+            }
+          }
           await FsAgent._withTimeout(
             this.restore(incomingTree, void 0, restoreOptions),
             this._timeouts.restore,
@@ -1111,23 +1793,44 @@ ${err.stack}` : String(err);
           );
           const postRestoreTree = await this._scanner.scan();
           const dbAdapter = new FsDbAdapter(db, treeKey);
+          const previous = await this._ancestryPrevious(
+            db,
+            treeKey,
+            predecessorRefs
+          );
           const postRestoreRef = await dbAdapter.storeFsTree(postRestoreTree, {
-            skipNotification: true
+            skipNotification: true,
+            previous
           });
           this._lastSentRef = postRestoreRef;
           this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
+          this._currentRef = postRestoreRef;
           return;
         } catch (err) {
           if (attempt === maxAttempts) {
-            console.error(
-              `[FsAgent] syncFromDb processRef failed after ${maxAttempts} attempts:`,
-              err
-            );
-            this._writeSyncError("syncFromDb/processRef", err);
+            if (recoveryAttempt >= this._timeouts.recoveryRetries) {
+              console.error(
+                `[FsAgent] syncFromDb processRef failed after ${maxAttempts} attempts and ${recoveryAttempt} recoveries:`,
+                err
+              );
+              this._writeSyncError("syncFromDb/processRef", err);
+            } else {
+              if (pendingRef === null) {
+                console.warn(
+                  `[FsAgent] syncFromDb: ref=${treeRef.slice(0, 8)}… not yet fetchable after ${maxAttempts} attempts, re-queueing (recovery ${recoveryAttempt + 1}/${this._timeouts.recoveryRetries}): ${FsAgent._errMessage(err)}`
+                );
+                scheduleProcess(
+                  treeRef,
+                  this._timeouts.processRefRetryDelayMs * maxAttempts,
+                  recoveryAttempt + 1,
+                  predecessorRefs
+                );
+              }
+            }
           } else {
             const delaySec = attempt * this._timeouts.processRefRetryDelayMs / 1e3;
             console.warn(
-              `[FsAgent] syncFromDb: attempt ${attempt}/${maxAttempts} failed for ref=${treeRef.slice(0, 8)}…, retrying in ${delaySec}s: ${err instanceof Error ? err.message : String(err)}`
+              `[FsAgent] syncFromDb: attempt ${attempt}/${maxAttempts} failed for ref=${treeRef.slice(0, 8)}…, retrying in ${delaySec}s: ${FsAgent._errMessage(err)}`
             );
           }
         } finally {
@@ -1138,20 +1841,28 @@ ${err.stack}` : String(err);
         );
       }
     };
-    const syncCallback = async (treeRef) => {
-      if (!treeRef || typeof treeRef !== "string") {
-        return;
-      }
-      pendingRef = treeRef;
+    const scheduleProcess = (ref, delayMs, recoveryAttempt, predecessorRefs) => {
+      pendingRef = ref;
+      pendingRecoveryAttempt = recoveryAttempt;
+      pendingPredecessorRefs = predecessorRefs;
       if (fromDbTimer) clearTimeout(fromDbTimer);
       fromDbTimer = setTimeout(async () => {
         fromDbTimer = null;
-        const ref = pendingRef;
+        const r = pendingRef;
+        const ra = pendingRecoveryAttempt;
+        const pr = pendingPredecessorRefs;
         pendingRef = null;
-        if (ref) {
-          await processRef(ref);
+        if (r) {
+          await processRef(r, ra, pr);
         }
-      }, this._timeouts.debounceMs);
+      }, delayMs);
+    };
+    const syncCallback = (treeRef, predecessorRefs) => {
+      if (!treeRef || typeof treeRef !== "string") {
+        return Promise.resolve();
+      }
+      scheduleProcess(treeRef, this._timeouts.debounceMs, 0, predecessorRefs);
+      return Promise.resolve();
     };
     connector.listen(syncCallback);
     return () => {
@@ -1283,10 +1994,19 @@ async function runClientServerSetup(opts = {}) {
   return { baseDir, folderA, folderB, contentB, cleanup };
 }
 export {
+  DIR_MARKER,
   FsAgent,
   FsBlobAdapter,
+  FsConflictResolver,
   FsDbAdapter,
   FsScanner,
   SYNC_ERROR_FILE,
-  runClientServerSetup
+  compareTips,
+  conflictCopyName,
+  decideWinner,
+  findCommonAncestor,
+  formatConflictTimestamp,
+  fsTreeToContentMap,
+  runClientServerSetup,
+  threeWayMerge
 };