checkpoint_maintenance.py 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614
  1. """Checkpoint store retention, orphan pruning, status and cleanup."""
  2. import logging
  3. import os
  4. import time
  5. from pathlib import Path
  6. from typing import Dict, Optional
  7. from hermes_cli.gitlock import clear_stale_tmp_packs
  8. from utils import rmtree_readonly
  9. from tools.checkpoint_manager import (
  10. _GIT_TIMEOUT, _LEGACY_PREFIX, _PRUNE_MARKER_NAME, _REFS_PREFIX, _STORE_DIRNAME,
  11. _dir_size_bytes, _index_path, _list_projects, _pre_v2_shadow_repos,
  12. _project_meta_path, _ref_name, _resolve_checkpoint_base, _run_git, _store_has_head,
  13. _store_path,
  14. )
  15. logger = logging.getLogger(__name__)
  16. # ---------------------------------------------------------------------------
  17. # Auto-maintenance
  18. # ---------------------------------------------------------------------------
  19. #
  20. # v2 rewrite. The sweep now operates on per-project refs inside the shared
  21. # store rather than per-project shadow repos. Legacy-archive dirs
  22. # (``legacy-<ts>/``) are swept with the same retention policy.
  23. def _delete_ref(store: Path, ref: str) -> bool:
  24. """Delete a ref from the store. Returns True on success."""
  25. ok, _, _ = _run_git(
  26. ["update-ref", "-d", ref], store, str(store.parent),
  27. allowed_returncodes={128},
  28. )
  29. return ok
  30. def _workdir_is_observably_gone(
  31. workdir: str,
  32. parent_dev: Optional[int] = None,
  33. parent_ino: Optional[int] = None,
  34. require_parent_identity: bool = True,
  35. ) -> bool:
  36. """True only when we can positively observe that ``workdir`` was removed.
  37. ``Path.exists()`` returns False for a deleted directory AND for one whose
  38. storage simply is not attached right now — an unplugged external drive, a
  39. network share behind a downed VPN, a bind-mount absent from this
  40. container, an offline Windows mapped drive. Orphan pruning deletes the
  41. project's entire checkpoint history, so treating that ambiguity as
  42. "deleted" throws away the user's restore points over a transient mount
  43. state, unattended, at startup.
  44. Require corroboration, in three steps.
  45. First, the parent directory must be present, so the absence of the project
  46. inside it is something we actually observed. When the parent is missing
  47. too, the volume is not there and we know nothing.
  48. Second, the present parent must be the directory we knew — not merely a
  49. directory at the same path. Unmounting swaps the directory visible at a
  50. mount point: while the volume is attached the path resolves to the
  51. mounted filesystem's root; after detach it resolves to the *underlying*
  52. (underlay) directory, which may carry entries of its own (a ``.keep``
  53. placeholder, sibling mount points). Those entries were never next to the
  54. project and prove nothing about the volume being attached. So the
  55. parent's ``(st_dev, st_ino)`` must match the identity recorded in the
  56. project's metadata while the project was observably live
  57. (``parent_dev``/``parent_ino``). A mismatch means a different directory
  58. is visible at that path — a detached volume, not an observed deletion.
  59. When no identity was ever recorded (metadata written by an older
  60. version) and ``require_parent_identity`` is True, stay conservative and
  61. do not classify as orphan. Callers that have no identity channel at all
  62. (the frozen pre-v2 layout) pass ``require_parent_identity=False`` to
  63. keep the structural checks only.
  64. Third, the (identity-confirmed) parent must actually carry information.
  65. Unmounting leaves classic static mount points (``/mnt/volume/proj``, an
  66. fstab entry, a container bind-mount) behind as *empty* directories, so an
  67. empty parent is the signature of a detached volume just as much as of a
  68. deleted project. Prune only when the parent holds something else (we
  69. observed a populated directory that does not contain the project) or is
  70. itself a live mount point (the volume is demonstrably attached and the
  71. project is demonstrably not on it).
  72. Genuinely abandoned projects are still reclaimed by the retention/stale
  73. rule, which runs off ``last_touch`` rather than a filesystem probe.
  74. """
  75. if not workdir:
  76. return False
  77. path = Path(workdir)
  78. try:
  79. if path.exists():
  80. return False
  81. parent = path.parent
  82. # A path whose parent is itself (a filesystem root) gives us nothing
  83. # to corroborate against.
  84. if parent == path:
  85. return False
  86. if not parent.is_dir():
  87. return False
  88. if parent_dev is not None and parent_ino is not None:
  89. st = parent.stat()
  90. if (st.st_dev, st.st_ino) != (parent_dev, parent_ino):
  91. # A different directory is visible at the parent's path than
  92. # the one the project lived in — the volume is detached (its
  93. # underlay showing through) or was swapped. Not a deletion.
  94. return False
  95. elif require_parent_identity:
  96. # No recorded identity to check against — we cannot tell the
  97. # project's real parent from an underlay directory exposed by an
  98. # unmount. Unsure never deletes; retention still reclaims.
  99. return False
  100. if _dir_has_any_entry(parent):
  101. return True
  102. # Empty parent: only evidence if that directory is a mount point, i.e.
  103. # the volume is attached right now and simply does not hold the
  104. # project. An empty plain directory is an unmounted mount point as
  105. # readily as an emptied project root.
  106. return os.path.ismount(parent)
  107. except OSError:
  108. # Probe failed (permission, I/O error) — not evidence of deletion.
  109. return False
  110. def _dir_has_any_entry(directory: Path) -> bool:
  111. """True when ``directory`` contains at least one entry.
  112. Stops after the first entry rather than materializing the listing; a
  113. project root can hold a large tree.
  114. """
  115. with os.scandir(directory) as entries:
  116. for _ in entries:
  117. return True
  118. return False
  119. def prune_checkpoints(
  120. retention_days: int = 7,
  121. delete_orphans: bool = True,
  122. checkpoint_base: Optional[Path] = None,
  123. max_total_size_mb: int = 0,
  124. orphan_allowlist: Optional[set] = None,
  125. ) -> dict[str, int]:
  126. """Delete stale/orphan checkpoints and reclaim store space.
  127. A project entry is deleted when either:
  128. * ``delete_orphans=True`` and its ``workdir`` no longer exists on disk
  129. (the original project was deleted / moved); OR
  130. * its ``last_touch`` is older than ``retention_days`` days.
  131. ``orphan_allowlist``, when not ``None``, restricts orphan deletion to
  132. the given identities (v2 project ``_hash`` strings and/or pre-v2 shadow
  133. repo paths as ``str``). This lets a caller that showed the user a
  134. confirmation preview (built from ``store_status()``) bind the resulting
  135. deletion to exactly what was displayed — a project that only becomes
  136. orphaned *after* the preview (e.g. its workdir vanishes while the human
  137. is answering the prompt) is skipped rather than swept up under the
  138. earlier confirmation. Pass ``None`` (the default) to delete every
  139. currently-orphaned project, e.g. for ``--force`` or unattended callers
  140. that never show a preview.
  141. Additionally, if ``max_total_size_mb > 0`` and the store exceeds that
  142. after orphan/stale pruning, the oldest commit per remaining project is
  143. dropped until the store is under the cap.
  144. Legacy-archive dirs (``legacy-*``) older than ``retention_days`` are
  145. also deleted.
  146. Returns a dict with counts ``{"scanned", "deleted_orphan",
  147. "deleted_stale", "errors", "bytes_freed"}``.
  148. Never raises — maintenance must never block interactive startup.
  149. """
  150. base = checkpoint_base or _resolve_checkpoint_base()
  151. result = {
  152. "scanned": 0,
  153. "deleted_orphan": 0,
  154. "deleted_stale": 0,
  155. "errors": 0,
  156. "bytes_freed": 0,
  157. }
  158. if not base.exists():
  159. return result
  160. from tools.checkpoint_pruning import PruneError, store_lock
  161. try:
  162. with store_lock(base):
  163. return _prune_checkpoints(base, result, retention_days, delete_orphans, max_total_size_mb, orphan_allowlist)
  164. except (PruneError, OSError) as exc:
  165. result["errors"] += 1
  166. logger.warning("Checkpoint maintenance stopped: %s", exc)
  167. return result
  168. def _prune_checkpoints(
  169. base: Path, result: dict[str, int], retention_days: int, delete_orphans: bool,
  170. max_total_size_mb: int, orphan_allowlist: Optional[set],
  171. ) -> dict[str, int]:
  172. size_before = _dir_size_bytes(base)
  173. # --- Legacy pre-v2 per-project shadow repos (kept directly under base) ---
  174. # Pre-v2 layout: ``base/<hash>/HEAD`` etc. We treat these exactly as the
  175. # v1 pruner did so behaviour is unchanged for anyone still on that layout
  176. # or sitting on a mid-migration system.
  177. cutoff = 0.0
  178. if retention_days > 0:
  179. cutoff = time.time() - retention_days * 86400
  180. for child in base.iterdir():
  181. if not child.is_dir():
  182. continue
  183. if child.name == _STORE_DIRNAME:
  184. continue
  185. if child.name.startswith(_LEGACY_PREFIX):
  186. # Legacy archive: prune by dir mtime using same retention rule.
  187. if retention_days <= 0:
  188. continue
  189. try:
  190. m = child.stat().st_mtime
  191. except OSError:
  192. continue
  193. if m >= cutoff:
  194. continue
  195. try:
  196. size = _dir_size_bytes(child)
  197. rmtree_readonly(child)
  198. result["bytes_freed"] += size
  199. result["deleted_stale"] += 1
  200. except OSError as exc:
  201. result["errors"] += 1
  202. logger.warning("Failed to delete legacy archive %s: %s", child, exc)
  203. # Pre-v2 per-project shadow repos. Scanned via the same helper
  204. # `store_status()` uses for its orphan preview, so a confirmation prompt
  205. # built from that preview always matches what gets deleted here.
  206. for repo in _pre_v2_shadow_repos(base):
  207. child = repo["path"]
  208. result["scanned"] += 1
  209. reason: Optional[str] = None
  210. if (
  211. delete_orphans
  212. and not repo["marker_unreadable"]
  213. and (
  214. repo["workdir"] is None
  215. # The frozen pre-v2 layout has no metadata channel to carry a
  216. # recorded parent identity, so only the structural checks
  217. # (parent present + populated / live mount point) apply here.
  218. or _workdir_is_observably_gone(
  219. repo["workdir"], require_parent_identity=False,
  220. )
  221. )
  222. and (orphan_allowlist is None or str(child) in orphan_allowlist)
  223. ):
  224. reason = "orphan"
  225. if reason is None and retention_days > 0:
  226. newest = 0.0
  227. try:
  228. for p in child.rglob("*"):
  229. try:
  230. mt = p.stat().st_mtime
  231. newest = max(newest, mt)
  232. except OSError:
  233. continue
  234. except OSError:
  235. pass
  236. if newest > 0 and newest < cutoff:
  237. reason = "stale"
  238. if reason is None:
  239. continue
  240. try:
  241. size = _dir_size_bytes(child)
  242. rmtree_readonly(child)
  243. result["bytes_freed"] += size
  244. if reason == "orphan":
  245. result["deleted_orphan"] += 1
  246. else:
  247. result["deleted_stale"] += 1
  248. except OSError as exc:
  249. result["errors"] += 1
  250. logger.warning("Failed to prune checkpoint repo %s: %s", child.name, exc)
  251. # --- v2 shared store: per-project ref pruning via metadata ---
  252. store = _store_path(base)
  253. if (store / "HEAD").exists():
  254. # A gc killed by the store timeout strands tmp_pack_* files that gc.auto=0 means git
  255. # itself never reclaims; sweep them even when no ref moved (a sweep is a directory
  256. # listing, unlike the pack-rewriting gc gated on refs below).
  257. clear_stale_tmp_packs(store)
  258. for meta in _list_projects(store):
  259. dir_hash = meta.get("_hash") or ""
  260. workdir = meta.get("workdir") or ""
  261. if not dir_hash:
  262. continue
  263. result["scanned"] += 1
  264. reason = None
  265. parent_dev = meta.get("workdir_parent_dev")
  266. parent_ino = meta.get("workdir_parent_ino")
  267. if not isinstance(parent_dev, int) or isinstance(parent_dev, bool):
  268. parent_dev = None
  269. if not isinstance(parent_ino, int) or isinstance(parent_ino, bool):
  270. parent_ino = None
  271. if (
  272. delete_orphans
  273. and (
  274. not workdir
  275. or _workdir_is_observably_gone(
  276. workdir,
  277. parent_dev=parent_dev,
  278. parent_ino=parent_ino,
  279. )
  280. )
  281. and (orphan_allowlist is None or dir_hash in orphan_allowlist)
  282. ):
  283. reason = "orphan"
  284. elif retention_days > 0:
  285. last_touch = float(meta.get("last_touch", 0) or 0)
  286. if last_touch > 0 and last_touch < cutoff:
  287. reason = "stale"
  288. if reason is None:
  289. continue
  290. ref = _ref_name(dir_hash)
  291. if not _delete_ref(store, ref):
  292. result["errors"] += 1
  293. return result
  294. # Drop per-project index and metadata.
  295. try:
  296. idx = _index_path(store, dir_hash)
  297. if idx.exists():
  298. idx.unlink()
  299. except OSError:
  300. pass
  301. try:
  302. mp = _project_meta_path(store, dir_hash)
  303. if mp.exists():
  304. mp.unlink()
  305. except OSError:
  306. pass
  307. if reason == "orphan":
  308. result["deleted_orphan"] += 1
  309. else:
  310. result["deleted_stale"] += 1
  311. from tools.checkpoint_pruning import Pruner, PruneError
  312. pruner = Pruner(_run_git, store, str(base), _GIT_TIMEOUT, _dir_size_bytes, _REFS_PREFIX)
  313. try:
  314. if result["deleted_orphan"] + result["deleted_stale"] or pruner.gc_pending():
  315. pruner.reclaim()
  316. if not pruner.enforce_size(max_total_size_mb * 1024 * 1024):
  317. result["errors"] += 1
  318. logger.warning("Checkpoint store remains over its size cap; minimum history retained")
  319. except (PruneError, OSError) as exc:
  320. result["errors"] += 1
  321. logger.warning("Checkpoint pruning stopped: %s", exc)
  322. size_after = _dir_size_bytes(base)
  323. delta = size_before - size_after
  324. result["bytes_freed"] = max(result["bytes_freed"], delta)
  325. return result
  326. def maybe_auto_prune_checkpoints(
  327. retention_days: int = 7,
  328. min_interval_hours: int = 24,
  329. delete_orphans: bool = True,
  330. checkpoint_base: Optional[Path] = None,
  331. max_total_size_mb: int = 0,
  332. ) -> dict[str, object]:
  333. """Idempotent wrapper around ``prune_checkpoints`` for startup hooks.
  334. Writes ``CHECKPOINT_BASE/.last_prune`` on completion so subsequent
  335. calls within ``min_interval_hours`` short-circuit.
  336. Returns ``{"skipped": bool, "result": prune_checkpoints-dict,
  337. "error": optional str}``.
  338. """
  339. base = checkpoint_base or _resolve_checkpoint_base()
  340. out: dict[str, object] = {"skipped": False}
  341. try:
  342. if not base.exists():
  343. out["result"] = {
  344. "scanned": 0, "deleted_orphan": 0, "deleted_stale": 0,
  345. "errors": 0, "bytes_freed": 0,
  346. }
  347. return out
  348. marker = base / _PRUNE_MARKER_NAME
  349. now = time.time()
  350. try:
  351. if marker.exists() and now - float(marker.read_text(encoding="utf-8-sig").strip()) < min_interval_hours * 3600:
  352. out["skipped"] = True
  353. return out
  354. except (OSError, ValueError):
  355. pass # corrupt marker — treat as no prior run
  356. # Claim the interval before pruning: callers run on a periodic tick, and a prune that
  357. # dies mid-way must cost one skipped day, not a git gc every tick.
  358. try:
  359. marker.write_text(str(now), encoding="utf-8")
  360. except OSError as exc:
  361. logger.debug("Could not write checkpoint prune marker: %s", exc)
  362. result = out["result"] = prune_checkpoints(retention_days=retention_days, delete_orphans=delete_orphans,
  363. checkpoint_base=base, max_total_size_mb=max_total_size_mb)
  364. total = result["deleted_orphan"] + result["deleted_stale"]
  365. if total > 0:
  366. logger.info(
  367. "checkpoint auto-maintenance: pruned %d entry(ies) "
  368. "(%d orphan, %d stale), reclaimed %.1f MB",
  369. total,
  370. result["deleted_orphan"],
  371. result["deleted_stale"],
  372. result["bytes_freed"] / (1024 * 1024),
  373. )
  374. except Exception as exc:
  375. logger.warning("checkpoint auto-maintenance failed: %s", exc)
  376. out["error"] = str(exc)
  377. return out
  378. def auto_prune_from_config() -> dict[str, object]:
  379. """``maybe_auto_prune_checkpoints`` driven by the ``checkpoints:`` config section — the one
  380. startup/housekeeping entry point for the CLI and the gateway. ``delete_orphans`` is never
  381. honoured unattended: a missing workdir is ambiguous (deleted vs. unmounted share); orphan
  382. cleanup is only via explicit ``hermes checkpoints prune``. Never raises."""
  383. try:
  384. from hermes_cli.config import load_config
  385. cfg = load_config().get("checkpoints") or {}
  386. if not cfg.get("auto_prune", False):
  387. return {"skipped": True}
  388. return maybe_auto_prune_checkpoints(
  389. retention_days=int(cfg.get("retention_days", 7)),
  390. min_interval_hours=int(cfg.get("min_interval_hours", 24)),
  391. delete_orphans=False,
  392. max_total_size_mb=int(cfg.get("max_total_size_mb", 500)))
  393. except Exception as exc:
  394. logger.debug("checkpoint auto-maintenance skipped: %s", exc)
  395. return {"skipped": True, "error": str(exc)}
  396. def checkpoint_footprint_notice() -> Optional[str]:
  397. """One-line notice when ``/rollback`` checkpoints are on and their store sits at or above
  398. ``checkpoints.max_total_size_mb``, else None. Checkpoints were on by default for a while
  399. (Mar–May 2026) and that ``enabled: true`` persisted into user configs; many users carry a
  400. GB-scale store for a feature they never invoke. The cap is a floor of one snapshot per
  401. project, so a big store is expected, not broken — the notice names the opt-out. Never raises."""
  402. try:
  403. from hermes_cli.config import load_config
  404. cfg = load_config().get("checkpoints") or {}
  405. if not cfg.get("enabled", False):
  406. return None
  407. cap_mb = int(cfg.get("max_total_size_mb", 500) or 0)
  408. if cap_mb <= 0:
  409. return None
  410. base = _resolve_checkpoint_base()
  411. size = _dir_size_bytes(base)
  412. if size < cap_mb * 1024 * 1024:
  413. return None
  414. # The notice needs no commit counts: full status runs Git for every project.
  415. store = _store_path(base)
  416. project_count = len(_list_projects(store)) if _store_has_head(store) else 0
  417. from hermes_cli.sizefmt import format_bytes
  418. return (f"Filesystem checkpoints (/rollback) are on: {format_bytes(size)} across "
  419. f"{project_count} project(s), above the {cap_mb} MB cap (one snapshot per project is "
  420. f"always kept). Not using /rollback? `hermes config set checkpoints.enabled false` then "
  421. f"`hermes checkpoints clear`; or lower `checkpoints.retention_days`.")
  422. except Exception as exc:
  423. logger.debug("checkpoint footprint notice skipped: %s", exc)
  424. return None
  425. # ---------------------------------------------------------------------------
  426. # Public helpers for `hermes checkpoints` CLI
  427. # ---------------------------------------------------------------------------
  428. def store_status(checkpoint_base: Optional[Path] = None) -> dict:
  429. """Return a summary of the shadow store.
  430. ``{"base": path, "store_size_bytes": N, "legacy_size_bytes": N,
  431. "total_size_bytes": N, "project_count": N, "projects": [...],
  432. "pre_v2_projects": [...], "legacy_archives": [...]}``
  433. ``pre_v2_projects`` covers shadow repos still on the pre-v2 per-project
  434. layout (``base/<hash>/HEAD``) — distinct from ``legacy_archives``, which
  435. are already-migrated ``legacy-<ts>/`` dirs. Callers that preview an
  436. orphan-deletion sweep must include both ``projects`` and
  437. ``pre_v2_projects``, since ``prune_checkpoints`` deletes orphans from
  438. both layouts.
  439. """
  440. base = checkpoint_base or _resolve_checkpoint_base()
  441. out: dict = {
  442. "base": str(base),
  443. "store_size_bytes": 0,
  444. "legacy_size_bytes": 0,
  445. "total_size_bytes": 0,
  446. "project_count": 0,
  447. "projects": [],
  448. "pre_v2_projects": [],
  449. "legacy_archives": [],
  450. }
  451. if not base.exists():
  452. return out
  453. store = _store_path(base)
  454. if store.exists():
  455. out["store_size_bytes"] = _dir_size_bytes(store)
  456. if (store / "HEAD").exists():
  457. for meta in _list_projects(store):
  458. dir_hash = meta.get("_hash") or ""
  459. workdir = meta.get("workdir") or ""
  460. ref = _ref_name(dir_hash)
  461. ok, count_out, _ = _run_git(
  462. ["rev-list", "--count", ref], store, str(base),
  463. allowed_returncodes={128},
  464. )
  465. try:
  466. commits = int(count_out) if ok else 0
  467. except ValueError:
  468. commits = 0
  469. out["projects"].append({
  470. "hash": dir_hash,
  471. "workdir": workdir,
  472. "exists": bool(workdir) and Path(workdir).exists(),
  473. "created_at": meta.get("created_at"),
  474. "last_touch": meta.get("last_touch"),
  475. "commits": commits,
  476. })
  477. out["project_count"] = len(out["projects"])
  478. out["pre_v2_projects"] = [
  479. {
  480. "path": str(r["path"]),
  481. "workdir": r["workdir"],
  482. "exists": r["exists"],
  483. }
  484. for r in _pre_v2_shadow_repos(base)
  485. ]
  486. for child in base.iterdir():
  487. if child.is_dir() and child.name.startswith(_LEGACY_PREFIX):
  488. try:
  489. size = _dir_size_bytes(child)
  490. except OSError:
  491. size = 0
  492. out["legacy_size_bytes"] += size
  493. try:
  494. mt = child.stat().st_mtime
  495. except OSError:
  496. mt = 0
  497. out["legacy_archives"].append({
  498. "name": child.name,
  499. "size_bytes": size,
  500. "mtime": mt,
  501. })
  502. out["total_size_bytes"] = _dir_size_bytes(base)
  503. return out
  504. def _rmtree_force(path: Path) -> None:
  505. rmtree_readonly(path)
  506. def clear_all(checkpoint_base: Optional[Path] = None) -> dict[str, int]:
  507. """Nuke the entire checkpoint base (store + legacy). Irreversible.
  508. Returns ``{"bytes_freed": N, "deleted": bool}``.
  509. """
  510. base = checkpoint_base or _resolve_checkpoint_base()
  511. out = {"bytes_freed": 0, "deleted": False}
  512. if not base.exists():
  513. return out
  514. size = _dir_size_bytes(base)
  515. try:
  516. from tools.checkpoint_pruning import store_lock
  517. with store_lock(base):
  518. _rmtree_force(base)
  519. out["bytes_freed"] = size
  520. out["deleted"] = True
  521. except (OSError, RuntimeError) as exc:
  522. logger.warning("Could not clear checkpoint base %s: %s", base, exc)
  523. return out
  524. def clear_legacy(checkpoint_base: Optional[Path] = None) -> dict[str, int]:
  525. """Delete all ``legacy-*`` archive directories and report any failures."""
  526. base = checkpoint_base or _resolve_checkpoint_base()
  527. out = {"bytes_freed": 0, "deleted": 0, "errors": 0}
  528. if not base.exists():
  529. return out
  530. from tools.checkpoint_pruning import store_lock
  531. try:
  532. with store_lock(base):
  533. for child in list(base.iterdir()):
  534. if not child.is_dir() or not child.name.startswith(_LEGACY_PREFIX):
  535. continue
  536. try:
  537. size = _dir_size_bytes(child)
  538. _rmtree_force(child)
  539. out["bytes_freed"] += size
  540. out["deleted"] += 1
  541. except OSError as exc:
  542. out["errors"] += 1
  543. logger.warning("Could not delete legacy archive %s: %s", child, exc)
  544. except (OSError, RuntimeError) as exc:
  545. out["errors"] += 1
  546. logger.warning("Could not clear legacy archives: %s", exc)
  547. return out