feat(cache): purge stale cargo cache entries in retention run

TODO 2.9 recorded a retention policy that warned about low disk while freeing
0.0 GB twice in a row, because it governed artifacts, logs and IP leases -- 52
KB in total on this host -- while 195 G of backups sat outside its reach.
Adding an unbounded directory of ~645 MB entries, one per Cargo.lock change,
without extending retention in the same change would repeat that at a larger
scale.

The window is the tighter of the global retention and the cache's own, so the
aggressive low-disk mode reaches the cache rather than stopping at the light
directories.

Sizes are read before deleting, not after. Summing st_size over files that have
already been unlinked yields 0 -- which is exactly how a policy ends up
reporting that it freed nothing while doing real work. A test asserts the
reported figure.

tests/python/test_commands_retention.py

@@ -11,6 +11,7 @@ from click.testing import CliRunner
 
 import ci_orchestrator.commands.retention as ret
 from ci_orchestrator.__main__ import cli
+from ci_orchestrator.config import Config
 
 # ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -191,3 +192,134 @@ def test_purge_old_log_dirs(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) ->
     assert result.exit_code == 0, result.output
     assert not old.exists()
     assert "Purged log" in result.output
+
+
+# ── cargo cache entries ───────────────────────────────────────────────────────
+
+
+def _cache_config(
+    tmp_path: Path, *, enabled: bool = True, days: int = 30
+) -> tuple[Path, Config]:
+    """Point the loaded config at a throwaway cache store.
+
+    Returns ``(store root, config)`` — the root so tests can seed entries, the
+    config so they can substitute it for ``load_config``.
+    """
+    from ci_orchestrator.config import BackendConfig, CargoCacheConfig, Config, Paths
+
+    root = tmp_path / "cache" / "cargo"
+    cfg = Config(
+        paths=Paths(
+            root=tmp_path,
+            templates=tmp_path / "t",
+            build_vms=tmp_path / "b",
+            artifacts=tmp_path / "artifacts",
+            keys=tmp_path / "k",
+        ),
+        backend=BackendConfig(),
+        cargo_cache=CargoCacheConfig(enabled=enabled, root=root, retention_days=days),
+    )
+    return root, cfg
+
+
+def _seed_entry(root: Path, digest: str, *, age_days: int, size: int = 1024) -> Path:
+    import os
+
+    from ci_orchestrator.cargo_cache import CargoCacheStore, cache_key
+
+    store = CargoCacheStore(root)
+    src = root.parent / f"seed-{digest}.tar.zst"
+    src.parent.mkdir(parents=True, exist_ok=True)
+    src.write_bytes(b"x" * size)
+    entry = store.publish(cache_key(lock_digest=digest, rustc_version="r", host_triple="t"), src)
+    stamp = time.time() - age_days * 86400
+    os.utime(entry, (stamp, stamp))
+    return entry
+
+
+def test_retention_purges_stale_cargo_cache_entries(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root, cfg = _cache_config(tmp_path)
+    old = _seed_entry(root, "old", age_days=90)
+    fresh = _seed_entry(root, "new", age_days=1)
+
+    monkeypatch.setattr(ret, "load_config", lambda: cfg)
+    monkeypatch.setattr(ret.shutil, "disk_usage", lambda _p: _fake_usage(free_gb=200))
+
+    result = CliRunner().invoke(cli, ["retention", "run"])
+    assert result.exit_code == 0, result.output
+    assert not old.exists(), "stale entry should be purged"
+    assert fresh.exists(), "fresh entry should survive"
+
+
+def test_retention_reports_the_bytes_it_freed(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """TODO 2.9: a policy that frees space without saying how much is the bug."""
+    root, cfg = _cache_config(tmp_path)
+    _seed_entry(root, "old", age_days=90, size=3 * 1024 * 1024)
+
+    monkeypatch.setattr(ret, "load_config", lambda: cfg)
+    monkeypatch.setattr(ret.shutil, "disk_usage", lambda _p: _fake_usage(free_gb=200))
+
+    result = CliRunner().invoke(cli, ["retention", "run"])
+    assert result.exit_code == 0, result.output
+    assert "Purged 1 cargo cache entry (3 MB)" in result.output
+
+
+def test_retention_what_if_keeps_cargo_cache_entries(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root, cfg = _cache_config(tmp_path)
+    old = _seed_entry(root, "old", age_days=90)
+
+    monkeypatch.setattr(ret, "load_config", lambda: cfg)
+    monkeypatch.setattr(ret.shutil, "disk_usage", lambda _p: _fake_usage(free_gb=200))
+
+    result = CliRunner().invoke(cli, ["retention", "run", "--what-if"])
+    assert result.exit_code == 0, result.output
+    assert old.exists()
+    assert "would purge 1 cargo cache entry" in result.output
+
+
+def test_retention_skips_the_cache_when_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root, cfg = _cache_config(tmp_path, enabled=False)
+    old = _seed_entry(root, "old", age_days=90)
+
+    monkeypatch.setattr(ret, "load_config", lambda: cfg)
+    monkeypatch.setattr(ret.shutil, "disk_usage", lambda _p: _fake_usage(free_gb=200))
+
+    result = CliRunner().invoke(cli, ["retention", "run"])
+    assert result.exit_code == 0, result.output
+    assert old.exists(), "a disabled cache must not be touched"
+    assert "disabled" in result.output
+
+
+def test_low_disk_tightens_the_cache_window_too(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Aggressive mode must reach the cache — it is the heaviest thing here."""
+    root, cfg = _cache_config(tmp_path, days=30)
+    entry = _seed_entry(root, "old", age_days=10)  # young for 30d, old for 7d
+
+    monkeypatch.setattr(ret, "load_config", lambda: cfg)
+    monkeypatch.setattr(ret.shutil, "disk_usage", lambda _p: _fake_usage(free_gb=10))
+
+    result = CliRunner().invoke(cli, ["retention", "run"])
+    assert result.exit_code == 0, result.output
+    assert not entry.exists(), "aggressive retention should have reached the cache"
+
+
+def test_retention_missing_cache_store_is_not_an_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _root, cfg = _cache_config(tmp_path)
+    monkeypatch.setattr(ret, "load_config", lambda: cfg)
+    monkeypatch.setattr(ret.shutil, "disk_usage", lambda _p: _fake_usage(free_gb=200))
+
+    result = CliRunner().invoke(cli, ["retention", "run"])
+    assert result.exit_code == 0, result.output
+    assert "nothing to purge" in result.output