venv_sync.py 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743
  1. """Pre-venv entry point for PM's dependency transaction.
  2. Stdlib-only at import: installers call this before dependencies exist.
  3. All checkout roots use PM's selected generation and facts; sealed payloads
  4. remain build-owned. ``--check`` is passive and never provisions tools.
  5. """
  6. from __future__ import annotations
  7. import argparse
  8. import json
  9. import os
  10. import subprocess
  11. from pathlib import Path
  12. from hermes_cli.steward import UPDATE_MECHANISMS
  13. def _project_root() -> Path:
  14. return Path(__file__).resolve().parents[1]
  15. def _is_sealed(project_root: Path) -> bool:
  16. """A sealed tree ships its interpreter; only checkouts own a venv.
  17. The stamp file is the authority (shared with hermes_cli.steward).
  18. A tree with BOTH a stamp and .git is a dev tree — treat as checkout.
  19. A stamp without a valid ``updateMechanism`` is a build-lane bug and
  20. must not be silently read as "not sealed" (that is exactly the
  21. misclassification that made sealed trees look updatable) — same
  22. guard as hermes_cli.version_info._stamp_version_info.
  23. """
  24. if (project_root / ".git").exists():
  25. return False
  26. from hermes_cli.steward import read_install_stamp
  27. from pm.paths import install_stamp_path
  28. stamp_path = install_stamp_path(project_root)
  29. data = read_install_stamp(project_root)
  30. if not data:
  31. return False
  32. if data.get("updateMechanism") not in UPDATE_MECHANISMS:
  33. raise RuntimeError(
  34. f"install-stamp.json at {stamp_path.parent} is missing a valid "
  35. f"'updateMechanism' (one of {', '.join(UPDATE_MECHANISMS)}). The "
  36. "build lane that wrote this stamp must pass --update-mechanism to "
  37. "scripts/write_install_stamp.py."
  38. )
  39. return True
  40. def check_runtime(project_root: Path) -> str | None:
  41. """One passive startup verdict; callers only choose stderr or logging."""
  42. import pm
  43. from hermes_cli.steward import read_install_stamp, sealed_steward
  44. if (Path(project_root) / ".git").exists() and read_install_stamp(project_root).get("updateMechanism") != "self":
  45. return None # A developer's checkout does not owe managed products.
  46. problems = pm.activate()
  47. if not problems:
  48. return None
  49. steward = sealed_steward(Path(project_root))
  50. remedy = (f"this {steward}-managed install must rebuild the artifact to fix"
  51. if steward else "run `hermes pm install`")
  52. return f"install out of sync ({'; '.join(problems)}) — {remedy}"
  53. def publish_launchers(project_root: Path, *, create: bool = True) -> None:
  54. """Refresh durable commands; bootstrap repairs only existing PATH exposure."""
  55. import logging
  56. from hermes_cli._launchers import ENTRY_POINTS, ensure_install_launchers, expose_cli, resolve_store_python
  57. from hermes_cli.steward import read_install_stamp
  58. root = Path(project_root)
  59. log = logging.getLogger(__name__)
  60. if _is_sealed(root):
  61. log.info("launchers: sealed tree at %s keeps its own", root)
  62. return # Sealed and external/Nix interpreters retain their own launchers.
  63. if read_install_stamp(root).get("updateMechanism") == "external":
  64. log.info("launchers: external runtime at %s keeps its own", root)
  65. return
  66. if resolve_store_python(root) is None:
  67. # A PM tree promises its launchers (tests/install/e2e-assets/
  68. # source-driver.sh refuses to let --version paper over the gap), so
  69. # this skip is a half-finished update, never a quiet no-op.
  70. log.warning("launchers: no managed interpreter under %s; %s not published",
  71. root, root / ".hermes" / "bin")
  72. return
  73. written = ensure_install_launchers(root, root / ".hermes" / "bin")
  74. if len(written) != len(ENTRY_POINTS):
  75. from pm.package import InstallError
  76. raise InstallError("launchers", "source launcher publication failed", "retry the source update")
  77. result = expose_cli(root, create=create)
  78. if not result["ok"]:
  79. import logging
  80. logging.getLogger(__name__).warning("CLI exposure failed: %s", result["error"])
  81. def sync(project_root: Path | None = None, *, check: bool = False) -> dict:
  82. """Report or sync dependencies. A malformed install stamp is a build error."""
  83. from hermes_cli.update_stage import publish_stage
  84. root = Path(project_root) if project_root is not None else _project_root()
  85. if _is_sealed(root):
  86. return {"state": "sealed", "ok": True}
  87. if not (root / "pyproject.toml").is_file():
  88. return {"state": "failed", "ok": False, "detail": f"no pyproject.toml under {root}"}
  89. try:
  90. import pm
  91. if pm.venv_is_current(project_root=root):
  92. if not check:
  93. publish_launchers(root)
  94. return {"state": "current", "ok": True}
  95. if check:
  96. return {"state": "would-sync", "ok": True}
  97. publish_stage("Updating Python dependencies")
  98. refuse_foreign_owned_venv(root)
  99. pm.sync_venv(explicit=True, project_root=root, evict_incompatible_plugins=True)
  100. collect_superseded_generations(root)
  101. publish_launchers(root)
  102. return {"state": "synced", "ok": True}
  103. except Exception as exc:
  104. return {"state": "failed", "ok": False, "detail": str(exc)}
  105. def collect_superseded_generations(project_root: Path) -> None:
  106. """Collect what a publish just superseded, as the Docker boot already does.
  107. Without this only a manual `hermes pm gc` reclaimed old environments. Safe
  108. right after a sync: the collectors skip leased, selected and day-young
  109. generations and yield to any in-flight install instead of waiting.
  110. """
  111. import logging
  112. from hermes_cli.runtime_state import collect_generations
  113. from pm.environments import install_state_dir
  114. from pm.runtime import collect_runtime_generations
  115. try:
  116. removed = collect_generations(project_root) + collect_runtime_generations(
  117. install_state_dir(project_root) / "pm-runtime")
  118. except (OSError, ValueError) as exc:
  119. # Reclaiming space must never turn a committed update into a failure.
  120. logging.getLogger(__name__).warning("dependency generation cleanup skipped: %s", exc)
  121. return
  122. if removed:
  123. logging.getLogger(__name__).info("collected %d unused dependency generations", len(removed))
  124. #: Answered from the tree alone; a metadata query must never wait on (or fail with)
  125. #: a network-bound source-update completion.
  126. _METADATA_FLAGS = frozenset({"-h", "--help", "-V", "--version"})
  127. def _is_read_only_gateway_status(command: list[str]) -> bool:
  128. """Whether *command* is the recovery diagnostic that must not run an update tail."""
  129. return command[:2] == ["gateway", "status"]
  130. def completion_pending_path(project_root: Path) -> Path:
  131. """Marker for a source update whose dependency sync committed but whose tail
  132. (launchers, products, maintenance) has not finished.
  133. Lives beside PM's facts, not in the checkout: it is per-install state, and a
  134. root-level file would trip the ZIP updater's dirty-tree check.
  135. """
  136. from pm.environments import install_state_dir
  137. return install_state_dir(project_root) / "source-completion-pending"
  138. def arm_completion(project_root: Path) -> Path:
  139. """Persist the tail obligation before selecting a new dependency generation."""
  140. pending = completion_pending_path(project_root)
  141. pending.parent.mkdir(parents=True, exist_ok=True)
  142. pending.write_text("source update tail not finished\n", encoding="utf-8")
  143. return pending
  144. #: Relaunch-driven completion retries are bounded (#122206): a tail that keeps
  145. #: failing re-runs on every launch ("every launch burns ~4 minutes"), so after
  146. #: this many consecutive failures the tail waits out a backoff window before
  147. #: trying again, and past the cap it stops self-starting entirely and leaves
  148. #: the marker for an explicit ``hermes update`` instead. The counter is the
  149. #: tail's own attempt record beside the pending marker: same lifetime, same
  150. #: install scope, cleared by the same success path.
  151. COMPLETION_RETRY_BACKOFF_ATTEMPTS = 2
  152. COMPLETION_RETRY_BACKOFF_SECONDS = 15 * 60
  153. COMPLETION_RETRY_MAX_ATTEMPTS = 6
  154. def _completion_attempts_path(project_root: Path) -> Path:
  155. return completion_pending_path(project_root).with_name("source-completion-attempts")
  156. #: What a launch-time dependency sync consumes. A failed sync is recorded against
  157. #: these inputs (#139952): relaunching over the same inputs repeats the same doomed
  158. #: repair and backs off, while a corrected source update is a fresh repair.
  159. _SYNC_INPUTS = ("pyproject.toml", "uv.lock", "pm/lock.json")
  160. def _sync_inputs_digest(root: Path) -> str:
  161. import hashlib
  162. digest = hashlib.sha256()
  163. for name in _SYNC_INPUTS:
  164. try:
  165. digest.update((root / name).read_bytes())
  166. except OSError:
  167. digest.update(b"-")
  168. digest.update(b"\0")
  169. return digest.hexdigest()
  170. def _read_completion_attempts(record: Path) -> tuple[int, str | None]:
  171. """``(attempts, inputs digest or None)``; raises OSError/ValueError when unreadable."""
  172. lines = record.read_text(encoding="utf-8-sig").split()
  173. return int(lines[0]) if lines else 0, lines[1] if len(lines) > 1 else None
  174. def _record_completion_attempt(root: Path, *, failed: bool, inputs: str | None = None) -> None:
  175. """Track consecutive completion-tail failures beside the pending marker.
  176. The pending marker itself is armed *before* the tail runs (a crash between
  177. the dependency commit and the tail must leave the obligation), so the
  178. marker alone cannot distinguish "never tried" from "tried and failed N
  179. times". The attempts record can: success clears both, failure bumps it.
  180. *inputs* (a failed dependency sync's input digest) restarts the count when
  181. the failures before it were for other inputs.
  182. """
  183. record = _completion_attempts_path(root)
  184. if not failed:
  185. record.unlink(missing_ok=True)
  186. return
  187. try:
  188. attempts, recorded = _read_completion_attempts(record)
  189. except (OSError, ValueError):
  190. attempts, recorded = 0, None
  191. if inputs is not None and recorded is not None and recorded != inputs:
  192. attempts = 0
  193. try:
  194. record.write_text(f"{attempts + 1}\n" + (f"{inputs}\n" if inputs else ""), encoding="utf-8")
  195. except OSError:
  196. pass # a read-only install state degrades to unbounded retries, never blocks boot
  197. def completion_retry_state(project_root: Path, *, now=None) -> tuple[bool, int, int]:
  198. """``(may_retry_now, attempts, backoff_seconds)`` for the owed tail.
  199. Never raises; an unreadable record answers ``(True, 0, 0)`` — the
  200. historical unbounded behavior — because a bookkeeping failure must not
  201. stop a launch from finishing its own update.
  202. """
  203. import time as _time
  204. record = _completion_attempts_path(project_root)
  205. try:
  206. attempts, inputs = _read_completion_attempts(record)
  207. except (OSError, ValueError):
  208. return True, 0, 0
  209. if attempts <= 0 or (inputs is not None and inputs != _sync_inputs_digest(project_root)):
  210. # Failed syncs of other inputs say nothing about this tree's repair.
  211. return True, 0, 0
  212. if attempts >= COMPLETION_RETRY_MAX_ATTEMPTS:
  213. return False, attempts, 0
  214. if attempts < COMPLETION_RETRY_BACKOFF_ATTEMPTS:
  215. # A single failure is the historical case (a flaky tail that a plain
  216. # relaunch fixes): retry immediately, exactly as before (#122206's
  217. # "the next launch owes the tail only" contract).
  218. return True, attempts, 0
  219. try:
  220. mtime = record.stat().st_mtime
  221. except OSError:
  222. return True, attempts, 0
  223. reference = (now or _time.time)()
  224. age = max(0.0, reference - mtime)
  225. if age >= COMPLETION_RETRY_BACKOFF_SECONDS:
  226. return True, attempts, COMPLETION_RETRY_BACKOFF_SECONDS
  227. return False, attempts, int(COMPLETION_RETRY_BACKOFF_SECONDS - age)
  228. def clear_completion(root: Path) -> None:
  229. completion_pending_path(root).unlink(missing_ok=True)
  230. _completion_attempts_path(root).unlink(missing_ok=True)
  231. def refuse_foreign_owned_venv(project_root: Path) -> None:
  232. """Refuse cross-user mutation before PM changes the selected environment (#83529)."""
  233. if not hasattr(os, "geteuid"):
  234. return
  235. uid = os.geteuid() # windows-footgun: ok — guarded POSIX ownership check
  236. root = Path(project_root)
  237. # A root-run update on a user's checkout is not safe even if a fresh
  238. # generation would be allocated: it publishes root-owned state for them.
  239. from pm.environments import selected_venv
  240. candidates = [root, root / "venv", root / ".venv", root / ".hermes", selected_venv(root)]
  241. for venv in (root / "venv", root / ".venv", candidates[-1]):
  242. for directory in (venv / ("Scripts" if os.name == "nt" else "bin"),
  243. *venv.glob("lib/python*/site-packages")):
  244. if directory.is_dir():
  245. candidates.append(directory)
  246. for entry in list(directory.iterdir())[:2000]:
  247. candidates.append(entry)
  248. if entry.name.endswith(".dist-info") and entry.is_dir():
  249. candidates.extend(list(entry.iterdir())[:100])
  250. for path in candidates:
  251. try:
  252. owner = path.lstat().st_uid
  253. except FileNotFoundError:
  254. continue
  255. if owner != uid:
  256. raise RuntimeError(
  257. f"refusing to update {root}: {path} is owned by uid {owner}, "
  258. f"not the current uid {uid}; repair ownership before retrying"
  259. )
  260. #: The completion tails import the CLI (so prepare_launch) while the pending marker is armed.
  261. #: The lock-ancestry check covers that only under a live claim; an unwritable, expired or
  262. #: absent one (an installer run) would start a tail inside the tail, recursively.
  263. _TAIL_SCRIPTS = frozenset({"source_completion.py", "update_completion.py"})
  264. def _is_tail_script(root: Path, argv0: str) -> bool:
  265. """Exact own-script identity; argv is not inherited by the processes a tail spawns."""
  266. script = Path(argv0)
  267. return script.name in _TAIL_SCRIPTS and script.resolve().parent == root / "hermes_cli"
  268. def _supervised_child() -> bool:
  269. """A launcher-marked child: booted by a manager, not a user's shell.
  270. Launcher markers only — not INVOCATION_ID, which systemd exports to every
  271. descendant: an ordinary hermes command inside a CI runner still owes its repair.
  272. Parsed as a truthy flag, so an explicit ``0``/``false`` does not suppress the tail.
  273. """
  274. return any(
  275. os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
  276. for name in ("HERMES_SUPERVISED_CHILD", "HERMES_S6_SUPERVISED_CHILD")
  277. )
  278. def _tree_matches_completed_stamp(root: Path) -> bool:
  279. """True when the checkout is the exact clean tree the last install/update completed.
  280. Every finished tail records its tree in install-stamp.json (write_source_stamp);
  281. when that commit is a clean HEAD, the products in the tree were built for it, so a
  282. stale venv only needs re-provisioning and a marker armed BEFORE that stamp is a
  283. leftover from a previous home/install, never a rebuild of the same SHA (fresh
  284. Windows installs and pristine HERMES_HOMEs hit exactly this: #123314). A marker
  285. armed after the stamp is newer debt (a same-commit ``hermes update`` that failed
  286. or was killed) and is still owed. Boot-time adoption also stamps HEAD but builds
  287. nothing, so its stamp (``adoptedAt``) is not evidence; neither is a dirty tree.
  288. """
  289. from hermes_cli.steward import read_install_stamp
  290. from hermes_cli.version_info import _git_version_info
  291. stamp = read_install_stamp(root)
  292. commit = stamp.get("commit")
  293. if not isinstance(commit, str) or not commit or "adoptedAt" in stamp or stamp.get("dirty") is not False:
  294. return False
  295. pending = completion_pending_path(root)
  296. if pending.is_file() and pending.stat().st_mtime >= (root / "install-stamp.json").stat().st_mtime:
  297. return False
  298. info = _git_version_info(root, include_untracked=True)
  299. return info.commit == commit and not info.dirty
  300. # `hermes update` flags that report and exit without changing anything (subcommands/update.py).
  301. _REPORT_ONLY_UPDATE_FLAGS = frozenset({"--check", "--plan", "--list-venv-holders"})
  302. def _may_retry_completion(root: Path, command: list[str], *, current: bool) -> bool:
  303. """Whether this launch runs the owed repair now; a suppressed one says why when it matters."""
  304. import sys
  305. if not current and command[:1] == ["update"] and not _REPORT_ONLY_UPDATE_FLAGS & set(command):
  306. # `hermes update` is the remedy every backed-off launch names: it always tries the repair.
  307. # Its report-only forms change nothing, so they stay inside the backoff like any launch.
  308. return True
  309. may_retry, attempts, backoff = completion_retry_state(root)
  310. if not may_retry and attempts >= COMPLETION_RETRY_MAX_ATTEMPTS:
  311. # The tail has failed often enough that every relaunch re-running it
  312. # does more harm than good (#122206: "every launch burns ~4 minutes").
  313. # Leave the marker for an explicit `hermes update`; say so once.
  314. print(
  315. f"hermes: a source update could not be finished automatically "
  316. f"({attempts} attempts); run `hermes update` from a shell to finish it",
  317. file=sys.stderr, flush=True,
  318. )
  319. elif not may_retry and not current:
  320. # Inside the backoff window a finished-dependencies tail waits silently (the record's age
  321. # tracks the wait); stale dependencies are worth one line in front of the user.
  322. print(
  323. f"hermes: running with the previous dependencies after {attempts} failed syncs; "
  324. f"next automatic retry in {max(1, backoff // 60)} min, or run `hermes update` to finish it",
  325. file=sys.stderr, flush=True,
  326. )
  327. return may_retry
  328. def _relaunch_target(root: Path, python: Path, *, same: bool) -> Path | None:
  329. """*python*, unless this process is a relaunch into that same interpreter and is still stale.
  330. A relaunched child that is still stale would find the same install state in the next child
  331. too: exec'ing would loop forever (#122513), so it boots as it is. The marker can outlive the
  332. relaunch that set it (a restore re-execs ``sys.orig_argv``), so a marked child whose sync DID
  333. make the install current relaunches once more: that next child boots current, never here.
  334. """
  335. import sys
  336. import pm
  337. if same and getattr(sys, "_hermes_relaunched", False) and not pm.venv_is_current(project_root=root):
  338. print("hermes: relaunching did not leave this install current; running with the "
  339. "dependencies it has — run `hermes update` to finish it", file=sys.stderr, flush=True)
  340. return None
  341. return python
  342. def prepare_launch(project_root: Path, argv: list[str]) -> Path | None:
  343. """Finish a self-managed source update before importing app dependencies.
  344. PM's successful input stamp signals a finished dependency sync; the
  345. ``source-completion-pending`` marker signals the tail still owed after it,
  346. so a tail that failed is retried on the next launch WITHOUT rebuilding
  347. dependencies that are already current. Old updaters need not write a
  348. marker (and cannot accidentally clear this obligation).
  349. A supervised child leaves that tail to ``hermes update`` when its dependencies
  350. are current: its manager restarts it on every start, so a sticky marker would
  351. re-run the tail (and its environment builds) on each boot until the disk fills.
  352. Return the store interpreter when this process must restart cleanly.
  353. """
  354. import os
  355. import sys
  356. root = Path(project_root).resolve()
  357. # sys.argv[0] is this process's script identity; *argv* carries only the command.
  358. if _is_tail_script(root, sys.argv[0]):
  359. return None
  360. from hermes_cli._parser import command_argv
  361. from hermes_cli.steward import read_install_stamp
  362. command = command_argv(argv)
  363. if (command[:1] == ["pm"]
  364. or _METADATA_FLAGS & set(argv)
  365. # This is the recovery path shown by the Desktop when a pending update has
  366. # fenced the gateway. Completing that same tail first can take minutes and
  367. # leaves the user without the fence diagnosis or a usable restart remedy.
  368. or _is_read_only_gateway_status(command)
  369. or os.environ.get("HERMES_DISABLE_LAZY_INSTALLS", "").lower() in ("1", "true", "yes")
  370. or not (root / ".git").exists()
  371. or not (root / "pyproject.toml").is_file()):
  372. return None
  373. stamp = read_install_stamp(root)
  374. if not stamp:
  375. from hermes_cli.post_update import step_adopt_blessed_checkout
  376. step_adopt_blessed_checkout(root)
  377. stamp = read_install_stamp(root)
  378. if stamp.get("updateMechanism") != "self":
  379. return None # Developer checkouts and packaged runtimes retain their owner.
  380. import pm
  381. from hermes_cli._launchers import resolve_store_python
  382. from hermes_cli.update_lock import UpdateLock, read_live_update
  383. current = pm.venv_is_current(project_root=root)
  384. from pm.environments import owning_home_root
  385. owner = owning_home_root(root)
  386. if owner is not None:
  387. return _prepare_borrowed_launch(root, owner, current=current)
  388. pending = completion_pending_path(root)
  389. owed_to_cli = current and pending.is_file() and _supervised_child()
  390. if not _may_retry_completion(root, command, current=current):
  391. if not current:
  392. # No repair ran, so this install is exactly as stale as it was: a relaunch would land
  393. # back here with the same answer and exec again, forever. Boot on the previous
  394. # dependency generation, as a launch whose sync failed does.
  395. return None
  396. elif not owed_to_cli and (not current or pending.is_file()):
  397. # The marker alone first (a process the live update spawned runs under its claim and
  398. # inherits no checkout lock); install_root still names the checkout whose held lock
  399. # keeps a dead update's marker (R6: refused as held, never reclaimed).
  400. lock = UpdateLock(install_root=root, checkout_first=False)
  401. if not lock.acquire():
  402. raise RuntimeError("an update is still running; wait for it to exit, then relaunch Hermes")
  403. try:
  404. # Under the launching update's own claim (its pid is our ancestor) a process it
  405. # spawned owes no tail: that obligation is the updater's.
  406. if not lock.acquired and read_live_update(install_root=root) is not None:
  407. if current:
  408. return None
  409. # A process the update spawns before its dependencies are current (a restarted
  410. # gateway) would boot on a tree built for another interpreter. Sync — never the
  411. # tail, which is the updater's — then relaunch below into a current install.
  412. _sync_source_dependencies(root, arm=False)
  413. if not pm.venv_is_current(project_root=root):
  414. # Relaunching would land back here and sync again, forever.
  415. raise RuntimeError("dependency sync left this install out of date")
  416. else:
  417. # The tail mutates the checkout: ACQUIRE its lock (R2), never sample it. A free
  418. # marker over a held checkout lock is a killed update whose tree (its completion
  419. # child) still runs.
  420. if not lock.acquire_checkout(root):
  421. raise RuntimeError("an update is still running; wait for it to exit, then relaunch Hermes")
  422. _finish_source_update(root, current=current, pending=pending)
  423. finally:
  424. lock.release()
  425. python = resolve_store_python(root)
  426. if python is None:
  427. raise RuntimeError("source update has no managed Python; run `hermes pm install`")
  428. # Lexical identity, never resolve(): PM spells the store path through
  429. # HERMES_HOME (which may carry '..') while sys.executable arrives
  430. # normalized, so a raw compare re-execs every child forever (#122513). A
  431. # venv interpreter symlinked to the same binary is still a different
  432. # interpreter (its own sys.prefix) and must re-exec once.
  433. same = os.path.normcase(os.path.abspath(python)) == os.path.normcase(os.path.abspath(sys.executable))
  434. if not current or not same:
  435. publish_launchers(root)
  436. return _relaunch_target(root, python, same=same)
  437. if owed_to_cli:
  438. # Left owed, not dropped: say so (once, in the process that boots) where an
  439. # operator of the unit will read it.
  440. print("hermes: a source update is unfinished; run `hermes update` from a shell to finish it",
  441. file=sys.stderr, flush=True)
  442. return None
  443. def _prepare_borrowed_launch(root: Path, owner: Path, *, current: bool) -> Path | None:
  444. """Launch a checkout that another data root owns (#123238).
  445. Dependency state is per data root, so a borrowing root -- a test's temporary
  446. ``HERMES_HOME``, a per-task home -- still gets an environment of its own, synced exactly
  447. as a process spawned under a live update syncs. The rest is the checkout's, and so the
  448. owner's: launchers, product builds, post-update maintenance, the install stamp and the
  449. owner's own update markers. None of it is armed, run or published from here, so a
  450. borrowing launch cannot rebind the shared launchers, rebuild products another root is
  451. serving, or race the owner's tail under a lock that lives in a different home.
  452. """
  453. import os
  454. import sys
  455. import pm
  456. from hermes_cli._launchers import resolve_store_python
  457. from hermes_cli.update_lock import UpdateLock
  458. if not current:
  459. lock = UpdateLock(install_root=root, checkout_first=False) # R6, as in prepare_launch
  460. if not lock.acquire():
  461. raise RuntimeError("an update is still running; wait for it to exit, then relaunch Hermes")
  462. try:
  463. _sync_source_dependencies(root, arm=False, borrowed_from=owner)
  464. finally:
  465. lock.release()
  466. if not pm.venv_is_current(project_root=root):
  467. # Relaunching would land back here and sync again, forever.
  468. raise RuntimeError("dependency sync left this install out of date")
  469. python = resolve_store_python(root)
  470. if python is None:
  471. raise RuntimeError("source update has no managed Python; run `hermes pm install`")
  472. same = os.path.normcase(os.path.abspath(python)) == os.path.normcase(os.path.abspath(sys.executable))
  473. return python if not current or not same else None
  474. def _finish_source_update(root: Path, *, current: bool, pending: Path) -> None:
  475. """Sync dependencies when they are stale, then run the tail the marker still owes."""
  476. import sys
  477. from hermes_cli._early_recovery import _marker_owner_is_live
  478. from pm.environments import activation_environment
  479. if not current:
  480. # Existing markers guard liveness, never create the completion obligation.
  481. # Current post-sync verification children can boot under a live updater.
  482. legacy_markers = (root / ".update-incomplete", root / ".lazy-refresh-incomplete")
  483. if any(_marker_owner_is_live(marker) for marker in legacy_markers):
  484. raise RuntimeError("an update is still running; wait for it to exit, then relaunch Hermes")
  485. print("hermes: completing source-update dependencies...", file=sys.stderr, flush=True)
  486. completed = _tree_matches_completed_stamp(root)
  487. # ponytail: commit-only match; a product dir deleted by hand is rebuilt on demand
  488. # by its own entry point (the TUI/web freshness gates), not here.
  489. try:
  490. _sync_source_dependencies(root, arm=not completed)
  491. except Exception:
  492. # The pending marker is armed before this sync. A sync failure is
  493. # therefore an automatic completion failure too: without recording
  494. # it, every Desktop relaunch bypasses the retry backoff and starts
  495. # the same expensive repair again.
  496. if not completed:
  497. _record_completion_attempt(root, failed=True, inputs=_sync_inputs_digest(root))
  498. raise
  499. if completed:
  500. clear_completion(root)
  501. return
  502. elif _tree_matches_completed_stamp(root):
  503. # The stamp names HEAD, so the last install/update already built this tree:
  504. # a pending marker is a leftover from a previous home/install, not an
  505. # interrupted update, and owing nothing is quieter than announcing one.
  506. clear_completion(root)
  507. return
  508. else:
  509. print("hermes: finishing an interrupted source update...", file=sys.stderr, flush=True)
  510. # Sync commits the dependency generation, but a source update also owes
  511. # the product builds and the post-build maintenance -- the tail every
  512. # install and finished update shares (hermes_cli/source_completion.py).
  513. # Those builds need PM's selected interpreter with its dependencies
  514. # activated, so hand that file THIS interpreter and let it re-exec
  515. # itself, exactly as the installers do.
  516. desktop_app = root / "apps/desktop"
  517. desktop = ((desktop_app / "dist/index.html").is_file()
  518. or any((desktop_app / "release").glob("*")))
  519. # The tail's progress lines go to stderr: this is an automatic repair in
  520. # front of whatever command the user ran, and that command may be
  521. # emitting machine-readable stdout (a JSON probe, a piped query).
  522. from hermes_cli.update_custody import CustodyRefused, run
  523. # The completion child stays in this launch's checkout custody (POSIX: it inherits the lock
  524. # fd; Windows: created suspended and bound to the lock owner's kill-on-close job), so a
  525. # contender never sees the checkout free while it builds. A child the job refuses never runs:
  526. # the tail stays owed.
  527. try:
  528. code = run(
  529. [sys.executable, "-I", "-B", "-u",
  530. str(root / "hermes_cli/source_completion.py"),
  531. "--source", str(root), "--finish-update",
  532. *(("--desktop",) if desktop else ())],
  533. inherit_lock=True, cwd=root, env=activation_environment(root), stdout=sys.__stderr__,
  534. ).returncode
  535. except CustodyRefused as exc:
  536. print(f"hermes: {exc.reason}", file=sys.stderr, flush=True)
  537. code = 1
  538. if code != 0:
  539. _record_completion_attempt(root, failed=True)
  540. raise RuntimeError(
  541. "source update completion failed; run `hermes update` to finish it"
  542. )
  543. clear_completion(root)
  544. def _sync_source_dependencies(root: Path, *, arm: bool, borrowed_from: Path | None = None) -> None:
  545. """Commit the tree's dependency generation; *arm* also owes the tail afterwards.
  546. *borrowed_from* names the data root that owns the checkout when this one only borrows
  547. it: the sync is this root's own, but the checkout's update markers stay the owner's.
  548. """
  549. import sys
  550. import pm
  551. from pm.client import ensure_tools_for_sync
  552. from pm.environments import runtime_facts_path
  553. from pm.extras import legacy_selection
  554. if borrowed_from is not None:
  555. print(f"hermes: preparing dependencies for this data root (the checkout's updates belong to "
  556. f"{borrowed_from})...", file=sys.stderr, flush=True)
  557. elif not arm:
  558. print("hermes: preparing dependencies for this update...", file=sys.stderr, flush=True)
  559. refuse_foreign_owned_venv(root)
  560. if arm:
  561. # Owed from before the sync commits: a crash between the commit and the
  562. # tail must leave the tail, not a "current" install with nothing built.
  563. arm_completion(root)
  564. # Main-era installs have no PM ledger; carry what their venv held.
  565. # Established PM installs retain their recorded extras and plugin union instead.
  566. extras = legacy_selection(root) if not runtime_facts_path(root).is_file() else None
  567. # Same order as `hermes update`: an interrupted update or a hand-run
  568. # `git pull` leaves this tree's lockfile ahead of the installed tools.
  569. ensure_tools_for_sync()
  570. # The old venv's extras are carried, not asked for: none of them undoes a `--without`, and
  571. # one beyond [all] that no longer builds is left out.
  572. carried = {"carried": extras[1:]} if extras and len(extras) > 1 else {}
  573. pm.sync_venv(extras, explicit=True, project_root=root, evict_incompatible_plugins=True, **carried)
  574. collect_superseded_generations(root)
  575. if borrowed_from is not None:
  576. return # The checkout's markers describe the owner's environment, not this one.
  577. # These can predate the swap. Once PM commits the replacement they
  578. # must not make early recovery immediately rebuild it a second time.
  579. for name in (".update-incomplete", ".lazy-refresh-incomplete"):
  580. (root / name).unlink(missing_ok=True)
  581. def relaunch_command(
  582. python: Path, root: Path, argv: list[str], original: list[str], module: str | None,
  583. ) -> list[str]:
  584. """Re-enter the same script/module/launcher with the managed interpreter.
  585. An old venv may use a different Python ABI. Do not add the new generation
  586. to that interpreter, and do not depend on its obsolete editable finder.
  587. """
  588. # Preserve interpreter options, not application flags with the same names.
  589. options: list[str] = []
  590. index = 1
  591. while index < len(original):
  592. option = original[index]
  593. if option in ("-c", "-m", "--", "-") or not option.startswith("-"):
  594. break
  595. options.append(option)
  596. index += 1
  597. if option in ("-W", "-X") and index < len(original):
  598. options.append(original[index])
  599. index += 1
  600. # _hermes_relaunched marks the child this starts (not processes it spawns) for _relaunch_target;
  601. # a restore re-execs sys.orig_argv and keeps it, which is why that guard re-checks currency.
  602. prefix = (f"import sys, runpy; sys.path.insert(0, {str(root)!r}); sys.argv = {argv!r}; "
  603. "sys._hermes_relaunched = True; ")
  604. if argv[0] == "-c":
  605. body = f"exec({original[index + 1]!r})"
  606. elif module and module != "__main__":
  607. body = f"runpy.run_module({module!r}, run_name='__main__', alter_sys=True)"
  608. else:
  609. # distlib .exe launchers are executable zip files with __main__, not
  610. # importable modules named '__main__'. run_path handles both shapes.
  611. body = f"runpy.run_path({str(Path(argv[0]).absolute())!r}, run_name='__main__')"
  612. return [str(python), *options, "-I", "-c", prefix + body]
  613. def main(argv: list | None = None) -> int:
  614. parser = argparse.ArgumentParser(prog="hermes_cli.venv_sync")
  615. parser.add_argument("--project-root", default=None)
  616. parser.add_argument(
  617. "--check", action="store_true", help="report; change nothing"
  618. )
  619. parser.add_argument("--json", action="store_true")
  620. args = parser.parse_args(argv)
  621. result = sync(
  622. Path(args.project_root) if args.project_root else None, check=args.check
  623. )
  624. if args.json:
  625. print(json.dumps(result))
  626. else:
  627. detail = f" ({result['detail']})" if result.get("detail") else ""
  628. print(f"venv sync: {result['state']}{detail}")
  629. return 0 if result["ok"] else 1
  630. if __name__ == "__main__":
  631. raise SystemExit(main())