worktree_ops.py 57 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231
  1. """Git worktree isolation for ``hermes -w`` sessions: create, classify, prune.
  2. Every git call goes through ``_git``/``_git_out``/``_git_quiet`` (UTF-8 text, captured,
  3. bounded timeout). Classification helpers fail SAFE toward "preserve". ``cli`` re-exports
  4. these names; ``_cprint`` is imported lazily from ``cli`` to avoid a cycle.
  5. """
  6. import concurrent.futures
  7. import json
  8. import logging
  9. import os
  10. import re
  11. import shutil
  12. import subprocess
  13. import sys
  14. import threading
  15. import time
  16. import uuid
  17. from pathlib import Path
  18. from typing import Dict, Optional
  19. from hermes_cli._subprocess_compat import noninteractive_git_env
  20. from hermes_cli.git_commit_graph import (
  21. claim_commit_graph_refresh,
  22. claim_maintenance_slot,
  23. common_git_dir,
  24. refresh_commit_graph,
  25. run_bounded_git,
  26. )
  27. from hermes_constants import get_hermes_home
  28. from utils import atomic_json_write
  29. logger = logging.getLogger("cli")
  30. def _cprint(text: str) -> None:
  31. from cli import _cprint as _impl
  32. _impl(text)
  33. def _git(args, cwd, timeout: float = 10, **kwargs):
  34. """Run ``git *args`` in *cwd* capturing UTF-8 text; raises like ``subprocess.run``."""
  35. return subprocess.run(["git", *args], capture_output=True, text=True, encoding="utf-8", # noqa: PLW1510 -- forwarding wrapper: callers pass subprocess kwargs via **kwargs (check may arrive through it); an explicit check=False would raise TypeError
  36. errors="replace", timeout=timeout, cwd=cwd, **kwargs)
  37. def _git_out(args, cwd, timeout: float = 10, **kwargs) -> Optional[str]:
  38. """``_git`` returning stripped stdout, or None on a non-zero exit. Raises like ``_git``."""
  39. result = _git(args, cwd, timeout=timeout, **kwargs)
  40. return result.stdout.strip() if result.returncode == 0 else None
  41. def _git_quiet(args, cwd, timeout: float = 10, log: str | None = None, **kwargs) -> None:
  42. """Fail-soft ``_git``: swallow every error, optionally logging it at DEBUG with *log* as prefix."""
  43. try:
  44. _git(args, cwd, timeout=timeout, **kwargs)
  45. except Exception as e:
  46. if log:
  47. logger.debug("%s: %s", log, e)
  48. def _normalize_git_bash_path(p: Optional[str]) -> Optional[str]:
  49. """Translate a Git Bash path (``/c/..``, ``/cygdrive/c/..``, ``/mnt/c/..``) to ``C:\\..`` on Windows."""
  50. if not p or sys.platform != "win32":
  51. return p
  52. m = re.match(r"^/(?:(?:cygdrive|mnt)/)?([a-zA-Z])/(.*)$", p)
  53. if m:
  54. return f"{m.group(1).upper()}:\\{m.group(2).replace('/', chr(92))}"
  55. return p
  56. def _git_repo_root() -> Optional[str]:
  57. """Return the git repo root for CWD (Git-Bash-normalized), or None if not in a repo."""
  58. try:
  59. return _normalize_git_bash_path(_git_out(["rev-parse", "--show-toplevel"], None, timeout=5))
  60. except Exception:
  61. return None
  62. def _path_is_within_root(path: Path, root: Path) -> bool:
  63. """Return True when a resolved path stays within the expected root."""
  64. try:
  65. path.relative_to(root)
  66. return True
  67. except ValueError:
  68. return False
  69. def release_lsp_clients(wt_path: str) -> None:
  70. """Shut down this process's language servers for ``wt_path`` before ``git worktree remove``.
  71. A gateway outlives the sessions it runs, so without this the ``(server, root)`` client for the
  72. removed tree stays registered (tsserver heaps of several GiB pointed at a deleted worktree).
  73. Best-effort: LSP trouble must never block worktree removal.
  74. """
  75. try:
  76. from agent.lsp import release_workspace
  77. release_workspace(wt_path)
  78. except Exception as e:
  79. logger.debug("LSP release for worktree %s failed: %s", wt_path, e)
  80. def _cleanup_failed_worktree_add(repo_root: str, wt_path: Path, branch_name: str) -> None:
  81. """Sweep the leftovers of a failed/timed-out ``git worktree add`` (fail-soft).
  82. ``worktree add`` is not transactional: killed mid-checkout it leaves the partial dir, a
  83. LOCKED admin entry naming the *live* pid (immune to the pruner's dead-pid unlock) and
  84. sometimes the branch, so any retry of the same name fails.
  85. """
  86. try:
  87. # Unlock first: `worktree remove --force` refuses a locked tree.
  88. _git_quiet(["worktree", "unlock", str(wt_path)], repo_root, timeout=15)
  89. _git_quiet(["worktree", "remove", "--force", str(wt_path)], repo_root, timeout=15)
  90. if wt_path.exists():
  91. shutil.rmtree(wt_path, ignore_errors=True)
  92. # `remove` needs the dir; `prune` drops the admin entry when it is already gone.
  93. _git_quiet(["worktree", "prune"], repo_root, timeout=15,
  94. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  95. # A ref update runs the repository's reference-transaction hook (core.hooksPath).
  96. _git_quiet(["branch", "-D", branch_name], repo_root, timeout=15,
  97. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  98. except Exception as e:
  99. logger.debug("cleanup after failed worktree add: %s", e)
  100. _PACK_SPRAWL_THRESHOLD = 15
  101. _REPACK_TIMEOUT = 1800
  102. # One repack attempt per clone per interval, box-wide. Every ``hermes -w`` launch on a shared clone
  103. # used to start its own ``git repack -a`` of the whole store; on a multi-agent box that stacked 50+
  104. # concurrent multi-GB repacks (each too slow under the others to ever finish inside the timeout).
  105. _REPACK_MIN_INTERVAL = 6 * 3600
  106. _REPACK_LOCK = "hermes-repack.lock"
  107. def _claim_repack_slot(git_dir: Path) -> bool:
  108. """Exactly one process per clone gets to repack per ``_REPACK_MIN_INTERVAL``."""
  109. return claim_maintenance_slot(git_dir, _REPACK_LOCK, _REPACK_MIN_INTERVAL)
  110. def _run_bounded_repack(repo_root: str) -> None:
  111. """Incremental geometric repack whose whole process tree dies with the timeout or with us."""
  112. run_bounded_git(repo_root, ["repack", "-d", "--geometric=2", "--write-midx", "--quiet"], _REPACK_TIMEOUT)
  113. def _maintain_pack_health(repo_root: str) -> None:
  114. """Repack on pack sprawl and keep the commit-graph fresh (background thread, fail-soft).
  115. ``gc --auto`` only fires at 50 packs; past a few dozen, every object lookup scans every
  116. pack index and worktree creation can blow its timeout under concurrent load.
  117. """
  118. try:
  119. # A linked worktree's or submodule's ``.git`` is a file; its objects live in the common dir.
  120. git_dir = common_git_dir(repo_root)
  121. pack_dir = git_dir / "objects" / "pack" if git_dir else None
  122. if pack_dir is None or not pack_dir.is_dir():
  123. return
  124. packs = len(list(pack_dir.glob("*.pack")))
  125. if packs >= _PACK_SPRAWL_THRESHOLD and _claim_repack_slot(git_dir):
  126. from hermes_cli.gitlock import clear_stale_tmp_packs
  127. clear_stale_tmp_packs(git_dir)
  128. logger.info("git pack sprawl (%d packs) — repacking in background", packs)
  129. _run_bounded_repack(repo_root)
  130. # Repacking can strand now-duplicated admin files; prune on the same pass.
  131. _git(["worktree", "prune"], repo_root, timeout=60, check=False,
  132. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  133. if claim_commit_graph_refresh(git_dir):
  134. refresh_commit_graph(repo_root, git_dir)
  135. except Exception as e:
  136. logger.debug("pack maintenance skipped: %s", e)
  137. def _resolve_worktree_base(repo_root: str, fetch_timeout: float = 5,
  138. freshness_window: float = 300) -> tuple:
  139. """Resolve the freshest base ref to branch a new worktree from -> ``(base_ref, banner_label)``.
  140. Local ``HEAD`` can lag the remote by hundreds of commits, so try in order: (1) the current
  141. branch's upstream, refreshed; (2) the remote default branch (``origin/HEAD``), refreshed;
  142. (3) local ``HEAD``. The fetch is skipped when ``FETCH_HEAD`` is younger than
  143. *freshness_window* s, capped at *fetch_timeout*, and never retried: on failure the cached
  144. remote-tracking ref is used (the pre-push stale-base gate backstops genuine staleness).
  145. """
  146. from hermes_cli._subprocess_compat import noninteractive_git_env
  147. from hermes_cli.update_cmd_check import tracking_refspec
  148. def _run(args, timeout: float = 20):
  149. return _git(args, repo_root, timeout=timeout, stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  150. def _ref_exists(ref: str) -> bool:
  151. try:
  152. return _run(["rev-parse", "--verify", "--quiet", ref + "^{commit}"]).returncode == 0
  153. except Exception:
  154. return False
  155. def _fetch_head_age() -> Optional[float]:
  156. try:
  157. gd = _run(["rev-parse", "--git-dir"])
  158. if gd.returncode != 0:
  159. return None
  160. fetch_head = Path(repo_root) / gd.stdout.strip() / "FETCH_HEAD"
  161. if not fetch_head.exists():
  162. return None
  163. return max(0.0, time.time() - fetch_head.stat().st_mtime)
  164. except Exception:
  165. return None
  166. def _refresh(remote: str, branch: str, ref: str) -> tuple:
  167. """(ref, label) after one best-effort fetch; never raises."""
  168. age = _fetch_head_age()
  169. if age is not None and age < freshness_window and _ref_exists(ref):
  170. return ref, f"{ref} (fetched {int(age)}s ago)"
  171. try:
  172. fetched = _run(["fetch", remote, tracking_refspec(remote, branch)], timeout=fetch_timeout)
  173. if fetched.returncode == 0:
  174. return ref, f"{ref} (fetched)"
  175. reason = "fetch failed"
  176. except subprocess.TimeoutExpired:
  177. reason = f"fetch timed out after {fetch_timeout:g}s"
  178. except Exception as e:
  179. reason = f"fetch error: {e}"
  180. if _ref_exists(ref):
  181. logger.debug("worktree base: %s — using cached %s", reason, ref)
  182. return ref, f"{ref} (cached — {reason})"
  183. return "HEAD", f"HEAD (local — {reason}, no cached {ref})"
  184. # 1. Current branch's upstream, if it tracks one.
  185. try:
  186. up = _run(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"])
  187. if up.returncode == 0:
  188. upstream = up.stdout.strip()
  189. if upstream and "/" in upstream:
  190. remote, branch = upstream.split("/", 1)
  191. return _refresh(remote, branch, upstream)
  192. except Exception as e:
  193. logger.debug("worktree base: upstream resolution failed: %s", e)
  194. # 2. Remote default branch (origin/HEAD).
  195. try:
  196. head_ref = _run(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"])
  197. default_ref = (head_ref.stdout.strip().replace("refs/remotes/", "", 1)
  198. if head_ref.returncode == 0 else "")
  199. if not default_ref:
  200. # origin/HEAD not set locally; ask the remote (network, capped like the fetch).
  201. show = _run(["remote", "show", "origin"], timeout=max(fetch_timeout, 5))
  202. for line in show.stdout.splitlines():
  203. line = line.strip()
  204. if line.startswith("HEAD branch:"):
  205. _branch = line.split(":", 1)[1].strip()
  206. if _branch and _branch != "(unknown)":
  207. default_ref = "origin/" + _branch
  208. break
  209. if default_ref and "/" in default_ref:
  210. remote, branch = default_ref.split("/", 1)
  211. return _refresh(remote, branch, default_ref)
  212. except Exception as e:
  213. logger.debug("worktree base: default-branch resolution failed: %s", e)
  214. # 3. Local HEAD (offline / no remote / detached).
  215. return "HEAD", "HEAD (local — could not reach remote)"
  216. def _ensure_worktrees_gitignored(repo_root: str) -> None:
  217. """Append ``.worktrees/`` to the repo's .gitignore when missing (fail-soft)."""
  218. gitignore = Path(repo_root) / ".gitignore"
  219. try:
  220. # utf-8-sig: a Notepad BOM would glue to the first line and defeat the membership check.
  221. existing = gitignore.read_text(encoding="utf-8-sig", errors="replace") if gitignore.exists() else ""
  222. if ".worktrees/" not in existing.splitlines():
  223. with open(gitignore, "a", encoding="utf-8") as f:
  224. if existing and not existing.endswith("\n"):
  225. f.write("\n")
  226. f.write(".worktrees/\n")
  227. except Exception as e:
  228. logger.debug("Could not update .gitignore: %s", e)
  229. def _worktreeinclude_entries(repo_root) -> list:
  230. """Non-blank, non-comment entries of *repo_root*/``.worktreeinclude`` (``[]`` when absent).
  231. utf-8-sig, not the locale default: a cp1251/GBK locale would mojibake or raise on a UTF-8
  232. list, and a Notepad BOM would glue to the first entry.
  233. """
  234. include_file = Path(repo_root) / ".worktreeinclude"
  235. if not include_file.is_file():
  236. return []
  237. entries = []
  238. for line in include_file.read_text(encoding="utf-8-sig", errors="replace").splitlines():
  239. entry = line.strip()
  240. if entry and not entry.startswith("#"):
  241. entries.append(entry)
  242. return entries
  243. def _copy_worktree_includes(repo_root: str, wt_path: Path) -> None:
  244. """Copy/symlink the entries listed in ``.worktreeinclude`` (gitignored files the agent needs)."""
  245. try:
  246. entries = _worktreeinclude_entries(repo_root)
  247. if not entries:
  248. return
  249. repo_root_resolved = Path(repo_root).resolve()
  250. wt_path_resolved = wt_path.resolve()
  251. for entry in entries:
  252. src, dst = Path(repo_root) / entry, wt_path / entry
  253. # Traversal/symlink-escape guard: both resolved endpoints must stay inside their roots.
  254. try:
  255. src_resolved = src.resolve(strict=False)
  256. dst_resolved = dst.resolve(strict=False)
  257. except (OSError, ValueError):
  258. logger.debug("Skipping invalid .worktreeinclude entry: %s", entry)
  259. continue
  260. if not _path_is_within_root(src_resolved, repo_root_resolved):
  261. logger.warning("Skipping .worktreeinclude entry outside repo root: %s", entry)
  262. continue
  263. if not _path_is_within_root(dst_resolved, wt_path_resolved):
  264. logger.warning("Skipping .worktreeinclude entry that escapes worktree: %s", entry)
  265. continue
  266. if src.is_file():
  267. dst.parent.mkdir(parents=True, exist_ok=True)
  268. shutil.copy2(str(src), str(dst))
  269. elif src.is_dir() and not dst.exists():
  270. # Symlink directories (no disk). Windows needs Developer Mode for symlinks: copy there.
  271. dst.parent.mkdir(parents=True, exist_ok=True)
  272. try:
  273. os.symlink(str(src_resolved), str(dst))
  274. except (OSError, NotImplementedError) as _sym_err:
  275. if sys.platform != "win32":
  276. raise
  277. logger.info(".worktreeinclude: symlink failed (%s) — falling back to copytree on Windows.",
  278. _sym_err)
  279. try:
  280. shutil.copytree(str(src_resolved), str(dst), symlinks=True, dirs_exist_ok=False)
  281. except Exception as _copy_err:
  282. logger.warning(".worktreeinclude: copy fallback also failed for %s -> %s: %s",
  283. src, dst, _copy_err)
  284. except Exception as e:
  285. logger.debug("Error copying .worktreeinclude entries: %s", e)
  286. def _worktree_add(repo_root: str, wt_path: Path, branch_name: str, base_ref: str, base_label: str):
  287. """``git worktree add`` with a local-HEAD retry -> ``(base_ref, base_label)``, or None on failure.
  288. Every failed attempt is swept with ``_cleanup_failed_worktree_add`` so the retry is not poisoned.
  289. """
  290. from hermes_cli._subprocess_compat import noninteractive_repo_git_env
  291. # The checkout runs repo-named smudge filters too; refuse when they cannot be neutralized.
  292. env = noninteractive_repo_git_env(repo_root)
  293. if env is None:
  294. _cprint("\033[31m✗ Failed to create worktree: could not read the repository's filter config\033[0m")
  295. return None
  296. def _add(cfg):
  297. # 120s: on a multi-agent box the ~10k-file checkout contends for disk (113s measured under load).
  298. return _git([*cfg, "worktree", "add", str(wt_path), "-b", branch_name, base_ref], repo_root,
  299. timeout=120, stdin=subprocess.DEVNULL, env=env)
  300. # checkout.workers parallelizes materialization; older git ignores unknown -c keys.
  301. try:
  302. result = _add(["-c", "checkout.workers=8", "-c", "checkout.thresholdForParallelism=100"])
  303. if result.returncode != 0:
  304. if base_ref != "HEAD":
  305. # A partial fetch can leave the remote ref unusable; never hard-fail on a sync hiccup.
  306. logger.warning("worktree add from %s failed (%s); retrying from local HEAD",
  307. base_ref, result.stderr.strip())
  308. _cleanup_failed_worktree_add(repo_root, wt_path, branch_name)
  309. base_ref, base_label = "HEAD", "HEAD (fallback — remote base failed)"
  310. result = _add([])
  311. if result.returncode != 0:
  312. _cleanup_failed_worktree_add(repo_root, wt_path, branch_name)
  313. _cprint(f"\033[31m✗ Failed to create worktree: {result.stderr.strip()}\033[0m")
  314. return None
  315. except Exception as e:
  316. _cleanup_failed_worktree_add(repo_root, wt_path, branch_name)
  317. _cprint(f"\033[31m✗ Failed to create worktree: {e}\033[0m")
  318. return None
  319. return base_ref, base_label
  320. def _setup_worktree(repo_root: str | None = None, sync_base: bool = True,
  321. name: Optional[str] = None, retain_db=None) -> Optional[dict[str, str]]:
  322. """Create an isolated git worktree -> ``{path, branch, repo_root, base}``, or None on failure.
  323. *sync_base* branches from the fetched remote tip (``_resolve_worktree_base``), else local
  324. HEAD. *name* replaces the random ``hermes-<id>``; named trees lack the ``hermes-`` prefix so
  325. the pruner ages them on its slower schedule. *retain_db* (``-w``, ``--tui -w``) records the tree
  326. for resume and names the profile store in the lock. A ``--tui -w`` tree outlives its launcher
  327. while a session there can resume in it; a classic ``-w`` row's cwd is the repo root, so its
  328. reaped clean tree is recreated on resume instead.
  329. Set ``worktree_sync: false`` in config to branch from local ``HEAD`` (the pre-#10760-followup behavior).
  330. """
  331. repo_root = repo_root or _git_repo_root()
  332. if not repo_root:
  333. _cprint("\033[31m✗ --worktree requires being inside a git repository.\033[0m")
  334. print(" cd into your project repo first, then run hermes -w")
  335. return None
  336. wt_name = ((name and re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-._")[:40])
  337. or f"hermes-{uuid.uuid4().hex[:8]}")
  338. branch_name = f"hermes/{wt_name}"
  339. worktrees_dir = Path(repo_root) / ".worktrees"
  340. worktrees_dir.mkdir(parents=True, exist_ok=True)
  341. wt_path = worktrees_dir / wt_name
  342. if name and wt_path.exists():
  343. _cprint(f"\033[31m✗ Worktree already exists: {wt_path}\033[0m")
  344. print(f" Pick a different name, or remove it with: git worktree remove {wt_path}")
  345. return None
  346. _ensure_worktrees_gitignored(repo_root)
  347. # Resolve the base ref. By default branch from the freshly-fetched remote tip so the worktree starts
  348. # current with the project, not from the (possibly stale) local HEAD of the standalone clone (#10760
  349. # follow-up).
  350. base_ref, base_label = (_resolve_worktree_base(repo_root) if sync_base
  351. else ("HEAD", "HEAD (local — worktree_sync disabled)"))
  352. added = _worktree_add(repo_root, wt_path, branch_name, base_ref, base_label)
  353. if added is None:
  354. return None
  355. base_ref, base_label = added
  356. _copy_worktree_includes(repo_root, wt_path)
  357. # Lock so other processes (and `git worktree remove`) see it is in use; fail-soft.
  358. try:
  359. reason = f"hermes pid={os.getpid()}" + (f" db={retain_db}" if retain_db is not None else "")
  360. _git(["worktree", "lock", "--reason", reason, str(wt_path)], repo_root)
  361. logger.debug("Worktree locked: %s (pid=%s)", wt_path, os.getpid())
  362. except Exception as e:
  363. logger.debug("git worktree lock failed (non-fatal): %s", e)
  364. from hermes_cli.worktree_registry import record_worktree_repo
  365. record_worktree_repo(repo_root)
  366. if retain_db is not None: # a -w tree: a resume may recreate it once quit removed it (N8)
  367. from hermes_cli.tui_worktree_resume import record_tui_worktree
  368. record_tui_worktree({"path": str(wt_path), "branch": branch_name, "repo_root": repo_root})
  369. _cprint(f"\033[32m✓ Worktree created:\033[0m {wt_path}")
  370. print(f" Branch: {branch_name}")
  371. print(f" Base: {base_label}")
  372. return {"path": str(wt_path), "branch": branch_name, "repo_root": repo_root, "base": base_ref}
  373. _REMOTE_TRUNK_CANDIDATES = ("origin/HEAD", "origin/main", "origin/master")
  374. _LOCAL_TRUNK_CANDIDATES = ("main", "master")
  375. def _worktree_local_trunk(path: str, timeout: float = 5) -> Optional[str]:
  376. """Local trunk of a repo with NO remote-tracking refs: ``main``/``master``, else the branch
  377. checked out in the main worktree. None = no baseline at all; callers must preserve.
  378. Nothing in such a repo was ever pushed, so "merged into the local trunk" is the only fact
  379. that can tell redundant scratch work from unique commits. May raise like ``_git``.
  380. """
  381. for name in _LOCAL_TRUNK_CANDIDATES:
  382. if _git_out(["rev-parse", "--verify", "--quiet", f"refs/heads/{name}"], path, timeout=timeout):
  383. return name
  384. porcelain = _git_out(["worktree", "list", "--porcelain"], path, timeout=timeout) or ""
  385. for line in porcelain.split("\n\n", 1)[0].splitlines(): # first block = the main worktree
  386. if line.startswith("branch refs/heads/"):
  387. return line[len("branch refs/heads/"):].strip() or None
  388. return None
  389. def _worktree_merge_base_ref(path: str, timeout: float = 5) -> Optional[str]:
  390. """Ref merged work is judged against: ``origin/HEAD``/``origin/main``/``origin/master``, or the
  391. local trunk when the repo has no remote-tracking refs at all. None = nothing to compare
  392. against -> every consumer must preserve. May raise like ``_git``.
  393. """
  394. for cand in _REMOTE_TRUNK_CANDIDATES:
  395. if _git_out(["rev-parse", "--verify", "--quiet", cand], path, timeout=timeout):
  396. return cand
  397. if _git_out(["for-each-ref", "--format=%(refname)", "refs/remotes"], path, timeout=timeout) == "":
  398. return _worktree_local_trunk(path, timeout=timeout)
  399. return None
  400. def _worktree_has_unpushed_commits(worktree_path: str, timeout: int = 10) -> bool:
  401. """Whether a worktree has commits unreachable from any remote branch. Fails SAFE toward True.
  402. No remote-tracking refs = nothing was ever pushed, so the tree is compared against the local
  403. trunk instead (``_worktree_local_trunk``); no trunk either -> True. A shallow boundary can
  404. disconnect an older HEAD from origin/* so public commits look unpushed;
  405. ``_deepen_shallow_repo`` first if affordable.
  406. """
  407. try:
  408. remote_refs = _git_out(["for-each-ref", "--format=%(refname)", "refs/remotes"], worktree_path,
  409. timeout=timeout)
  410. if remote_refs is None:
  411. return True
  412. baseline = ["--remotes"]
  413. if not remote_refs:
  414. trunk = _worktree_local_trunk(worktree_path, timeout=timeout)
  415. if trunk is None:
  416. return True
  417. baseline = [trunk]
  418. unpushed = _git_out(["log", "--oneline", "HEAD", "--not", *baseline], worktree_path,
  419. timeout=timeout)
  420. return unpushed is None or bool(unpushed)
  421. except Exception:
  422. return True
  423. def _include_symlink_paths(worktree_path: str, repo_root) -> set:
  424. """Relative paths in *worktree_path* that are ``.worktreeinclude`` directory symlinks.
  425. ``_copy_worktree_includes`` symlinks included directories back to the main checkout
  426. (*repo_root*). A trailing-slash gitignore pattern
  427. (``node_modules/``) never matches a symlink, so git reports each one as untracked. Only a
  428. symlink at a listed entry that resolves to that same entry in the main repo qualifies —
  429. anything else is real user state.
  430. """
  431. root = Path(repo_root)
  432. wt = Path(worktree_path)
  433. paths = set()
  434. for entry in _worktreeinclude_entries(root):
  435. dst = wt / entry
  436. if dst.is_symlink() and dst.resolve() == (root / entry).resolve():
  437. paths.add(Path(entry).as_posix().rstrip("/")) # git status paths use "/" on Windows too
  438. return paths
  439. def _worktree_is_dirty(worktree_path: str, repo_root, timeout: int = 10) -> bool:
  440. """Whether a worktree has staged/unstaged/untracked changes. Fails SAFE toward True.
  441. Untracked ``.worktreeinclude`` directory symlinks back to the main checkout *repo_root* are
  442. ignored: they are our own scaffolding, and counting them would keep every worktree of such a
  443. repo forever. ``status.showUntrackedFiles=no`` is overridden (it would hide new files), and
  444. skip-worktree / assume-unchanged files whose bytes differ from the index count as changes
  445. (``git status`` trusts both flags).
  446. """
  447. from hermes_cli._subprocess_compat import noninteractive_repo_git_env
  448. try:
  449. # Reclaimers run this unattended; status reads the index (core.fsmonitor, clean filters).
  450. env = noninteractive_repo_git_env(worktree_path)
  451. if env is None:
  452. return True
  453. result = _git(["status", "--porcelain", "-z", "--untracked-files=normal"], worktree_path,
  454. timeout=timeout, stdin=subprocess.DEVNULL, env=env)
  455. if result.returncode != 0:
  456. return True
  457. entries = [e for e in result.stdout.split("\0") if e]
  458. if not entries:
  459. from hermes_cli.worktree_retention import hidden_index_edits
  460. return bool(hidden_index_edits(worktree_path))
  461. if any(not e.startswith("?? ") for e in entries):
  462. return True
  463. include_links = _include_symlink_paths(worktree_path, repo_root)
  464. return any(e[3:].rstrip("/") not in include_links for e in entries)
  465. except Exception:
  466. return True
  467. def _repo_is_shallow(repo_path: str, timeout: int = 5) -> bool:
  468. """Whether *repo_path* is a shallow clone (installer default). Fails toward False on unknown state.
  469. Shallowness poisons connectivity verdicts: an old worktree HEAD misreports as unpushed forever.
  470. """
  471. try:
  472. return _git_out(["rev-parse", "--is-shallow-repository"], repo_path, timeout=timeout) == "true"
  473. except Exception:
  474. return False
  475. def _deepen_shallow_repo(repo_root: str, timeout: int = 600) -> bool:
  476. """Blobless unshallow so history verdicts are correct -> whether the repo is non-shallow afterwards.
  477. Falls back to a plain ``--unshallow`` if the server rejects filters. Background paths only.
  478. """
  479. if not _repo_is_shallow(repo_root):
  480. return True
  481. try:
  482. remotes = _git_out(["remote"], repo_root)
  483. if not remotes:
  484. return False
  485. names = [r.strip() for r in remotes.splitlines() if r.strip()]
  486. remote = "origin" if "origin" in names else names[0]
  487. try:
  488. for extra in (["--filter=blob:none"], []):
  489. try:
  490. # Unattended fetch: a repo-level core.sshCommand / credential.helper must not run.
  491. result = _git(["fetch", remote, "--unshallow", *extra], repo_root, timeout=timeout,
  492. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  493. except subprocess.TimeoutExpired:
  494. return False
  495. if result.returncode == 0:
  496. break
  497. logger.debug("git fetch --unshallow%s failed: %s", " " + " ".join(extra) if extra else "",
  498. result.stderr.strip()[-500:])
  499. finally:
  500. # The filtered attempt makes the clone partial (git writes the config before fetching,
  501. # so even when it fails); its old packs need the marker or git 2.53+ crashes every
  502. # later fetch (#124272). Markers are inert in a clone without a promisor remote.
  503. from hermes_cli.gitlock import mark_unmarked_packs_promisor
  504. mark_unmarked_packs_promisor(Path(repo_root))
  505. except Exception as e:
  506. logger.debug("Deepening shallow repo failed (non-fatal): %s", e)
  507. return False
  508. deepened = not _repo_is_shallow(repo_root)
  509. if deepened:
  510. logger.info("Deepened shallow clone at %s so worktree cleanup can verify push state", repo_root)
  511. return deepened
  512. # Retained `git cherry` verdict entries (~90 bytes each).
  513. _WORKTREE_MERGE_CACHE_MAX = 1000
  514. def _worktree_merge_cache_path() -> Path:
  515. """Path of the patch-equivalence verdict cache (profile-aware)."""
  516. return get_hermes_home() / "cache" / "worktree_merge_verdicts.json"
  517. def _load_worktree_merge_cache() -> dict[str, bool]:
  518. """Load the ``git cherry`` verdict cache. Missing/corrupt cache = empty."""
  519. try:
  520. entries = json.loads(_worktree_merge_cache_path().read_text(encoding="utf-8-sig")).get("verdicts")
  521. except Exception:
  522. return {}
  523. # A hand-edited or partially written cache must never inject a non-bool verdict.
  524. return {k: v for k, v in entries.items() if isinstance(v, bool)} if isinstance(entries, dict) else {}
  525. def _save_worktree_merge_cache(verdicts: dict[str, bool]) -> None:
  526. """Atomically persist the newest ``_WORKTREE_MERGE_CACHE_MAX`` verdicts. Never raises."""
  527. try:
  528. items = list(verdicts.items())[-_WORKTREE_MERGE_CACHE_MAX:]
  529. atomic_json_write(_worktree_merge_cache_path(), {"version": 1, "verdicts": dict(items)}, indent=None)
  530. except Exception as e:
  531. logger.debug("Could not persist worktree merge cache: %s", e)
  532. def _worktree_commits_all_merged_upstream(
  533. worktree_path: str, timeout: int = 30, max_ahead: int = 20, cache: Optional[dict[str, bool]] = None,
  534. ) -> bool:
  535. """Whether every local-only commit is patch-equivalent (``git cherry``) to upstream. Fails SAFE -> False.
  536. Catches squash-merged/cherry-picked PRs whose remote branch was deleted (commits unreachable
  537. from ``refs/remotes/*`` forever). Upstream is ``_worktree_merge_base_ref`` (the local trunk in
  538. a repo without remotes). More than *max_ahead* ahead = stale-base tree -> False.
  539. *cache* memoizes on ``(base_sha, head_sha, max_ahead)``, exactly what ``git cherry`` consumes.
  540. """
  541. try:
  542. base = _worktree_merge_base_ref(worktree_path, timeout=timeout)
  543. if base is None:
  544. return False
  545. cache_key = None
  546. if cache is not None:
  547. revs = _git_out(["rev-parse", f"{base}^{{commit}}", "HEAD^{commit}"], worktree_path,
  548. timeout=timeout)
  549. shas = (revs or "").split()
  550. if len(shas) == 2:
  551. cache_key = f"{shas[0]}..{shas[1]}:{max_ahead}"
  552. if cache_key in cache:
  553. return cache[cache_key]
  554. def _memo(verdict: bool) -> bool:
  555. if cache is not None and cache_key is not None:
  556. cache[cache_key] = verdict
  557. return verdict
  558. ahead = _git_out(["rev-list", "--count", f"{base}..HEAD"], worktree_path, timeout=timeout)
  559. if ahead is None:
  560. return False
  561. count = int(ahead or "0")
  562. if count == 0:
  563. return _memo(True)
  564. if count > max_ahead:
  565. return _memo(False)
  566. cherry = _git(["cherry", base, "HEAD"], worktree_path, timeout=timeout)
  567. if cherry.returncode != 0:
  568. return False
  569. lines = [ln for ln in cherry.stdout.splitlines() if ln.strip()]
  570. # "-" = patch-equivalent upstream; "+" = unique local work
  571. return _memo(bool(lines) and all(ln.startswith("-") for ln in lines))
  572. except Exception:
  573. return False
  574. def _worktree_current_branch(worktree_path: str, timeout: int) -> Optional[str]:
  575. """Checked-out branch name, or None when detached/git fails. May raise on subprocess errors."""
  576. branch = _git_out(["rev-parse", "--abbrev-ref", "HEAD"], worktree_path, timeout=timeout)
  577. return branch if branch and branch != "HEAD" else None # "HEAD" = detached
  578. def _worktree_branch_pr_merged(
  579. worktree_path: str, timeout: int = 15, cache: Optional[dict[str, bool]] = None,
  580. ) -> bool:
  581. """Whether the branch's PR is MERGED on GitHub (``gh pr list``). Fails SAFE toward False.
  582. Catches rebase-merges whose altered diff defeats ``git cherry``. Memoized on
  583. ``(branch, head_sha)``; only True is cached since the PR may merge later without new commits.
  584. """
  585. try:
  586. branch = _worktree_current_branch(worktree_path, timeout)
  587. if branch is None:
  588. return False
  589. cache_key = None
  590. if cache is not None:
  591. sha = _git_out(["rev-parse", "HEAD"], worktree_path, timeout=timeout)
  592. if sha:
  593. cache_key = f"pr-merged:{branch}:{sha}"
  594. if cache.get(cache_key) is True:
  595. return True
  596. result = subprocess.run(
  597. ["gh", "pr", "list", "--head", branch, "--state", "merged", "--json", "number", "--limit", "1"],
  598. capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout, cwd=worktree_path,
  599. check=False,
  600. )
  601. if result.returncode != 0:
  602. return False
  603. prs = json.loads(result.stdout or "[]")
  604. merged = isinstance(prs, list) and bool(prs)
  605. if merged and cache is not None and cache_key is not None:
  606. cache[cache_key] = True
  607. return merged
  608. except Exception:
  609. return False
  610. def _fetch_remote_branch_heads(repo_root: str, timeout: int = 20) -> Optional[dict[str, str]]:
  611. """``{branch: sha}`` for every branch on origin (one ``ls-remote``), or None = cannot verify, preserve.
  612. Managed installs fetch a single-branch refspec, so pushed PR branches have no
  613. remote-tracking ref and would read as unpushed forever.
  614. """
  615. try:
  616. # Runs from the reclaim sweep, unattended: same transport pins as the base fetch.
  617. result = _git(["ls-remote", "--heads", "origin"], repo_root, timeout=timeout,
  618. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  619. if result.returncode != 0:
  620. return None
  621. pairs = (line.split("\t", 1) for line in result.stdout.splitlines())
  622. return {p[1][len("refs/heads/"):].strip(): p[0].strip()
  623. for p in pairs if len(p) == 2 and p[1].startswith("refs/heads/")}
  624. except Exception:
  625. return None
  626. def _worktree_branch_pushed_exact(
  627. worktree_path: str, remote_heads: Optional[dict[str, str]], timeout: int = 10,
  628. ) -> bool:
  629. """Whether the branch head is EXACTLY what origin holds (tree redundant; reap it, keep the branch).
  630. Equality is deliberately the only True case: ahead/diverged heads have commits origin lacks
  631. and ancestry can't be proven cheaply without remote-tracking refs -> fail SAFE toward preserve.
  632. """
  633. if not remote_heads:
  634. return False
  635. try:
  636. branch = _worktree_current_branch(worktree_path, timeout)
  637. remote_sha = remote_heads.get(branch) if branch is not None else None
  638. return bool(remote_sha) and (
  639. _git_out(["rev-parse", "HEAD"], worktree_path, timeout=timeout) == remote_sha)
  640. except Exception:
  641. return False
  642. # ``hermes pid=<pid>`` (``/worktree new``), ``hermes pid=<pid> db=<state.db>`` (``-w`` / ``--tui -w`` launch)
  643. # and ``hermes session=<id> db=<state.db>`` (re-lock when the TUI exits). Read raw from the admin
  644. # dir: plain ``list --porcelain`` C-quotes a reason holding a backslash, a quote, a control or a
  645. # non-ASCII byte (every Windows path), and the ``db=`` path would never parse.
  646. _HERMES_LOCK_RE = re.compile(r"hermes (?:pid=(\d+)|session=\S+)(?: db=(.+))?", re.DOTALL)
  647. def _retain_worktree_for_session(repo_root: str, worktree_path: str, session_id: str, db_path) -> bool:
  648. """Re-lock a ``--tui -w`` tree its exiting launcher retains, naming the session that uses it.
  649. The tree stays live while any resumable session of that store works inside it
  650. (``_retained_tree_is_live``), not only the named one: ``/new`` leaves the older session's
  651. history in the same checkout.
  652. """
  653. _git_quiet(["worktree", "unlock", worktree_path], repo_root, log="worktree unlock before retain failed")
  654. try:
  655. result = _git(["worktree", "lock", "--reason", f"hermes session={session_id} db={db_path}",
  656. worktree_path], repo_root)
  657. except (OSError, subprocess.SubprocessError) as exc:
  658. logger.debug("worktree retain lock failed for %s: %s", worktree_path, exc)
  659. return False
  660. return result.returncode == 0
  661. def _inside_tree(worktree_path: str):
  662. """``inside(path) -> 0/1``: *path* is the tree or under it (native path identity: Windows is
  663. case-insensitive, either separator; the tree's own spelling and its resolved one)."""
  664. def key(value) -> str:
  665. return os.path.normcase(str(value)).replace("\\", "/").rstrip("/")
  666. roots = {key(Path(worktree_path)), key(Path(worktree_path).resolve())}
  667. def inside(cwd) -> int:
  668. return int(bool(cwd) and any(key(cwd) == r or key(cwd).startswith(r + "/") for r in roots))
  669. return inside
  670. # The gateway's own records that it will still act in a session after its last viewer quits:
  671. # an active /loop, /heartbeat or /goal (its continuation) row (``hermes_cli.loops`` / ``heartbeat`` /
  672. # ``goals``, keyed by the stored session id, status ``active`` when the field is absent), and a row
  673. # no viewer close ended: Ink's exit detaches with ``tui_shutdown`` and the owner ends the idle row
  674. # only once no other viewer holds it (``gateway/session_viewer_close.py``).
  675. _SERVED_TREE_SQL = (
  676. "SELECT 1 FROM sessions s WHERE hermes_inside_tree(s.cwd) AND (s.ended_at IS NULL OR EXISTS ("
  677. "SELECT 1 FROM state_meta m WHERE m.key IN ('loop:'||s.id, 'heartbeat:'||s.id, 'goal:'||s.id) "
  678. "AND (json_valid(m.value)=0 OR COALESCE(json_extract(m.value,'$.status'),'active')='active'))) LIMIT 1")
  679. def _tree_still_served(db_path: str, worktree_path: str) -> Optional[str]:
  680. """Why the gateway still needs a ``--tui -w`` tree the launcher is about to remove, or None.
  681. Beyond pending admissions (``_retained_tree_is_live(pending_only=True)``): scheduled work for a
  682. session inside it (an active loop, heartbeat or goal continuation), another viewer still holding
  683. such a session (its row was not ended by the quit), or an enabled cron job that runs in the tree
  684. (``workdir``) or is bound to such a session's local chat. Reads only; unreadable fails SAFE."""
  685. import sqlite3
  686. from urllib.parse import quote
  687. path = Path(db_path)
  688. chats: set = set()
  689. if path.is_file():
  690. try:
  691. conn = sqlite3.connect(f"file:{quote(str(path))}?mode=ro", uri=True, timeout=2)
  692. try:
  693. conn.create_function("hermes_inside_tree", 1, _inside_tree(worktree_path), deterministic=True)
  694. if conn.execute(_SERVED_TREE_SQL).fetchone():
  695. return "session"
  696. chats = {row[0] for row in conn.execute(
  697. "SELECT chat_id FROM sessions WHERE hermes_inside_tree(cwd) AND chat_id IS NOT NULL")}
  698. finally:
  699. conn.close()
  700. except sqlite3.Error as exc:
  701. logger.debug("retained worktree serve check failed (%s); keeping tree", exc)
  702. return "unreadable"
  703. return "cron" if _cron_bound_to_tree(worktree_path, chats) else None
  704. def _cron_bound_to_tree(worktree_path: str, chats: set) -> bool:
  705. """An enabled, non-terminal cron job whose ``workdir`` is inside the tree, or whose origin is
  706. the local chat of a session there. Reads ``jobs.json`` directly (``load_jobs`` may repair-write);
  707. an unreadable store fails SAFE."""
  708. try:
  709. from cron.jobs import _current_cron_store, _parse_jobs_file, is_job_runnable, is_terminal_job
  710. jobs_file = _current_cron_store().jobs_file
  711. if not jobs_file.exists():
  712. return False
  713. data, _ = _parse_jobs_file(jobs_file)
  714. except Exception as exc: # health: allow BLE001 -- an unreadable cron store keeps the tree (fail safe)
  715. logger.debug("cron store unreadable (%s); keeping tree", exc)
  716. return True
  717. jobs = data.get("jobs") if isinstance(data, dict) else data
  718. inside = _inside_tree(worktree_path)
  719. for job in jobs if isinstance(jobs, list) else ():
  720. if not isinstance(job, dict) or not is_job_runnable(job) or is_terminal_job(job):
  721. continue
  722. origin = job.get("origin") if isinstance(job.get("origin"), dict) else {}
  723. if inside(job.get("workdir")) or (
  724. str(origin.get("platform") or "").lower() == "local" and str(origin.get("chat_id") or "") in chats):
  725. return True
  726. return False
  727. def _retained_tree_is_live(db_path: str, worktree_path: str, *, pending_only: bool = False) -> bool:
  728. """Whether a session that can still be resumed has its frozen cwd inside the retained tree:
  729. a row with history or pending gateway work (*pending_only*: pending work alone, the exiting
  730. ``--tui -w`` launcher's "is the gateway still using it" check). A missing store means the
  731. profile is gone; unreadable fails SAFE (live)."""
  732. import sqlite3
  733. from urllib.parse import quote
  734. path = Path(db_path)
  735. if not path.is_file():
  736. return False
  737. inside = _inside_tree(worktree_path)
  738. try:
  739. conn = sqlite3.connect(f"file:{quote(str(path))}?mode=ro", uri=True, timeout=2)
  740. try:
  741. conn.create_function("hermes_inside_tree", 1, inside, deterministic=True)
  742. row = conn.execute(
  743. "SELECT 1 FROM sessions s WHERE hermes_inside_tree(s.cwd) AND ("
  744. + ("" if pending_only else "s.message_count>0 OR ")
  745. + "EXISTS (SELECT 1 FROM session_admissions a WHERE a.target_session_id=s.id "
  746. "AND a.status!='terminal')) LIMIT 1").fetchone()
  747. finally:
  748. conn.close()
  749. except sqlite3.Error as exc:
  750. logger.debug("retained worktree session check failed (%s); keeping tree", exc)
  751. return True
  752. return row is not None
  753. def _worktree_lock_reason(repo_root: str, worktree_path: str, timeout: int):
  754. """``(found, reason)`` from the tree's admin dir (``gitdir:`` of its ``.git`` file, under
  755. ``<common-dir>/worktrees/``); reason is ``None`` when unlocked and ``""`` for a bare lock.
  756. Read raw and trimmed, as git does: ``list --porcelain -z`` needs git 2.36. Raises when git
  757. or the admin dir cannot be read."""
  758. common = _git_out(["rev-parse", "--git-common-dir"], repo_root, timeout=timeout)
  759. if not common:
  760. raise RuntimeError("not a git repository")
  761. tree = Path(worktree_path)
  762. if not (tree / ".git").is_file():
  763. return False, None # no tree there, or the main checkout
  764. link = (tree / ".git").read_text(encoding="utf-8-sig")
  765. if not link.startswith("gitdir:"):
  766. raise RuntimeError(f"unreadable .git file in {tree}")
  767. admin = (tree / link[len("gitdir:"):].strip()).resolve()
  768. if admin.parent != (Path(repo_root) / common / "worktrees").resolve():
  769. return False, None # a checkout of another repository
  770. try:
  771. return True, (admin / "locked").read_text(encoding="utf-8-sig", errors="replace").strip(" \t\n\v\f\r")
  772. except FileNotFoundError:
  773. return True, None
  774. def _worktree_lock_is_live(repo_root: str, worktree_path: str, timeout: int = 10):
  775. """Lock state: ``"live"`` (owning pid runs / a resumable session works in the tree),
  776. ``"dead"`` (pid and sessions gone / non-hermes reason), None (unlocked).
  777. A Hermes tree locks with reason ``hermes pid=<pid>``; ``worktree remove --force`` refuses
  778. locked trees, so a crashed session's lock would keep its tree forever. A ``-w`` tree
  779. also names its profile's ``state.db`` from creation, so a ``--tui -w`` launcher killed with
  780. its terminal (SIGHUP skips the exit re-lock) still keeps the tree while a resumable session's
  781. row cwd is inside it. A classic ``-w`` row's cwd is the repo root: its tree is only recorded,
  782. and a reaped clean one is recreated on resume. Fails SAFE toward "live", including a
  783. ``hermes`` reason this version cannot parse.
  784. """
  785. try:
  786. found, reason = _worktree_lock_reason(repo_root, worktree_path, timeout)
  787. except Exception:
  788. return "live"
  789. if not found or reason is None:
  790. return None
  791. if not reason.startswith("hermes "):
  792. # A foreign lock here is a leftover; the age/dirty/unpushed gates already passed.
  793. return "dead"
  794. lock = _HERMES_LOCK_RE.fullmatch(reason)
  795. if lock is None:
  796. return "live"
  797. pid, db_path = lock.groups()
  798. if pid is not None:
  799. if int(pid) == os.getpid():
  800. return "live"
  801. try:
  802. from gateway.status import _pid_exists
  803. if _pid_exists(int(pid)):
  804. return "live"
  805. except Exception:
  806. return "live"
  807. if db_path is not None:
  808. return "live" if _retained_tree_is_live(db_path, worktree_path) else "dead"
  809. return "dead" if pid is not None else "live" # a session lock without its store: unverifiable
  810. # Trees Hermes names itself (``hermes -w`` sessions, subagent isolation) age on the base tier.
  811. _AUTO_TREE_PREFIXES = ("hermes-", "subagent-")
  812. def prune_tier_hours(name: str, max_age_hours: float) -> float:
  813. """Idle hours before a tree may be reclaimed: *max_age_hours* for Hermes-made trees
  814. (``hermes-*``, ``subagent-*``), 3x for deliberately named ones."""
  815. return max_age_hours if name.startswith(_AUTO_TREE_PREFIXES) else max_age_hours * 3
  816. def _prune_candidates(worktrees_dir: Path, max_age_hours: int, now: float) -> list:
  817. """Phase 1, stat-only age filter -> ``[(entry, mtime, force)]`` for trees past their soft cutoff.
  818. Kanban trees (``t_<hex>``) belong to the kanban gc. Hermes-made trees age on *max_age_hours*,
  819. deliberately named trees at 3x (``prune_tier_hours``); *force* marks the hard (3x) tier.
  820. """
  821. kanban_re = re.compile(r"^t_[0-9a-f]+$")
  822. candidates: list = []
  823. for entry in sorted(worktrees_dir.iterdir()):
  824. if not entry.is_dir() or kanban_re.match(entry.name):
  825. continue
  826. tier_hours = prune_tier_hours(entry.name, max_age_hours)
  827. try:
  828. mtime = entry.stat().st_mtime
  829. if mtime > now - (tier_hours * 3600):
  830. continue # Too recent — skip
  831. except Exception:
  832. continue
  833. candidates.append((entry, mtime, mtime <= now - (tier_hours * 3 * 3600)))
  834. return candidates
  835. def _classify_prune_candidates(repo_root: str, candidates: list) -> list:
  836. """Phase 2, parallel read-only classification -> ``[(entry, mtime, force, verdict, lock_state)]``.
  837. verdict in ``dirty`` / ``unpushed`` / ``locked-live`` / ``reap`` / ``reap-keep-branch``. Each
  838. check is a read-only query on a distinct worktree (no repo-wide lock), so a bounded pool is
  839. safe; mutation stays serial. ``git cherry`` verdicts are memoized on disk.
  840. """
  841. merge_cache = _load_worktree_merge_cache()
  842. cache_size_before = len(merge_cache)
  843. cache_lock = threading.Lock()
  844. # Lazy once-per-sweep ls-remote: only paid when a tree reaches the pushed tier (TUI runs this sync).
  845. _remote_heads_memo: dict = {}
  846. _remote_heads_lock = threading.Lock()
  847. def _get_remote_heads():
  848. with _remote_heads_lock:
  849. if "heads" not in _remote_heads_memo:
  850. _remote_heads_memo["heads"] = _fetch_remote_branch_heads(repo_root, timeout=10)
  851. return _remote_heads_memo["heads"]
  852. def _classify(item):
  853. entry, mtime, force = item
  854. # Never delete real work regardless of age: only clean, merged/pushed trees are reaped.
  855. if _worktree_is_dirty(str(entry), repo_root, timeout=5):
  856. return (entry, mtime, force, "dirty", None)
  857. keep_branch = False
  858. if _worktree_has_unpushed_commits(str(entry), timeout=5):
  859. # Squash-merge escape hatch: patch-equivalent commits are merged, not unpushed.
  860. with cache_lock:
  861. snapshot = dict(merge_cache)
  862. merged = _worktree_commits_all_merged_upstream(str(entry), timeout=30, cache=snapshot)
  863. if not merged:
  864. # Rebase-merge escape hatch: cherry misses changed patch-ids, GitHub knows.
  865. merged = _worktree_branch_pr_merged(str(entry), timeout=15, cache=snapshot)
  866. with cache_lock:
  867. merge_cache.update(snapshot)
  868. # Pushed tier: head EXACTLY matches origin -> reap the tree, keep the branch (open-PR anchor).
  869. if not merged and not _worktree_branch_pushed_exact(str(entry), _get_remote_heads(),
  870. timeout=10):
  871. return (entry, mtime, force, "unpushed", None)
  872. keep_branch = not merged
  873. # Live lock = running hermes; a dead lock is unlocked in phase 3.
  874. lock_state = _worktree_lock_is_live(repo_root, str(entry), timeout=5)
  875. if lock_state == "live":
  876. return (entry, mtime, force, "locked-live", None)
  877. return (entry, mtime, force, "reap-keep-branch" if keep_branch else "reap", lock_state)
  878. # Enough workers to hide git's per-process startup latency without dozens of gits.
  879. workers = max(1, min(8, (os.cpu_count() or 4), len(candidates)))
  880. try:
  881. if workers > 1:
  882. with concurrent.futures.ThreadPoolExecutor(
  883. max_workers=workers, thread_name_prefix="hermes-wt-prune"
  884. ) as pool:
  885. verdicts = list(pool.map(_classify, candidates))
  886. else:
  887. verdicts = [_classify(c) for c in candidates]
  888. except Exception as e:
  889. logger.debug("Parallel worktree classification failed (%s); serial", e)
  890. verdicts = [_classify(c) for c in candidates]
  891. if len(merge_cache) != cache_size_before:
  892. _save_worktree_merge_cache(merge_cache)
  893. return verdicts
  894. # Preserving verdicts -> reason reported for trees past the stale-work cutoff.
  895. _PRESERVE_REASONS = {"dirty": "uncommitted changes", "unpushed": "unpushed commits"}
  896. def removal_blocked(path: str) -> Optional[tuple[str, str]]:
  897. """``(keep-action, reason)`` when deleting the clean tree at *path* would lose something no
  898. branch holds (``worktree_retention.removal_blocker``: a checked-out submodule, an embedded
  899. repository, a per-worktree ref); unverifiable counts as blocked."""
  900. from hermes_cli.worktree_retention import removal_blocker
  901. return removal_blocker(path)
  902. def _reap_prune_verdicts(repo_root: str, verdicts: list, stale_work_cutoff: float) -> tuple[list, set]:
  903. """Phase 3, serial unlock / remove / branch -D -> ``(preserved_stale, kept_branches)``.
  904. *kept_branches* must survive the orphaned-branch pass. Branch deletion is gated on
  905. ``worktree remove`` succeeding so a failed removal never orphans reachable commits.
  906. """
  907. preserved_stale: list = []
  908. kept_branches: set = set()
  909. for entry, mtime, force, verdict, lock_state in verdicts:
  910. reason = _PRESERVE_REASONS.get(verdict)
  911. if reason:
  912. if mtime <= stale_work_cutoff:
  913. preserved_stale.append(f"{entry.name} ({reason})")
  914. continue
  915. if verdict == "locked-live":
  916. logger.debug("Skipping live-locked worktree: %s", entry.name)
  917. continue
  918. blocked = removal_blocked(str(entry))
  919. if blocked:
  920. preserved_stale.append(f"{entry.name} ({blocked[1]})")
  921. continue
  922. if lock_state == "dead":
  923. _git_quiet(["worktree", "unlock", str(entry)], repo_root,
  924. log=f"Failed to unlock dead worktree {entry.name}")
  925. try:
  926. branch = _git(["branch", "--show-current"], str(entry), timeout=5).stdout.strip()
  927. remove_result = _git(["worktree", "remove", str(entry), "--force"], repo_root, timeout=15)
  928. if remove_result.returncode != 0:
  929. logger.debug("Failed to remove worktree %s: %s", entry.name, remove_result.stderr.strip())
  930. continue
  931. if branch and verdict == "reap-keep-branch":
  932. kept_branches.add(branch)
  933. elif branch:
  934. # Unattended sweep: the repository's reference-transaction hook must not run.
  935. _git(["branch", "-D", branch], repo_root,
  936. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  937. logger.debug("Pruned stale worktree: %s (force=%s)", entry.name, force)
  938. except Exception as e:
  939. logger.debug("Failed to prune worktree %s: %s", entry.name, e)
  940. return preserved_stale, kept_branches
  941. def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
  942. """Remove stale worktrees and orphaned branches on startup.
  943. Default (``worktrees.archive_dirty: true``): ``worktree_sweep.run_sweep`` — an idle dirty or
  944. unpushed tree past its tier is archived to ``refs/hermes/archive/<tree>`` and then removed;
  945. live trees (lock owner or any process inside) and Kanban trees are never touched.
  946. ``archive_dirty: false`` (no size budget) runs the classic pass below: dirty trees are never
  947. removed; unpushed commits are never removed UNLESS patch-equivalent to upstream, the PR is
  948. MERGED on GitHub, or the head EXACTLY matches origin (tree reaped, branch kept). Live-locked
  949. trees are skipped; dead locks are unlocked first. Phases: ``_prune_candidates`` ->
  950. ``_classify_prune_candidates`` -> ``_reap_prune_verdicts`` -> ``_prune_orphaned_branches``.
  951. """
  952. try:
  953. _prune_stale_worktree_trees(repo_root, max_age_hours)
  954. finally:
  955. _reclaim_orphan_install_states()
  956. def _reclaim_orphan_install_states() -> None:
  957. """Trees removed by any path (the prune pass, `git worktree remove` by hand, `rm -rf` of a
  958. scratch clone) leave their ~200 MB dependency state under <home>/installs/; reclaim it on
  959. every pass, including the early returns where no tree is old enough to prune. Startup
  960. maintenance must never block a launch; the traceback goes to the debug log."""
  961. try:
  962. from pm.environments import installs_root
  963. from pm.install_states import collect_orphan_install_states
  964. reclaimed = collect_orphan_install_states(installs_root())
  965. if reclaimed:
  966. logger.info("Reclaimed %d dependency state dir(s) of deleted checkouts", len(reclaimed))
  967. except Exception:
  968. logger.debug("Orphan install-state reclaim failed", exc_info=True)
  969. def _prune_stale_worktree_trees(repo_root: str, max_age_hours: int) -> None:
  970. worktrees_dir = Path(repo_root) / ".worktrees"
  971. if not worktrees_dir.exists():
  972. _prune_orphaned_branches(repo_root)
  973. return
  974. # Shallow clones make every aged tree read as unpushed forever; deepen once (fail-soft).
  975. if _repo_is_shallow(repo_root):
  976. _deepen_shallow_repo(repo_root)
  977. from hermes_cli import worktree_sweep
  978. settings = worktree_sweep.sweep_settings()
  979. if not worktree_sweep.classic_mode(settings):
  980. worktree_sweep.run_sweep(repo_root, max_age_hours, settings)
  981. _warn_worktree_footprint(repo_root)
  982. return
  983. now = time.time()
  984. candidates = _prune_candidates(worktrees_dir, max_age_hours, now)
  985. if not candidates:
  986. _prune_orphaned_branches(repo_root)
  987. return
  988. verdicts = _classify_prune_candidates(repo_root, candidates)
  989. preserved_stale, kept_branches = _reap_prune_verdicts(repo_root, verdicts, now - (7 * 24 * 3600))
  990. if preserved_stale:
  991. logger.warning("Preserving %d worktree(s) older than 7 days with unmerged work "
  992. "(run `hermes worktree prune` to review and reclaim): %s",
  993. len(preserved_stale), ", ".join(sorted(preserved_stale)))
  994. _prune_orphaned_branches(repo_root, protect=kept_branches)
  995. _warn_worktree_footprint(repo_root)
  996. def _warn_worktree_footprint(repo_root: str) -> None:
  997. """The startup pass can leave trees it may not reclaim; say so once per launch."""
  998. try:
  999. from hermes_cli.worktree_gc import worktrees_summary
  1000. count, size_mb = worktrees_summary(repo_root, size_below_count=10)
  1001. if count >= 10 or (size_mb or 0) >= 5120:
  1002. size_txt = f" ({size_mb / 1024:.1f}GB)" if size_mb else ""
  1003. logger.warning(".worktrees/ holds %d tree(s)%s — run `hermes worktree list` "
  1004. "to audit and `hermes worktree prune` to reclaim safely.", count, size_txt)
  1005. except Exception:
  1006. logger.debug("worktree summary failed", exc_info=True)
  1007. def _prune_orphaned_branches(repo_root: str, protect: Optional[set] = None) -> None:
  1008. """Delete local ``hermes/hermes-*`` and ``pr-*`` branches with no worktree, except *protect*."""
  1009. try:
  1010. listing = _git_out(["branch", "--format=%(refname:short)"], repo_root)
  1011. if listing is None:
  1012. return
  1013. all_branches = [b.strip() for b in listing.split("\n") if b.strip()]
  1014. except Exception:
  1015. return
  1016. active_branches: set = set()
  1017. try:
  1018. wt_result = _git(["worktree", "list", "--porcelain"], repo_root)
  1019. for line in wt_result.stdout.split("\n"):
  1020. if line.startswith("branch refs/heads/"):
  1021. active_branches.add(line.split("branch refs/heads/", 1)[-1].strip())
  1022. except Exception:
  1023. return # can't determine active branches: bail
  1024. # Also protect the checked-out branch and main.
  1025. try:
  1026. current = _git(["branch", "--show-current"], repo_root, timeout=5).stdout.strip()
  1027. if current:
  1028. active_branches.add(current)
  1029. except Exception:
  1030. pass
  1031. active_branches.add("main")
  1032. orphaned = [b for b in all_branches if b not in active_branches and b not in (protect or ())
  1033. and (b.startswith("hermes/hermes-") or b.startswith("pr-"))]
  1034. if not orphaned:
  1035. return
  1036. for i in range(0, len(orphaned), 50):
  1037. _git_quiet(["branch", "-D"] + orphaned[i:i + 50], repo_root, timeout=30,
  1038. log="Failed to prune orphaned branches",
  1039. stdin=subprocess.DEVNULL, env=noninteractive_git_env())
  1040. logger.debug("Pruned %d orphaned branches", len(orphaned))