hermes_bootstrap.py 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622
  1. """Process bootstrap for Hermes entry points: Windows UTF-8 stdio and ANSI console, import-path
  2. hardening, durable lazy-install target, and dual-stack (Happy Eyeballs) connects.
  3. Windows binds stdio to the console code page (cp1252), so ``print("café")`` raises
  4. ``UnicodeEncodeError``, and Python children inherit the same default unless
  5. ``PYTHONUTF8``/``PYTHONIOENCODING`` are set. Import this module first in every entry
  6. point (``hermes``, ``hermes-agent``, ``hermes-acp``, ``gateway.run``, ``batch_runner``,
  7. ``cron/scheduler``). It does NOT re-exec with ``-X utf8``: ``open()`` in the current
  8. process still needs an explicit ``encoding="utf-8"`` (ruff ``PLW1514``). POSIX is left
  9. alone deliberately — users' ``LANG``/``LC_*`` choices are respected.
  10. Stdlib only: entry points import this before ``harden_import_path()`` runs, so nothing
  11. here may pull in a Hermes package that a project-local directory could shadow.
  12. """
  13. from __future__ import annotations
  14. import errno
  15. import importlib.abc
  16. import importlib.util
  17. import os
  18. import selectors
  19. import socket
  20. import sys
  21. import time
  22. _IS_WINDOWS = sys.platform == "win32"
  23. _bootstrap_applied = False
  24. _HAPPY_EYEBALLS_DELAY_SECONDS = 0.25
  25. _URLLIB3_CONNECTION_MODULE = "urllib3.util.connection"
  26. def _interleave_addrinfos(addrinfos: list[tuple]) -> list[tuple]:
  27. """Round-robin the resolved address families (deduped), preserving resolver order within each."""
  28. queues: dict[int, list[tuple]] = {}
  29. seen: set[tuple] = set()
  30. for addrinfo in addrinfos:
  31. family, socktype, proto, _canonname, sockaddr = addrinfo
  32. if (family, socktype, proto, sockaddr) not in seen:
  33. seen.add((family, socktype, proto, sockaddr))
  34. queues.setdefault(family, []).append(addrinfo)
  35. interleaved: list[tuple] = []
  36. while any(queues.values()):
  37. interleaved.extend(queue.pop(0) for queue in queues.values() if queue)
  38. return interleaved
  39. def _quiet_unregister(selector, sock) -> None:
  40. try:
  41. selector.unregister(sock)
  42. except Exception:
  43. pass
  44. def _happy_eyeballs_create_connection(address: tuple[str, int], timeout: float | None,
  45. source_address: tuple[str, int] | None = None, socket_options=()):
  46. """RFC 8305-style connect: staggered non-blocking attempts across families.
  47. ``socket.create_connection`` tries addresses serially, so broken-but-
  48. advertised IPv6 can burn the whole timeout per AAAA record before IPv4.
  49. """
  50. host, port = address
  51. addrinfos = _interleave_addrinfos(socket.getaddrinfo(host, port, type=socket.SOCK_STREAM))
  52. if not addrinfos:
  53. raise OSError(f"getaddrinfo returned no addresses for {host}")
  54. selector = selectors.DefaultSelector()
  55. active: set[socket.socket] = set()
  56. winner = None
  57. last_error: OSError | None = None
  58. deadline = None if timeout is None else time.monotonic() + max(timeout, 0.0)
  59. next_launch = time.monotonic()
  60. pending = list(addrinfos)
  61. in_progress = {0, errno.EINPROGRESS, errno.EWOULDBLOCK, errno.EALREADY, errno.EINTR, getattr(errno, "WSAEWOULDBLOCK", 10035)}
  62. def start_attempt(addrinfo):
  63. family, socktype, proto, _canonname, sockaddr = addrinfo
  64. candidate = socket.socket(family, socktype, proto)
  65. try:
  66. if source_address is not None:
  67. local_infos = socket.getaddrinfo(source_address[0], source_address[1], family=family, type=socktype)
  68. if not local_infos:
  69. raise OSError(f"getaddrinfo returned no local {family} address for {source_address[0]}")
  70. candidate.bind(local_infos[0][4])
  71. candidate.setblocking(False)
  72. result = candidate.connect_ex(sockaddr)
  73. if result in (0, errno.EISCONN):
  74. return candidate
  75. if result not in in_progress:
  76. raise OSError(result, os.strerror(result))
  77. selector.register(candidate, selectors.EVENT_WRITE)
  78. active.add(candidate)
  79. return None
  80. except Exception:
  81. candidate.close()
  82. raise
  83. try:
  84. while pending or active:
  85. now = time.monotonic()
  86. if deadline is not None and now >= deadline:
  87. raise TimeoutError("timed out")
  88. if pending and now >= next_launch:
  89. try:
  90. winner = start_attempt(pending.pop(0))
  91. except OSError as exc:
  92. last_error = exc
  93. if not active:
  94. next_launch = now
  95. continue
  96. if winner is not None:
  97. break
  98. next_launch = now + _HAPPY_EYEBALLS_DELAY_SECONDS
  99. wait_timeout = None if deadline is None else max(0.0, deadline - now)
  100. if pending:
  101. until_launch = max(0.0, next_launch - now)
  102. wait_timeout = until_launch if wait_timeout is None else min(wait_timeout, until_launch)
  103. for key, _mask in selector.select(wait_timeout):
  104. candidate = key.fileobj
  105. error_code = candidate.getsockopt(socket.SOL_SOCKET, socket.SO_ERROR)
  106. selector.unregister(candidate)
  107. active.discard(candidate)
  108. if error_code == 0:
  109. winner = candidate
  110. break
  111. candidate.close()
  112. last_error = OSError(error_code, os.strerror(error_code))
  113. if winner is not None:
  114. break
  115. if not active and pending:
  116. next_launch = time.monotonic()
  117. if winner is None:
  118. raise last_error if last_error is not None else OSError(f"Could not connect to {host}:{port}")
  119. _quiet_unregister(selector, winner)
  120. active.discard(winner)
  121. winner.settimeout(timeout)
  122. for option in socket_options or ():
  123. winner.setsockopt(*option)
  124. winner.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
  125. return winner
  126. finally:
  127. for candidate in active:
  128. _quiet_unregister(selector, candidate)
  129. candidate.close()
  130. selector.close()
  131. def _patch_urllib3_create_connection(module) -> None:
  132. """Point ``urllib3.util.connection.create_connection`` (its own serial walker) at the racer."""
  133. if getattr(module.create_connection, "_hermes_happy_eyeballs", False):
  134. return
  135. urllib3_sentinel = module._DEFAULT_TIMEOUT
  136. def _urllib3_racer(address, timeout=urllib3_sentinel, source_address=None, socket_options=None):
  137. effective = socket.getdefaulttimeout() if timeout is urllib3_sentinel else timeout
  138. # OSError = every candidate failed (identical to the serial original); anything else is a
  139. # racer bug and must surface rather than silently fall back to the serial stall.
  140. return _happy_eyeballs_create_connection(
  141. address, effective, source_address=source_address, socket_options=tuple(socket_options or ()))
  142. _urllib3_racer._hermes_happy_eyeballs = True # type: ignore[attr-defined]
  143. module.create_connection = _urllib3_racer
  144. class _Urllib3ConnectionPatcher(importlib.abc.MetaPathFinder, importlib.abc.Loader):
  145. """One-shot import hook: patch urllib3's connect walker the moment the module loads.
  146. Importing urllib3 eagerly costs ~50 ms on every CLI start, and ``hermes`` / the TUI
  147. gateway never load it unless something actually calls ``requests``.
  148. """
  149. def find_spec(self, fullname, path, target=None):
  150. if fullname != _URLLIB3_CONNECTION_MODULE:
  151. return None
  152. if self in sys.meta_path:
  153. sys.meta_path.remove(self)
  154. spec = importlib.util.find_spec(fullname)
  155. if spec is None or spec.loader is None:
  156. return None
  157. self._inner = spec.loader
  158. spec.loader = self
  159. return spec
  160. def create_module(self, spec):
  161. return self._inner.create_module(spec)
  162. def exec_module(self, module):
  163. self._inner.exec_module(module)
  164. _patch_urllib3_create_connection(module)
  165. def install_happy_eyeballs_socket_connect() -> None:
  166. """Race IPv6/IPv4 for every sync TCP connect in the process (RFC 8305, #114265).
  167. The startup path does not build its HTTP clients in one place: the model catalog
  168. fetch goes through ``requests``/``urllib3``, sync LLM and OAuth clients through
  169. httpcore, plugins through ``urllib``/``http.client``. All of them funnel their TCP
  170. connect into ``socket.create_connection`` (``http.client`` re-reads it per connection;
  171. httpcore looks it up at call time) or into urllib3's own serial copy in
  172. ``urllib3.util.connection``. The stock implementations walk the ``getaddrinfo``
  173. results serially — on a network whose advertised IPv6 route is blackholed, each AAAA
  174. record burns the full connect timeout before IPv4 answers. Idempotent, best-effort.
  175. """
  176. if getattr(socket.create_connection, "_hermes_happy_eyeballs", False):
  177. return
  178. def _socket_racer(address, timeout=socket._GLOBAL_DEFAULT_TIMEOUT, source_address=None, *, all_errors=False):
  179. # Stock create_connection leaves the sentinel alone, so the socket keeps the
  180. # process default from socket.setdefaulttimeout(); the racer re-applies the
  181. # timeout on the winner, so it must resolve the sentinel the same way.
  182. effective = socket.getdefaulttimeout() if timeout is socket._GLOBAL_DEFAULT_TIMEOUT else timeout
  183. # OSError = every candidate failed (identical to the serial original); anything else is a
  184. # racer bug and must surface rather than silently fall back to the serial stall.
  185. return _happy_eyeballs_create_connection(address, effective, source_address=source_address)
  186. _socket_racer._hermes_happy_eyeballs = True # type: ignore[attr-defined]
  187. socket.create_connection = _socket_racer
  188. urllib3_connection = sys.modules.get(_URLLIB3_CONNECTION_MODULE)
  189. if urllib3_connection is not None:
  190. _patch_urllib3_create_connection(urllib3_connection)
  191. elif not any(isinstance(finder, _Urllib3ConnectionPatcher) for finder in sys.meta_path):
  192. sys.meta_path.insert(0, _Urllib3ConnectionPatcher())
  193. def apply_windows_utf8_bootstrap() -> bool:
  194. """Apply the Windows UTF-8 bootstrap once; True only when it was applied this call."""
  195. global _bootstrap_applied
  196. if not _IS_WINDOWS or _bootstrap_applied:
  197. return False
  198. # setdefault() so a user can opt out with PYTHONUTF8=0 / PYTHONIOENCODING=...
  199. os.environ.setdefault("PYTHONUTF8", "1")
  200. os.environ.setdefault("PYTHONIOENCODING", "utf-8")
  201. # os.environ changes don't rebind streams bound at interpreter startup, so
  202. # reconfigure them in-process. errors="replace" keeps a non-UTF-8 legacy
  203. # pipe on stdin from crashing us (U+FFFD instead of an exception).
  204. # Non-TextIOWrapper streams (BytesIO in tests, embedded hosts) have no
  205. # reconfigure(): skip — the env-var fix for children is the bigger win.
  206. for stream_name in ("stdout", "stderr", "stdin"):
  207. reconfigure = getattr(getattr(sys, stream_name, None), "reconfigure", None)
  208. if reconfigure is None:
  209. continue
  210. try:
  211. reconfigure(encoding="utf-8", errors="replace")
  212. except (OSError, ValueError):
  213. pass # closed, or replaced with something non-reconfigurable
  214. _bootstrap_applied = True
  215. return True
  216. _ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
  217. def enable_windows_vt(streams=None) -> bool:
  218. """Opt the console behind stdout/stderr in to ANSI escape processing.
  219. ``hermes_cli.colors`` and the skins emit raw SGR codes whenever stdout is a TTY. A
  220. conhost console (PowerShell 5.1, cmd.exe, the installer's ``hermes setup``) prints
  221. them as ``←[35m`` until the output handle has ENABLE_VIRTUAL_TERMINAL_PROCESSING, and
  222. shells hand native children a console with it off. The mode belongs to the console
  223. buffer, so setting it here also covers the relaunched child. Handles that are not a
  224. console (pipes, files, NUL, a windowless pythonw) fail GetConsoleMode and are left
  225. alone. A console that refuses VT (pre-Windows 10) gets NO_COLOR instead, which
  226. ``should_use_color`` and rich honour, so it shows plain text rather than garbage.
  227. Returns False only in that fallback case.
  228. """
  229. if not _IS_WINDOWS:
  230. return True
  231. import ctypes
  232. import msvcrt
  233. from ctypes import wintypes
  234. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  235. enabled = True
  236. for stream in (sys.stdout, sys.stderr) if streams is None else streams:
  237. try:
  238. handle = msvcrt.get_osfhandle(stream.fileno())
  239. except (AttributeError, OSError, ValueError):
  240. continue # no fd (None under pythonw, StringIO in embedders)
  241. mode = wintypes.DWORD()
  242. if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
  243. continue
  244. if mode.value & _ENABLE_VIRTUAL_TERMINAL_PROCESSING:
  245. continue
  246. if not kernel32.SetConsoleMode(handle, mode.value | _ENABLE_VIRTUAL_TERMINAL_PROCESSING):
  247. enabled = False
  248. if not enabled:
  249. os.environ.setdefault("NO_COLOR", "1")
  250. return enabled
  251. def suppress_platform_ver_console() -> None:
  252. """Stub ``platform._syscmd_ver`` on Windows — decode-crash + console-flash guard.
  253. ``platform.win32_ver()`` (reached via ``platform.platform()``, which the OpenAI SDK
  254. calls) shells out ``cmd /c ver`` with ``shell=True`` and no ``CREATE_NO_WINDOW``: a
  255. windowless parent (pythonw gateway, slash/kanban workers) flashes a console per call,
  256. and Python 3.11.0/3.11.1 (no ``encoding="locale"`` fix) strict-utf-8-decodes the OEM
  257. code page output under PEP 540 mode and raises (#69413). Returning the inputs makes
  258. ``win32_ver()`` fall back to ``sys.getwindowsversion()`` — same data, no subprocess.
  259. Mirrors ``hermes_cli._subprocess_compat.suppress_platform_ver_console`` for callers
  260. that never import ``hermes_cli.main``; double application is harmless.
  261. """
  262. if not _IS_WINDOWS:
  263. return
  264. try:
  265. import platform
  266. if hasattr(platform, "_syscmd_ver"):
  267. def _quiet_syscmd_ver(system="", release="", version="",
  268. supported_platforms=("win32", "win16", "dos")):
  269. return system, release, version
  270. platform._syscmd_ver = _quiet_syscmd_ver
  271. except Exception:
  272. pass # hardening only — never break an entry point
  273. def _glibc_frees_environ() -> bool:
  274. """True on glibc < 2.41, whose ``setenv`` of a NEW name reallocs the ``environ`` array
  275. and frees the old one (2.41+ never frees it, so a concurrent ``getenv`` stays safe)."""
  276. if not sys.platform.startswith("linux"):
  277. return False
  278. try:
  279. libc, _, version = (os.confstr("CS_GNU_LIBC_VERSION") or "").partition(" ")
  280. return libc == "glibc" and tuple(int(p) for p in version.split(".")[:2]) < (2, 41)
  281. except (AttributeError, OSError, TypeError, ValueError):
  282. return False
  283. def install_never_free_environ() -> None:
  284. """Make ``os.environ`` writes safe against native ``getenv`` in other threads.
  285. On glibc < 2.41 adding a name reallocs ``environ`` and frees the old array while a
  286. thread that dropped the GIL (``getaddrinfo``, OpenSSL's ``SSL_CERT_FILE`` lookup) may
  287. still be walking it; the freed slots hold tcache pointers, so the walk segfaults the
  288. whole process. Hermes writes new names at runtime from many places (``session.create``
  289. turns on gateway prompts, the agent build sets ``HERMES_SESSION_ID``) while background
  290. threads fetch catalogs, so the tui_gateway died with SIGSEGV. This is glibc 2.41's own
  291. fix: entry strings are cached per ``NAME=value`` and never freed; a new name is
  292. appended in place to an array with spare room, and only a full array is replaced by
  293. a bigger one, the old one kept forever. Set/del churn of the same names therefore
  294. allocates nothing after the first cycle.
  295. Residual: a NEW-name ``setenv`` from native code (a C or Rust extension, not
  296. ``os.environ``) bypasses the lock and still reallocs glibc's own last array, so a
  297. ``getenv`` that started walking that array before our swap can still fault. None of
  298. the gateway's crash paths do this.
  299. """
  300. if getattr(os.putenv, "_hermes_never_free_environ", False) or not _glibc_frees_environ():
  301. return
  302. import _thread
  303. import ctypes
  304. try:
  305. libc = ctypes.CDLL(None)
  306. environ = ctypes.c_void_p.in_dll(libc, "environ")
  307. getenv = libc.getenv
  308. except (AttributeError, OSError, ValueError):
  309. return
  310. getenv.restype, getenv.argtypes = ctypes.c_void_p, [ctypes.c_char_p]
  311. real_putenv, real_unsetenv = os.putenv, os.unsetenv
  312. # Two unserialized writers both copy the live array and the later publish drops the
  313. # other's new name or undoes its replacement. Reentrant: audit hooks run inside it.
  314. lock = _thread.RLock()
  315. # A fork while another thread holds the lock would leave it held forever in the child.
  316. os.register_at_fork(before=lock.acquire, after_in_parent=lock.release, after_in_child=lock.release)
  317. lines: dict[bytes, ctypes.Array] = {} # b"NAME=value" -> its C string (glibc's known_values)
  318. arrays: list[tuple[ctypes.Array, int]] = [] # every array we published + its address; only the last grows
  319. gen = [0] # bumped by every publish, so a nested write inside an audited call forces a redo
  320. def _putenv(key, value) -> None:
  321. name, val = os.fsencode(key), os.fsencode(value)
  322. if not name or b"=" in name or b"\0" in name + val:
  323. real_putenv(key, value) # the usual OSError/ValueError
  324. return
  325. sys.audit("os.putenv", name, val)
  326. prefix = name + b"="
  327. with lock:
  328. if (line := lines.get(prefix + val)) is None:
  329. line = lines[prefix + val] = ctypes.create_string_buffer(prefix + val)
  330. entry = ctypes.addressof(line)
  331. # create_string_buffer/addressof above are audited and a hook may write os.environ
  332. # re-entrantly (RLock): redo the read if any write was published before ours. The loop
  333. # itself makes no audited call, so a hook that writes on every event cannot spin it.
  334. while True:
  335. start = gen[0]
  336. # getenv returns a pointer just past "NAME=" inside the matching entry, so the
  337. # walk compares pointers instead of reading every string.
  338. found = getenv(name)
  339. target = found - len(prefix) if found else None
  340. live = ctypes.cast(environ.value, ctypes.POINTER(ctypes.c_void_p)) if environ.value else None
  341. n, hit = 0, False
  342. while live and (current := live[n]):
  343. if current == target:
  344. hit = True
  345. break
  346. n += 1
  347. own, own_addr = arrays[-1] if arrays else (None, None)
  348. grow = not hit and not (own is not None and environ.value == own_addr and n + 2 <= len(own))
  349. if grow:
  350. fresh = (ctypes.c_void_p * max(2 * (n + 2), 64))(*(live[:n] if live else ()), entry)
  351. fresh_addr = ctypes.cast(fresh, ctypes.c_void_p).value # unaudited, unlike addressof
  352. if gen[0] == start:
  353. break
  354. # No audited call from here on. Plain aligned stores: a concurrent walker sees them in
  355. # order on x86-64 (TSO). aarch64 may reorder them, which is theoretical there and
  356. # matches glibc < 2.41's own plain-store publish; Python has no cheap portable fence.
  357. gen[0] += 1
  358. if hit:
  359. live[n] = entry # replace in place, as glibc does
  360. elif not grow:
  361. own[n + 1] = None # terminator first, so a walker never runs past the new entry
  362. own[n] = entry
  363. else:
  364. arrays.append((fresh, fresh_addr))
  365. environ.value = fresh_addr
  366. def _unsetenv(key) -> None:
  367. with lock: # glibc shifts the entries of the live array (ours included) in place
  368. real_unsetenv(key)
  369. gen[0] += 1
  370. _putenv._hermes_never_free_environ = True # type: ignore[attr-defined]
  371. _unsetenv._hermes_never_free_environ = True # type: ignore[attr-defined]
  372. os.putenv, os.unsetenv = _putenv, _unsetenv
  373. def harden_import_path(src_root: str | None = None) -> None:
  374. """Stop a package in the current directory from shadowing Hermes modules.
  375. Hermes ships top-level modules with common names (``utils``, ``proxy``, ``ui``); a
  376. project with its own ``utils/`` launched from its directory would win the import.
  377. The cwd reaches ``sys.path`` as ``""``/``"."`` (script/``-m`` launches) AND as an
  378. absolute path (venv activation, PYTHONPATH), so both are handled: relative forms are
  379. dropped and the Hermes root is *relocated* to the front, not merely inserted when
  380. absent. ``src_root`` defaults to this module's directory (the repo root for every
  381. shipped entry point), so no spawner env var is required.
  382. """
  383. root = src_root or os.environ.get("HERMES_PYTHON_SRC_ROOT") or os.path.dirname(
  384. os.path.abspath(__file__)
  385. )
  386. sys.path[:] = [p for p in sys.path if p not in ("", ".")]
  387. root_abs = os.path.abspath(root)
  388. sys.path[:] = [p for p in sys.path if os.path.abspath(p) != root_abs]
  389. sys.path.insert(0, root)
  390. def export_scratch_tmp_env() -> None:
  391. """Point ``TMPDIR``/``TMP``/``TEMP`` at ``HERMES_HOME/cache/scratch`` unless the user set them.
  392. System temp is tmpfs on most Linux hosts and containers; Hermes' browser profiles, PTY
  393. probes and every ``tempfile`` default a child script makes would eat RAM there. Runs at
  394. import so every entry point and every child they spawn inherits it; ``hermes_cli.main``
  395. re-runs it after ``--profile`` re-homes the process. Never raises.
  396. """
  397. try:
  398. from hermes_constants import export_scratch_tmp_env as _export
  399. _export()
  400. except Exception:
  401. pass # a missing/unwritable home just leaves the system temp dir in place
  402. # Apply on import — entry points just need ``import hermes_bootstrap``
  403. # (or ``from hermes_bootstrap import apply_windows_utf8_bootstrap``) at
  404. # the very top of their module, before importing anything else. The
  405. # import side effect does the right thing.
  406. apply_windows_utf8_bootstrap()
  407. enable_windows_vt()
  408. suppress_platform_ver_console()
  409. install_never_free_environ()
  410. # Every entry point imports this module before its dependency graph.
  411. from pathlib import Path
  412. _root = Path(__file__).resolve().parent
  413. try:
  414. os.getcwd()
  415. except FileNotFoundError:
  416. # Reaped workspaces leave children in a deleted cwd. PM resolves relative
  417. # import paths before the CLI's guards, so recover before any PM work.
  418. os.chdir(_root)
  419. def _legacy_post_swap_invocation(argv: list[str]) -> tuple[Path, list[str]] | None:
  420. """Recognize the exact fresh-checkout command emitted by shipped updaters."""
  421. if not argv or argv[0] != "update":
  422. return None
  423. try:
  424. marker = argv.index("--post-swap", 1)
  425. except ValueError:
  426. return None
  427. if marker + 2 != len(argv):
  428. return None
  429. return Path(argv[marker + 1]), argv[1:marker]
  430. # Everything below imports Hermes packages, so the root goes on sys.path first. A venv
  431. # editable-installed from a pre-PM tree maps only the top-level packages it knew then:
  432. # without this, ``pm`` is unimportable and the launch silently skips PM adoption.
  433. harden_import_path(str(_root))
  434. def _settle_interrupted_update() -> None:
  435. """Put back the tree a killed ``hermes update`` left half-moved, before PM, launch preparation or
  436. any Hermes package imports from it (``hermes_cli._early_recovery``; ``hermes_cli.main`` repeats the
  437. call for entries that never reach this module). A killed ZIP swap can leave ``hermes_cli/`` itself
  438. moved aside: the journal-driven restore then runs from that moved-aside copy, the code that wrote
  439. the journal. Root files are never absent mid-swap (``update_cmd_zip._commit_staged_replacements``)."""
  440. try:
  441. from hermes_cli import _early_recovery as recovery
  442. except ImportError:
  443. moved_aside = _root / "hermes_cli.hermes-update-old" / "_early_recovery.py"
  444. if not (_root / ".hermes-update-zip-swap").is_file() or not moved_aside.is_file():
  445. return # not a torn update: the imports below report the real damage
  446. import types
  447. # The moved-aside directory stands in as ``hermes_cli`` (its ``__init__`` not run), so the
  448. # repair's own ``from hermes_cli import update_lock`` finds the custody code beside it:
  449. # without that the restore refuses to repair unguarded. Dropped again unless it relaunches.
  450. package = types.ModuleType("hermes_cli")
  451. package.__path__ = [str(moved_aside.parent), str(_root / "hermes_cli")]
  452. sys.modules["hermes_cli"] = package
  453. try:
  454. from hermes_cli import _early_recovery as recovery
  455. if recovery.restore_interrupted_pull(_root):
  456. recovery.relaunch_after_restore()
  457. finally:
  458. for name in [n for n in sys.modules if n == "hermes_cli" or n.startswith("hermes_cli.")]:
  459. del sys.modules[name]
  460. return
  461. if recovery.restore_interrupted_pull(_root):
  462. recovery.relaunch_after_restore()
  463. _settle_interrupted_update()
  464. def _pin_launcher_home() -> None:
  465. """A minted launcher (``hermes_cli._launchers``) pins ``HERMES_HOME`` to the install's default
  466. root. That needs ``hermes_constants`` from the checkout, so the launcher asks for it here, after
  467. the repair above: a merge killed while writing ``hermes_constants.py`` must not keep the repair
  468. from ever running. The flag name is ``_launchers.PIN_DEFAULT_HOME_FLAG``."""
  469. if getattr(sys, "_hermes_pin_default_home", False) and not os.environ.get("HERMES_HOME"):
  470. from hermes_constants import get_default_hermes_root
  471. os.environ["HERMES_HOME"] = str(get_default_hermes_root())
  472. _pin_launcher_home()
  473. _legacy_post_swap = _legacy_post_swap_invocation(sys.argv[1:])
  474. if _legacy_post_swap is not None:
  475. # This continuation exists precisely because the replacement tree may not
  476. # run under the old release's dependency graph. Take it over before PM
  477. # activation, launch preparation, or argparse imports any of that graph.
  478. from hermes_cli.update_handoff import _continue_legacy_post_swap
  479. _handoff_path, _argv_tail = _legacy_post_swap
  480. raise SystemExit(_continue_legacy_post_swap(_handoff_path, argv_tail=_argv_tail))
  481. class RelaunchExit(SystemExit):
  482. """Exit carrying a relaunched child's status: that child already produced this run's output,
  483. so callers that report their own boot failures (the Bot Chat delivery runner) must not."""
  484. relaunched = True
  485. from pm.environments import activate_dependencies, install_state_permission_message
  486. from hermes_cli._early_recovery import recover_if_needed
  487. from hermes_cli._parser import command_argv
  488. # Repair needs only stdlib. Do not activate the damaged tree to reach it.
  489. _pm_repair = command_argv(sys.argv[1:])[:2] == ["pm", "repair"]
  490. if not _pm_repair:
  491. from hermes_cli.venv_sync import prepare_launch, relaunch_command
  492. try:
  493. _launch_python = prepare_launch(_root, sys.argv[1:])
  494. if _launch_python is not None:
  495. _main_spec = getattr(sys.modules.get("__main__"), "__spec__", None)
  496. _command = relaunch_command(
  497. _launch_python, _root, sys.argv, sys.orig_argv,
  498. getattr(_main_spec, "name", None),
  499. )
  500. if os.name == "nt":
  501. import subprocess
  502. raise RelaunchExit(subprocess.call(_command))
  503. os.execv(str(_launch_python), _command)
  504. except Exception as exc:
  505. if isinstance(exc, PermissionError) and (message := install_state_permission_message(_root, exc)):
  506. print(f"hermes: {message}", file=sys.stderr)
  507. raise SystemExit(1) from None
  508. # Degrade, never brick the CLI: the previous dependency generation is still selected
  509. # (a failed sync commits nothing), so an offline or half-finished update leaves a
  510. # usable Hermes plus a warning. Activation below is the real gate — a tree whose
  511. # dependencies cannot load still exits with the repair remedy.
  512. print(f"hermes: source-update completion failed: {exc}; "
  513. "running with the previous dependencies — run `hermes update` to finish it",
  514. file=sys.stderr)
  515. try:
  516. recover_if_needed(_root)
  517. activate_dependencies(_root)
  518. except (RuntimeError, OSError) as exc:
  519. if isinstance(exc, PermissionError) and (message := install_state_permission_message(_root, exc)):
  520. print(f"hermes: {message}", file=sys.stderr)
  521. raise SystemExit(1) from None
  522. if command_argv(sys.argv[1:])[:1] != ["pm"]:
  523. print(f"hermes: {exc}; run `hermes pm repair`", file=sys.stderr)
  524. raise SystemExit(1) from None
  525. install_happy_eyeballs_socket_connect()
  526. export_scratch_tmp_env()