_old_updater.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  1. """The newly imported escape hatch from an already-running historical updater.
  2. This module must remain stdlib-only: the parent still has the old interpreter,
  3. modules and native extensions. Only the child imports the updated application.
  4. """
  5. from __future__ import annotations
  6. import dataclasses
  7. import json
  8. import os
  9. from pathlib import Path
  10. import subprocess
  11. import sys
  12. import tempfile
  13. from typing import Any, NoReturn
  14. _result: int | None = None
  15. # The historical updater entrypoints. `_historical_context` reads capture data
  16. # from these frames; `tools.lazy_deps.install_specs` hands off only inside them.
  17. # Keep in sync with scripts/audit-old-updater-imports.py UPDATE_ENTRYPOINTS: the
  18. # audit list is wider on purpose (helpers run *under* these frames and are found
  19. # by the frame walk).
  20. _HISTORICAL_UPDATE_FRAMES = (
  21. ("hermes_cli.update_cmd", "hermes_cli.main"),
  22. ("_cmd_update_impl", "cmd_update"),
  23. )
  24. def _is_historical_update_frame(frame: Any) -> bool:
  25. modules, names = _HISTORICAL_UPDATE_FRAMES
  26. return (frame.f_globals.get("__name__") in modules
  27. and frame.f_code.co_name in names)
  28. def in_historical_update() -> bool:
  29. """True when an ancestor frame is a historical updater entrypoint.
  30. The current tree's updater sets ``_hermes_current_updater_frame`` in its
  31. entrypoints; no historical on-disk version contains that local, so its
  32. presence proves the caller is current code that must keep running rather
  33. than hand control to a takeover child.
  34. """
  35. frame = sys._getframe(1)
  36. try:
  37. while frame is not None:
  38. if (_is_historical_update_frame(frame)
  39. and "_hermes_current_updater_frame" not in frame.f_code.co_varnames):
  40. return True
  41. frame = frame.f_back
  42. finally:
  43. del frame
  44. return False
  45. def _historical_context() -> tuple[dict, list[dict], Any]:
  46. """Carry data already held by old frames, without importing their modules.
  47. Older callers did not pass a continuation object. Read only the historical
  48. updater's known local names; do not serialize frames or arbitrary globals.
  49. """
  50. names = ("had_desktop_app_before_update", "pre_update_snapshot_id",
  51. "pre_update_version", "gateway_mode", "assume_yes", "_pre_update_plan")
  52. found = {}
  53. resumes = []
  54. restart_update = None
  55. frame = sys._getframe(1)
  56. try:
  57. while frame is not None:
  58. # Capture hooks can be imported BEFORE the old updater has pulled.
  59. # A declared-but-unassigned version in its innermost known frame
  60. # proves early entry; a None value is still a post-capture value.
  61. if (restart_update is None and _is_historical_update_frame(frame)
  62. and "pre_update_version" in frame.f_code.co_varnames):
  63. restart_update = "pre_update_version" not in frame.f_locals
  64. for name in names:
  65. if name not in found and name in frame.f_locals:
  66. found[name] = frame.f_locals[name]
  67. token = frame.f_locals.get("_windows_gateway_resume")
  68. if isinstance(token, dict) and not any(token is item for item in resumes):
  69. resumes.append(token)
  70. frame = frame.f_back
  71. finally:
  72. del frame
  73. receipt_module = sys.modules.get("hermes_cli.update_receipt")
  74. receipt_slot = vars(receipt_module).get("_current") if receipt_module else None
  75. get_current = getattr(receipt_slot, "get", None)
  76. current = get_current() if get_current is not None else receipt_slot
  77. receipt = getattr(current, "data", None)
  78. plan = found.get("_pre_update_plan")
  79. if dataclasses.is_dataclass(plan) and not isinstance(plan, type):
  80. plan = dataclasses.asdict(plan)
  81. elif not isinstance(plan, dict):
  82. plan = receipt.get("plan") if isinstance(receipt, dict) else None
  83. return {
  84. "restart_update": restart_update is True,
  85. # Some old updaters reach this hook before checking Desktop at all.
  86. "desktop": found.get("had_desktop_app_before_update"),
  87. "pre_update_snapshot_id": found.get("pre_update_snapshot_id"),
  88. "pre_update_version": found.get("pre_update_version"),
  89. "gateway_mode": bool(found.get("gateway_mode", "--gateway" in sys.argv)),
  90. "assume_yes": bool(found.get("assume_yes", "--yes" in sys.argv)),
  91. "windows_resume": resumes[0] if resumes else None,
  92. "plan": plan,
  93. "receipt": receipt if isinstance(receipt, dict) else None,
  94. }, resumes, receipt_slot
  95. def _run_child(request: dict) -> tuple[int, dict]:
  96. """One JSON exchange; the old process never imports the updated graph."""
  97. root = Path(__file__).resolve().parents[1]
  98. home = os.environ.get("HERMES_HOME")
  99. constants = sys.modules.get("hermes_constants")
  100. override = vars(constants).get("_HERMES_HOME_OVERRIDE") if constants else None
  101. if override is not None:
  102. value = override.get()
  103. if isinstance(value, (str, Path)) and value:
  104. home = str(value)
  105. request.update(root=str(root), home=home, argv=list(sys.argv))
  106. env = {key: value for key, value in os.environ.items()
  107. if not key.startswith(("PYTHON", "UV_")) and key != "VIRTUAL_ENV"}
  108. if home:
  109. env["HERMES_HOME"] = home
  110. env.setdefault("HERMES_UPDATE_HANDOFF_PID", str(os.getpid()))
  111. # Everything the user saw so far came from the OLD updater; say so before the
  112. # new one (package manager) takes over, so logs show where the switch happened.
  113. # ASCII only, like every line printed before the child starts: a Windows pipe encodes this
  114. # process's stdout in the ANSI code page, and a non-cp1252 character raised here, before the
  115. # takeover ever ran (review S1).
  116. print("-> Handing off to the new updater (package manager) for the rest of this update...", flush=True)
  117. with tempfile.TemporaryDirectory(prefix="hermes-update-takeover-") as directory:
  118. context = Path(directory) / "request.json"
  119. result = Path(directory) / "result.json"
  120. context.write_text(json.dumps(request), encoding="utf-8")
  121. code = _run_in_custody(
  122. [sys.executable, "-I", "-S", "-B", "-X", "utf8", str(root / "hermes_cli/_update_takeover.py"),
  123. str(context), str(result)], root, cwd=root, env=env,
  124. )
  125. completed = json.loads(result.read_text(encoding="utf-8-sig")) if result.is_file() else {}
  126. if not isinstance(completed, dict):
  127. raise ValueError("invalid update takeover acknowledgement")
  128. return code if code >= 0 else 1, completed
  129. def _run_in_custody(argv: list, root: Path, **kwargs) -> int:
  130. """Run the takeover (it syncs and builds the checkout) in this updater's checkout custody,
  131. from the update_lock module ALREADY loaded here (nothing new is imported). Windows: created
  132. suspended, bound to this updater's kill-on-close job, then resumed; a refused bind still runs
  133. (the update committed) and the takeover joins the lock holding its own lease. Releases
  134. without these helpers hold no checkout lock, and the takeover acquires it itself."""
  135. lock = sys.modules.get("hermes_cli.update_lock")
  136. bind, resume = (getattr(lock, name, None) for name in ("bind_child_to_update_tree", "resume_suspended_child"))
  137. if os.name != "nt" or bind is None or resume is None or getattr(lock, "_HELD", None) is None:
  138. # Unbounded for the same reason as the Windows wait below (review L7): the takeover is
  139. # the rest of a committed update (sync + build), and it holds the checkout lock fd, so the
  140. # checkout stays locked for as long as it runs, even past this updater's death.
  141. # health: allow HX006 -- unbounded by design: the update's own supervised child
  142. return subprocess.run(argv, **kwargs, **_checkout_custody(root)).returncode # noqa: PLW1510 -- forwarding wrapper: callers pass subprocess kwargs via **kwargs (check may arrive through it); an explicit check=False would raise TypeError
  143. proc = subprocess.Popen(argv, creationflags=lock.CREATE_SUSPENDED, **kwargs)
  144. try:
  145. refusal = bind(proc)
  146. if refusal is not None:
  147. print(f" ! The update's job would not take the takeover ({refusal}); it runs outside the job, "
  148. "holding its own checkout lease.", flush=True)
  149. resume(proc)
  150. # The takeover is the rest of a committed update (sync + build): a bound would abandon it
  151. # mid-write. It dies with this updater (kill-on-close job, or the except path below).
  152. # health: allow HX006 -- unbounded by design: the update's own supervised child
  153. return proc.wait()
  154. except BaseException:
  155. proc.kill()
  156. raise
  157. def _checkout_custody(root: Path) -> dict:
  158. """The takeover child keeps the checkout lock this (old) updater holds: its fd, read from the
  159. update_lock module ALREADY loaded in this process (nothing new is imported here). Releases
  160. without a checkout lock hold none, and the takeover acquires it itself."""
  161. held = getattr(sys.modules.get("hermes_cli.update_lock"), "checkout_lock_fds", None)
  162. try:
  163. fds = tuple(held(root)) if held is not None and os.name == "posix" else ()
  164. except Exception: # health: allow BLE001 -- any older release's checkout_lock_fds; no fds = takeover locks itself
  165. fds = ()
  166. return {"pass_fds": fds} if fds else {}
  167. def stop_for_relaunch(*, incomplete: bool = False) -> NoReturn:
  168. """Finish in a fresh child, then exit rather than resume an old fallback.
  169. The historical name is retained. A finally/atexit path can call another
  170. shim while unwinding; it must receive the same result, not start again.
  171. """
  172. if incomplete:
  173. # A newly retired completion hook has no complete captured worklist.
  174. # It must not start another update or invent a successful receipt. It names its stop on
  175. # the receipt the loaded update_receipt keeps open (an older one lacks the call: no-op).
  176. record = getattr(sys.modules.get("hermes_cli.update_receipt"), "record_stop_reason", None)
  177. if record is not None:
  178. record("old_version_handoff")
  179. print(
  180. "You're updating from an older version of Hermes Agent. "
  181. "To complete this update, run `hermes update` again.",
  182. file=sys.stderr,
  183. )
  184. raise SystemExit(1)
  185. global _result
  186. if _result is not None:
  187. raise SystemExit(_result)
  188. _result = 1
  189. try:
  190. request, resumes, receipt_slot = _historical_context()
  191. _result, completed = _run_child(request)
  192. if completed.get("resume_handled"):
  193. for token in resumes:
  194. token["resume_needed"] = False
  195. if completed.get("receipt_handled"):
  196. if hasattr(receipt_slot, "set"):
  197. receipt_slot.set(None)
  198. elif receipt_slot is not None:
  199. vars(sys.modules["hermes_cli.update_receipt"])["_current"] = None
  200. except (OSError, ValueError, TypeError) as exc:
  201. _result = 1
  202. print(f"Update takeover failed: {exc}", file=sys.stderr, flush=True)
  203. raise SystemExit(_result)
  204. def relaunch_stopped_serves(token: dict) -> None:
  205. """A historical atexit token is separate work, not another whole update."""
  206. if not token.get("pending"):
  207. return
  208. code = 1
  209. try:
  210. code, completed = _run_child({"stopped_serves": token})
  211. if completed.get("serves_handled") is True:
  212. token["pending"] = False
  213. except (OSError, ValueError, TypeError) as exc:
  214. print(f"Stopped serve recovery failed: {exc}", file=sys.stderr, flush=True)
  215. if code or token.get("pending"):
  216. print("Stopped serve recovery did not complete; restart the affected "
  217. "serve/dashboard backends manually.", file=sys.stderr, flush=True)