update_cmd_commit.py 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619
  1. """The single commit point of a source ``hermes update``: everything the tree move needs armed first.
  2. Before git (or the ZIP swap) writes the first file of the new code, three things are durable:
  3. * the interrupted-pull marker (``.git/hermes-update-pull``) naming the commit git moves to, for EVERY
  4. tree move (branch switch, upstream fork pull, the pull itself) so a launch after any exit that left
  5. a torn tree puts the old one back (``_early_recovery.restore_interrupted_pull``);
  6. * the source-completion tail (``venv_sync.arm_completion``) and the host fleet-restart obligation,
  7. so a kill after the move but before the completion child starts still leaves the tail owed to the
  8. next launch (``venv_sync.prepare_launch``) and the restart owed to the next ``hermes update``.
  9. Failures before the move are no-ops: ``disarm_commit_obligations`` puts both obligations back the way
  10. this run found them once the tree is verified at its pre-update commit again.
  11. """
  12. from __future__ import annotations
  13. import logging
  14. import os
  15. import subprocess
  16. import sys
  17. from contextlib import suppress
  18. from pathlib import Path
  19. from typing import Optional
  20. from hermes_cli._early_recovery import (
  21. RECOVERY_CLOSURE,
  22. RECOVERY_CLOSURE_INIT,
  23. RECOVERY_CLOSURE_MANIFEST,
  24. blob_id,
  25. _lock_identity,
  26. interrupted_pull_marker,
  27. is_object_id,
  28. recovery_closure_dir,
  29. recovery_closure_verified,
  30. restore_interrupted_pull,
  31. write_durable_text,
  32. )
  33. from hermes_cli.update_cmd_common import _record_stop
  34. from hermes_cli.update_custody import run_git
  35. logger = logging.getLogger("hermes_cli.update_cmd")
  36. # What this run found before it armed anything: {path: bytes or None}. None = nothing armed yet.
  37. _armed_snapshot: Optional[dict[Path, Optional[bytes]]] = None
  38. # What this run's latest arm left at each path: disarm hands back only records still exactly these.
  39. _armed_bytes: dict[Path, Optional[bytes]] = {}
  40. # (git_cmd, (HEAD, branch)) when this run reached its checkout phase, and the checkout it names.
  41. _run_start: Optional[tuple[list, tuple[str, str]]] = None
  42. _obligation_root: Optional[Path] = None
  43. # This run's stake in the shared host record (``owners``): disarm removes only this one.
  44. _owner: str = ""
  45. def _owns_live_checkout(root: Path) -> bool:
  46. from hermes_cli.update_cmd import _m
  47. return _m()._pytest_owns_live_checkout(root)
  48. def _obligation_paths(root: Path) -> list[Path]:
  49. from hermes_cli.update_cmd_fleet import _fleet_restart_pending_marker_path
  50. from hermes_cli.update_host_obligation import host_obligation_path
  51. from hermes_cli.venv_sync import completion_pending_path
  52. return [completion_pending_path(root), _fleet_restart_pending_marker_path(), host_obligation_path()]
  53. def _read_or_none(path: Path) -> Optional[bytes]:
  54. """The record's bytes, None when absent. Any other read error raises: custody is never guessed."""
  55. try:
  56. return path.read_bytes()
  57. except FileNotFoundError:
  58. return None
  59. def arm_commit_obligations(root: Path, expected_sha: str) -> None:
  60. """Owe the completion tail and the fleet restart for ``expected_sha`` BEFORE the tree moves.
  61. Idempotent within a run (the first call snapshots what to restore on a no-op failure). An
  62. unwritable install state, an unreadable record or a fleet restart neither store accepted
  63. raises: nothing has moved yet, and moving without the obligation is exactly the
  64. tail-never-runs state this exists to prevent.
  65. """
  66. global _armed_snapshot, _owner
  67. import uuid
  68. from hermes_cli.update_cmd_fleet import _write_fleet_restart_pending_marker
  69. from hermes_cli.venv_sync import arm_completion
  70. root = Path(root)
  71. if _owns_live_checkout(root):
  72. return
  73. if _armed_snapshot is None:
  74. _armed_snapshot = {path: _read_or_none(path) for path in _obligation_paths(root)}
  75. _owner = f"{root}|{os.getpid()}|{uuid.uuid4().hex}"
  76. try:
  77. arm_completion(root)
  78. owed = _write_fleet_restart_pending_marker(expected_sha=expected_sha or "", owner=_owner)
  79. finally: # even a half-done arm: disarm must still recognise what this run wrote
  80. _armed_bytes.update({path: _read_or_none(path) for path in _armed_snapshot})
  81. if not owed:
  82. raise OSError("could not record the pending gateway-restart obligation")
  83. def disarm_commit_obligations() -> None:
  84. """Restore both obligations to what this run found: the tree never left its pre-update commit.
  85. Off the commit this run STARTED from nothing is handed back: a failed later move (CP1 refused
  86. or failed after the CP0 branch switch, the upstream fork ff after the origin pull) settles on a
  87. commit that is already new code, so the obligations are owed for THAT head instead of the
  88. failed move's target, which the checkout does not contain and no restart could discharge.
  89. """
  90. global _armed_snapshot
  91. if _run_start is not None:
  92. git_cmd, (start_head, _branch) = _run_start
  93. root = Path(_obligation_root) if _obligation_root is not None else None
  94. head = head_and_branch(git_cmd, root)[0] if root is not None else ""
  95. if root is None or not start_head or head != start_head:
  96. if root is not None:
  97. _owe_for(root, head)
  98. return
  99. from hermes_cli.update_host_obligation import host_obligation_path, release_host_obligation, replace_bytes
  100. snapshot, _armed_snapshot = _armed_snapshot, None
  101. armed = dict(_armed_bytes)
  102. _armed_bytes.clear()
  103. host = host_obligation_path()
  104. for path, data in (snapshot or {}).items():
  105. try:
  106. if path == host:
  107. # Shared by every install of the OS user: same-SHA arms join one record, so bytes
  108. # cannot tell whose it is; the ``owners`` stake can (review C2).
  109. release_host_obligation(_owner)
  110. continue
  111. if path not in armed or _read_or_none(path) != armed[path]:
  112. continue # rewritten since this run armed it (another install's update): theirs now
  113. if data is None:
  114. path.unlink(missing_ok=True)
  115. else:
  116. # An unpredictable exclusive temp, never a fixed name: nothing at any guessable
  117. # sibling is written through or deleted first (reviews N05, O1).
  118. replace_bytes(path, data)
  119. except OSError:
  120. pass # an owed tail/restart left armed is a retry, never a lost obligation
  121. def owe_restore_of(root: Path, pre: str | None) -> None:
  122. """A failed move left a torn tree under its marker: the next launch's restore puts ``pre`` back,
  123. so the obligations name ``pre``, never the target the checkout will not hold."""
  124. _owe_for(Path(root), pre or "")
  125. def _owe_for(root: Path, sha: str) -> None:
  126. """Re-arm what this run armed for ``sha``, the commit the checkout is (or is restored) on."""
  127. if _armed_snapshot is None or not is_object_id(sha):
  128. return # nothing armed by this run, or nothing names the code: keep what stands
  129. try:
  130. arm_commit_obligations(root, sha)
  131. except OSError as exc:
  132. logger.warning("Could not re-arm the update obligations for %s: %s", sha[:10], exc)
  133. print(f" ⚠ Could not record the restart this update still owes for {sha[:10]} ({exc}); "
  134. "run `hermes gateway restart` once the update is done.", file=sys.stderr)
  135. def debt_sha_for_move(pre: str, target: str) -> str:
  136. """The commit a fast-forward ``pre`` -> ``target`` arms the obligations for.
  137. A later move of this run (the upstream sync after the origin pull) owes ``pre``: the commit the
  138. earlier move already owes, which every landing of a fast-forward contains, and the fleet
  139. discharge holds the gateways to the checkout's actual HEAD whenever it contains the debt. Its
  140. failure then needs no retarget write, which could itself fail and leave the debt naming a commit
  141. the checkout never reached (review O4). The run's first move owes its ``target``: its failure
  142. hands the obligations back whole (``disarm_commit_obligations``).
  143. """
  144. start = _run_start[1][0] if _run_start is not None else ""
  145. return pre if start and pre != start else target
  146. def arm_commit_point(git_cmd, root: Path, expected_sha: str, **move) -> str | None:
  147. """Arm the obligations, then the tree-move marker (``arm_tree_move(**move)``): no marker, no move.
  148. ``None`` when both are durable; otherwise why not, with the obligations handed back
  149. (``disarm_commit_obligations``), and the caller must stop before git writes a file.
  150. Linux/macOS gateways are paused first: this is every route's first checkout move.
  151. """
  152. from hermes_cli.update_cmd_posix_pause import pause_at_commit_point
  153. if refused := pause_at_commit_point():
  154. return refused
  155. try:
  156. arm_commit_obligations(root, expected_sha)
  157. arm_tree_move(git_cmd, root, **move)
  158. except OSError as exc:
  159. disarm_commit_obligations()
  160. head = head_and_branch(git_cmd, root)[0] if _run_start is not None else ""
  161. if head and head != _run_start[1][0]:
  162. # A later move (CP1 after the CP0 switch): THIS step moved nothing, an earlier one did.
  163. return (f"could not arm the update ({exc}); this step changed nothing, but an earlier step "
  164. f"of this update already moved the checkout to {head[:10]}")
  165. return f"could not arm the update ({exc}); the checkout was not changed"
  166. return None
  167. def arm_tree_move(git_cmd, root: Path, *, pre: str | None, target: str, stash: str | None,
  168. rollback: str | None = None) -> Path:
  169. """Write the interrupted-pull marker for one git tree move (pre -> target).
  170. ``rollback`` (``branch``/``detach``): a syntax rollback that moves HEAD and the index back to
  171. ``pre`` before any file; a kill before that step finds HEAD still on ``target`` and the restore
  172. redoes it first, only while HEAD still names the ``ref`` recorded here (empty: detached).
  173. """
  174. marker = interrupted_pull_marker(root)
  175. ref = ""
  176. if rollback:
  177. named = run_git(git_cmd, ["symbolic-ref", "-q", "HEAD"], cwd=str(root), capture_output=True, text=True,
  178. encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL, timeout=60)
  179. ref = named.stdout.strip() if named.returncode == 0 else ""
  180. if pre:
  181. with suppress(OSError, subprocess.SubprocessError): # no closure: the in-tree repair still runs
  182. publish_recovery_closure(git_cmd, root, pre)
  183. # The restore's only record, durable before git writes: temp + fsync + rename, never in place.
  184. # ``index_lock``: the lock generation already there before this move's git ran (empty: none). Only
  185. # THAT one is another git's for sure; a lock that appears later can be our own killed git's.
  186. write_durable_text(marker, f"pid={os.getpid()}\npre={pre or ''}\ntarget={target}\nstash={stash or ''}\n"
  187. + f"index_lock={_lock_identity(marker.parent / 'index.lock')}\n"
  188. + (f"rollback={rollback}\nref={ref}\n" if rollback else "")
  189. + (f"git={git}\n" if (git := _absolute_git(git_cmd)) else ""))
  190. return marker
  191. def publish_recovery_closure(git_cmd, root: Path, pre: str) -> Path:
  192. """Copy the launch repair's modules, as committed at ``pre``, beside the marker (outside the tree).
  193. The bytes come from the commit the repair restores, never from the working tree: a rollback move
  194. starts from a broken tree, and a second move in one run starts from code this process never ran.
  195. A manifest names each file's blob id; the launcher runs the closure only when every file hashes
  196. to it (``recovery_closure_verified``) and rebuilds it from git's objects otherwise. Files and
  197. directory are fsynced before the atomic rename, so a power loss during the move that follows
  198. finds the whole closure or none. An older run's closure (another ``pre``) is dropped.
  199. """
  200. import shutil
  201. if not is_object_id(pre):
  202. raise OSError(f"not a commit id: {pre!r}")
  203. dest = recovery_closure_dir(Path(root), pre)
  204. if recovery_closure_verified(dest, pre):
  205. return dest
  206. git_cmd = [*([git_cmd] if isinstance(git_cmd, str) else git_cmd), "--no-replace-objects"]
  207. listed = run_git(git_cmd, ["ls-tree", "-z", "--full-tree", pre, "--", *RECOVERY_CLOSURE], cwd=str(root),
  208. capture_output=True, stdin=subprocess.DEVNULL, timeout=120)
  209. ids = {}
  210. for entry in (listed.stdout or b"").split(b"\0") if listed.returncode == 0 else ():
  211. meta, _, rel = entry.decode("utf-8", "replace").partition("\t")
  212. if meta.split()[1:2] == ["blob"]:
  213. ids[rel] = meta.split()[2]
  214. blobs = {RECOVERY_CLOSURE_INIT: b""}
  215. shown = read_target_files(git_cmd, root, pre, RECOVERY_CLOSURE) # one spawn, not a cat-file per file
  216. for rel in RECOVERY_CLOSURE:
  217. if rel not in ids or shown[rel] is None or blob_id(shown[rel], pre) != ids[rel]:
  218. raise OSError(f"{rel} is not in {pre[:10]}")
  219. blobs[rel] = shown[rel]
  220. manifest = "".join(f"{blob_id(data, pre)} {rel}\n" for rel, data in blobs.items()).encode("utf-8")
  221. staging = dest.with_name(f".{pre}.{os.getpid()}.staging")
  222. shutil.rmtree(staging, ignore_errors=True)
  223. try:
  224. for rel, data in {**blobs, RECOVERY_CLOSURE_MANIFEST: manifest}.items():
  225. (staging / rel).parent.mkdir(parents=True, exist_ok=True)
  226. with open(staging / rel, "wb") as handle:
  227. handle.write(data)
  228. handle.flush()
  229. os.fsync(handle.fileno())
  230. for directory in (staging / "hermes_cli", staging):
  231. _fsync_dir(directory)
  232. shutil.rmtree(dest, ignore_errors=True)
  233. os.replace(staging, dest)
  234. _fsync_dir(dest.parent)
  235. finally:
  236. shutil.rmtree(staging, ignore_errors=True)
  237. for stale in dest.parent.iterdir():
  238. if stale != dest:
  239. shutil.rmtree(stale, ignore_errors=True)
  240. return dest
  241. def _fsync_dir(directory: Path) -> None:
  242. """POSIX: make a directory's entries durable. Windows opens no directory handle; NTFS journals
  243. the rename itself."""
  244. if os.name == "nt":
  245. return
  246. fd = os.open(directory, os.O_RDONLY)
  247. try:
  248. os.fsync(fd)
  249. finally:
  250. os.close(fd)
  251. def _absolute_git(git_cmd) -> str:
  252. """The git this run moves the tree with, as an absolute path for the next launch's repair.
  253. A Windows install's git is often PM's store copy, on PATH only inside the updater
  254. (``expose_pm_git``); the repair cannot look it up through ``pm`` when the killed move tore a
  255. module ``pm`` imports (``hermes_constants``)."""
  256. import shutil
  257. head = (list(git_cmd) or ["git"])[0] if not isinstance(git_cmd, str) else git_cmd
  258. found = shutil.which(head)
  259. return os.path.abspath(found) if found else ""
  260. def files_added_by(git_cmd, root: Path, pre: str, target: str | None) -> list[str]:
  261. """Paths ``target`` adds over ``pre``. A rollback's mixed reset un-tracks them and ``reset --hard``
  262. never touches untracked files, so ``drop_added_files`` removes them by name afterwards."""
  263. if not target or target == pre:
  264. return []
  265. cp = run_git(git_cmd, ["diff", "--name-only", "-z", "--no-renames", "--diff-filter=A", pre, target],
  266. cwd=str(root), capture_output=True, text=True, encoding="utf-8", errors="replace",
  267. stdin=subprocess.DEVNULL, timeout=120)
  268. return [p for p in cp.stdout.split("\0") if p] if cp.returncode == 0 else []
  269. def drop_added_files(root: Path, added: list[str]) -> bool:
  270. """Every one is the move's own file: git refuses to move a checkout over an untracked file.
  271. False when one of them is still there (the caller keeps the marker; the restore retries)."""
  272. root = Path(root)
  273. gone = True
  274. for rel in added:
  275. try:
  276. (root / rel).unlink(missing_ok=True)
  277. except OSError:
  278. gone = False
  279. for parent in sorted({p for rel in added for p in Path(rel).parents if str(p) != "."},
  280. key=lambda p: len(p.parts), reverse=True):
  281. try:
  282. (root / parent).rmdir() # only when empty: anything else inside keeps it
  283. except OSError:
  284. pass
  285. return gone and not any(os.path.lexists(root / rel) for rel in added)
  286. def tree_whole_at(git_cmd, root: Path, sha: str) -> bool:
  287. """HEAD is ``sha``, no ``index.lock`` is left and no tracked file differs from it."""
  288. def run(*args: str) -> subprocess.CompletedProcess:
  289. return run_git(git_cmd, [*args], cwd=str(root), capture_output=True, text=True, encoding="utf-8",
  290. errors="replace", stdin=subprocess.DEVNULL, timeout=120)
  291. head = run("rev-parse", "-q", "--verify", "HEAD")
  292. if head.returncode != 0 or head.stdout.strip() != sha or (interrupted_pull_marker(Path(root)).parent / "index.lock").exists():
  293. return False
  294. status = run("status", "--porcelain", "-z", "--untracked-files=no")
  295. return status.returncode == 0 and not status.stdout.strip("\0")
  296. def settle_failed_tree_move(root: Path) -> bool:
  297. """Git exited without finishing a tree move: put back what it wrote, keep the marker if we can't.
  298. True when the tree is verified whole again (at the pre-move commit, or at the target when git got
  299. there anyway); False leaves the marker for the next launch's ``restore_interrupted_pull``.
  300. """
  301. marker = interrupted_pull_marker(Path(root))
  302. if not marker.is_file():
  303. return False # no marker names the move: its absence proves nothing about the tree
  304. restore_interrupted_pull(Path(root), after_failure=True)
  305. return not marker.is_file()
  306. def _requires_python_spec(pyproject: bytes | str | None) -> str | None:
  307. """The target's ``requires-python`` specifier, None when absent or unreadable."""
  308. if not pyproject:
  309. return None
  310. import tomllib
  311. try:
  312. text = pyproject.decode("utf-8") if isinstance(pyproject, bytes) else pyproject
  313. spec = tomllib.loads(text)["project"]["requires-python"]
  314. except (KeyError, TypeError, ValueError): # TOMLDecodeError is a ValueError
  315. return None
  316. return spec if isinstance(spec, str) else None
  317. def _spec_admits(spec: str, version: str) -> bool:
  318. import re
  319. try:
  320. from packaging.specifiers import InvalidSpecifier, SpecifierSet
  321. except ImportError: # the lower bound is the part a Python bump moves
  322. floor = re.search(r">=\s*(\d+)\.(\d+)", spec)
  323. found = re.match(r"(\d+)\.(\d+)", version)
  324. return not floor or bool(found) and (int(found[1]), int(found[2])) >= (int(floor[1]), int(floor[2]))
  325. try:
  326. return SpecifierSet(spec).contains(version, prereleases=True)
  327. except InvalidSpecifier:
  328. return True # unknown: keep judging with this interpreter, never wave a file through
  329. def requires_other_python(pyproject: bytes | str | None) -> bool:
  330. """True when a target's ``requires-python`` excludes the running interpreter.
  331. Its startup modules may then use a newer Python's syntax that this interpreter's ``compile()``
  332. cannot judge: ``startup_syntax_error`` asks an installed interpreter the target admits instead.
  333. Unknown -> False: keep checking, so a real syntax error is never waved through on a guess.
  334. """
  335. import platform
  336. spec = _requires_python_spec(pyproject)
  337. return spec is not None and not _spec_admits(spec, platform.python_version())
  338. _PYTHON_VERSION = "import platform; print(platform.python_version())"
  339. # Run by the target's interpreter: compile every startup file sent on stdin, print the first error.
  340. _COMPILE_ALL = (
  341. "import base64, json, sys\n"
  342. "verdict = None\n"
  343. "for rel, data in json.load(sys.stdin).items():\n"
  344. " try:\n"
  345. " compile(base64.b64decode(data), rel, 'exec', dont_inherit=True)\n"
  346. " except (SyntaxError, ValueError) as exc:\n"
  347. " verdict = [rel, f'{type(exc).__name__}: {exc}']\n"
  348. " break\n"
  349. "print(json.dumps(verdict))\n")
  350. def _run_python(argv: list[str], *, stdin: str = "", timeout: float = 60) -> str | None:
  351. """Stdout of a read-only interpreter child (it never writes the checkout), None when it failed."""
  352. from hermes_cli._subprocess_compat import windows_hide_flags
  353. try:
  354. done = subprocess.run(argv, input=stdin, capture_output=True, text=True, encoding="utf-8",
  355. errors="replace", timeout=timeout, creationflags=windows_hide_flags(), check=False)
  356. except (OSError, subprocess.SubprocessError):
  357. return None
  358. return done.stdout if done.returncode == 0 else None
  359. def _admitted_python(spec: str) -> str | None:
  360. """An installed ``python3.N`` the target's ``requires-python`` admits (newest first), or None
  361. when this machine has none. No uv tier: Hermes never resolves the user's uv
  362. (tests/test_managed_runtime_resolution.py), and a missing interpreter only means this one judges."""
  363. from hermes_platform.resolver import locate_command
  364. candidates = [res.command[0] for minor in range(40, sys.version_info[1], -1)
  365. if (res := locate_command(f"python3.{minor}")).command][:3]
  366. for python in candidates:
  367. version = (_run_python([python, "-I", "-c", _PYTHON_VERSION], timeout=30) or "").strip()
  368. if version and _spec_admits(spec, version):
  369. return python
  370. return None
  371. def _compile_here(sources: dict[str, bytes]) -> tuple[str, str] | None:
  372. for rel, data in sources.items():
  373. try:
  374. compile(data, rel, "exec", dont_inherit=True)
  375. except (SyntaxError, ValueError) as exc:
  376. return rel, f"{type(exc).__name__}: {exc}"
  377. return None
  378. def startup_syntax_error(sources: dict[str, bytes | None], pyproject: bytes | None) -> tuple[str, str] | None:
  379. """``(path, error)`` for the first startup file that does not compile, else None.
  380. Judged by the interpreter that will run the target: this one when the target's
  381. ``requires-python`` admits it, else an installed interpreter it admits (review N15: a
  382. conflict-marker scan is not a syntax check). With none installed, this interpreter still
  383. judges: code it parses is code a newer Python parses, and a refusal names the Python to install
  384. so the release can be judged by its own interpreter. ``None`` values (absent files) are skipped.
  385. """
  386. import base64
  387. import json
  388. import platform
  389. present = {rel: data for rel, data in sources.items() if data is not None}
  390. spec = _requires_python_spec(pyproject)
  391. if spec is None or _spec_admits(spec, platform.python_version()):
  392. return _compile_here(present)
  393. if python := _admitted_python(spec):
  394. payload = json.dumps({rel: base64.b64encode(data).decode("ascii") for rel, data in present.items()})
  395. out = _run_python([python, "-I", "-c", _COMPILE_ALL], stdin=payload, timeout=120)
  396. try:
  397. verdict = json.loads((out or "").strip().splitlines()[-1])
  398. except (IndexError, ValueError):
  399. verdict = False # the target's interpreter gave no verdict: judge here (below)
  400. if verdict is None:
  401. return None
  402. if isinstance(verdict, list) and len(verdict) == 2:
  403. return str(verdict[0]), f"{verdict[1]} (judged by {python})"
  404. broken = _compile_here(present)
  405. if broken is None:
  406. return None
  407. return broken[0], (f"{broken[1]}\nJudged by Python {platform.python_version()}: the target requires Python "
  408. f"{spec} and no installed interpreter satisfies it. Install one (`uv python install "
  409. f"'{spec}'`) and re-run `hermes update` so the release is judged by its own Python.")
  410. def read_target_files(git_cmd, root: Path, target_ref: str, relpaths) -> dict[str, bytes | None]:
  411. """``{rel: bytes}`` of each path as committed at ``target_ref`` (None: absent there or unreadable),
  412. in ONE ``git cat-file --batch`` instead of one ``git show`` per file."""
  413. names = list(dict.fromkeys(relpaths))
  414. found: dict[str, bytes | None] = dict.fromkeys(names)
  415. request = "".join(f"{target_ref}:{rel}\n" for rel in names).encode("utf-8")
  416. cp = run_git(git_cmd, ["cat-file", "--batch"], cwd=str(root), input=request, capture_output=True, timeout=120)
  417. out, pos = (cp.stdout or b"") if cp.returncode == 0 else b"", 0
  418. for rel in names:
  419. end = out.find(b"\n", pos)
  420. if end < 0:
  421. break
  422. header, pos = out[pos:end].split(), end + 1
  423. if len(header) == 3 and header[2].isdigit(): # "<oid> <type> <size>", then the bytes and "\n"
  424. size = int(header[2])
  425. if header[1] == b"blob":
  426. found[rel] = out[pos:pos + size]
  427. pos += size + 1
  428. return found
  429. def target_syntax_error(git_cmd, root: Path, target_ref: str, relpaths) -> tuple[str, str] | None:
  430. """``(path, error)`` for the first startup-critical file that does not compile at ``target_ref``.
  431. Read from the object store, never written to the tree: this runs BEFORE HEAD moves, so a broken
  432. release is refused with the install untouched (the post-pull rollback stays as the backstop).
  433. ``startup_syntax_error`` judges it under the interpreter the target admits. A file absent at the
  434. target (or unreadable) is skipped: the post-pull guard has the last word.
  435. """
  436. try:
  437. files = read_target_files(git_cmd, root, target_ref, ["pyproject.toml", *relpaths])
  438. except subprocess.TimeoutExpired:
  439. # A blobless install (install.sh clones --filter=blob:none) lazily fetches each changed blob
  440. # in its own round trip; on a slow link that outlasts the limit. Unread, like an absent file.
  441. print(" ⚠ Syntax preflight skipped (slow object fetch); the post-update check still runs.")
  442. return None
  443. pyproject = files.pop("pyproject.toml", None)
  444. return startup_syntax_error(files, pyproject)
  445. def tree_syntax_error(root: Path, relpaths) -> tuple[str, str] | None:
  446. """``startup_syntax_error`` for the files in the worktree at ``root`` (the post-move backstop)."""
  447. root = Path(root)
  448. sources: dict[str, bytes | None] = {}
  449. for rel in relpaths:
  450. try:
  451. sources[rel] = (root / rel).read_bytes() if (root / rel).is_file() else None
  452. except OSError as exc:
  453. return str(rel), f"could not read: {exc}"
  454. pyproject = root / "pyproject.toml"
  455. return startup_syntax_error(sources, pyproject.read_bytes() if pyproject.is_file() else None)
  456. def head_and_branch(git_cmd, root: Path) -> tuple[str, str]:
  457. def out(*args: str) -> str:
  458. cp = run_git(git_cmd, [*args], cwd=str(root), capture_output=True, text=True, encoding="utf-8", errors="replace",
  459. stdin=subprocess.DEVNULL, timeout=60)
  460. return cp.stdout.strip() if cp.returncode == 0 else ""
  461. return out("rev-parse", "HEAD"), out("rev-parse", "--abbrev-ref", "HEAD")
  462. def checkout_untouched(git_cmd, root: Path, start: tuple[str, str] | None) -> bool:
  463. """True when the checkout is exactly where this run found it: same HEAD, same branch, no
  464. autostash taken, no tree move armed. Only then may a failed git update fall back to ZIP."""
  465. from hermes_cli.update_cmd_stash import _unrestored_autostash_notice
  466. if start is None or not start[0]:
  467. return False
  468. if _unrestored_autostash_notice() is not None or interrupted_pull_marker(root).is_file():
  469. return False
  470. return head_and_branch(git_cmd, root) == start
  471. def begin_update_attempt() -> None:
  472. """A new ``hermes update`` attempt owns nothing yet: no snapshot, no stake, no run start.
  473. The state above is per attempt, not per process: a second update in one interpreter (a
  474. long-lived caller) that inherited the first one's snapshot and owner would hand back the
  475. first update's committed debt as its own undo when its move is refused (review O5).
  476. """
  477. global _armed_snapshot, _run_start, _obligation_root, _owner
  478. _owner = ""
  479. _armed_snapshot = None
  480. _armed_bytes.clear()
  481. _run_start = None
  482. _obligation_root = None
  483. def record_run_start(git_cmd, root: Path) -> None:
  484. global _run_start, _obligation_root
  485. _run_start = (list(git_cmd), head_and_branch(git_cmd, root))
  486. _obligation_root = Path(root)
  487. def run_checkout_untouched(root: Path) -> bool:
  488. """``checkout_untouched`` for this run; True before the checkout phase (nothing can have moved)."""
  489. if _run_start is None:
  490. return True
  491. return checkout_untouched(_run_start[0], Path(root), _run_start[1])
  492. def preflight_refusal(git_cmd, root: Path, target_ref: str, critical_files) -> str | None:
  493. """Why this update must not start, checked BEFORE the first tree move; ``None`` to proceed.
  494. * a venv owned by another OS user (the completion child used to refuse only after the swap);
  495. * a target whose startup-critical modules do not compile (rollback used to be the only guard).
  496. """
  497. root = Path(root)
  498. if not _owns_live_checkout(root):
  499. try:
  500. from hermes_cli.venv_sync import refuse_foreign_owned_venv
  501. refuse_foreign_owned_venv(root)
  502. except ImportError:
  503. pass
  504. except Exception as exc: # health: allow BLE001 -- fail closed: any probe error refuses before the first move
  505. _record_stop("venv_foreign_owner")
  506. return f"✗ {exc}" # pm's refusal carries its own remediation text
  507. broken = target_syntax_error(git_cmd, root, target_ref, critical_files)
  508. if broken is not None:
  509. path, error = broken
  510. _record_stop("target_syntax_error")
  511. return (f"✗ The update target has a syntax error in a critical file:\n {path}\n "
  512. + "\n ".join(error.splitlines()[:6]))
  513. return None