curator_backup.py 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492
  1. """Curator snapshot + rollback. Before any mutating curator pass, ``~/.hermes/skills/`` is tar.gz'd under
  2. ``~/.hermes/skills/.curator_backups/<utc-iso>/`` with a ``manifest.json``. Rollback first snapshots the CURRENT tree (so it is
  3. itself undoable), then extracts the chosen snapshot into place. Excluded: ``.curator_backups/``, ``.hub/`` (hub-managed), ``.git/``.
  4. Included: skill dirs, ``.usage.json``, ``.archive/``, ``.curator_state`` (so rollback also restores last-run-at and the curator
  5. doesn't re-fire), ``.bundled_manifest``, ``.curator_suppressed``. Each snapshot also copies ``~/.hermes/cron/jobs.json`` as
  6. ``cron-jobs.json``: the consolidation pass rewrites cron ``skills``/``skill`` references in place, so rollback restores those two
  7. fields (only) — the rest is live state."""
  8. from __future__ import annotations
  9. import contextlib
  10. import json
  11. import logging
  12. import os
  13. import re
  14. import shutil
  15. import tarfile
  16. from datetime import datetime, timezone, UTC
  17. from itertools import chain, count
  18. from pathlib import Path
  19. from typing import Any, Dict, List, Optional, Set, Tuple
  20. from hermes_constants import get_hermes_home
  21. from agent.skill_utils import is_excluded_skill_path
  22. from agent.curator import _read_config_section
  23. from hermes_cli.sizefmt import format_bytes
  24. logger = logging.getLogger(__name__)
  25. DEFAULT_KEEP = 2
  26. # Never rolled into a snapshot: .hub/ is owned by the skills hub (rolling it back breaks lockfile invariants); .curator_backups
  27. # is the backup dir itself; .git is repository metadata — rolling it back breaks git tracking, and snapshots that include it grow
  28. # with the full history (once backups are committed back, each snapshot contains the prior ones: 38MB of skills inflated to 24GB
  29. # in weeks); .locks holds skill_manage's per-skill lock files — restoring them would swap a lock out from under a waiting
  30. # writer. The tar filter in ``snapshot_skills`` applies the same set to nested paths, so a nested ``.git`` is skipped too.
  31. # See #91449. ``.curator_ledger.jsonl`` is the append-only audit log and ``.archive/`` the recoverable store the curator
  32. # promises never to delete: rolling either back to an older copy LOSES entries/skills, and both grow without bound (a 650MB
  33. # ledger made every snapshot 820MB — and every archive step gunzips the newest snapshot in full, so a pass that pruned 57
  34. # skills held the CLI prompt for 6 minutes).
  35. _EXCLUDE_TOP_LEVEL = {".curator_backups", ".hub", ".locks", ".git", ".archive", ".curator_ledger.jsonl"}
  36. def _excluded_member(ti: tarfile.TarInfo) -> bool:
  37. """Skip excluded names anywhere in the path, plus regeneratable DIRECTORIES (venv, node_modules,
  38. caches — a 1.3 GB torch venv inside one skill made every snapshot 349 MB, #107539). Directory
  39. parts only: a plain file that happens to be called ``venv`` is skill content."""
  40. from tools.skill_ledger import TRANSIENT_DIRS
  41. parts = Path(ti.name).parts
  42. dir_parts = parts if ti.isdir() else parts[:-1]
  43. return any(p in _EXCLUDE_TOP_LEVEL for p in parts) or any(p in TRANSIENT_DIRS for p in dir_parts)
  44. # Snapshot id: UTC ISO with colons replaced by dashes (Windows-safe filename); optional ``-NN`` suffix for same-second snapshots.
  45. _ID_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z(-\d{2})?$")
  46. CRON_JOBS_FILENAME = "cron-jobs.json"
  47. _ARCHIVE_NAME = "skills.tar.gz"
  48. _STAGING_PREFIX = ".rollback-staging-"
  49. _UNRESTORED_PREFIX = ".rollback-unrestored-" # retained staging; outside _STAGING_PREFIX so _prune_old keeps it
  50. def _skills_dir() -> Path:
  51. return get_hermes_home() / "skills"
  52. def _backups_dir() -> Path:
  53. return _skills_dir() / ".curator_backups"
  54. def _jobs_list(parsed: Any) -> Optional[list]:
  55. """jobs.json is ``{"jobs": [...], "updated_at": ...}``; also accept a bare list for forward compat. None otherwise."""
  56. parsed = parsed.get("jobs") if isinstance(parsed, dict) else parsed
  57. return parsed if isinstance(parsed, list) else None
  58. def _backup_cron_jobs_into(dest: Path) -> dict[str, Any]:
  59. """Copy the live ``~/.hermes/cron/jobs.json`` into ``dest`` as ``cron-jobs.json``. Never raises: a missing/unreadable
  60. file yields ``backed_up=False`` plus a reason, and the snapshot proceeds."""
  61. src = get_hermes_home() / "cron" / "jobs.json"
  62. info: dict[str, Any] = {"backed_up": False, "jobs_count": 0}
  63. if not src.exists():
  64. return {**info, "reason": "no cron/jobs.json present"}
  65. try:
  66. # utf-8-sig, same dialect as cron/jobs.load_jobs: a Windows-editor BOM would otherwise break json.loads
  67. # AND be written into the backup.
  68. raw = src.read_text(encoding="utf-8-sig")
  69. except OSError as e:
  70. logger.debug("Failed to read cron/jobs.json for backup: %s", e)
  71. return {**info, "reason": f"read error: {e}"}
  72. try: # jobs_count is a diagnostic only — an unparseable file is still stored raw.
  73. info["jobs_count"] = len(_jobs_list(json.loads(raw)) or [])
  74. except (json.JSONDecodeError, TypeError):
  75. info["parse_warning"] = "jobs.json was not valid JSON at snapshot time"
  76. try:
  77. (dest / CRON_JOBS_FILENAME).write_text(raw, encoding="utf-8")
  78. except OSError as e:
  79. logger.debug("Failed to write cron backup file: %s", e)
  80. return {**info, "reason": f"write error: {e}"}
  81. return {**info, "backed_up": True}
  82. def _utc_id(now: Optional[datetime] = None) -> str:
  83. """UTC ISO-ish filesystem-safe timestamp: ``2026-05-01T13-05-42Z``."""
  84. s = (datetime.now(UTC) if now is None else now).replace(microsecond=0).isoformat()
  85. return s.removesuffix("+00:00").replace(":", "-") + "Z"
  86. def _load_config() -> dict[str, Any]:
  87. return _read_config_section("curator", "backup", label="curator backup", log=logger)
  88. def is_enabled() -> bool:
  89. """Default ON — the whole point of the backup is safety by default."""
  90. return bool(_load_config().get("enabled", True))
  91. def get_keep() -> int:
  92. try:
  93. return max(1, int(_load_config().get("keep", DEFAULT_KEEP)))
  94. except (TypeError, ValueError):
  95. return DEFAULT_KEEP
  96. # --- Snapshot ---
  97. def _count_skill_files(base: Path) -> int:
  98. try:
  99. return sum(1 for p in base.rglob("SKILL.md") if not is_excluded_skill_path(p))
  100. except OSError:
  101. return 0
  102. def _write_manifest(dest: Path, reason: str, archive_path: Path, skills_counted: int, cron_info: dict[str, Any]) -> None:
  103. cron_jobs: dict[str, Any] = {"backed_up": bool(cron_info.get("backed_up", False)), "jobs_count": int(cron_info.get("jobs_count", 0))}
  104. if not cron_info.get("backed_up"):
  105. cron_jobs["reason"] = cron_info.get("reason", "not captured")
  106. if cron_info.get("parse_warning"):
  107. cron_jobs["parse_warning"] = cron_info["parse_warning"]
  108. manifest = {"id": dest.name, "reason": reason, "created_at": datetime.now(UTC).isoformat(), "archive": archive_path.name,
  109. "archive_bytes": archive_path.stat().st_size, "skill_files": skills_counted, "cron_jobs": cron_jobs}
  110. (dest / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
  111. def _mkdir(path: Path, what: str, *, exist_ok: bool) -> bool:
  112. try:
  113. path.mkdir(parents=True, exist_ok=exist_ok)
  114. return True
  115. except OSError as e:
  116. logger.debug("Failed to create %s %s: %s", what, path, e)
  117. return False
  118. def snapshot_skills(reason: str = "manual", *, protect_ids: Optional[set[str]] = None) -> Optional[Path]:
  119. """Create a tar.gz snapshot of ``~/.hermes/skills/`` and prune old ones. Returns the snapshot dir, or None when
  120. skipped (disabled, skills dir missing, IO error) — logged at debug so the curator never aborts a pass over a
  121. backup failure. ``protect_ids`` survive the prune step (rollback protects its target)."""
  122. if not is_enabled():
  123. logger.debug("Curator backup disabled by config; skipping snapshot")
  124. return None
  125. skills, backups = _skills_dir(), _backups_dir()
  126. if not skills.exists():
  127. logger.debug("No ~/.hermes/skills/ directory — nothing to back up")
  128. return None
  129. if not _mkdir(backups, "backups dir", exist_ok=True):
  130. return None
  131. base_id = _utc_id() # Two curator runs in the same second must not clobber each other: -NN suffix.
  132. snap_id = next(i for i in chain([base_id], (f"{base_id}-{n:02d}" for n in count(1))) if not (backups / i).exists())
  133. dest = backups / snap_id
  134. if not _mkdir(dest, "snapshot dir", exist_ok=False):
  135. return None
  136. archive = dest / _ARCHIVE_NAME
  137. try:
  138. with tarfile.open(archive, "w:gz", compresslevel=6) as tf:
  139. for entry in sorted(skills.iterdir()):
  140. if entry.name not in _EXCLUDE_TOP_LEVEL:
  141. # arcname relative to skills/ so extraction drops back in cleanly; the filter excludes nested paths too.
  142. tf.add(str(entry), arcname=entry.name, recursive=True,
  143. filter=lambda ti: None if _excluded_member(ti) else ti)
  144. # Cron capture is additive and never fails the snapshot; the manifest records whether it happened so rollback can say "no cron data".
  145. _write_manifest(dest, reason, archive, _count_skill_files(skills), _backup_cron_jobs_into(dest))
  146. except (OSError, tarfile.TarError) as e:
  147. logger.debug("Curator snapshot failed: %s", e, exc_info=True)
  148. shutil.rmtree(dest, ignore_errors=True) # clean up partial snapshot
  149. return None
  150. # A same-second id reuse after a prune (`...Z` next to a surviving `...Z-02`) sorts BELOW its sibling;
  151. # the snapshot just written must never be its own prune victim.
  152. _prune_old(keep=get_keep(), protect=(protect_ids or set()) | {snap_id})
  153. logger.info("Curator snapshot created: %s (%s)", snap_id, reason)
  154. return dest
  155. def prune_old_snapshots() -> list[str]:
  156. """Apply ``curator.backup.keep`` without taking a new snapshot (the prune-only curator pass)."""
  157. return _prune_old(keep=get_keep())
  158. def _prune_old(keep: int, protect: Optional[set[str]] = None) -> list[str]:
  159. """Delete regular snapshots beyond the newest *keep*; returns deleted ids. Ids in *protect* are never deleted —
  160. rollback() uses this so the mandatory pre-rollback safety snapshot cannot evict the snapshot being restored.
  161. Stale ``.rollback-staging-*`` dirs (crashed rollback) are cleaned up on every call; ``.rollback-unrestored-*`` is kept on purpose."""
  162. protect = protect or set()
  163. backups = _backups_dir()
  164. if not backups.exists():
  165. return []
  166. dirs = [c for c in backups.iterdir() if c.is_dir()]
  167. # Newest first (lexicographic works because the id is UTC ISO).
  168. entries = sorted((c for c in dirs if _ID_RE.match(c.name)), key=lambda c: c.name, reverse=True)
  169. doomed = [(p, "prune") for p in entries[keep:] if p.name not in protect]
  170. doomed += [(p, "clean stale staging dir") for p in dirs if p.name.startswith(_STAGING_PREFIX)]
  171. deleted: list[str] = []
  172. for path, what in doomed:
  173. try:
  174. shutil.rmtree(path)
  175. if what == "prune":
  176. deleted.append(path.name)
  177. except OSError as e:
  178. logger.debug("Failed to %s %s: %s", what, path, e)
  179. return deleted
  180. # --- List + rollback ---
  181. def _read_manifest(snap_dir: Path) -> dict[str, Any]:
  182. try:
  183. return json.loads((snap_dir / "manifest.json").read_text(encoding="utf-8-sig"))
  184. except (OSError, json.JSONDecodeError):
  185. return {}
  186. def _is_restorable(child: Path) -> bool:
  187. """A real snapshot dir with a tarball (excludes ``.rollback-staging-*`` and retained ``.rollback-unrestored-*``)."""
  188. return bool(child.is_dir() and _ID_RE.match(child.name) and (child / _ARCHIVE_NAME).exists())
  189. def _restorable_snapshots() -> list[Path]:
  190. """Restorable snapshot dirs, newest first."""
  191. backups = _backups_dir()
  192. return [c for c in sorted(backups.iterdir(), reverse=True) if _is_restorable(c)] if backups.exists() else []
  193. def list_backups() -> list[dict[str, Any]]:
  194. """All restorable snapshots (manifest dicts), newest first."""
  195. out: list[dict[str, Any]] = []
  196. for child in _restorable_snapshots():
  197. mf = {"id": child.name, "path": str(child), **_read_manifest(child)}
  198. try:
  199. mf.setdefault("archive_bytes", (child / _ARCHIVE_NAME).stat().st_size)
  200. except OSError:
  201. mf.setdefault("archive_bytes", 0)
  202. out.append(mf)
  203. return out
  204. def _resolve_backup(backup_id: Optional[str]) -> Optional[Path]:
  205. """Path of the requested backup (newest if *backup_id* is None); None if no match."""
  206. if backup_id:
  207. target = _backups_dir() / backup_id
  208. return target if _ID_RE.match(backup_id) and _is_restorable(target) else None
  209. return next(iter(_restorable_snapshots()), None)
  210. def _restore_cron_skill_links(snapshot_dir: Path) -> dict[str, Any]:
  211. """Reconcile backed-up cron skill links into the live ``cron/jobs.json``. Only ``skills``/``skill`` are restored,
  212. and only on jobs that still exist live (by ``id``) — everything else is live state. Backup-only jobs are skipped
  213. and reported; live-only jobs untouched. Never raises; writes through ``cron.jobs`` under the scheduler's lock so
  214. we don't race tick()."""
  215. report: dict[str, Any] = {"attempted": False, "restored": [], "skipped_missing": [], "unchanged": 0, "error": None}
  216. backup_file = snapshot_dir / CRON_JOBS_FILENAME
  217. if not backup_file.exists():
  218. return {**report, "error": f"snapshot has no {CRON_JOBS_FILENAME}"}
  219. try:
  220. backup_jobs = _jobs_list(json.loads(backup_file.read_text(encoding="utf-8-sig")))
  221. except (OSError, json.JSONDecodeError) as e:
  222. return {**report, "error": f"failed to load backed-up jobs: {e}"}
  223. if backup_jobs is None:
  224. return {**report, "error": "backed-up cron-jobs.json has no jobs list"}
  225. # Backed-up skill state keyed by job id (legacy single + modern list field).
  226. backup_by_id: dict[str, dict[str, Any]] = {
  227. job["id"]: {"skills": job.get("skills"), "skill": job.get("skill"), "name": job.get("name") or job["id"]}
  228. for job in backup_jobs if isinstance(job, dict) and isinstance(job.get("id"), str) and job.get("id")
  229. }
  230. if not backup_by_id:
  231. return {**report, "attempted": True} # we tried but there was nothing to do
  232. try:
  233. from cron.jobs import load_jobs, save_jobs, _jobs_lock
  234. except ImportError as e:
  235. return {**report, "error": f"cron module unavailable: {e}"}
  236. report["attempted"] = True
  237. try:
  238. with _jobs_lock():
  239. live_jobs = load_jobs()
  240. changed, live_ids = False, set()
  241. for live in live_jobs:
  242. jid = live.get("id") if isinstance(live, dict) else None
  243. if not isinstance(jid, str) or not jid:
  244. continue
  245. live_ids.add(jid)
  246. backup = backup_by_id.get(jid)
  247. if backup is None: # live job didn't exist at snapshot time
  248. continue
  249. cur = {"skills": live.get("skills"), "skill": live.get("skill")}
  250. bkp = {"skills": backup.get("skills"), "skill": backup.get("skill")}
  251. if cur == bkp:
  252. report["unchanged"] += 1
  253. continue
  254. for key, value in bkp.items(): # Restore, preserving absence (don't add a key the backup lacked).
  255. if value is None:
  256. live.pop(key, None)
  257. else:
  258. live[key] = value
  259. report["restored"].append({"job_id": jid, "job_name": backup.get("name") or jid, "from": cur, "to": bkp})
  260. changed = True
  261. # Jobs in backup but not live = user deleted them after the snapshot.
  262. report["skipped_missing"] = [{"job_id": jid, "job_name": b.get("name") or jid}
  263. for jid, b in backup_by_id.items() if jid not in live_ids]
  264. if changed:
  265. save_jobs(live_jobs)
  266. except Exception as e:
  267. logger.debug("Cron skill-link restore failed: %s", e, exc_info=True)
  268. report["error"] = f"restore failed mid-flight: {e}"
  269. return report
  270. def _remove_entry(entry: Path) -> None:
  271. if entry.is_dir() and not entry.is_symlink():
  272. shutil.rmtree(entry)
  273. elif entry.exists() or entry.is_symlink():
  274. entry.unlink()
  275. def _restore_excluded_subtrees(staged: Path, skills: Path) -> list[str]:
  276. """Move excluded entries (nested ``.git``/``.hub``/...) from *staged* back under *skills* after a successful extract.
  277. Snapshots never contain these, so the staged copy of the live tree is the only source. ``.git`` may be a dir or a file
  278. (submodule / worktree ``gitdir:`` pointer) — both are moved. Best-effort and conditional: an entry is carried only when
  279. its parent skill dir was restored and nothing sits at the target. If the target snapshot predates the skill, the entry
  280. is dropped with the staging dir rather than left orphaned; the safety snapshot excludes these paths too, so not undoable.
  281. Returns entries whose move failed, so their only surviving copies stay staged for recovery."""
  282. from tools.skill_ledger import TRANSIENT_DIRS
  283. failed: list[str] = []
  284. for dirpath, dirnames, filenames in os.walk(staged):
  285. carried = [Path(dirpath) / n for n in filenames if n in _EXCLUDE_TOP_LEVEL]
  286. carried += [Path(dirpath) / n for n in dirnames if n in _EXCLUDE_TOP_LEVEL or n in TRANSIENT_DIRS]
  287. for src in carried:
  288. dest = skills / src.relative_to(staged)
  289. if dest.parent.is_dir() and not dest.exists():
  290. try:
  291. shutil.move(str(src), str(dest))
  292. except OSError as e:
  293. failed.append(str(src.relative_to(staged)))
  294. logger.debug("Could not restore excluded entry %s: %s", src, e)
  295. dirnames[:] = [d for d in dirnames if d not in _EXCLUDE_TOP_LEVEL and d not in TRANSIENT_DIRS]
  296. return failed
  297. def _retain_staging(staged: Path, unrestored: list[str], reason: str) -> tuple[bool, str, None]:
  298. """Keep a staging dir that still holds the only copy of *unrestored* entries and build rollback()'s failure result.
  299. The dir is renamed out of the prunable prefix (unique suffix on a same-second collision). If the rename fails, the
  300. original path is reported so recovery never raises out of rollback()."""
  301. base = _UNRESTORED_PREFIX + staged.name[len(_STAGING_PREFIX):]
  302. kept, n = staged.with_name(base), 1
  303. while kept.exists():
  304. kept, n = staged.with_name(f"{base}-{n}"), n + 1
  305. note = ""
  306. try:
  307. staged.rename(kept)
  308. except OSError as e:
  309. logger.warning("Could not retain rollback staging dir %s: %s", staged, e)
  310. kept, note = staged, f" (rename failed: {e}; move it before the next curator run or it will be pruned)"
  311. return (False, f"{reason} - could not restore {', '.join(sorted(unrestored))}; staged copies kept at {kept}{note}", None)
  312. def _unstage(moved: list[tuple[Path, Path]]) -> list[str]:
  313. """Move staged entries back to their original paths; returns names that could not be restored. ``shutil.move``
  314. moves *into* an existing destination dir, so partial-extract debris would bury the real skill
  315. (``skills/foo/foo/``) — clear each original path first. The staged copy is authoritative."""
  316. failed: list[str] = []
  317. for orig, dest in moved:
  318. try:
  319. _remove_entry(orig)
  320. shutil.move(str(dest), str(orig))
  321. except OSError:
  322. failed.append(orig.name)
  323. return failed
  324. def _cron_summary(cron_report: dict[str, Any]) -> Optional[str]:
  325. if not cron_report.get("attempted"):
  326. return None
  327. if cron_report.get("error"):
  328. return f"cron links: error — {cron_report['error']}"
  329. # (attempted with nothing matched — empty snapshot or no overlapping ids — says nothing)
  330. parts = [f"{n} {label}" for n, label in (
  331. (len(cron_report.get("restored") or []), "job(s) had skill links restored"),
  332. (len(cron_report.get("skipped_missing") or []), "backed-up job(s) no longer exist (skipped)"),
  333. (cron_report.get("unchanged", 0), "already matched"),
  334. ) if n]
  335. return "cron links: " + ", ".join(parts) if parts else None
  336. def rollback(backup_id: Optional[str] = None) -> tuple[bool, str, Optional[Path]]:
  337. """Restore ``~/.hermes/skills/`` from a snapshot (explicit id or newest): safety-snapshot the CURRENT tree; stage
  338. current top-level entries; extract; on failure move staged entries back. Returns ``(ok, message, snapshot_path)``."""
  339. target = _resolve_backup(backup_id)
  340. if target is None:
  341. return (False, "no matching backup found" + (f" for id '{backup_id}'" if backup_id else "")
  342. + " (use `hermes curator rollback --list` to see available snapshots)", None)
  343. archive = target / _ARCHIVE_NAME
  344. if not archive.exists():
  345. return (False, f"snapshot {target.name} has no skills.tar.gz — corrupted?", None)
  346. skills, backups = _skills_dir(), _backups_dir()
  347. backups.mkdir(parents=True, exist_ok=True) # parents=True also creates skills/
  348. # Safety snapshot FIRST; bail if it fails, else a failed extract could leave the user with no skills. Protect the target from its prune.
  349. try:
  350. safety_snapshot = snapshot_skills(reason=f"pre-rollback to {target.name}", protect_ids={target.name})
  351. except Exception as e:
  352. return (False, f"pre-rollback safety snapshot failed: {e}", None)
  353. if safety_snapshot is None:
  354. return (False, "pre-rollback safety snapshot failed; backups may be disabled "
  355. "or unavailable, and current skills were not changed", None)
  356. # Stage current entries so the extract lands in an empty tree; the safety snapshot above (not staging) is the user-facing undo handle.
  357. staged = backups / f"{_STAGING_PREFIX}{_utc_id()}"
  358. try:
  359. staged.mkdir(parents=True, exist_ok=False)
  360. except OSError as e:
  361. return (False, f"failed to create staging dir: {e}", None)
  362. moved: list[tuple[Path, Path]] = []
  363. try:
  364. for entry in list(skills.iterdir()):
  365. if entry.name not in _EXCLUDE_TOP_LEVEL:
  366. shutil.move(str(entry), str(staged / entry.name))
  367. moved.append((entry, staged / entry.name))
  368. except OSError as e:
  369. unrestored = _unstage(moved)
  370. if unrestored:
  371. return _retain_staging(staged, unrestored, f"failed to stage current skills: {e}")
  372. shutil.rmtree(staged, ignore_errors=True)
  373. return (False, f"failed to stage current skills: {e}", None)
  374. try:
  375. with tarfile.open(archive, "r:gz") as tf:
  376. # Reject absolute paths and ".." defensively; Python 3.12+ also gets filter='data', older interpreters fall back unfiltered.
  377. for member in tf.getmembers():
  378. if member.name.startswith("/") or ".." in Path(member.name).parts:
  379. raise tarfile.TarError(f"refusing to extract unsafe path: {member.name!r}")
  380. try:
  381. tf.extractall(str(skills), filter="data") # type: ignore[call-arg]
  382. except TypeError:
  383. tf.extractall(str(skills)) # Python < 3.12 — no filter kwarg
  384. except (OSError, tarfile.TarError) as e:
  385. # A partial extract can leave entries the original tree never had; drop those first or the "restored" tree is skills + a slice of snapshot.
  386. keep = _EXCLUDE_TOP_LEVEL | {orig.name for orig, _ in moved}
  387. for entry in [e for e in skills.iterdir() if e.name not in keep]:
  388. with contextlib.suppress(OSError):
  389. _remove_entry(entry)
  390. unrestored = _unstage(moved)
  391. if unrestored: # Don't claim a clean restore; keep the staging dir for hand recovery.
  392. return _retain_staging(staged, unrestored, f"snapshot extract failed: {e}")
  393. shutil.rmtree(staged, ignore_errors=True)
  394. return (False, f"snapshot extract failed (state restored): {e}", None)
  395. # Snapshots never contain excluded subtrees (nested ``.git``, ``.hub``, ...), so carry them over from the staged live tree
  396. # (top-level ``.git`` is never staged). Then staging is done; the undo handle is the safety snapshot.
  397. unrestored = _restore_excluded_subtrees(staged, skills)
  398. if unrestored:
  399. return _retain_staging(staged, unrestored, "snapshot extracted but excluded entries were not carried over")
  400. shutil.rmtree(staged, ignore_errors=True)
  401. # Cron reconciliation failures don't fail the rollback — the skills tree (the main guarantee) is already restored.
  402. cron_report = _restore_cron_skill_links(target)
  403. logger.info("Curator rollback: restored from %s (cron_report=%s)", target.name, cron_report)
  404. return (True, "; ".join(filter(None, [f"restored from snapshot {target.name}", _cron_summary(cron_report)])), target)
  405. # --- Human-readable summary for CLI ---
  406. def summarize_backups() -> str:
  407. rows = list_backups()
  408. if not rows:
  409. return "No curator snapshots yet."
  410. header = f"{'id':<24} {'reason':<40} {'skills':>6} {'size':>8}"
  411. return "\n".join([header, "─" * len(header)] + [
  412. f"{r.get('id','?'):<24} {(r.get('reason','?') or '?')[:40]:<40} "
  413. f"{r.get('skill_files', 0):>6} {format_bytes(int(r.get('archive_bytes', 0))):>8}" for r in rows])