pivot 0.3.3__tar.gz → 0.3.4__tar.gz

{pivot-0.3.3 → pivot-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pivot
-Version: 0.3.3
+Version: 0.3.4
 Summary: High-performance Python pipeline tool with automatic code change detection
 Author: Sami Jawhar
 Author-email: Sami Jawhar <sami@metr.org>

{pivot-0.3.3 → pivot-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pivot"
-version = "0.3.3"
+version = "0.3.4"
 description = "High-performance Python pipeline tool with automatic code change detection"
 requires-python = ">=3.13,<3.14"
 readme = "README.md"

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/cli/checkout.py

@@ -74,11 +74,15 @@ def _on_disk_matches_expected(
     if is_dir_hash(expected_hash):
         if not path.is_dir():
             return False
-        actual_hash, _ = cache.hash_directory(path, cache_dir=cache_dir)
-    else:
-        if not path.is_file():
-            return False
-        actual_hash, _ = cache.hash_file(path)
+        actual = cache.hash_directory(path, cache_dir=cache_dir)
+        # A hash pivot 0.3.3 recorded lists no empty directories, and repro still honors it.
+        # When only empty directories differ, checkout would change no file, so it matches.
+        return actual["hash"] == expected_hash["hash"] or (
+            "empty_dirs" not in expected_hash and actual["manifest"] == expected_hash["manifest"]
+        )
+    if not path.is_file():
+        return False
+    actual_hash, _ = cache.hash_file(path)
     return actual_hash == expected_hash["hash"]
 
 

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/cli/track.py

@@ -154,9 +154,10 @@ def _track_single_path(
 
     # Hash and cache
     if path.is_dir():
-        tree_hash, manifest = cache.hash_directory(
+        dir_hash = cache.hash_directory(
             path, cache_dir=cache_dir, warn_left_out_symlinks=warn_left_out_symlinks
         )
+        manifest = dir_hash["manifest"]
         total_size = sum(e["size"] for e in manifest)
         num_files = len(manifest)
 
@@ -171,11 +172,13 @@ def _track_single_path(
 
         pvt_data: track_mod.PvtData = {
             "path": path.name,
-            "hash": tree_hash,
+            "hash": dir_hash["hash"],
             "size": total_size,
             "num_files": num_files,
             "manifest": manifest,
         }
+        if "empty_dirs" in dir_hash:
+            pvt_data["empty_dirs"] = dir_hash["empty_dirs"]
     else:
         file_hash, _ = cache.hash_file(path)
         file_size = path.stat().st_size

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/executor/core.py

@@ -409,7 +409,7 @@ def verify_tracked_files(project_root: pathlib.Path, checkout_missing: bool = Fa
                 if path.is_file():
                     current_hash, _ = cache.hash_file(path, state_db)
                 elif path.is_dir():
-                    current_hash, _ = cache.hash_directory(path, state_db, cache_dir=cache_dir)
+                    current_hash = cache.hash_directory(path, state_db, cache_dir=cache_dir)["hash"]
                 else:
                     # Path doesn't exist
                     raise FileNotFoundError(data_path)

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/executor/worker.py

@@ -39,7 +39,6 @@ from pivot.storage import artifact_lock, cache, lock, state
 from pivot.storage import store as store_mod
 from pivot.types import (
     DeferredWrites,
-    DirHash,
     FileHash,
     HashInfo,
     LockData,
@@ -631,8 +630,7 @@ def hash_output(
     ``cache_dir`` is the cache object root whose symlinks count as directory content.
     """
     if path.is_dir():
-        tree_hash, manifest = cache.hash_directory(path, state_db, cache_dir=cache_dir)
-        return DirHash(hash=tree_hash, manifest=manifest)
+        return cache.hash_directory(path, state_db, cache_dir=cache_dir)
     file_hash, _ = cache.hash_file(path, state_db)
     return FileHash(hash=file_hash)
 
@@ -1063,12 +1061,9 @@ def _hash_output_paths(
         if not path.exists():
             raise exceptions.OutputMissingError(f"Stage did not produce output: {path}")
         if path.is_dir():
-            tree_hash, manifest = cache.hash_directory(
+            output_hashes[types.identity_key(ref.identity)] = cache.hash_directory(
                 path, state_db, cache_dir=cache_dir, warn_left_out_symlinks=True
             )
-            output_hashes[types.identity_key(ref.identity)] = DirHash(
-                hash=tree_hash, manifest=manifest
-            )
         else:
             file_hash, _ = cache.hash_file(path, state_db)
             output_hashes[types.identity_key(ref.identity)] = FileHash(hash=file_hash)
@@ -1290,8 +1285,7 @@ def hash_dependencies(
             path = pathlib.Path(normalized_path)
             try:
                 if path.is_dir():
-                    tree_hash, manifest = cache.hash_directory(path, state_db)
-                    hashes[dep] = DirHash(hash=tree_hash, manifest=manifest)
+                    hashes[dep] = cache.hash_directory(path, state_db)
                 else:
                     file_hash, fs_stat = cache.hash_file(path, state_db)
                     hashes[dep] = FileHash(hash=file_hash)

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/explain.py

@@ -14,7 +14,7 @@ import pydantic
 
 from pivot import parameters, project, registry, skip, types
 from pivot.executor import worker
-from pivot.storage import lock, state
+from pivot.storage import lock, state, track
 from pivot.storage import store as store_mod
 from pivot.types import (
     ArtifactIdentity,
@@ -30,8 +30,6 @@ if TYPE_CHECKING:
 
     import pygtrie
 
-    from pivot.storage.track import PvtData
-
 OUTPUTS_MISSING_REASON = "Outputs missing from cache"
 """Reason for a stage whose lock is current but whose cacheable outputs are absent locally.
 
@@ -105,7 +103,7 @@ def _find_tracked_ancestor(dep: Path, tracked_trie: pygtrie.Trie[str]) -> Path |
 
 def _find_tracked_hash(
     dep: Path,
-    tracked_files: dict[str, PvtData],
+    tracked_files: dict[str, track.PvtData],
     tracked_trie: pygtrie.Trie[str],
 ) -> HashInfo | None:
     """Find hash for dep from tracked files data.
@@ -121,9 +119,7 @@ def _find_tracked_hash(
 
     # Exact match - use top-level hash
     if dep == tracked_path:
-        if "manifest" in pvt_data:
-            return {"hash": pvt_data["hash"], "manifest": pvt_data["manifest"]}
-        return {"hash": pvt_data["hash"]}
+        return track.pvt_to_hash_info(pvt_data)
 
     # Nested path - find in manifest
     if "manifest" not in pvt_data:
@@ -155,7 +151,7 @@ def get_stage_explanation(
     lock_data: LockData | None,
     force: bool = False,
     allow_missing: bool = False,
-    tracked_files: dict[str, PvtData] | None = None,
+    tracked_files: dict[str, track.PvtData] | None = None,
     tracked_trie: pygtrie.Trie[str] | None = None,
     producer_hashes: dict[ArtifactIdentity, HashInfo] | None = None,
 ) -> StageExplanation:

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/remote/sync.py

@@ -11,7 +11,7 @@ from pivot.remote import config as remote_config
 from pivot.remote import storage as remote_mod
 from pivot.storage import cache, lock, track
 from pivot.storage import store as store_mod
-from pivot.types import DirHash, FileHash, HashInfo, RemoteStatus, TransferSummary, is_dir_hash
+from pivot.types import HashInfo, RemoteStatus, TransferSummary, is_dir_hash
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -175,9 +175,7 @@ def _get_file_hash_from_pvt(rel_path: str, proj_root: pathlib.Path) -> HashInfo
     if track_data is None:
         return None
 
-    if "manifest" in track_data:
-        return DirHash(hash=track_data["hash"], manifest=track_data["manifest"])
-    return FileHash(hash=track_data["hash"])
+    return track.pvt_to_hash_info(track_data)
 
 
 def _get_tracked_hashes(proj_root: pathlib.Path) -> set[str]:

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/run_history.py

@@ -64,6 +64,7 @@ class OutputHashEntry(TypedDict):
     path: str
     hash: str
     manifest: NotRequired[list[DirManifestEntry]]
+    empty_dirs: NotRequired[list[str]]
 
 
 def output_hash_to_entry(path: str, oh: HashInfo) -> OutputHashEntry:
@@ -71,6 +72,8 @@ def output_hash_to_entry(path: str, oh: HashInfo) -> OutputHashEntry:
     entry = OutputHashEntry(path=path, hash=oh["hash"])
     if is_dir_hash(oh):
         entry["manifest"] = oh["manifest"]
+        if "empty_dirs" in oh:
+            entry["empty_dirs"] = oh["empty_dirs"]
     return entry
 
 
@@ -78,7 +81,10 @@ def entry_to_output_hash(entry: OutputHashEntry) -> FileHash | DirHash:
     """Convert serialized OutputHashEntry back to internal HashInfo."""
     # Null check guards against corrupted JSON where manifest could be null
     if "manifest" in entry and entry["manifest"] is not None:  # pyright: ignore[reportUnnecessaryComparison]
-        return DirHash(hash=entry["hash"], manifest=entry["manifest"])
+        dir_hash = DirHash(hash=entry["hash"], manifest=entry["manifest"])
+        if "empty_dirs" in entry and entry["empty_dirs"]:
+            dir_hash["empty_dirs"] = entry["empty_dirs"]
+        return dir_hash
     return FileHash(hash=entry["hash"])
 
 

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/status.py

@@ -356,7 +356,7 @@ def get_tracked_files_status(
 
             try:
                 if path.is_dir():
-                    current_hash, _ = cache.hash_directory(path, state_db, cache_dir=cache_dir)
+                    current_hash = cache.hash_directory(path, state_db, cache_dir=cache_dir)["hash"]
                 else:
                     current_hash, _ = cache.hash_file(path, state_db)
             except FileNotFoundError:

{pivot-0.3.3 → pivot-0.3.4}/src/pivot/storage/cache.py

@@ -9,6 +9,7 @@ import logging
 import mmap
 import os
 import pathlib
+import posixpath
 import secrets
 import shutil
 import stat
@@ -25,7 +26,7 @@ from pivot.types import DirHash, DirManifestEntry, FileHash, HashInfo, is_dir_ha
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Generator
+    from collections.abc import Callable, Generator, Iterable
 
     from pivot.storage import state as state_mod
 
@@ -186,7 +187,10 @@ def _cache_object_key(path: pathlib.Path, cache_dir: pathlib.Path | None) -> str
 
 
 def _scandir_recursive(
-    path: pathlib.Path, cache_dir: pathlib.Path | None, left_out: list[pathlib.Path]
+    path: pathlib.Path,
+    cache_dir: pathlib.Path | None,
+    left_out: list[pathlib.Path],
+    dirs: list[pathlib.Path],
 ) -> Generator[os.DirEntry[str]]:
     """Yield every file under `path` recursively, using os.scandir() for efficiency.
 
@@ -202,6 +206,7 @@ def _scandir_recursive(
         path: Directory to scan
         cache_dir: Cache object root whose links count as content, or None for no cache
         left_out: Collects the symlinks that are not part of the artifact
+        dirs: Collects every directory under ``path`` (symlinked directories are not followed)
     """
     with os.scandir(path) as entries:
         for entry in entries:
@@ -213,7 +218,38 @@ def _scandir_recursive(
             elif entry.is_file():
                 yield entry
             elif entry.is_dir():
-                yield from _scandir_recursive(pathlib.Path(entry.path), cache_dir, left_out)
+                dirs.append(pathlib.Path(entry.path))
+                yield from _scandir_recursive(pathlib.Path(entry.path), cache_dir, left_out, dirs)
+
+
+def _parent_dirs(relpaths: Iterable[str]) -> set[str]:
+    """Every directory above each relpath, short of the root, as relpaths."""
+    return {
+        str(parent) for relpath in relpaths for parent in pathlib.PurePath(relpath).parents[:-1]
+    }
+
+
+def _recorded_empty_dirs(output_hash: DirHash) -> list[str]:
+    return output_hash["empty_dirs"] if "empty_dirs" in output_hash else []
+
+
+def _restored_dirs(output_hash: DirHash) -> set[str]:
+    """Every directory a restore of ``output_hash`` creates under its root, as relpaths."""
+    empty_dirs = _recorded_empty_dirs(output_hash)
+    file_parents = _parent_dirs(entry["relpath"] for entry in output_hash["manifest"])
+    return file_parents | _parent_dirs(empty_dirs) | set(empty_dirs)
+
+
+def _empty_dir_path(root: pathlib.Path, relpath: str) -> pathlib.Path:
+    """Return where the recorded empty directory ``relpath`` belongs under ``root``.
+
+    ``relpath`` may come straight from a lock file, so one leading outside ``root`` is refused,
+    as the file-by-file restore refuses a manifest entry's.
+    """
+    target = root / relpath
+    if not target.resolve().is_relative_to(root.resolve()):
+        raise exceptions.SecurityValidationError(f"Manifest contains path traversal: {relpath!r}")
+    return target
 
 
 def _warn_left_out_symlinks(path: pathlib.Path, left_out: list[pathlib.Path]) -> None:
@@ -239,8 +275,12 @@ def hash_directory(
     *,
     cache_dir: pathlib.Path | None = None,
     warn_left_out_symlinks: bool = False,
-) -> tuple[str, list[DirManifestEntry]]:
-    """Compute tree hash of directory, returning hash and manifest.
+) -> DirHash:
+    """Compute the tree hash of a directory, returning it with the manifest.
+
+    The hash covers the manifest and the directory's empty directories (see ``DirHash``). With
+    no empty directories it hashes the manifest alone, so recording them changed no hash of a
+    directory that holds none.
 
     Symlink handling:
     - A symlink to an object in ``cache_dir`` is hashed by its target's content under its own
@@ -263,9 +303,10 @@ def hash_directory(
     _t = metrics.start()
     manifest = list[DirManifestEntry]()
     left_out = list[pathlib.Path]()
+    dirs = list[pathlib.Path]()
     resolved_base = path.resolve()
 
-    for entry in sorted(_scandir_recursive(path, cache_dir, left_out), key=lambda e: e.path):
+    for entry in sorted(_scandir_recursive(path, cache_dir, left_out, dirs), key=lambda e: e.path):
         file_path = pathlib.Path(entry.path)
         # Verify a regular file is still within the directory (paranoid check). A cache-object
         # link resolves into the cache by design.
@@ -291,11 +332,20 @@ def hash_directory(
     if left_out and warn_left_out_symlinks:
         _warn_left_out_symlinks(path, left_out)
 
-    manifest_json = json.dumps(manifest, sort_keys=True, separators=(",", ":"))
-    tree_hash = xxhash.xxh64(manifest_json.encode()).hexdigest()
+    # A deepest empty directory holds no stored file and no other directory.
+    found_dirs = {str(directory.relative_to(path)) for directory in dirs}
+    file_dirs = {posixpath.dirname(entry["relpath"]) for entry in manifest}
+    has_child = {posixpath.dirname(directory) for directory in found_dirs}
+    empty_dirs = sorted(found_dirs - file_dirs - has_child)
+
+    hashed: object = {"empty_dirs": empty_dirs, "manifest": manifest} if empty_dirs else manifest
+    hashed_json = json.dumps(hashed, sort_keys=True, separators=(",", ":"))
+    output_hash = DirHash(hash=xxhash.xxh64(hashed_json.encode()).hexdigest(), manifest=manifest)
+    if empty_dirs:
+        output_hash["empty_dirs"] = empty_dirs
 
     metrics.end("cache.hash_directory", _t)
-    return tree_hash, manifest
+    return output_hash
 
 
 _VALID_HASH_CHARS = frozenset("0123456789abcdef")
@@ -586,6 +636,85 @@ def _repair_tree_dir_isexec(cache_dir_path: pathlib.Path, manifest: list[DirMani
             os.chmod(f, 0o555)
 
 
+_TREE_LAYOUT_MARKER_SUFFIX = ".layout-checked"
+
+
+def _tree_layout_marker(cache_dir_path: pathlib.Path) -> pathlib.Path:
+    """Return the file beside a whole-directory SYMLINK cache tree that records its layout
+    holds exactly what its hash records. The name is never a cache key, so cache scans skip it.
+    """
+    return cache_dir_path.with_name(cache_dir_path.name + _TREE_LAYOUT_MARKER_SUFFIX)
+
+
+def _ensure_tree_dir_layout(cache_dir_path: pathlib.Path, output_hash: DirHash) -> None:
+    """Repair a whole-directory SYMLINK cache tree's layout once, not on every restore.
+
+    Only this pivot records ``empty_dirs``, so a tree whose hash records them was built by it
+    and needs no check. Any other tree is checked once and then marked.
+    """
+    if "empty_dirs" in output_hash:
+        return
+    marker = _tree_layout_marker(cache_dir_path)
+    if marker.exists():
+        return
+    _repair_tree_dir_layout(cache_dir_path, output_hash)
+    # The marker only saves a walk; a cache the restoring user cannot write still restores.
+    with contextlib.suppress(OSError):
+        marker.touch()
+
+
+def _repair_tree_dir_layout(cache_dir_path: pathlib.Path, output_hash: DirHash) -> None:
+    """Give a whole-directory SYMLINK cache tree exactly the files and directories
+    ``output_hash`` records.
+
+    A tree an older pivot built can hold entries its hash does not record: directories its hash
+    left out because they were empty, and copies of the targets of symlinks its hash left out.
+    The tree's name never changes, so neither _store_directory's ``not cache_dir_path.exists()``
+    branch nor the symlink_fast_path restore would otherwise revisit it, and an output restored
+    through it would not hash to the hash it was restored for. Changing the tree in place is
+    safe for the reason ``_repair_tree_dir_isexec`` gives.
+    """
+    found_files, found = _scan_entries(cache_dir_path)
+    found_dirs = set(found)
+    unlisted = set(found_files) - {entry["relpath"] for entry in output_hash["manifest"]}
+    extra_dirs = found_dirs - _restored_dirs(output_hash)
+    missing = [
+        _empty_dir_path(cache_dir_path, relpath)
+        for relpath in _recorded_empty_dirs(output_hash)
+        if relpath not in found_dirs
+    ]
+    if not unlisted and not extra_dirs and not missing:
+        return
+    modes = dict[pathlib.Path, int]()
+
+    def _make_writable(directory: pathlib.Path) -> None:
+        if directory not in modes:
+            modes[directory] = directory.stat().st_mode
+            os.chmod(directory, modes[directory] | stat.S_IWUSR)
+
+    try:
+        for relpath in unlisted:
+            target = cache_dir_path / relpath
+            _make_writable(target.parent)
+            target.unlink(missing_ok=True)
+        # Reverse order reaches a directory's children before the directory itself.
+        for relpath in sorted(extra_dirs, reverse=True):
+            target = cache_dir_path / relpath
+            _make_writable(target.parent)
+            modes.pop(target, None)
+            with contextlib.suppress(FileNotFoundError):  # a concurrent repair got there first
+                target.rmdir()
+        for target in missing:
+            existing = target.parent
+            while not existing.exists():
+                existing = existing.parent
+            _make_writable(existing)
+            target.mkdir(parents=True, exist_ok=True)
+    finally:
+        for directory, mode in modes.items():
+            os.chmod(directory, mode)
+
+
 def _checkout_with_fallback(
     path: pathlib.Path,
     cache_path: pathlib.Path,
@@ -763,18 +892,17 @@ def _save_directory_to_cache(
     state_dir: pathlib.Path | None,
 ) -> DirHash:
     """Save directory to cache."""
-    # Idempotency check for SYMLINK mode
-    if checkout_modes and checkout_modes[0] == CheckoutMode.SYMLINK and path.is_symlink():
-        existing_hash = _get_symlink_cache_hash(path, cache_dir)
-        if existing_hash is not None:
-            cache_dir_path = get_cache_path(cache_dir, existing_hash)
-            if cache_dir_path.exists():
-                # Already correctly linked - compute manifest from actual content
-                _, manifest = hash_directory(path, state_db, cache_dir=cache_dir)
-                return DirHash(hash=existing_hash, manifest=manifest)
-
-    tree_hash, manifest = hash_directory(path, state_db, cache_dir=cache_dir)
-    output_hash = DirHash(hash=tree_hash, manifest=manifest)
+    output_hash = hash_directory(path, state_db, cache_dir=cache_dir)
+    # Idempotency check for SYMLINK mode: already linked to the tree its content hashes to
+    if (
+        checkout_modes
+        and checkout_modes[0] == CheckoutMode.SYMLINK
+        and path.is_symlink()
+        and _get_symlink_cache_hash(path, cache_dir) == output_hash["hash"]
+        and get_cache_path(cache_dir, output_hash["hash"]).exists()
+    ):
+        return output_hash
+
     _store_directory(
         path,
         output_hash,
@@ -808,7 +936,17 @@ def _store_directory(
             cache_dir_path = get_cache_path(cache_dir, output_hash["hash"])
             if not cache_dir_path.exists():
                 cache_dir_path.parent.mkdir(parents=True, exist_ok=True)
-                shutil.copytree(path, cache_dir_path)
+
+                def _user_symlinks(directory: str, names: list[str]) -> list[str]:
+                    # Not stored (see _scandir_recursive); copytree would copy each target.
+                    return [
+                        name
+                        for name in names
+                        if (link := pathlib.Path(directory, name)).is_symlink()
+                        and _cache_object_key(link, cache_dir) is None
+                    ]
+
+                shutil.copytree(path, cache_dir_path, ignore=_user_symlinks)
                 isexec_by_relpath = {entry["relpath"]: entry["isexec"] for entry in manifest}
                 for f in cache_dir_path.rglob("*"):
                     # Skip symlinks to avoid changing permissions on target files outside cache
@@ -817,11 +955,14 @@ def _store_directory(
                         executable = isexec_by_relpath.get(relpath, False)
                         os.chmod(f, 0o555 if executable else 0o444)
                 os.chmod(cache_dir_path, 0o555)
+                with contextlib.suppress(OSError):
+                    _tree_layout_marker(cache_dir_path).touch()
 
-            # A tree an older pivot built keeps its 0o444-everywhere files forever otherwise:
-            # the tree hash already incorporates isexec, so this branch never revisits an
-            # existing tree directory above.
+            # A tree an older pivot built keeps its 0o444-everywhere files, and entries its hash
+            # does not record, forever otherwise: its name never changes, so this branch never
+            # revisits an existing tree directory above.
             _repair_tree_dir_isexec(cache_dir_path, manifest)
+            _ensure_tree_dir_layout(cache_dir_path, output_hash)
 
             _clear_path(path)
             path.symlink_to(cache_dir_path.resolve())
@@ -994,10 +1135,11 @@ def _restore_directory_from_cache(
     restore_prefix = f"{_RESTORE_TEMP_PREFIX}{target_token}."
 
     if symlink_fast_path:
-        # Same repair as _store_directory: a tree an older pivot built keeps its
-        # 0o444-everywhere files forever otherwise, since the tree hash already
-        # incorporates isexec and this path never rebuilds an existing tree directory.
+        # Same repairs as _store_directory: a tree an older pivot built keeps its
+        # 0o444-everywhere files, and entries its hash does not record, forever otherwise,
+        # since this path never rebuilds an existing tree directory.
         _repair_tree_dir_isexec(cache_dir_path, output_hash["manifest"])
+        _ensure_tree_dir_layout(cache_dir_path, output_hash)
         temp_symlink = path.parent / f"{restore_prefix}symlink_{secrets.token_hex(4)}"
         try:
             temp_symlink.symlink_to(cache_dir_path.resolve())
@@ -1039,6 +1181,9 @@ def _restore_directory_from_cache(
                 except OSError as e:
                     logger.debug(f"mtime refresh failed (may be NFS with root_squash): {e}")
 
+        for relpath in _recorded_empty_dirs(output_hash):
+            _empty_dir_path(temp_path, relpath).mkdir(parents=True, exist_ok=True)
+
         try:
             os.utime(temp_path, None)
         except OSError as e:
@@ -1090,7 +1235,7 @@ def remove_output(path: pathlib.Path) -> None:
 class MissingRestore(TypedDict):
     """Outcome of restore_missing_in_directory."""
 
-    restored: int  # missing files restored in place
+    restored: int  # missing files and empty directories restored in place
     unavailable: int  # missing files whose blob is not in the cache
     local_changes: list[str]  # changed or extra files whose content the cache lacks
     replace: bool  # directory holds only cached content but not the target: replace it whole
@@ -1104,12 +1249,13 @@ def _is_cached(cache_dir: pathlib.Path, content_hash: str | None) -> bool:
     )
 
 
-def _scan_entries(path: pathlib.Path) -> list[str]:
-    """Return every file and symlink under ``path`` as relative paths.
+def _scan_entries(path: pathlib.Path) -> tuple[list[str], list[str]]:
+    """Return every file and symlink, and every directory, under ``path`` as relative paths.
 
-    Symlinked directories are not followed.
+    Symlinked directories count as symlinks and are not followed.
     """
     files = list[str]()
+    dirs = list[str]()
 
     def _walk(directory: pathlib.Path) -> None:
         with os.scandir(directory) as entries:
@@ -1119,10 +1265,11 @@ def _scan_entries(path: pathlib.Path) -> list[str]:
                 if entry.is_symlink() or entry.is_file():
                     files.append(relpath)
                 elif entry.is_dir():
+                    dirs.append(relpath)
                     _walk(entry_path)
 
     _walk(path)
-    return files
+    return files, dirs
 
 
 def _is_same_file(file_stat: os.stat_result, cache_path: pathlib.Path) -> bool:
@@ -1142,12 +1289,13 @@ def restore_missing_in_directory(
     checkout_modes: list[CheckoutMode],
     state_db: state_mod.StateDB | None = None,
 ) -> MissingRestore:
-    """Restore missing target files without overwriting local changes.
+    """Restore missing target files and empty directories without overwriting local changes.
 
-    When every existing file matches the target, missing files are restored in place. When a
-    file differs from the target or an extra file exists, only a whole-directory swap can
-    restore the target. The swap is safe only when every file it removes is in the cache;
-    otherwise the local changes are returned without writing anything.
+    When every existing file matches the target, missing files and empty directories are
+    restored in place. When a file differs from the target or an extra file or directory
+    exists, only a whole-directory swap can restore the target. The swap is safe only when
+    every file it removes is in the cache (an extra empty directory removes none); otherwise
+    the local changes are returned without writing anything.
 
     A retained file is read only when nothing else proves its content: a symlink to the
     target's cache path, a hardlink to the target's cache blob, or a matching ``state_db``
@@ -1198,7 +1346,15 @@ def restore_missing_in_directory(
             )
         missing.append((entry, file_path, file_cache_path))
 
-    files = _scan_entries(path)
+    missing_dirs = [
+        dir_path
+        for dir_path in (
+            _empty_dir_path(path, relpath) for relpath in _recorded_empty_dirs(output_hash)
+        )
+        if not dir_path.exists() and not dir_path.is_symlink()
+    ]
+
+    files, dirs = _scan_entries(path)
     for relpath in files:
         if relpath in expected_paths:
             continue
@@ -1207,8 +1363,12 @@ def restore_missing_in_directory(
             changed[relpath] = _get_symlink_cache_hash(extra_path, cache_dir)
         else:
             changed[relpath], _ = hash_file(extra_path, state_db)
+    # A hash pivot 0.3.3 recorded lists no empty directories, so on disk none of them is extra.
+    extra_dirs = (
+        set(dirs) - _restored_dirs(output_hash) if "empty_dirs" in output_hash else set[str]()
+    )
 
-    if changed:
+    if changed or extra_dirs:
         # Replacing the directory deletes every file it holds; refuse if any is not cached.
         local_changes = sorted(
             rel for rel, content_hash in changed.items() if not _is_cached(cache_dir, content_hash)
@@ -1228,8 +1388,12 @@ def restore_missing_in_directory(
         _checkout_with_fallback(
             file_path, file_cache_path, checkout_modes, executable=entry["isexec"]
         )
+    for dir_path in missing_dirs:
+        dir_path.mkdir(parents=True, exist_ok=True)
 
-    return MissingRestore(restored=len(missing), unavailable=0, local_changes=[], replace=False)
+    return MissingRestore(
+        restored=len(missing) + len(missing_dirs), unavailable=0, local_changes=[], replace=False
+    )
 
 
 def protect(path: pathlib.Path) -> None: