pushwork 1.0.5 → 1.0.11

package/src/core/sync-engine.ts

@@ -1,40 +1,42 @@
 import {
   AutomergeUrl,
   Repo,
-  updateText,
   DocHandle,
-  UrlHeads,
+  parseAutomergeUrl,
+  stringifyAutomergeUrl,
 } from "@automerge/automerge-repo";
 import * as A from "@automerge/automerge";
 import {
   SyncSnapshot,
   SyncResult,
-  SyncError,
-  SyncOperation,
-  PendingSyncOperation,
   FileDocument,
   DirectoryDocument,
-  FileType,
   ChangeType,
   MoveCandidate,
+  DirectoryConfig,
+  DetectedChange,
 } from "../types";
 import {
-  readFileContent,
   writeFileContent,
   removePath,
-  movePath,
-  ensureDirectoryExists,
   getFileExtension,
-  normalizePath,
-  getRelativePath,
   getEnhancedMimeType,
-  isEnhancedTextFile,
+  formatRelativePath,
+  findFileInDirectoryHierarchy,
+  joinAndNormalizePath,
+  getPlainUrl,
 } from "../utils";
 import { isContentEqual } from "../utils/content";
-import { waitForSync, getSyncServerStorageId } from "../utils/network-sync";
+import { waitForSync, waitForBidirectionalSync } from "../utils/network-sync";
 import { SnapshotManager } from "./snapshot";
-import { ChangeDetector, DetectedChange } from "./change-detection";
+import { ChangeDetector } from "./change-detection";
 import { MoveDetector } from "./move-detection";
+import { out } from "../utils/output";
+
+/**
+ * Sync configuration constants
+ */
+const BIDIRECTIONAL_SYNC_TIMEOUT_MS = 5000; // Timeout for bidirectional sync stability check
 
 /**
  * Bidirectional sync engine implementing two-phase sync
@@ -43,22 +45,24 @@ export class SyncEngine {
   private snapshotManager: SnapshotManager;
   private changeDetector: ChangeDetector;
   private moveDetector: MoveDetector;
-  private networkSyncEnabled: boolean = true;
-  private handlesToWaitOn: DocHandle<unknown>[] = [];
-  private syncServerStorageId?: string;
+  // Map from path to handle for leaf-first sync ordering
+  // Path depth determines sync order (deepest first)
+  private handlesByPath: Map<string, DocHandle<unknown>> = new Map();
+  private config: DirectoryConfig;
 
   constructor(
     private repo: Repo,
     private rootPath: string,
-    excludePatterns: string[] = [],
-    networkSyncEnabled: boolean = true,
-    syncServerStorageId?: string
+    config: DirectoryConfig
   ) {
+    this.config = config;
     this.snapshotManager = new SnapshotManager(rootPath);
-    this.changeDetector = new ChangeDetector(repo, rootPath, excludePatterns);
-    this.moveDetector = new MoveDetector();
-    this.networkSyncEnabled = networkSyncEnabled;
-    this.syncServerStorageId = syncServerStorageId;
+    this.changeDetector = new ChangeDetector(
+      repo,
+      rootPath,
+      config.exclude_patterns
+    );
+    this.moveDetector = new MoveDetector(config.sync.move_detection_threshold);
   }
 
   /**
@@ -71,6 +75,16 @@ export class SyncEngine {
     return typeof content === "string";
   }
 
+  /**
+   * Get a versioned URL from a handle (includes current heads).
+   * This ensures clients can fetch the exact version of the document.
+   */
+  private getVersionedUrl(handle: DocHandle<unknown>): AutomergeUrl {
+    const { documentId } = parseAutomergeUrl(handle.url);
+    const heads = handle.heads();
+    return stringifyAutomergeUrl({ documentId, heads });
+  }
+
   /**
    * Set the root directory URL in the snapshot
    */
@@ -86,7 +100,7 @@ export class SyncEngine {
   /**
    * Commit local changes only (no network sync)
    */
-  async commitLocal(dryRun = false): Promise<SyncResult> {
+  async commitLocal(): Promise<SyncResult> {
     const result: SyncResult = {
       success: false,
       filesChanged: 0,
@@ -102,27 +116,20 @@ export class SyncEngine {
         snapshot = this.snapshotManager.createEmpty();
       }
 
-      // Backup snapshot before starting
-      if (!dryRun) {
-        await this.snapshotManager.backup();
-      }
-
       // Detect all changes
       const changes = await this.changeDetector.detectChanges(snapshot);
 
       // Detect moves
       const { moves, remainingChanges } = await this.moveDetector.detectMoves(
         changes,
-        snapshot,
-        this.rootPath
+        snapshot
       );
 
       // Apply local changes only (no network sync)
       const commitResult = await this.pushLocalChanges(
         remainingChanges,
         moves,
-        snapshot,
-        dryRun
+        snapshot
       );
 
       result.filesChanged += commitResult.filesChanged;
@@ -130,17 +137,18 @@ export class SyncEngine {
       result.errors.push(...commitResult.errors);
       result.warnings.push(...commitResult.warnings);
 
+      // Update directory URLs with current heads after all children are populated
+      await this.updateDirectoryUrlsLeafFirst(snapshot);
+
       // Touch root directory if any changes were made
       const hasChanges =
         result.filesChanged > 0 || result.directoriesChanged > 0;
       if (hasChanges) {
-        await this.touchRootDirectory(snapshot, dryRun);
+        await this.touchRootDirectory(snapshot);
       }
 
-      // Save updated snapshot if not dry run
-      if (!dryRun) {
-        await this.snapshotManager.save(snapshot);
-      }
+      // Save updated snapshot
+      await this.snapshotManager.save(snapshot);
 
       result.success = result.errors.length === 0;
 
@@ -160,10 +168,7 @@ export class SyncEngine {
   /**
    * Run full bidirectional sync
    */
-  async sync(dryRun = false): Promise<SyncResult> {
-    const syncStartTime = Date.now();
-    const timings: { [key: string]: number } = {};
-
+  async sync(): Promise<SyncResult> {
     const result: SyncResult = {
       success: false,
       filesChanged: 0,
@@ -173,189 +178,161 @@ export class SyncEngine {
       timings: {},
     };
 
-    // Reset handles to wait on
-    this.handlesToWaitOn = [];
+    // Reset tracked handles for sync
+    this.handlesByPath = new Map();
 
     try {
       // Load current snapshot
-      const t0 = Date.now();
-      let snapshot = await this.snapshotManager.load();
-      timings["load_snapshot"] = Date.now() - t0;
-      if (!snapshot) {
-        snapshot = this.snapshotManager.createEmpty();
-      }
+      const snapshot =
+        (await this.snapshotManager.load()) ||
+        this.snapshotManager.createEmpty();
 
-      // Backup snapshot before starting
-      const t1 = Date.now();
-      if (!dryRun) {
-        await this.snapshotManager.backup();
+      // Wait for initial sync to receive any pending remote changes
+      if (this.config.sync_enabled && snapshot.rootDirectoryUrl) {
+        try {
+          await waitForBidirectionalSync(
+            this.repo,
+            snapshot.rootDirectoryUrl,
+            this.config.sync_server_storage_id,
+            {
+              timeoutMs: 3000, // Short timeout for initial sync
+              pollIntervalMs: 100,
+              stableChecksRequired: 3,
+            }
+          );
+        } catch (error) {
+          out.taskLine(`Initial sync: ${error}`, true);
+        }
       }
-      timings["backup_snapshot"] = Date.now() - t1;
 
       // Detect all changes
-      const t2 = Date.now();
       const changes = await this.changeDetector.detectChanges(snapshot);
-      timings["detect_changes"] = Date.now() - t2;
 
       // Detect moves
-      const t3 = Date.now();
       const { moves, remainingChanges } = await this.moveDetector.detectMoves(
         changes,
-        snapshot,
-        this.rootPath
+        snapshot
       );
-      timings["detect_moves"] = Date.now() - t3;
 
       // Phase 1: Push local changes to remote
-      const t4 = Date.now();
       const phase1Result = await this.pushLocalChanges(
         remainingChanges,
         moves,
-        snapshot,
-        dryRun
+        snapshot
       );
-      timings["phase1_push"] = Date.now() - t4;
 
       result.filesChanged += phase1Result.filesChanged;
       result.directoriesChanged += phase1Result.directoriesChanged;
       result.errors.push(...phase1Result.errors);
       result.warnings.push(...phase1Result.warnings);
 
-      // Always wait for network sync when enabled (not just when local changes exist)
-      // This is critical for clone scenarios where we need to pull remote changes
-      const t5 = Date.now();
-      timings["documents_to_sync"] = this.handlesToWaitOn.length;
-      if (!dryRun && this.networkSyncEnabled) {
+      // Update directory URLs with current heads after all children are populated
+      await this.updateDirectoryUrlsLeafFirst(snapshot);
+
+      // Wait for network sync (important for clone scenarios)
+      if (this.config.sync_enabled) {
         try {
-          // If we have a root directory URL, wait for it to sync
+          // If we have a root directory URL, add it to tracked handles
           if (snapshot.rootDirectoryUrl) {
+            const rootDirUrl = snapshot.rootDirectoryUrl;
             const rootHandle = await this.repo.find<DirectoryDocument>(
-              snapshot.rootDirectoryUrl
+              rootDirUrl
             );
-            this.handlesToWaitOn.push(rootHandle);
+            this.handlesByPath.set("", rootHandle);
           }
 
-          if (this.handlesToWaitOn.length > 0) {
-            const tWaitStart = Date.now();
+          if (this.handlesByPath.size > 0) {
+            // Sort handles leaf-first (deepest paths first, then shallower)
+            const sortedHandles = this.sortHandlesLeafFirst();
             await waitForSync(
-              this.handlesToWaitOn,
-              getSyncServerStorageId(this.syncServerStorageId)
+              sortedHandles,
+              this.config.sync_server_storage_id
             );
-            timings["network_sync"] = Date.now() - tWaitStart;
-
-            // CRITICAL: Wait a bit after our changes reach the server to allow
-            // time for WebSocket to deliver OTHER peers' changes to us.
-            // waitForSync only ensures OUR changes reached the server, not that
-            // we've RECEIVED changes from other peers. This delay allows the
-            // WebSocket protocol to propagate peer changes before we re-detect.
-            // Without this, concurrent operations on different peers can miss
-            // each other due to timing races.
-            //
-            // Optimization: Only wait if we pushed changes (shorter delay if no changes)
-            const tDelayStart = Date.now();
-            const delayMs = phase1Result.filesChanged > 0 ? 200 : 100;
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
-            timings["post_sync_delay"] = Date.now() - tDelayStart;
           }
+
+          // Wait for bidirectional sync to stabilize.
+          // This polls document heads until they stop changing, which indicates
+          // that both our outgoing changes and any incoming peer changes have
+          // been received.
+          await waitForBidirectionalSync(
+            this.repo,
+            snapshot.rootDirectoryUrl,
+            this.config.sync_server_storage_id,
+            {
+              timeoutMs: BIDIRECTIONAL_SYNC_TIMEOUT_MS,
+              pollIntervalMs: 100,
+              stableChecksRequired: 3,
+            }
+          );
         } catch (error) {
-          console.error(`❌ Network sync failed: ${error}`);
+          out.taskLine(`Network sync failed: ${error}`, true);
           result.warnings.push(`Network sync failed: ${error}`);
         }
       }
-      timings["total_network"] = Date.now() - t5;
 
-      // Re-detect remote changes after network sync to ensure fresh state
-      // This fixes race conditions where we detect changes before server propagation
-      // NOTE: We DON'T update snapshot heads yet - that would prevent detecting remote changes!
-      const t6 = Date.now();
+      // Re-detect changes after network sync for fresh state
       const freshChanges = await this.changeDetector.detectChanges(snapshot);
       const freshRemoteChanges = freshChanges.filter(
         (c) =>
           c.changeType === ChangeType.REMOTE_ONLY ||
           c.changeType === ChangeType.BOTH_CHANGED
       );
-      timings["redetect_changes"] = Date.now() - t6;
 
       // Phase 2: Pull remote changes to local using fresh detection
-      const t7 = Date.now();
       const phase2Result = await this.pullRemoteChanges(
         freshRemoteChanges,
-        snapshot,
-        dryRun
+        snapshot
       );
-      timings["phase2_pull"] = Date.now() - t7;
       result.filesChanged += phase2Result.filesChanged;
       result.directoriesChanged += phase2Result.directoriesChanged;
       result.errors.push(...phase2Result.errors);
       result.warnings.push(...phase2Result.warnings);
 
-      // CRITICAL FIX: Update snapshot heads AFTER pulling remote changes
-      // This ensures that change detection can find remote changes, and we only
-      // update the snapshot after the filesystem is in sync with the documents
-      const t8 = Date.now();
-      if (!dryRun) {
-        // Update file document heads
-        for (const [filePath, snapshotEntry] of snapshot.files.entries()) {
-          try {
-            const handle = await this.repo.find(snapshotEntry.url);
-            const currentHeads = handle.heads();
-            if (!A.equals(currentHeads, snapshotEntry.head)) {
-              // Update snapshot with current heads after pulling changes
-              snapshot.files.set(filePath, {
-                ...snapshotEntry,
-                head: currentHeads,
-              });
-            }
-          } catch (error) {
-            // Handle might not exist if file was deleted, skip
-            console.warn(`Could not update heads for ${filePath}: ${error}`);
+      // Update snapshot heads after pulling remote changes
+      for (const [filePath, snapshotEntry] of snapshot.files.entries()) {
+        try {
+          const handle = await this.repo.find(snapshotEntry.url);
+          const currentHeads = handle.heads();
+          if (!A.equals(currentHeads, snapshotEntry.head)) {
+            // Update snapshot with current heads after pulling changes
+            snapshot.files.set(filePath, {
+              ...snapshotEntry,
+              head: currentHeads,
+            });
           }
+        } catch (error) {
+          // Handle might not exist if file was deleted
         }
+      }
 
-        // Update directory document heads
-        for (const [dirPath, snapshotEntry] of snapshot.directories.entries()) {
-          try {
-            const handle = await this.repo.find(snapshotEntry.url);
-            const currentHeads = handle.heads();
-            if (!A.equals(currentHeads, snapshotEntry.head)) {
-              // Update snapshot with current heads after pulling changes
-              snapshot.directories.set(dirPath, {
-                ...snapshotEntry,
-                head: currentHeads,
-              });
-            }
-          } catch (error) {
-            // Handle might not exist if directory was deleted, skip
-            console.warn(
-              `Could not update heads for directory ${dirPath}: ${error}`
-            );
+      // Update directory document heads
+      for (const [dirPath, snapshotEntry] of snapshot.directories.entries()) {
+        try {
+          const handle = await this.repo.find(snapshotEntry.url);
+          const currentHeads = handle.heads();
+          if (!A.equals(currentHeads, snapshotEntry.head)) {
+            // Update snapshot with current heads after pulling changes
+            snapshot.directories.set(dirPath, {
+              ...snapshotEntry,
+              head: currentHeads,
+            });
           }
+        } catch (error) {
+          // Handle might not exist if directory was deleted
         }
       }
-      timings["update_snapshot_heads"] = Date.now() - t8;
 
       // Touch root directory if any changes were made during sync
-      const t9 = Date.now();
       const hasChanges =
         result.filesChanged > 0 || result.directoriesChanged > 0;
       if (hasChanges) {
-        await this.touchRootDirectory(snapshot, dryRun);
+        await this.touchRootDirectory(snapshot);
       }
-      timings["touch_root"] = Date.now() - t9;
 
       // Save updated snapshot if not dry run
-      const t10 = Date.now();
-      if (!dryRun) {
-        await this.snapshotManager.save(snapshot);
-      }
-      timings["save_snapshot"] = Date.now() - t10;
-
-      // Calculate total time
-      const totalTime = Date.now() - syncStartTime;
-      timings["total"] = totalTime;
+      await this.snapshotManager.save(snapshot);
 
       result.success = result.errors.length === 0;
-      result.timings = timings;
       return result;
     } catch (error) {
       result.errors.push({
@@ -374,8 +351,7 @@ export class SyncEngine {
   private async pushLocalChanges(
     changes: DetectedChange[],
     moves: MoveCandidate[],
-    snapshot: SyncSnapshot,
-    dryRun: boolean
+    snapshot: SyncSnapshot
   ): Promise<SyncResult> {
     const result: SyncResult = {
       success: true,
@@ -388,7 +364,7 @@ export class SyncEngine {
     // Process moves first - all detected moves are applied
     for (const move of moves) {
       try {
-        await this.applyMoveToRemote(move, snapshot, dryRun);
+        await this.applyMoveToRemote(move, snapshot);
         result.filesChanged++;
       } catch (error) {
         result.errors.push({
@@ -409,7 +385,7 @@ export class SyncEngine {
 
     for (const change of localChanges) {
       try {
-        await this.applyLocalChangeToRemote(change, snapshot, dryRun);
+        await this.applyLocalChangeToRemote(change, snapshot);
         result.filesChanged++;
       } catch (error) {
         result.errors.push({
@@ -429,8 +405,7 @@ export class SyncEngine {
    */
   private async pullRemoteChanges(
     changes: DetectedChange[],
-    snapshot: SyncSnapshot,
-    dryRun: boolean
+    snapshot: SyncSnapshot
   ): Promise<SyncResult> {
     const result: SyncResult = {
       success: true,
@@ -452,7 +427,7 @@ export class SyncEngine {
 
     for (const change of sortedChanges) {
       try {
-        await this.applyRemoteChangeToLocal(change, snapshot, dryRun);
+        await this.applyRemoteChangeToLocal(change, snapshot);
         result.filesChanged++;
       } catch (error) {
         result.errors.push({
@@ -472,47 +447,33 @@ export class SyncEngine {
    */
   private async applyLocalChangeToRemote(
     change: DetectedChange,
-    snapshot: SyncSnapshot,
-    dryRun: boolean
+    snapshot: SyncSnapshot
   ): Promise<void> {
     const snapshotEntry = snapshot.files.get(change.path);
 
-    // CRITICAL: Check for null explicitly, not falsy values
-    // Empty strings "" and empty Uint8Array are valid file content!
+    // Check for null (empty string/Uint8Array are valid content)
     if (change.localContent === null) {
       // File was deleted locally
       if (snapshotEntry) {
-        await this.deleteRemoteFile(
-          snapshotEntry.url,
-          dryRun,
-          snapshot,
-          change.path
-        );
+        await this.deleteRemoteFile(snapshotEntry.url, snapshot, change.path);
         // Remove from directory document
-        await this.removeFileFromDirectory(snapshot, change.path, dryRun);
-        if (!dryRun) {
-          this.snapshotManager.removeFileEntry(snapshot, change.path);
-        }
+        await this.removeFileFromDirectory(snapshot, change.path);
+        this.snapshotManager.removeFileEntry(snapshot, change.path);
       }
       return;
     }
 
     if (!snapshotEntry) {
       // New file
-      const handle = await this.createRemoteFile(change, dryRun);
-      if (!dryRun && handle) {
-        await this.addFileToDirectory(
-          snapshot,
-          change.path,
-          handle.url,
-          dryRun
-        );
+      const handle = await this.createRemoteFile(change);
+      if (handle) {
+        // Use versioned URL (includes heads) so clients fetch correct version
+        const versionedUrl = this.getVersionedUrl(handle);
+        await this.addFileToDirectory(snapshot, change.path, versionedUrl);
 
-        // CRITICAL FIX: Update snapshot with heads AFTER adding to directory
-        // The addFileToDirectory call above may have changed the document heads
         this.snapshotManager.updateFileEntry(snapshot, change.path, {
-          path: normalizePath(this.rootPath + "/" + change.path),
-          url: handle.url,
+          path: joinAndNormalizePath(this.rootPath, change.path),
+          url: versionedUrl,
           head: handle.heads(),
           extension: getFileExtension(change.path),
           mimeType: getEnhancedMimeType(change.path),
@@ -523,7 +484,6 @@ export class SyncEngine {
       await this.updateRemoteFile(
         snapshotEntry.url,
         change.localContent,
-        dryRun,
         snapshot,
         change.path
       );
@@ -535,10 +495,9 @@ export class SyncEngine {
    */
   private async applyRemoteChangeToLocal(
     change: DetectedChange,
-    snapshot: SyncSnapshot,
-    dryRun: boolean
+    snapshot: SyncSnapshot
   ): Promise<void> {
-    const localPath = normalizePath(this.rootPath + "/" + change.path);
+    const localPath = joinAndNormalizePath(this.rootPath, change.path);
 
     if (!change.remoteHead) {
       throw new Error(
@@ -546,50 +505,51 @@ export class SyncEngine {
       );
     }
 
-    // CRITICAL: Check for null explicitly, not falsy values
-    // Empty strings "" and empty Uint8Array are valid file content!
+    // Check for null (empty string/Uint8Array are valid content)
     if (change.remoteContent === null) {
       // File was deleted remotely
-      if (!dryRun) {
-        await removePath(localPath);
-        this.snapshotManager.removeFileEntry(snapshot, change.path);
-      }
+      await removePath(localPath);
+      this.snapshotManager.removeFileEntry(snapshot, change.path);
       return;
     }
 
     // Create or update local file
-    if (!dryRun) {
-      await writeFileContent(localPath, change.remoteContent);
+    await writeFileContent(localPath, change.remoteContent);
 
-      // Update or create snapshot entry for this file
-      const snapshotEntry = snapshot.files.get(change.path);
-      if (snapshotEntry) {
-        // Update existing entry
-        snapshotEntry.head = change.remoteHead;
-      } else {
-        // Create new snapshot entry for newly discovered remote file
-        // We need to find the remote file's URL from the directory hierarchy
-        if (snapshot.rootDirectoryUrl) {
-          try {
-            const fileEntry = await this.findFileInDirectoryHierarchy(
-              snapshot.rootDirectoryUrl,
-              change.path
-            );
+    // Update or create snapshot entry for this file
+    const snapshotEntry = snapshot.files.get(change.path);
+    if (snapshotEntry) {
+      // Update existing entry
+      snapshotEntry.head = change.remoteHead;
+    } else {
+      // Create new snapshot entry for newly discovered remote file
+      // We need to find the remote file's URL from the directory hierarchy
+      if (snapshot.rootDirectoryUrl) {
+        try {
+          const fileEntry = await findFileInDirectoryHierarchy(
+            this.repo,
+            snapshot.rootDirectoryUrl,
+            change.path
+          );
 
-            if (fileEntry) {
-              this.snapshotManager.updateFileEntry(snapshot, change.path, {
-                path: localPath,
-                url: fileEntry.url,
-                head: change.remoteHead,
-                extension: getFileExtension(change.path),
-                mimeType: getEnhancedMimeType(change.path),
-              });
-            }
-          } catch (error) {
-            console.warn(
-              `Failed to update snapshot for remote file ${change.path}: ${error}`
-            );
+          if (fileEntry) {
+            // Get versioned URL from handle (includes heads)
+            const fileHandle = await this.repo.find<FileDocument>(fileEntry.url);
+            const versionedUrl = this.getVersionedUrl(fileHandle);
+            this.snapshotManager.updateFileEntry(snapshot, change.path, {
+              path: localPath,
+              url: versionedUrl,
+              head: change.remoteHead,
+              extension: getFileExtension(change.path),
+              mimeType: getEnhancedMimeType(change.path),
+            });
           }
+        } catch (error) {
+          // Failed to update snapshot - file may have been deleted
+          out.taskLine(
+            `Warning: Failed to update snapshot for remote file ${change.path}`,
+            true
+          );
         }
       }
     }
@@ -600,90 +560,84 @@ export class SyncEngine {
    */
   private async applyMoveToRemote(
     move: MoveCandidate,
-    snapshot: SyncSnapshot,
-    dryRun: boolean
+    snapshot: SyncSnapshot
   ): Promise<void> {
     const fromEntry = snapshot.files.get(move.fromPath);
     if (!fromEntry) return;
 
     // Parse paths
-    const fromParts = move.fromPath.split("/");
-    const fromFileName = fromParts.pop() || "";
-    const fromDirPath = fromParts.join("/");
-
     const toParts = move.toPath.split("/");
     const toFileName = toParts.pop() || "";
     const toDirPath = toParts.join("/");
 
-    if (!dryRun) {
-      // 1) Remove file entry from old directory document
-      if (move.fromPath !== move.toPath) {
-        await this.removeFileFromDirectory(snapshot, move.fromPath, dryRun);
-      }
+    // 1) Remove file entry from old directory document
+    if (move.fromPath !== move.toPath) {
+      await this.removeFileFromDirectory(snapshot, move.fromPath);
+    }
 
-      // 2) Ensure destination directory document exists and add file entry there
-      const destDirUrl = await this.ensureDirectoryDocument(
-        snapshot,
-        toDirPath,
-        dryRun
-      );
-      await this.addFileToDirectory(
-        snapshot,
-        move.toPath,
-        fromEntry.url,
-        dryRun
-      );
+    // 2) Ensure destination directory document exists
+    await this.ensureDirectoryDocument(snapshot, toDirPath);
 
-      // 3) Update the FileDocument name and content to match new location/state
-      try {
-        const handle = await this.repo.find<FileDocument>(fromEntry.url);
-        const heads = fromEntry.head;
-
-        // Update both name and content (if content changed during move)
-        if (heads && heads.length > 0) {
-          handle.changeAt(heads, (doc: FileDocument) => {
-            doc.name = toFileName;
-
-            // If new content is provided, update it (handles move + modification case)
-            if (move.newContent !== undefined) {
-              const isText = this.isTextContent(move.newContent);
-              if (isText && typeof move.newContent === "string") {
-                updateText(doc, ["content"], move.newContent);
-              } else {
-                doc.content = move.newContent;
-              }
+    // 3) Update the FileDocument name and content to match new location/state
+    try {
+      // Use plain URL for mutable handle
+      const handle = await this.repo.find<FileDocument>(
+        getPlainUrl(fromEntry.url)
+      );
+      const heads = fromEntry.head;
+
+      // Update both name and content (if content changed during move)
+      if (heads && heads.length > 0) {
+        handle.changeAt(heads, (doc: FileDocument) => {
+          doc.name = toFileName;
+
+          // If new content is provided, update it (handles move + modification case)
+          if (move.newContent !== undefined) {
+            if (typeof move.newContent === "string") {
+              doc.content = new A.ImmutableString(move.newContent);
+            } else {
+              doc.content = move.newContent;
             }
-          });
-        } else {
-          handle.change((doc: FileDocument) => {
-            doc.name = toFileName;
-
-            // If new content is provided, update it (handles move + modification case)
-            if (move.newContent !== undefined) {
-              const isText = this.isTextContent(move.newContent);
-              if (isText && typeof move.newContent === "string") {
-                updateText(doc, ["content"], move.newContent);
-              } else {
-                doc.content = move.newContent;
-              }
+          }
+        });
+      } else {
+        handle.change((doc: FileDocument) => {
+          doc.name = toFileName;
+
+          // If new content is provided, update it (handles move + modification case)
+          if (move.newContent !== undefined) {
+            if (typeof move.newContent === "string") {
+              doc.content = new A.ImmutableString(move.newContent);
+            } else {
+              doc.content = move.newContent;
             }
-          });
-        }
-        // Track file handle for network sync
-        this.handlesToWaitOn.push(handle);
-      } catch (e) {
-        console.warn(
-          `Failed to update file name for move ${move.fromPath} -> ${move.toPath}: ${e}`
-        );
+          }
+        });
       }
 
-      // 4) Update snapshot entries
+      // Get versioned URL after changes (includes current heads)
+      const versionedUrl = this.getVersionedUrl(handle);
+
+      // 4) Add file entry to destination directory with versioned URL
+      await this.addFileToDirectory(snapshot, move.toPath, versionedUrl);
+
+      // Track file handle for network sync
+      this.handlesByPath.set(move.toPath, handle);
+
+      // 5) Update snapshot entries
       this.snapshotManager.removeFileEntry(snapshot, move.fromPath);
       this.snapshotManager.updateFileEntry(snapshot, move.toPath, {
         ...fromEntry,
-        path: normalizePath(this.rootPath + "/" + move.toPath),
-        head: fromEntry.head, // will be updated later when heads advance
+        path: joinAndNormalizePath(this.rootPath, move.toPath),
+        url: versionedUrl,
+        head: handle.heads(),
       });
+    } catch (e) {
+      // Failed to update file name - file may have been deleted
+      out.taskLine(
+        `Warning: Failed to rename ${move.fromPath} to ${move.toPath}`,
+        true
+      );
     }
   }
 
@@ -691,12 +645,9 @@ export class SyncEngine {
    * Create new remote file document
    */
   private async createRemoteFile(
-    change: DetectedChange,
-    dryRun: boolean
+    change: DetectedChange
   ): Promise<DocHandle<FileDocument> | null> {
-    // CRITICAL: Check for null explicitly, not falsy values
-    // Empty strings "" and empty Uint8Array are valid file content!
-    if (dryRun || change.localContent === null) return null;
+    if (change.localContent === null) return null;
 
     const isText = this.isTextContent(change.localContent);
 
@@ -706,7 +657,11 @@ export class SyncEngine {
       name: change.path.split("/").pop() || "",
       extension: getFileExtension(change.path),
       mimeType: getEnhancedMimeType(change.path),
-      content: isText ? "" : change.localContent, // Empty string for text, actual content for binary
+      content: isText
+        ? new A.ImmutableString("")
+        : typeof change.localContent === "string"
+        ? new A.ImmutableString(change.localContent)
+        : change.localContent, // Empty ImmutableString for text, wrap strings for safety, actual content for binary
       metadata: {
         permissions: 0o644,
       },
@@ -714,16 +669,16 @@ export class SyncEngine {
 
     const handle = this.repo.create(fileDoc);
 
-    // For text files, use updateText to set the content properly
+    // For text files, use ImmutableString for better performance
     if (isText && typeof change.localContent === "string") {
       handle.change((doc: FileDocument) => {
-        updateText(doc, ["content"], change.localContent as string);
+        doc.content = new A.ImmutableString(change.localContent as string);
       });
     }
 
     // Always track newly created files for network sync
     // (they always represent a change that needs to sync)
-    this.handlesToWaitOn.push(handle);
+    this.handlesByPath.set(change.path, handle);
 
     return handle;
   }
@@ -734,21 +689,18 @@ export class SyncEngine {
   private async updateRemoteFile(
     url: AutomergeUrl,
     content: string | Uint8Array,
-    dryRun: boolean,
     snapshot: SyncSnapshot,
     filePath: string
   ): Promise<void> {
-    if (dryRun) return;
-
-    const handle = await this.repo.find<FileDocument>(url);
+    // Use plain URL for mutable handle
+    const handle = await this.repo.find<FileDocument>(getPlainUrl(url));
 
     // Check if content actually changed before tracking for sync
     const doc = await handle.doc();
     const currentContent = doc?.content;
     const contentChanged = !isContentEqual(content, currentContent);
 
-    // CRITICAL FIX: Always update snapshot heads, even when content is identical
-    // This prevents stale head issues that cause false change detection
+    // Update snapshot heads even when content is identical
     const snapshotEntry = snapshot.files.get(filePath);
     if (snapshotEntry) {
       // Update snapshot with current document heads
@@ -761,9 +713,6 @@ export class SyncEngine {
     if (!contentChanged) {
       // Content is identical, but we've updated the snapshot heads above
       // This prevents fresh change detection from seeing stale heads
-      console.log(
-        `🔍 Content is identical, but we've updated the snapshot heads above`
-      );
       return;
     }
 
@@ -774,16 +723,15 @@ export class SyncEngine {
     }
 
     handle.changeAt(heads, (doc: FileDocument) => {
-      const isText = this.isTextContent(content);
-      if (isText && typeof content === "string") {
-        updateText(doc, ["content"], content);
+      if (typeof content === "string") {
+        doc.content = new A.ImmutableString(content);
       } else {
         doc.content = content;
       }
     });
 
     // Update snapshot with new heads after content change
-    if (!dryRun && snapshotEntry) {
+    if (snapshotEntry) {
       snapshot.files.set(filePath, {
         ...snapshotEntry,
         head: handle.heads(),
@@ -791,7 +739,7 @@ export class SyncEngine {
     }
 
     // Only track files that actually changed content
-    this.handlesToWaitOn.push(handle);
+    this.handlesByPath.set(filePath, handle);
   }
 
   /**
@@ -799,16 +747,14 @@ export class SyncEngine {
    */
   private async deleteRemoteFile(
     url: AutomergeUrl,
-    dryRun: boolean,
     snapshot?: SyncSnapshot,
     filePath?: string
   ): Promise<void> {
-    if (dryRun) return;
-
     // In Automerge, we don't actually delete documents
     // They become orphaned and will be garbage collected
     // For now, we just mark them as deleted by clearing content
-    const handle = await this.repo.find<FileDocument>(url);
+    // Use plain URL for mutable handle
+    const handle = await this.repo.find<FileDocument>(getPlainUrl(url));
     // const doc = await handle.doc(); // no longer needed
     let heads;
     if (snapshot && filePath) {
@@ -816,11 +762,11 @@ export class SyncEngine {
     }
     if (heads) {
       handle.changeAt(heads, (doc: FileDocument) => {
-        doc.content = "";
+        doc.content = new A.ImmutableString("");
       });
     } else {
       handle.change((doc: FileDocument) => {
-        doc.content = "";
+        doc.content = new A.ImmutableString("");
       });
     }
   }
@@ -831,10 +777,9 @@ export class SyncEngine {
   private async addFileToDirectory(
     snapshot: SyncSnapshot,
     filePath: string,
-    fileUrl: AutomergeUrl,
-    dryRun: boolean
+    fileUrl: AutomergeUrl
   ): Promise<void> {
-    if (dryRun || !snapshot.rootDirectoryUrl) return;
+    if (!snapshot.rootDirectoryUrl) return;
 
     const pathParts = filePath.split("/");
     const fileName = pathParts.pop() || "";
@@ -843,11 +788,13 @@ export class SyncEngine {
     // Get or create the parent directory document
     const parentDirUrl = await this.ensureDirectoryDocument(
       snapshot,
-      directoryPath,
-      dryRun
+      directoryPath
     );
 
-    const dirHandle = await this.repo.find<DirectoryDocument>(parentDirUrl);
+    // Use plain URL for mutable handle
+    const dirHandle = await this.repo.find<DirectoryDocument>(
+      getPlainUrl(parentDirUrl)
+    );
 
     let didChange = false;
     const snapshotEntry = snapshot.directories.get(directoryPath);
@@ -881,14 +828,11 @@ export class SyncEngine {
         }
       });
     }
-    if (didChange) {
-      this.handlesToWaitOn.push(dirHandle);
-
-      // CRITICAL FIX: Update snapshot with new directory heads immediately
-      // This prevents stale head issues that cause convergence problems
-      if (snapshotEntry) {
-        snapshotEntry.head = dirHandle.heads();
-      }
+    // Always track the directory (even if unchanged) for proper leaf-first sync ordering
+    this.handlesByPath.set(directoryPath, dirHandle);
+    
+    if (didChange && snapshotEntry) {
+      snapshotEntry.head = dirHandle.heads();
     }
   }
 
@@ -898,8 +842,7 @@ export class SyncEngine {
    */
   private async ensureDirectoryDocument(
     snapshot: SyncSnapshot,
-    directoryPath: string,
-    dryRun: boolean
+    directoryPath: string
   ): Promise<AutomergeUrl> {
     // Root directory case
     if (!directoryPath || directoryPath === "") {
@@ -920,8 +863,7 @@ export class SyncEngine {
     // Ensure parent directory exists first (recursive)
     const parentDirUrl = await this.ensureDirectoryDocument(
       snapshot,
-      parentPath,
-      dryRun
+      parentPath
     );
 
     // DISCOVERY: Check if directory already exists in parent on server
@@ -944,35 +886,30 @@ export class SyncEngine {
             const childDirHandle = await this.repo.find<DirectoryDocument>(
               existingDirEntry.url
             );
-            const childHeads = childDirHandle.heads();
-
-            // Update snapshot with discovered directory using validated heads
-            if (!dryRun) {
-              this.snapshotManager.updateDirectoryEntry(
-                snapshot,
-                directoryPath,
-                {
-                  path: normalizePath(this.rootPath + "/" + directoryPath),
-                  url: existingDirEntry.url,
-                  head: childHeads,
-                  entries: [],
-                }
-              );
-            }
 
-            return existingDirEntry.url;
+            // Track discovered directory for sync
+            this.handlesByPath.set(directoryPath, childDirHandle);
+
+            // Get versioned URL for storage (includes current heads)
+            const versionedUrl = this.getVersionedUrl(childDirHandle);
+
+            // Update snapshot with discovered directory using versioned URL
+            this.snapshotManager.updateDirectoryEntry(snapshot, directoryPath, {
+              path: joinAndNormalizePath(this.rootPath, directoryPath),
+              url: versionedUrl,
+              head: childDirHandle.heads(),
+              entries: [],
+            });
+
+            // Return versioned URL (callers use getPlainUrl() when they need to modify)
+            return versionedUrl;
           } catch (resolveErr) {
-            console.warn(
-              `Failed to resolve child directory ${currentDirName} at ${directoryPath}: ${resolveErr}`
-            );
-            // Fall through to create a fresh directory document
+            // Failed to resolve directory - fall through to create a fresh directory document
           }
         }
       }
     } catch (error) {
-      console.warn(
-        `Failed to check for existing directory ${currentDirName}: ${error}`
-      );
+      // Failed to check for existing directory - will create new one
     }
 
     // CREATE: Directory doesn't exist, create new one
@@ -983,8 +920,14 @@ export class SyncEngine {
 
     const dirHandle = this.repo.create(dirDoc);
 
+    // Get versioned URL for the new directory (includes heads)
+    const versionedDirUrl = this.getVersionedUrl(dirHandle);
+
     // Add this directory to its parent
-    const parentHandle = await this.repo.find<DirectoryDocument>(parentDirUrl);
+    // Use plain URL for mutable handle
+    const parentHandle = await this.repo.find<DirectoryDocument>(
+      getPlainUrl(parentDirUrl)
+    );
 
     let didChange = false;
     parentHandle.change((doc: DirectoryDocument) => {
@@ -997,36 +940,33 @@ export class SyncEngine {
         doc.docs.push({
           name: currentDirName,
           type: "folder",
-          url: dirHandle.url,
+          url: versionedDirUrl,
         });
         didChange = true;
       }
     });
 
     // Track directory handles for sync
-    if (!dryRun) {
-      this.handlesToWaitOn.push(dirHandle);
-      if (didChange) {
-        this.handlesToWaitOn.push(parentHandle);
-
-        // CRITICAL FIX: Update parent directory heads in snapshot immediately
-        // This prevents stale head issues when parent directory is modified
-        const parentSnapshotEntry = snapshot.directories.get(parentPath);
-        if (parentSnapshotEntry) {
-          parentSnapshotEntry.head = parentHandle.heads();
-        }
-      }
+    this.handlesByPath.set(directoryPath, dirHandle);
+    if (didChange) {
+      this.handlesByPath.set(parentPath, parentHandle);
 
-      // Update snapshot with new directory
-      this.snapshotManager.updateDirectoryEntry(snapshot, directoryPath, {
-        path: normalizePath(this.rootPath + "/" + directoryPath),
-        url: dirHandle.url,
-        head: dirHandle.heads(),
-        entries: [],
-      });
+      const parentSnapshotEntry = snapshot.directories.get(parentPath);
+      if (parentSnapshotEntry) {
+        parentSnapshotEntry.head = parentHandle.heads();
+      }
     }
 
-    return dirHandle.url;
+    // Update snapshot with new directory (use versioned URL for storage)
+    this.snapshotManager.updateDirectoryEntry(snapshot, directoryPath, {
+      path: joinAndNormalizePath(this.rootPath, directoryPath),
+      url: versionedDirUrl,
+      head: dirHandle.heads(),
+      entries: [],
+    });
+
+    // Return versioned URL (callers use getPlainUrl() when they need to modify)
+    return versionedDirUrl;
   }
 
   /**
@@ -1034,10 +974,9 @@ export class SyncEngine {
    */
   private async removeFileFromDirectory(
     snapshot: SyncSnapshot,
-    filePath: string,
-    dryRun: boolean
+    filePath: string
   ): Promise<void> {
-    if (dryRun || !snapshot.rootDirectoryUrl) return;
+    if (!snapshot.rootDirectoryUrl) return;
 
     const pathParts = filePath.split("/");
     const fileName = pathParts.pop() || "";
@@ -1050,19 +989,20 @@ export class SyncEngine {
     } else {
       const existingDir = snapshot.directories.get(directoryPath);
       if (!existingDir) {
-        console.warn(
-          `Directory ${directoryPath} not found in snapshot for file removal`
-        );
+        // Directory not found - file may already be removed
         return;
       }
       parentDirUrl = existingDir.url;
     }
 
     try {
-      const dirHandle = await this.repo.find<DirectoryDocument>(parentDirUrl);
+      // Use plain URL for mutable handle
+      const dirHandle = await this.repo.find<DirectoryDocument>(
+        getPlainUrl(parentDirUrl)
+      );
 
       // Track this handle for network sync waiting
-      this.handlesToWaitOn.push(dirHandle);
+      this.handlesByPath.set(directoryPath, dirHandle);
       const snapshotEntry = snapshot.directories.get(directoryPath);
       const heads = snapshotEntry?.head;
       let didChange = false;
@@ -1075,9 +1015,9 @@ export class SyncEngine {
           if (indexToRemove !== -1) {
             doc.docs.splice(indexToRemove, 1);
             didChange = true;
-            console.log(
-              `🗑️  Removed ${fileName} from directory ${
-                directoryPath || "root"
+            out.taskLine(
+              `Removed ${fileName} from ${
+                formatRelativePath(directoryPath) || "root"
               }`
             );
           }
@@ -1090,83 +1030,23 @@ export class SyncEngine {
           if (indexToRemove !== -1) {
             doc.docs.splice(indexToRemove, 1);
             didChange = true;
-            console.log(
-              `🗑️  Removed ${fileName} from directory ${
-                directoryPath || "root"
+            out.taskLine(
+              `Removed ${fileName} from ${
+                formatRelativePath(directoryPath) || "root"
               }`
             );
           }
         });
       }
 
-      // CRITICAL FIX: Update snapshot with new directory heads immediately
-      // This prevents stale head issues that cause convergence problems
       if (didChange && snapshotEntry) {
         snapshotEntry.head = dirHandle.heads();
       }
     } catch (error) {
-      console.warn(
-        `Failed to remove ${fileName} from directory ${
-          directoryPath || "root"
-        }: ${error}`
-      );
       throw error;
     }
   }
 
-  /**
-   * Find a file in the directory hierarchy by path
-   */
-  private async findFileInDirectoryHierarchy(
-    directoryUrl: AutomergeUrl,
-    filePath: string
-  ): Promise<{ name: string; type: string; url: AutomergeUrl } | null> {
-    try {
-      const pathParts = filePath.split("/");
-      let currentDirUrl = directoryUrl;
-
-      // Navigate through directories to find the parent directory
-      for (let i = 0; i < pathParts.length - 1; i++) {
-        const dirName = pathParts[i];
-        const dirHandle = await this.repo.find<DirectoryDocument>(
-          currentDirUrl
-        );
-        const dirDoc = await dirHandle.doc();
-
-        if (!dirDoc) return null;
-
-        const subDirEntry = dirDoc.docs.find(
-          (entry: { name: string; type: string; url: AutomergeUrl }) =>
-            entry.name === dirName && entry.type === "folder"
-        );
-
-        if (!subDirEntry) return null;
-        currentDirUrl = subDirEntry.url;
-      }
-
-      // Now look for the file in the final directory
-      const fileName = pathParts[pathParts.length - 1];
-      const finalDirHandle = await this.repo.find<DirectoryDocument>(
-        currentDirUrl
-      );
-      const finalDirDoc = await finalDirHandle.doc();
-
-      if (!finalDirDoc) return null;
-
-      const fileEntry = finalDirDoc.docs.find(
-        (entry: { name: string; type: string; url: AutomergeUrl }) =>
-          entry.name === fileName && entry.type === "file"
-      );
-
-      return fileEntry || null;
-    } catch (error) {
-      console.warn(
-        `Failed to find file ${filePath} in directory hierarchy: ${error}`
-      );
-      return null;
-    }
-  }
-
   /**
    * Sort changes by dependency order
    */
@@ -1227,11 +1107,7 @@ export class SyncEngine {
     }
 
     const changes = await this.changeDetector.detectChanges(snapshot);
-    const { moves } = await this.moveDetector.detectMoves(
-      changes,
-      snapshot,
-      this.rootPath
-    );
+    const { moves } = await this.moveDetector.detectMoves(changes, snapshot);
 
     const summary = this.generateChangeSummary(changes, moves);
 
@@ -1293,11 +1169,8 @@ export class SyncEngine {
   /**
    * Update the lastSyncAt timestamp on the root directory document
    */
-  private async touchRootDirectory(
-    snapshot: SyncSnapshot,
-    dryRun: boolean
-  ): Promise<void> {
-    if (dryRun || !snapshot.rootDirectoryUrl) {
+  private async touchRootDirectory(snapshot: SyncSnapshot): Promise<void> {
+    if (!snapshot.rootDirectoryUrl) {
       return;
     }
 
@@ -1322,21 +1195,300 @@ export class SyncEngine {
       }
 
       // Track root directory for network sync
-      this.handlesToWaitOn.push(rootHandle);
+      this.handlesByPath.set("", rootHandle);
 
-      // CRITICAL FIX: Update root directory heads in snapshot immediately
-      // This prevents stale head issues when root directory is modified
       if (snapshotEntry) {
         snapshotEntry.head = rootHandle.heads();
       }
-
-      console.log(
-        `🕒 Updated root directory lastSyncAt to ${new Date(
-          timestamp
-        ).toISOString()}`
-      );
     } catch (error) {
-      console.warn(`Failed to update root directory lastSyncAt: ${error}`);
+      // Failed to update root directory timestamp
+    }
+  }
+
+  /**
+   * Sort tracked handles leaf-first (deepest paths first).
+   * Returns handles in sorted order, logging URLs with heads for debugging.
+   */
+  private sortHandlesLeafFirst(): DocHandle<unknown>[] {
+    // Sort paths by depth (descending - deepest first), then alphabetically
+    const sortedPaths = Array.from(this.handlesByPath.keys()).sort((a, b) => {
+      const depthA = a ? a.split("/").length : 0;
+      const depthB = b ? b.split("/").length : 0;
+
+      // Deepest first
+      if (depthA !== depthB) {
+        return depthB - depthA;
+      }
+
+      // Alphabetically by path
+      return a.localeCompare(b);
+    });
+
+    // Log the sync order with versioned URLs for debugging (keep on complete)
+    const handles: DocHandle<unknown>[] = [];
+    for (const path of sortedPaths) {
+      const handle = this.handlesByPath.get(path)!;
+      const versionedUrl = this.getVersionedUrl(handle);
+      out.taskLine(`Sync: ${path || "(root)"} -> ${versionedUrl}`, true);
+      handles.push(handle);
+    }
+
+    return handles;
+  }
+
+  /**
+   * Update all URLs (files and directories) in directory documents with current heads.
+   *
+   * This MUST be called AFTER all changes are applied but BEFORE network sync.
+   * The problem it solves:
+   * 1. When we create/update a file or directory and store its URL, the URL captures
+   *    the heads at that moment
+   * 2. Later operations may advance the document's heads
+   * 3. But the URL stored in the parent directory has stale heads
+   * 4. Clients reading the directory would get old views of entries
+   *
+   * The fix: walk leaf-first and update all entry URLs with current heads,
+   * AFTER all changes have been applied. This ensures clients get consistent,
+   * up-to-date versioned URLs.
+   */
+  private async updateDirectoryUrlsLeafFirst(
+    snapshot: SyncSnapshot
+  ): Promise<void> {
+    // First, update file URLs in their parent directories
+    await this.updateFileUrlsInDirectories(snapshot);
+
+    // Then, update directory URLs in their parent directories (leaf-first)
+    await this.updateSubdirectoryUrls(snapshot);
+  }
+
+  /**
+   * Update file URLs in directory documents with current heads.
+   */
+  private async updateFileUrlsInDirectories(
+    snapshot: SyncSnapshot
+  ): Promise<void> {
+    // Group files by their parent directory
+    const filesByDir = new Map<string, string[]>();
+
+    for (const filePath of snapshot.files.keys()) {
+      const pathParts = filePath.split("/");
+      pathParts.pop(); // Remove filename
+      const dirPath = pathParts.join("/");
+
+      if (!filesByDir.has(dirPath)) {
+        filesByDir.set(dirPath, []);
+      }
+      filesByDir.get(dirPath)!.push(filePath);
+    }
+
+    // Process each directory that has files
+    for (const [dirPath, filePaths] of filesByDir.entries()) {
+      try {
+        // Get the directory URL
+        let dirUrl: AutomergeUrl;
+        if (!dirPath || dirPath === "") {
+          if (!snapshot.rootDirectoryUrl) continue;
+          dirUrl = snapshot.rootDirectoryUrl;
+        } else {
+          const dirEntry = snapshot.directories.get(dirPath);
+          if (!dirEntry) continue;
+          dirUrl = dirEntry.url;
+        }
+
+        // Get directory handle
+        const dirHandle = await this.repo.find<DirectoryDocument>(
+          getPlainUrl(dirUrl)
+        );
+
+        // Get current heads for changeAt
+        const snapshotEntry = snapshot.directories.get(dirPath);
+        const heads = snapshotEntry?.head;
+
+        // Build a map of file names to their current versioned URLs
+        const fileUrlUpdates = new Map<string, AutomergeUrl>();
+
+        for (const filePath of filePaths) {
+          const fileEntry = snapshot.files.get(filePath);
+          if (!fileEntry) continue;
+
+          // Get current handle for this file
+          const fileHandle = await this.repo.find<FileDocument>(
+            getPlainUrl(fileEntry.url)
+          );
+
+          // Get versioned URL with current heads
+          const currentVersionedUrl = this.getVersionedUrl(fileHandle);
+
+          // Update snapshot entry
+          snapshot.files.set(filePath, {
+            ...fileEntry,
+            url: currentVersionedUrl,
+            head: fileHandle.heads(),
+          });
+
+          // Store for directory update
+          const fileName = filePath.split("/").pop() || "";
+          fileUrlUpdates.set(fileName, currentVersionedUrl);
+        }
+
+        // Update all file entries in the directory document
+        let didChange = false;
+        if (heads) {
+          dirHandle.changeAt(heads, (doc: DirectoryDocument) => {
+            for (const [fileName, newUrl] of fileUrlUpdates) {
+              const existingIndex = doc.docs.findIndex(
+                (entry) => entry.name === fileName && entry.type === "file"
+              );
+              if (existingIndex !== -1 && doc.docs[existingIndex].url !== newUrl) {
+                doc.docs[existingIndex].url = newUrl;
+                didChange = true;
+              }
+            }
+          });
+        } else {
+          dirHandle.change((doc: DirectoryDocument) => {
+            for (const [fileName, newUrl] of fileUrlUpdates) {
+              const existingIndex = doc.docs.findIndex(
+                (entry) => entry.name === fileName && entry.type === "file"
+              );
+              if (existingIndex !== -1 && doc.docs[existingIndex].url !== newUrl) {
+                doc.docs[existingIndex].url = newUrl;
+                didChange = true;
+              }
+            }
+          });
+        }
+
+        // Track directory and update heads
+        if (didChange) {
+          this.handlesByPath.set(dirPath, dirHandle);
+          if (snapshotEntry) {
+            snapshotEntry.head = dirHandle.heads();
+          }
+        }
+      } catch (error) {
+        out.taskLine(
+          `Warning: Failed to update file URLs in directory ${dirPath}`,
+          true
+        );
+      }
+    }
+  }
+
+  /**
+   * Update subdirectory URLs in parent directories with current heads.
+   * Processes leaf-first (deepest directories first).
+   */
+  private async updateSubdirectoryUrls(snapshot: SyncSnapshot): Promise<void> {
+    // Get all directory paths and sort leaf-first (deepest first)
+    const directoryPaths = Array.from(snapshot.directories.keys()).sort(
+      (a, b) => {
+        const depthA = a ? a.split("/").length : 0;
+        const depthB = b ? b.split("/").length : 0;
+
+        // Deepest first
+        if (depthA !== depthB) {
+          return depthB - depthA;
+        }
+
+        // Alphabetically by path
+        return a.localeCompare(b);
+      }
+    );
+
+    // Update each directory's URL in its parent
+    for (const dirPath of directoryPaths) {
+      // Skip root directory (has no parent)
+      if (!dirPath || dirPath === "") {
+        continue;
+      }
+
+      const dirEntry = snapshot.directories.get(dirPath);
+      if (!dirEntry) continue;
+
+      try {
+        // Get current handle for this directory (use plain URL to get mutable handle)
+        const dirHandle = await this.repo.find<DirectoryDocument>(
+          getPlainUrl(dirEntry.url)
+        );
+
+        // Get versioned URL with CURRENT heads (after all children populated)
+        const currentVersionedUrl = this.getVersionedUrl(dirHandle);
+
+        // Update snapshot entry with current heads and versioned URL
+        snapshot.directories.set(dirPath, {
+          ...dirEntry,
+          url: currentVersionedUrl,
+          head: dirHandle.heads(),
+        });
+
+        // Get parent path
+        const pathParts = dirPath.split("/");
+        const dirName = pathParts.pop() || "";
+        const parentPath = pathParts.join("/");
+
+        // Get parent directory handle
+        let parentDirUrl: AutomergeUrl;
+        if (!parentPath || parentPath === "") {
+          // Parent is root
+          if (!snapshot.rootDirectoryUrl) continue;
+          parentDirUrl = snapshot.rootDirectoryUrl;
+        } else {
+          const parentEntry = snapshot.directories.get(parentPath);
+          if (!parentEntry) continue;
+          parentDirUrl = parentEntry.url;
+        }
+
+        // Update the directory entry in the parent with the new versioned URL
+        const parentHandle = await this.repo.find<DirectoryDocument>(
+          getPlainUrl(parentDirUrl)
+        );
+
+        // Get parent's current heads for changeAt
+        const parentSnapshotEntry =
+          parentPath === ""
+            ? snapshot.directories.get("")
+            : snapshot.directories.get(parentPath);
+        const parentHeads = parentSnapshotEntry?.head;
+
+        let didChange = false;
+        if (parentHeads) {
+          parentHandle.changeAt(parentHeads, (doc: DirectoryDocument) => {
+            const existingIndex = doc.docs.findIndex(
+              (entry) => entry.name === dirName && entry.type === "folder"
+            );
+            if (existingIndex !== -1) {
+              // Update the URL with current versioned URL
+              doc.docs[existingIndex].url = currentVersionedUrl;
+              didChange = true;
+            }
+          });
+        } else {
+          parentHandle.change((doc: DirectoryDocument) => {
+            const existingIndex = doc.docs.findIndex(
+              (entry) => entry.name === dirName && entry.type === "folder"
+            );
+            if (existingIndex !== -1) {
+              // Update the URL with current versioned URL
+              doc.docs[existingIndex].url = currentVersionedUrl;
+              didChange = true;
+            }
+          });
+        }
+
+        // Track parent for sync and update its heads in snapshot
+        if (didChange) {
+          this.handlesByPath.set(parentPath, parentHandle);
+          if (parentSnapshotEntry) {
+            parentSnapshotEntry.head = parentHandle.heads();
+          }
+        }
+      } catch (error) {
+        out.taskLine(
+          `Warning: Failed to update directory URL for ${dirPath}`,
+          true
+        );
+      }
     }
   }
 }