fix(sidecars): carry the identity map through a sidecar root move

A model root that moved earlier is mirrored under a pinned name derived
from its old path. If anything resolved against the new sidecar path before
the relocation ran, the destination got a map naming the mirror after the
*current* path. migrate_root's keep-newer transfer then dropped the source
map, so the moved metadata stayed orphaned under the pinned component while
reads followed the new name and rebuilt defaults — losing favorites, notes
and tags a second time.

The identity map is now relocated by relocate_root_map() instead of the
generic transfer: entries recorded under the old sidecar root win for the
roots they describe, destination-only entries are preserved, and the cache
is dropped so the next resolution reloads the merged map. A merge that
cannot be written is reported as a migration error rather than silently
stranding the moved metadata.

Reported by the Codex review on #1131.

py/services/use_cases/sidecar_migration_use_case.py

@@ -52,10 +52,12 @@ from ...utils.file_utils import find_preview_file, get_preview_extension
 from ...utils.metadata_manager import MetadataManager
 from ...utils.sidecar_paths import (
     METADATA_SUFFIX,
+    ROOT_MAP_FILENAME,
     STORAGE_MODE_CENTRALIZED,
     get_configured_sidecar_root,
     get_sidecar_root,
     get_storage_mode,
+    relocate_root_map,
     resolve_centralized_dir_for_dir,
 )
 
@@ -200,14 +202,19 @@ class SidecarMigrationUseCase:
             )
 
         files: List[Tuple[str, str]] = []
+        source_map_path = os.path.join(old, ROOT_MAP_FILENAME)
         if os.path.isdir(old):
             for dirpath, _dirnames, filenames in os.walk(old):
                 rel = os.path.relpath(dirpath, old)
                 target_dir = new_root if rel == os.curdir else os.path.join(new_root, rel)
                 for filename in filenames:
-                    files.append(
-                        (os.path.join(dirpath, filename), os.path.join(target_dir, filename))
-                    )
+                    source = os.path.join(dirpath, filename)
+                    # The identity map is handled by relocate_root_map below:
+                    # _transfer's keep-newer rule would let a destination map
+                    # written before the relocation displace it.
+                    if source == source_map_path:
+                        continue
+                    files.append((source, os.path.join(target_dir, filename)))
 
         errors: List[Dict[str, str]] = []
         counters: Dict[str, Any] = {"moved": 0, "conflicts": 0}
@@ -243,6 +250,23 @@ class SidecarMigrationUseCase:
                 errors.append({"model": os.path.basename(src), "error": str(exc)})
             await emit("processing", processed=index, current=os.path.basename(src))
 
+        # The identity map names the directories just moved, so it travels with
+        # them and wins over any map the destination acquired beforehand.
+        # A failure here strands the moved metadata, so it is a real error.
+        try:
+            if not relocate_root_map(old, new_root):
+                errors.append(
+                    {
+                        "model": ROOT_MAP_FILENAME,
+                        "error": "sidecar root map could not be written to the new root",
+                    }
+                )
+        except Exception as exc:
+            self._logger.error(
+                "Sidecar root relocation failed for the root map: %s", exc, exc_info=True
+            )
+            errors.append({"model": ROOT_MAP_FILENAME, "error": str(exc)})
+
         old_prefix = old.replace(os.sep, "/").rstrip("/") + "/"
         new_prefix = new_root.replace(os.sep, "/").rstrip("/") + "/"
         for sidecar in moved_sidecars: