fix(ci): bound Glaeda cache growth on the persistent Mac

docs/ci-runners.md

@@ -57,6 +57,14 @@ receives no repository secrets. Glaeda owns DerivedData, SwiftPM,
 module-cache, and Xcode compilation-cache persistence; every run still resolves
 packages and performs exact source/toolchain admission.
 
+Glaeda performs no automatic cache eviction, and each generation under
+`.glaeda/apple-build/cache/<key>/` holds a full cmux DerivedData tree, so a
+toolchain change would otherwise strand a multi-GB directory on the owned Mac
+indefinitely. After a verified compile, `run-persistent-mac-compile.py` stamps
+the generation it used and deletes all but the three most recently used ones,
+logging each removal and recording it in the admission metrics. The generation
+in use is never a candidate; an evicted generation costs only a cold rebuild.
+
 Rollout is reversible through two repository variables:
 
 - `CI_PERSISTENT_MAC_COMPILE=off` (or unset): hosted path only;

scripts/ci/run-persistent-mac-compile.py

@@ -19,6 +19,16 @@
 PROFILE = "ci-compile-admission"
 BASE_GENERATION = "cmux-ci-v1"
 QUARANTINE_RETAINED_STORES = 1
+# Glaeda performs no automatic eviction of its own cache generations
+# (docs/APPLE_NATIVE_BUILDS.md: "this prototype performs no automatic eviction
+# or broad cache cleanup"). Each generation under
+# .glaeda/apple-build/cache/<key>/ holds a full cmux DerivedData tree, so every
+# Xcode or SDK bump strands a multi-GB directory on the owned Mac forever.
+# Retain this run's generation plus the two most recently used others: enough
+# to survive a toolchain bump and a rollback back onto the previous generation
+# without a cold rebuild, while keeping disk bounded.
+CACHE_RETAINED_GENERATIONS = 3
+CACHE_GENERATION_KEY = re.compile(r"[a-f0-9]{64}")
 STATE_RESET_REASONS = (
     "state belongs to another checkout",
     "existing Apple state is incomplete",
@@ -136,6 +146,54 @@ def prune_quarantine_stores(project: Path, keep: Path | None = None) -> None:
         print(f"Pruned obsolete Glaeda quarantine {path.name}")
 
 
+def prune_cache_generations(project: Path, keep_key: str | None = None) -> list[str]:
+    """Bound Glaeda cache growth, which Glaeda itself never bounds.
+
+    Ordering is by directory mtime, which `main` stamps on the generation it
+    used immediately before calling this. That makes the ordering an explicit
+    least-recently-used record rather than an accident of what Xcode last wrote
+    deep inside the tree: writes under `derived_data/` do not touch the
+    generation directory's own mtime, so an unstamped warm generation could
+    otherwise look older than a cold one.
+
+    Only directories whose names are Glaeda cache keys are candidates, and the
+    key this run used is never one. Deleting the wrong generation costs a cold
+    rebuild, not correctness, so every ambiguous entry is left in place.
+    """
+    parent = project / ".glaeda" / "apple-build" / "cache"
+    if not parent.is_dir():
+        return []
+    candidates: list[tuple[int, Path]] = []
+    with os.scandir(parent) as entries:
+        for entry in entries:
+            if not CACHE_GENERATION_KEY.fullmatch(entry.name):
+                continue
+            if not (entry.is_dir(follow_symlinks=False) or entry.is_symlink()):
+                continue
+            info = entry.stat(follow_symlinks=False)
+            candidates.append((info.st_mtime_ns, Path(entry.path)))
+    candidates.sort(reverse=True)
+    retained: set[str] = set()
+    if keep_key is not None:
+        retained.add(keep_key)
+    pruned: list[str] = []
+    for _, path in candidates:
+        if path.name in retained:
+            continue
+        if len(retained) < CACHE_RETAINED_GENERATIONS:
+            retained.add(path.name)
+            continue
+        if path.parent != parent or not CACHE_GENERATION_KEY.fullmatch(path.name):
+            raise Refusal("refusing to prune a path outside the cmux Glaeda cache")
+        if path.is_symlink():
+            path.unlink()
+        else:
+            shutil.rmtree(path)
+        pruned.append(path.name)
+        print(f"Pruned obsolete Glaeda cache generation {path.name}")
+    return pruned
+
+
 def quarantine_state(project: Path, request_id: str) -> Path | None:
     state = apple_state(project)
     if not os.path.lexists(state):
@@ -467,6 +525,12 @@ def main() -> int:
     if not build_log.is_file() or not products.is_dir():
         raise Refusal("native compile completed without the admission log/products")
 
+    # Stamp the generation this run used, then evict the least recently used
+    # others. Pruning only after a verified-good compile means a failed run
+    # never deletes a generation on the strength of an unvalidated plan.
+    os.utime(resolved_cache)
+    pruned_cache_generations = prune_cache_generations(project, keep_key=cache_key)
+
     classification = (
         "cold-reset"
         if reset_reasons or initial_state == "cold"
@@ -508,6 +572,7 @@ def main() -> int:
             "reset_reasons": reset_reasons,
             "cache_key": plan.get("cache_key"),
             "invocation_identity": plan.get("invocation_identity"),
+            "pruned_cache_generations": pruned_cache_generations,
             "native_timings_seconds": native_timings if isinstance(native_timings, dict) else {},
             "native_work": native_work if isinstance(native_work, dict) else {},
         },

tests/test_ci_persistent_mac_compile.py

@@ -6,6 +6,7 @@
 import argparse
 import importlib.util
 import json
+import os
 from pathlib import Path
 import tempfile
 import unittest
@@ -218,6 +219,128 @@ def test_quarantine_pruning_keeps_only_newest_owned_store(self):
             self.assertEqual(remaining[0].name, old[-1].name)
             self.assertTrue(unrelated.is_dir())
 
+    @staticmethod
+    def _cache_generation(root: Path, index: int, mtime: int) -> Path:
+        """A fake Glaeda cache generation: a 64-hex key holding a DerivedData tree."""
+        path = root / f"{index:064x}"
+        (path / "derived_data" / "Build" / "Products" / "Debug").mkdir(parents=True)
+        (path / "derived_data" / "cmux-build.log").write_text(str(index))
+        os.utime(path, ns=(mtime, mtime))
+        return path
+
+    def test_cache_pruning_keeps_the_current_and_most_recent_generations(self):
+        with tempfile.TemporaryDirectory() as directory:
+            project = Path(directory)
+            cache = project / ".glaeda" / "apple-build" / "cache"
+            cache.mkdir(parents=True)
+            # index 0 is oldest, index 5 newest; the current run uses the oldest,
+            # which must survive precisely because it is the one in use.
+            generations = [
+                self._cache_generation(cache, index, 1_000_000_000 + index)
+                for index in range(6)
+            ]
+            current = generations[0]
+            # Neither of these is a cache key, so neither may ever be a candidate.
+            stray_file = cache / "README"
+            stray_file.write_text("not a generation")
+            stray_dir = cache / "scratch"
+            stray_dir.mkdir()
+
+            pruned = driver.prune_cache_generations(project, keep_key=current.name)
+
+            survivors = {path.name for path in cache.iterdir()}
+            expected = {
+                current.name,
+                generations[-1].name,
+                generations[-2].name,
+                stray_file.name,
+                stray_dir.name,
+            }
+            self.assertEqual(survivors, expected)
+            self.assertEqual(
+                sorted(pruned),
+                sorted(path.name for path in generations[1:-2]),
+            )
+            self.assertTrue((current / "derived_data" / "cmux-build.log").is_file())
+            self.assertEqual(
+                len(survivors) - 2, driver.CACHE_RETAINED_GENERATIONS
+            )
+
+    def test_cache_pruning_never_evicts_the_generation_in_use(self):
+        """Even as the least recently used generation, the current key survives."""
+        with tempfile.TemporaryDirectory() as directory:
+            project = Path(directory)
+            cache = project / ".glaeda" / "apple-build" / "cache"
+            cache.mkdir(parents=True)
+            generations = [
+                self._cache_generation(cache, index, 1_000_000_000 + index)
+                for index in range(driver.CACHE_RETAINED_GENERATIONS + 2)
+            ]
+            oldest = generations[0]
+
+            driver.prune_cache_generations(project, keep_key=oldest.name)
+
+            self.assertTrue(oldest.is_dir())
+            self.assertTrue((oldest / "derived_data" / "cmux-build.log").is_file())
+
+    def test_cache_pruning_is_a_noop_below_the_retention_bound(self):
+        with tempfile.TemporaryDirectory() as directory:
+            project = Path(directory)
+            cache = project / ".glaeda" / "apple-build" / "cache"
+            cache.mkdir(parents=True)
+            generations = [
+                self._cache_generation(cache, index, 1_000_000_000 + index)
+                for index in range(driver.CACHE_RETAINED_GENERATIONS)
+            ]
+
+            self.assertEqual(
+                driver.prune_cache_generations(project, keep_key=generations[0].name), []
+            )
+            self.assertEqual(
+                {path.name for path in cache.iterdir()},
+                {path.name for path in generations},
+            )
+
+    def test_cache_pruning_tolerates_an_absent_cache_root(self):
+        with tempfile.TemporaryDirectory() as directory:
+            self.assertEqual(driver.prune_cache_generations(Path(directory)), [])
+
+    def test_cache_pruning_unlinks_generation_symlinks_without_following_them(self):
+        with tempfile.TemporaryDirectory() as directory:
+            project = Path(directory)
+            cache = project / ".glaeda" / "apple-build" / "cache"
+            cache.mkdir(parents=True)
+            outside = project / "outside"
+            (outside / "derived_data").mkdir(parents=True)
+            (outside / "derived_data" / "treasure").write_text("keep me")
+            # Oldest entry is a symlink out of the cache root.
+            link = cache / f"{0:064x}"
+            link.symlink_to(outside, target_is_directory=True)
+            os.utime(link, ns=(1_000_000_000, 1_000_000_000), follow_symlinks=False)
+            newer = [
+                self._cache_generation(cache, index, 1_000_000_100 + index)
+                for index in range(1, driver.CACHE_RETAINED_GENERATIONS + 2)
+            ]
+
+            pruned = driver.prune_cache_generations(project, keep_key=newer[-1].name)
+
+            self.assertIn(link.name, pruned)
+            self.assertFalse(link.is_symlink())
+            self.assertTrue((outside / "derived_data" / "treasure").is_file())
+
+    def test_driver_prunes_cache_generations_after_a_verified_compile(self):
+        source = DRIVER.read_text()
+        prune = source.index("    pruned_cache_generations = prune_cache_generations(")
+        self.assertIn("os.utime(resolved_cache)", source[:prune])
+        # Eviction must follow every check that proves the current generation.
+        for guard in (
+            'raise Refusal("Glaeda cache locator escaped the project cache root")',
+            'raise Refusal("Glaeda DerivedData escaped the admitted cache generation")',
+            'raise Refusal("native compile completed without the admission log/products")',
+        ):
+            self.assertLess(source.index(guard), prune)
+        self.assertIn('"pruned_cache_generations": pruned_cache_generations', source)
+
 
 class WorkflowContractTests(unittest.TestCase):
     @classmethod