worktree_gc.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442
  1. """On-demand worktree + branch reclaim (``hermes worktree`` / ``/worktree prune``).
  2. The startup pruner (``cli._prune_stale_worktrees``) is conservative and silent — clean, fully
  3. merged scratch past an age tier only. This module also reclaims trees whose only "dirt" is
  4. untracked scratch (archived first) and branches whose content is on upstream.
  5. """
  6. from __future__ import annotations
  7. import contextlib
  8. import logging
  9. import os
  10. import re
  11. import shutil
  12. import subprocess
  13. import time
  14. from dataclasses import dataclass, field
  15. from pathlib import Path
  16. from typing import List, Optional
  17. logger = logging.getLogger(__name__)
  18. # Branches never considered for deletion, in any mode.
  19. _PROTECTED_BRANCHES = {"main", "master", "develop", "dev", "trunk"}
  20. # Trees owned by another lifecycle (kanban dispatcher gc) — never touched.
  21. _KANBAN_RE = re.compile(r"^t_[0-9a-f]+$")
  22. # Bounded cherry probe: a branch this far ahead of upstream is a stale-base
  23. # lane, not merged scratch; checking it is expensive and it stays preserved.
  24. _MAX_CHERRY_AHEAD = 50
  25. @dataclass
  26. class TreeRecord:
  27. name: str
  28. path: str
  29. branch: str
  30. age_days: float
  31. size_mb: Optional[int]
  32. verdict: str # reap | reap-archive | keep
  33. reason: str
  34. untracked: list[str] = field(default_factory=list)
  35. @dataclass
  36. class BranchRecord:
  37. name: str
  38. verdict: str # delete | keep
  39. reason: str
  40. def _run(cmd: list, timeout: int, cwd: Optional[str] = None,
  41. env: Optional[dict] = None) -> subprocess.CompletedProcess:
  42. return subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace",
  43. timeout=timeout, cwd=cwd, env=env, stdin=subprocess.DEVNULL, check=False)
  44. @dataclass
  45. class ExternalTreeRecord:
  46. """A linked worktree registered on the repo but living OUTSIDE
  47. ``.worktrees/`` — created by hand or by another tool. Reported for
  48. visibility only; the reclaim paths never touch these."""
  49. path: str
  50. branch: str # branch name, or "detached @<sha>" when detached
  51. locked: bool
  52. missing: bool # registered but the directory no longer exists
  53. def _git(args: list, cwd: str, timeout: int = 15) -> subprocess.CompletedProcess:
  54. """Run git, translating timeouts into returncode 124. Every verdict fails safe toward "keep"
  55. on nonzero, so a slow ``git cherry`` on a huge repo degrades to keep instead of aborting the
  56. audit mid-list. :func:`noninteractive_repo_git_env` because ``status`` executes the repo's
  57. ``core.fsmonitor`` and clean filters (GHSA-7x36-8jrh-v4pw)."""
  58. from hermes_cli._subprocess_compat import FILTER_DISCOVERY_FAILED, noninteractive_repo_git_env
  59. env = noninteractive_repo_git_env(cwd)
  60. if env is None:
  61. return subprocess.CompletedProcess(args=["git", *args], returncode=1, stdout="",
  62. stderr=FILTER_DISCOVERY_FAILED)
  63. try:
  64. return _run(["git", *args], timeout, cwd, env=env)
  65. except subprocess.TimeoutExpired:
  66. return subprocess.CompletedProcess(args=["git", *args], returncode=124, stdout="",
  67. stderr=f"timeout after {timeout}s")
  68. def _tree_size_mb(path: Path, timeout: int = 30) -> Optional[int]:
  69. """Cheap directory size via ``du -sm`` — best-effort, None on failure or timeout. Not
  70. ``subprocess.run``: its post-kill ``wait()`` never returns for a ``du`` stuck in uninterruptible
  71. disk I/O, so the caller (a ``hermes -w`` launch, the cron prune thread) would hang with it."""
  72. from hermes_cli._subprocess_compat import bounded_probe_run
  73. try:
  74. result = bounded_probe_run(["du", "-sm", str(path)], timeout=timeout)
  75. return int(result.stdout.split()[0]) if result and result.returncode == 0 and result.stdout.strip() else None
  76. except Exception:
  77. return None
  78. def _dirty_split(path: str) -> tuple[bool, list[str]]:
  79. """(has_tracked_modifications, untracked_paths) — tracked = real work, untracked = archivable."""
  80. try:
  81. result = _git(["status", "--porcelain", "--untracked-files=normal"], cwd=path, timeout=10)
  82. if result.returncode != 0:
  83. return True, [] # fail safe: treat as real work
  84. lines = [line for line in result.stdout.splitlines() if line.strip()]
  85. untracked = [line[3:].strip() for line in lines if line.startswith("??")]
  86. if len(untracked) == len(lines):
  87. from hermes_cli.worktree_retention import hidden_index_edits
  88. if hidden_index_edits(path): # skip-worktree / assume-unchanged edits
  89. return True, []
  90. return len(untracked) != len(lines), untracked
  91. except Exception:
  92. return True, []
  93. def _archive_untracked(tree: Path, untracked: list[str]) -> Optional[Path]:
  94. """Copy untracked files out of a doomed tree; None on any failure (caller must then keep)."""
  95. stamp = time.strftime("%Y%m%d-%H%M%S")
  96. from hermes_constants import get_hermes_home
  97. dest = get_hermes_home() / "archive" / "worktree-prune" / f"{tree.name}-{stamp}"
  98. try:
  99. for rel in untracked:
  100. src = tree / rel
  101. if not src.exists() or src.is_symlink():
  102. continue
  103. (dest / rel).parent.mkdir(parents=True, exist_ok=True)
  104. if src.is_dir():
  105. shutil.copytree(src, dest / rel, dirs_exist_ok=True)
  106. else:
  107. shutil.copy2(src, dest / rel)
  108. return dest if dest.exists() else None
  109. except Exception as exc:
  110. logger.warning("Could not archive untracked files from %s: %s", tree, exc)
  111. return None
  112. def _classify_tree(_ops, repo_root: str, entry: Path, merge_cache, remote_heads) -> tuple[str, str, list[str]]:
  113. """Return (verdict, reason, untracked) for one tree under ``.worktrees/``."""
  114. path = str(entry)
  115. if _KANBAN_RE.match(entry.name):
  116. return "keep", "kanban task tree (owned by kanban gc)", []
  117. if _ops._worktree_lock_is_live(repo_root, path, timeout=5) == "live":
  118. return "keep", "in use by a running hermes session", []
  119. tracked_dirty, untracked = _dirty_split(path)
  120. if tracked_dirty:
  121. return "keep", "uncommitted tracked changes (real work)", []
  122. archive_note = f"{len(untracked)} untracked file(s) will be archived"
  123. if _ops._worktree_has_unpushed_commits(path, timeout=5) and not _ops._worktree_commits_all_merged_upstream(
  124. path, timeout=30, cache=merge_cache, max_ahead=_MAX_CHERRY_AHEAD):
  125. # Pushed-branch tier: single-branch fetch refspecs (managed-install default) leave pushed
  126. # PR branches with no refs/remotes/* entry, so `git log HEAD --not --remotes` reads them
  127. # as unpushed forever. A head EXACTLY matching the remote branch has nothing origin lacks.
  128. if not _ops._worktree_branch_pushed_exact(path, remote_heads, timeout=10):
  129. return "keep", "unpushed commits not found upstream", []
  130. blocked = _ops.removal_blocked(path)
  131. if blocked:
  132. return "keep", blocked[1], []
  133. if untracked:
  134. return "reap-keep-branch", f"pushed to origin (open-PR lane); branch kept; {archive_note}", untracked
  135. return "reap-keep-branch", "pushed to origin (open-PR lane); branch kept", []
  136. blocked = _ops.removal_blocked(path)
  137. if blocked:
  138. return "keep", blocked[1], []
  139. if untracked:
  140. return "reap-archive", f"merged/pushed; {archive_note}", untracked
  141. return "reap", "clean and fully merged/pushed", []
  142. def audit_external_trees(repo_root: str) -> list[ExternalTreeRecord]:
  143. """List linked worktrees registered OUTSIDE ``.worktrees/``.
  144. ``hermes -w`` scratch trees all live under ``<repo>/.worktrees/``, but
  145. ``git worktree list --porcelain`` also knows about trees the user (or
  146. another tool) registered elsewhere. Those are someone else's state, so
  147. the reclaim paths never touch them — but hiding them entirely makes the
  148. audit lie about what the repo is carrying. Report them read-only, and
  149. flag registrations whose directory has vanished (safe to
  150. ``git worktree prune``).
  151. """
  152. result = _git(["worktree", "list", "--porcelain"], cwd=repo_root, timeout=10)
  153. if result.returncode != 0:
  154. return []
  155. managed_root = os.path.realpath(str(Path(repo_root) / ".worktrees"))
  156. main_root = os.path.realpath(repo_root)
  157. records: list[ExternalTreeRecord] = []
  158. current: dict = {}
  159. def _flush():
  160. path = current.get("path")
  161. if not path:
  162. return
  163. real = os.path.realpath(path)
  164. if real == main_root:
  165. return # the main checkout itself
  166. if real == managed_root or real.startswith(managed_root + os.sep):
  167. return # hermes-managed scratch tree — covered by audit_worktrees
  168. branch = current.get("branch", "")
  169. if not branch and current.get("head"):
  170. branch = f"detached @{current['head'][:10]}"
  171. records.append(ExternalTreeRecord(
  172. path=path,
  173. branch=branch,
  174. locked=bool(current.get("locked")),
  175. missing=not os.path.exists(path),
  176. ))
  177. for line in result.stdout.splitlines():
  178. line = line.rstrip()
  179. if not line:
  180. _flush()
  181. current = {}
  182. continue
  183. if line.startswith("worktree "):
  184. current["path"] = line[len("worktree "):]
  185. elif line.startswith("branch refs/heads/"):
  186. current["branch"] = line[len("branch refs/heads/"):]
  187. elif line.startswith("HEAD "):
  188. current["head"] = line[len("HEAD "):]
  189. elif line == "locked" or line.startswith("locked "):
  190. current["locked"] = True
  191. _flush()
  192. return records
  193. def prune_missing_registrations(repo_root: str, *, dry_run: bool = False) -> list[str]:
  194. """Drop registrations whose directory no longer exists (any location).
  195. The equivalent of a targeted ``git worktree prune``: purely
  196. metadata-level, never removes files, so it is safe even for external
  197. trees — a missing directory means there is nothing left to protect.
  198. """
  199. stale = [r for r in audit_external_trees(repo_root) if r.missing and not r.locked]
  200. if not stale:
  201. return []
  202. if dry_run:
  203. return [f"would prune stale registration {r.path}" for r in stale]
  204. result = _git(["worktree", "prune"], cwd=repo_root, timeout=15)
  205. if result.returncode != 0:
  206. return [f"failed to prune stale registrations: {result.stderr.strip()}"]
  207. return [f"pruned stale registration {r.path}" for r in stale]
  208. def audit_worktrees(repo_root: str, *, with_sizes: bool = True,
  209. older_than_days: Optional[float] = None) -> list[TreeRecord]:
  210. """Classify every tree under ``.worktrees/`` without mutating anything.
  211. ``older_than_days`` only ever RESTRICTS: a reapable tree younger than the threshold is kept
  212. ("too recent"). It never widens eligibility — age alone can't doom a tree carrying unmerged work.
  213. """
  214. from hermes_cli import worktree_ops as _ops
  215. worktrees_dir = Path(repo_root) / ".worktrees"
  216. if not worktrees_dir.exists():
  217. return []
  218. if _ops._repo_is_shallow(repo_root):
  219. _ops._deepen_shallow_repo(repo_root)
  220. merge_cache = _ops._load_worktree_merge_cache()
  221. cache_size_before = len(merge_cache)
  222. # One ls-remote for the whole sweep; None (offline) degrades pushed-tier verdicts to keep.
  223. remote_heads = _ops._fetch_remote_branch_heads(repo_root)
  224. now = time.time()
  225. records: list[TreeRecord] = []
  226. for entry in sorted(worktrees_dir.iterdir()):
  227. if not entry.is_dir():
  228. continue
  229. try:
  230. age_days = (now - entry.stat().st_mtime) / 86400.0
  231. except Exception:
  232. continue
  233. try:
  234. branch = _git(["branch", "--show-current"], cwd=str(entry), timeout=5).stdout.strip()
  235. except Exception:
  236. branch = ""
  237. verdict, reason, untracked = _classify_tree(_ops, repo_root, entry, merge_cache, remote_heads)
  238. if older_than_days is not None and verdict in _REAP_VERDICTS and age_days < older_than_days:
  239. verdict, reason, untracked = "keep", (
  240. f"reapable but only {age_days:.1f}d old (--older-than {older_than_days:g})"), []
  241. records.append(TreeRecord(
  242. name=entry.name, path=str(entry), branch=branch,
  243. age_days=age_days, size_mb=_tree_size_mb(entry) if with_sizes else None,
  244. verdict=verdict, reason=reason, untracked=untracked))
  245. if len(merge_cache) != cache_size_before:
  246. _ops._save_worktree_merge_cache(merge_cache)
  247. return records
  248. _REAP_VERDICTS = {"reap", "reap-archive", "reap-keep-branch"}
  249. def reclaim_worktrees(
  250. repo_root: str, *, dry_run: bool = False, records: Optional[list[TreeRecord]] = None
  251. ) -> list[str]:
  252. """Remove every reap-verdict tree from a frozen audit list — never re-globs inside the
  253. destructive loop, so trees created by concurrent sessions after the audit are out of scope."""
  254. if records is None:
  255. records = audit_worktrees(repo_root, with_sizes=False)
  256. actions: list[str] = []
  257. for record in records:
  258. if record.verdict not in _REAP_VERDICTS:
  259. continue
  260. if dry_run:
  261. actions.append(f"would remove {record.name} ({record.reason})")
  262. continue
  263. entry = Path(record.path)
  264. if record.untracked:
  265. archive = _archive_untracked(entry, record.untracked)
  266. if archive is None:
  267. actions.append(f"kept {record.name} (archive of untracked files failed)")
  268. continue
  269. actions.append(f"archived {len(record.untracked)} untracked file(s) → {archive}")
  270. # Dead-pid locks must be unlocked or `remove --force` refuses.
  271. with contextlib.suppress(Exception):
  272. _git(["worktree", "unlock", record.path], cwd=repo_root, timeout=10)
  273. try:
  274. remove_result = _git(["worktree", "remove", record.path, "--force"], cwd=repo_root, timeout=30)
  275. if remove_result.returncode != 0:
  276. actions.append(f"failed to remove {record.name}: {remove_result.stderr.strip()}")
  277. continue
  278. if record.verdict == "reap-keep-branch":
  279. actions.append(f"removed {record.name} (branch {record.branch} kept — pushed open-PR lane)")
  280. continue
  281. if record.branch and record.branch not in _PROTECTED_BRANCHES:
  282. _git(["branch", "-D", record.branch], cwd=repo_root, timeout=10)
  283. actions.append(f"removed {record.name}")
  284. except Exception as exc:
  285. actions.append(f"failed to remove {record.name}: {exc}")
  286. if not dry_run:
  287. with contextlib.suppress(Exception):
  288. _git(["worktree", "prune"], cwd=repo_root, timeout=15)
  289. return actions
  290. def audit_branches(repo_root: str) -> list[BranchRecord]:
  291. """Classify EVERY local branch: deletable when fully merged OR every commit is patch-equivalent
  292. upstream (``git cherry``) and not checked out. The gate is content reachability, not name."""
  293. from hermes_cli import worktree_ops as _ops
  294. if _ops._repo_is_shallow(repo_root):
  295. _ops._deepen_shallow_repo(repo_root)
  296. def _lines(result) -> list[str]:
  297. return [b.strip() for b in result.stdout.splitlines() if b.strip()]
  298. # No remote at all -> the local trunk; no trunk either -> nothing can be judged, report nothing.
  299. try:
  300. upstream = _ops._worktree_merge_base_ref(repo_root)
  301. except Exception:
  302. upstream = None
  303. if upstream is None:
  304. return []
  305. result = _git(["branch", "--format=%(refname:short)"], cwd=repo_root, timeout=10)
  306. if result.returncode != 0:
  307. return []
  308. branches = _lines(result)
  309. wt = _git(["worktree", "list", "--porcelain"], cwd=repo_root, timeout=10)
  310. active = {
  311. line.removeprefix("branch refs/heads/").strip()
  312. for line in wt.stdout.splitlines() if line.startswith("branch refs/heads/")}
  313. merged = set(_lines(_git(["branch", "--merged", upstream, "--format=%(refname:short)"], cwd=repo_root, timeout=15)))
  314. def _classify_branch(branch: str) -> BranchRecord:
  315. if branch in _PROTECTED_BRANCHES or branch in active:
  316. return BranchRecord(branch, "keep", "protected or checked out")
  317. if branch in merged:
  318. return BranchRecord(branch, "delete", "fully merged into " + upstream)
  319. # Rebase merges rewrite SHAs, so --merged misses them; cherry patch-equivalence catches
  320. # the dominant leak. Bounded: a branch far ahead is a stale-base lane, keep it.
  321. ahead = _git(["rev-list", "--count", f"{upstream}..{branch}"], cwd=repo_root, timeout=10)
  322. try:
  323. ahead_count = int(ahead.stdout.strip() or "0")
  324. except ValueError:
  325. ahead_count = _MAX_CHERRY_AHEAD + 1
  326. if ahead_count == 0:
  327. return BranchRecord(branch, "delete", "no commits beyond " + upstream)
  328. if ahead_count > _MAX_CHERRY_AHEAD:
  329. return BranchRecord(branch, "keep", f"{ahead_count} commits ahead (stale-base lane)")
  330. cherry = _git(["cherry", upstream, branch], cwd=repo_root, timeout=30)
  331. if cherry.returncode != 0:
  332. return BranchRecord(branch, "keep", "could not verify (git cherry failed)")
  333. lines = _lines(cherry)
  334. if lines and all(ln.startswith("-") for ln in lines):
  335. return BranchRecord(branch, "delete", "all commits patch-equivalent upstream")
  336. unique = sum(1 for ln in lines if ln.startswith("+"))
  337. return BranchRecord(branch, "keep", f"{unique} unique commit(s) not upstream")
  338. # Read-only, so parallel: hundreds of local branches × ~0.2-1s cherry probes would be minutes.
  339. import concurrent.futures
  340. workers = max(1, min(8, (os.cpu_count() or 4), len(branches)))
  341. if workers > 1:
  342. try:
  343. with concurrent.futures.ThreadPoolExecutor(max_workers=workers, thread_name_prefix="hermes-branch-gc") as pool:
  344. return list(pool.map(_classify_branch, branches))
  345. except Exception:
  346. pass
  347. return [_classify_branch(b) for b in branches]
  348. def reclaim_branches(
  349. repo_root: str, *, dry_run: bool = False, records: Optional[list[BranchRecord]] = None
  350. ) -> list[str]:
  351. """Delete every delete-verdict branch from a frozen audit list."""
  352. if records is None:
  353. records = audit_branches(repo_root)
  354. actions: list[str] = []
  355. for record in records:
  356. if record.verdict != "delete":
  357. continue
  358. if dry_run:
  359. actions.append(f"would delete branch {record.name} ({record.reason})")
  360. continue
  361. result = _git(["branch", "-D", record.name], cwd=repo_root, timeout=10)
  362. actions.append(
  363. f"deleted branch {record.name}" if result.returncode == 0
  364. else f"failed to delete {record.name}: {result.stderr.strip()}")
  365. return actions
  366. def worktrees_summary(repo_root: str, *, size_below_count: Optional[int] = None) -> tuple[int, Optional[int]]:
  367. """(tree_count, total_size_mb) for the escalation notice; size is best-effort with a timeout,
  368. and skipped (None) once the count reaches *size_below_count*: sizing walks every file of every
  369. tree, node_modules included."""
  370. worktrees_dir = Path(repo_root) / ".worktrees"
  371. if not worktrees_dir.exists():
  372. return 0, None
  373. try:
  374. count = sum(1 for e in worktrees_dir.iterdir() if e.is_dir())
  375. except Exception:
  376. return 0, None
  377. if size_below_count is not None and count >= size_below_count:
  378. return count, None
  379. return count, _tree_size_mb(worktrees_dir, timeout=20)