update_cmd_zip.py 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653
  1. """ZIP-download fallback for ``hermes update`` (Windows with broken git): two-phase stage/commit swap, dirty-tree guard.
  2. Split out of ``update_cmd.py``; every name is re-imported there so ``hermes_cli.update_cmd.<name>`` keeps
  3. resolving/monkeypatching. Origin helpers are imported lazily per function (no cycle; test patches stay effective).
  4. """
  5. import logging
  6. from contextlib import suppress
  7. import os
  8. import re
  9. import shutil
  10. import subprocess
  11. import sys
  12. from pathlib import Path
  13. from typing import Collection, Optional
  14. from hermes_cli._early_recovery import _keep_aside
  15. from hermes_cli._early_recovery_zip import (
  16. ZIP_SWAP_JOURNAL, restore_interrupted_zip_swap, write_zip_swap_journal, zip_entry_identity, zip_swap_owner_lock)
  17. from hermes_cli.update_cmd_common import _record_stop
  18. # Log-record parity with the origin module.
  19. logger = logging.getLogger("hermes_cli.update_cmd")
  20. _ZIP_STAGING_ARTIFACT_SUFFIXES = ".hermes-update-staging", ".hermes-update-old"
  21. # Hermes' own root breadcrumbs: the swap journal + its owner lock, and the update/refresh markers.
  22. # They are never user work, so the dirty-tree guard must not refuse (and wedge) on them.
  23. _ZIP_HERMES_ROOT_ARTIFACTS = frozenset({
  24. ".hermes-update-zip-swap", ".hermes-update-zip-swap.lock", ".update-incomplete", ".lazy-refresh-incomplete"})
  25. # A journal temp a killed writer left (``write_durable_text``'s unpredictable name). The swap never
  26. # touches it (no ZIP ships it) and nothing deletes it, so admitting it risks no user bytes. A file at
  27. # the old fixed ``.hermes-update-zip-swap.tmp`` name is no longer Hermes': it blocks (review Z5).
  28. _ZIP_JOURNAL_TEMP = re.compile(r"\.hermes-update-zip-swap\.[0-9a-f]{12}\.tmp")
  29. # Single source of truth for entries the ZIP swap preserves — used by the dirty-tree filter and the swap loop.
  30. _ZIP_PRESERVED_TOP_LEVEL = {"venv", ".venv", "node_modules", ".git", ".env"}
  31. # Gitignored build outputs the source ZIP never ships, nested under top-level entries the swap replaces
  32. # (so `_ZIP_PRESERVED_TOP_LEVEL` cannot shield them): the packaged Desktop app, its renderer bundle and
  33. # its own node_modules (electron itself), and the dashboard assets. The dirty-tree guard admits them and
  34. # `_stage_entries` grafts the live copies into the staged tree so the swap keeps them (#90495).
  35. _ZIP_PRESERVED_NESTED = {
  36. "apps": ("desktop/release", "desktop/dist", "desktop/dist-webapp", "desktop/node_modules", "desktop/build"),
  37. "hermes_cli": ("web_dist",),
  38. "scripts": ("whatsapp-bridge/node_modules",),
  39. "ui-tui": ("dist", "node_modules", "packages/hermes-ink/dist"),
  40. "web": ("node_modules",),
  41. }
  42. _STASH_HINT = " Stash or commit your changes, then rerun `hermes update`."
  43. def _remove_path(path: str, *, ignore_errors: bool = False) -> None:
  44. """Remove a dir or file; missing paths are a no-op."""
  45. if os.path.isdir(path):
  46. shutil.rmtree(path, ignore_errors=True)
  47. elif os.path.exists(path):
  48. if ignore_errors:
  49. with suppress(OSError):
  50. os.remove(path)
  51. else:
  52. os.remove(path)
  53. def _atomic_replace_dir(src: str, dst: str) -> None:
  54. """Replace *dst* with *src* without a half-deleted window (naive ``rmtree; copytree`` loses the old
  55. tree when the copy fails partway — likely here, since the ZIP path only runs when file I/O is flaky).
  56. Thin alias over the two-phase helpers; retained for the ``hermes_cli.main`` re-export surface.
  57. The naive ``rmtree(dst); copytree(src, dst)`` has a destructive window: if the copy fails partway
  58. (common on the Windows ZIP-update path, which only runs because file I/O is already flaky on that
  59. machine), the old directory is already gone and nothing replaced it — the install is left with a deleted
  60. tree (issue #49145, where ``ui-tui/`` vanished and broke the TUI).
  61. Now a thin single-entry alias over the two-phase helpers below, which generalise the same
  62. stage-then-swap discipline across every entry the ZIP update touches (#76104).
  63. """
  64. _commit_staged_replacements([(_stage_replacement(src, dst), dst)])
  65. def _stage_replacement(src: str, dst: str, on_created=None) -> str:
  66. """Phase 1: copy *src* (dir or file) to a sibling staging path for *dst*; return it.
  67. Touches nothing live, so a failure here leaves the install untouched. ``on_created(staging)`` runs
  68. once the staging entry exists (a directory: before it is filled), so the journal can record it."""
  69. staging = f"{dst}.hermes-update-staging"
  70. backup = f"{dst}.hermes-update-old"
  71. # A prior run may have died mid-swap leaving the backup as the ONLY copy. Restore it BEFORE
  72. # clearing leftovers, else deleting it then failing to stage (disk exhaustion) leaves a hole.
  73. if not os.path.lexists(dst) and os.path.lexists(backup): # a dangling symlink backup is still one (Z3)
  74. os.rename(backup, dst)
  75. # Nothing this run made is there yet: an entry at either suffix is not provably the update's (a
  76. # user's file created after the clean-tree preflight, or a pre-journal crash's), so it is kept aside,
  77. # never deleted (F78). Neither may stay: a backup would later be taken for this swap's own.
  78. for leftover in (staging, backup):
  79. if os.path.lexists(leftover):
  80. print(f" ⚠ Kept {leftover} aside as {_keep_aside(Path(leftover)).name}: nothing proves it is "
  81. "this update's.")
  82. # Never through the reusable pathname: copy2 opens it following a symlink planted after the sweep
  83. # (review Z2). copytree's own os.mkdir is exclusive and never follows; a file is created the same way.
  84. if os.path.isdir(src):
  85. os.mkdir(staging)
  86. else:
  87. _copy_file_exclusive(src, staging)
  88. made = zip_entry_identity(staging)
  89. try:
  90. if on_created is not None:
  91. on_created(staging)
  92. if zip_entry_identity(staging) != made: # swapped while the journal recorded it: never fill that
  93. raise OSError(f"the staging entry {staging} was replaced while it was being created")
  94. if os.path.isdir(src):
  95. shutil.copytree(src, staging, dirs_exist_ok=True)
  96. except BaseException:
  97. # A failed stage leaves nothing of its own (a full disk must not shrink further on the retry).
  98. # Best effort, like _discard_staged: the journal's recovery drops what this cannot.
  99. with suppress(OSError):
  100. if zip_entry_identity(staging) == made:
  101. _remove_path(staging)
  102. raise
  103. return staging
  104. def _copy_file_exclusive(src: str, dst: str, *, sync: bool = False, on_created=None) -> None:
  105. """``copy2`` that only ever creates ``dst``: O_CREAT|O_EXCL (+O_NOFOLLOW) fails on any entry there
  106. (symlink, hardlink, file) instead of writing through it, and the bytes and mode go through the held
  107. fd. Times are copied only where that can be done without following ``dst``. ``on_created(dst)``
  108. runs once ``dst`` exists, before a byte is written, so a journal can record what this run made."""
  109. flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
  110. st = os.stat(src)
  111. fd = os.open(dst, flags, 0o600)
  112. try:
  113. if on_created is not None:
  114. on_created(dst)
  115. with os.fdopen(fd, "wb") as out, open(src, "rb") as source:
  116. shutil.copyfileobj(source, out, 1 << 20)
  117. out.flush()
  118. if os.chmod in os.supports_fd:
  119. os.chmod(out.fileno(), st.st_mode & 0o7777)
  120. if os.utime in os.supports_fd:
  121. os.utime(out.fileno(), ns=(st.st_atime_ns, st.st_mtime_ns))
  122. if sync:
  123. os.fsync(out.fileno())
  124. except BaseException:
  125. with suppress(OSError): # our own half-written create: never leave it for the swap to install
  126. os.remove(dst)
  127. raise
  128. def _discard_staged(staged) -> None:
  129. """Remove staging paths for never-committed entries; otherwise a phase-1 failure (disk exhaustion)
  130. orphans up to a full second tree and the advised retry fails harder with less free space."""
  131. for staging, _dst in staged:
  132. try:
  133. _remove_path(staging)
  134. except OSError as exc: # best-effort cleanup, never fatal
  135. logger.warning("could not remove staging path %s: %s", staging, exc)
  136. def _hardlink_backup(path: str, backup: str) -> bool:
  137. """Hardlink ``path`` to ``backup``; False where links are unsupported. A link is all-or-nothing, so a
  138. killed swap never leaves a short backup the restore would put back."""
  139. try:
  140. os.link(path, backup)
  141. except OSError:
  142. return False
  143. return True
  144. def _file_backup(path: str, backup: str, tag: str = "", on_temp=None) -> None:
  145. """Back up the regular file ``path`` as a complete ``backup`` while ``path`` stays in place: a hardlink,
  146. or where links are unsupported (FAT32/exFAT/SMB) a synced copy landed whole by ``os.replace``. The
  147. copy's temp carries the journal's random ``tag``, and ``on_temp(temp)`` journals it as it comes into
  148. existence: recovery deletes a temp only on that record (F78-R)."""
  149. if _hardlink_backup(path, backup):
  150. return
  151. tmp = f"{backup}.{tag or os.urandom(6).hex()}.tmp"
  152. try:
  153. _copy_file_exclusive(path, tmp, sync=True, on_created=on_temp) # never through a planted link (Z2)
  154. os.replace(tmp, backup)
  155. except OSError:
  156. with suppress(OSError):
  157. os.remove(tmp)
  158. raise
  159. def _commit_staged_replacements(staged, *, on_committed=None, tag: str = "", on_temp=None) -> None:
  160. """Phase 2: swap every staged entry into place, rolling back all on failure.
  161. Per-entry safety wasn't enough: a partway failure over ~90 entries left a mixed-version tree (every
  162. file valid, combination unbootable). Covers plain files too (repo root holds 20 first-party modules).
  163. Each swap is an ``os.rename`` onto a just-moved-aside path — atomic on POSIX and NTFS, unlike
  164. ``copy2`` onto a live path. Stage-all-then-swap-all shrinks the failure window to N renames and a
  165. failed swap restores every entry already swapped, so the tree lands wholly new or wholly old.
  166. ``_atomic_replace_dir`` makes each *individual* directory swap safe, but the ZIP update replaces ~90
  167. top-level entries in a loop, and nothing made the loop atomic *as a whole*. See #63717, #76091, #76104.
  168. A plain file is never absent, not even for one rename: its backup is a hardlink (or, without
  169. hardlinks, a complete copy) and ``os.replace`` lands the new bytes over it; only directories move
  170. aside. The root modules every launcher imports first
  171. (``hermes_constants``, ``hermes_bootstrap``) therefore always import, and ``hermes_bootstrap`` runs the
  172. journal-driven restore even while a killed swap left a directory (``hermes_cli/`` included) moved aside.
  173. """
  174. swapped: list[tuple[str, str]] = [] # (dst, backup) in swap order; "" = absent
  175. try:
  176. for staging, dst in staged:
  177. backup = f"{dst}.hermes-update-old"
  178. if os.path.lexists(backup): # appeared since staging set leftovers aside: not ours to replace (F78)
  179. raise FileExistsError(f"{backup} appeared during the update; it was left in place")
  180. if os.path.isfile(dst) and not os.path.islink(dst):
  181. _file_backup(dst, backup, tag, on_temp)
  182. swapped.append((dst, backup))
  183. os.replace(staging, dst)
  184. continue
  185. if os.path.lexists(dst):
  186. os.rename(dst, backup)
  187. swapped.append((dst, backup))
  188. else:
  189. swapped.append((dst, ""))
  190. os.rename(staging, dst)
  191. except OSError:
  192. for dst, backup in reversed(swapped): # undo every swap already made so the install stays self-consistent
  193. try:
  194. if backup and os.path.isfile(backup) and not os.path.islink(backup):
  195. os.replace(backup, dst)
  196. continue
  197. _remove_path(dst)
  198. if backup and os.path.lexists(backup):
  199. os.rename(backup, dst)
  200. except OSError as exc:
  201. # Keep restoring the rest; a silent failure here turns a recoverable rollback into a mixed tree.
  202. logger.warning("rollback failed for %s: %s", dst, exc)
  203. raise
  204. if on_committed is not None:
  205. on_committed() # every rename landed: an interrupted cleanup now finishes, never rolls back
  206. for _dst, backup in swapped: # all swaps succeeded — drop the backups (best-effort, never fatal)
  207. if backup:
  208. _remove_path(backup, ignore_errors=True)
  209. def _zip_overlay_block_reason(
  210. root: Path, *, staged: Collection[str] = (), shipped: Optional[Collection[str]] = None,
  211. ) -> Optional[str]:
  212. """Why overlaying a ZIP onto ``root`` would destroy work, or None if safe.
  213. The swap replaces every top-level entry (minus a tiny preserve set) and deletes backups, so uncommitted
  214. edits and untracked files are gone. Fails closed when git status cannot run. ``staged`` is for the
  215. pre-swap re-check: phase 1 leaves ``<entry>.hermes-update-staging`` for those entries, which git
  216. reports as untracked; without the filter the re-check always refuses. ``shipped`` is the extracted
  217. ZIP's top-level entry set once known (the re-check); before the download the tracked root entries stand
  218. in for it. A gitignored path under a root entry the ZIP does not ship is never touched by the swap.
  219. Fail closed when git status cannot run: unknown dirtiness is not a license to clobber the tree (#87304).
  220. """
  221. if not (root / ".git").exists():
  222. return None
  223. from hermes_cli.update_custody import run_git
  224. git_cmd = ["git", "-c", "windows.appendAtomically=false"] if sys.platform == "win32" else ["git"]
  225. result = run_git(
  226. # -uall: a user-level ``status.showUntrackedFiles = no`` must not blind this guard. --ignored=matching:
  227. # gitignored files are still USER DATA the overlay would delete; ``matching`` reports an ignored dir
  228. # as one ``dir/`` line. ``--ignored=all`` is NOT a valid git mode (exits 128, would fail-close every update).
  229. # ``matching`` reports an ignored directory as one ``dir/`` line instead of enumerating its contents
  230. # (cheaper, same verdict for the top-level filter below). See #87392.
  231. git_cmd, ["status", "--porcelain", "--untracked-files=all", "--ignored=matching"],
  232. cwd=root, capture_output=True, text=True, encoding="utf-8", errors="replace",
  233. )
  234. if result.returncode == 0 and shipped is None:
  235. # Before the download the ZIP's entry set is unknown; the tracked root entries stand in for it (the
  236. # pre-swap re-check gets the real set), so an ignored root entry the swap never touches cannot refuse.
  237. tracked = run_git(
  238. git_cmd, ["ls-tree", "--name-only", "HEAD"],
  239. cwd=root, capture_output=True, text=True, encoding="utf-8", errors="replace",
  240. )
  241. shipped = set(tracked.stdout.splitlines()) if tracked.returncode == 0 else None
  242. result.returncode = tracked.returncode
  243. if result.returncode != 0:
  244. detail = (result.stderr or result.stdout or "").strip().splitlines()
  245. return f"could not check the working tree{f' ({detail[0]})' if detail else ''}"
  246. # Preserved entries (venv, node_modules are gitignored on every normal install) are never touched by the
  247. # swap, so they must not cause a false refusal. Everything else — including ignored files — blocks.
  248. dirty = any(
  249. line.strip()
  250. and not _is_zip_preserved_entry_status_line(line, shipped)
  251. and not _is_zip_staging_artifact_status_line(line, staged)
  252. for line in (result.stdout or "").splitlines()
  253. )
  254. return "the working tree has uncommitted changes or untracked files" if dirty else None
  255. def _status_top_level(path: str) -> str:
  256. return path.strip().strip('"').replace("\\", "/").rstrip("/").split("/", 1)[0]
  257. def _is_zip_preserved_entry_status_line(line: str, shipped: Optional[Collection[str]] = None) -> bool:
  258. """True when the swap would not destroy what a porcelain status line names: every path sits under a
  259. preserved top-level entry; or the line is gitignored (``!!``) and under a root entry the ZIP does not
  260. ship (``.bytecode-fingerprint``, ``.hermes-bootstrap-complete``, ``hermes_agent.egg-info/`` — the swap
  261. replaces ``shipped`` entries only); or a ``!!`` build output nested under a shipped dir that the swap
  262. keeps (`_ZIP_PRESERVED_NESTED`) or regenerates (``__pycache__``, ``node_modules``). Every real install
  263. has all of these, and blocking on them made the ZIP fallback refuse every install. Tracked edits,
  264. renames and other untracked/ignored user files still block.
  265. The ``" -> "`` split applies ONLY to R/C codes: porcelain v1 doesn't quote plain names with spaces, so
  266. ``venv -> node_modules`` on a ``!!``/``??`` line is ONE path and splitting would fail-open. Requiring
  267. EVERY path preserved keeps renames out of a preserved dir (``R venv/x -> src/x``) blocking.
  268. """
  269. status, payload = (line[:2], line[3:]) if len(line) >= 3 else ("", line)
  270. paths = payload.split(" -> ") if any(code in "RC" for code in status) else [payload]
  271. if all(_status_top_level(path) in _ZIP_PRESERVED_TOP_LEVEL for path in paths):
  272. return True
  273. if status != "!!":
  274. return False
  275. path = payload.strip().strip('"').replace("\\", "/").rstrip("/")
  276. top, _, nested = path.partition("/")
  277. if shipped is not None and top not in shipped:
  278. return True
  279. return path.rsplit("/", 1)[-1] in ("__pycache__", "node_modules") or any(
  280. nested == keep or nested.startswith(f"{keep}/") for keep in _ZIP_PRESERVED_NESTED.get(top, ()))
  281. def _is_zip_staging_artifact_status_line(line: str, staged: Collection[str] = ()) -> bool:
  282. """True when a porcelain status line is Hermes' own: a root breadcrumb, or the staging copy of an
  283. entry this run staged. Any other ``*.hermes-update-staging``/``-old`` may be a user's file (a manual
  284. ``cp -r tools tools.hermes-update-old``) that staging would delete, so it blocks."""
  285. top = _status_top_level(line[3:] if len(line) >= 3 else line)
  286. return (top in _ZIP_HERMES_ROOT_ARTIFACTS or bool(_ZIP_JOURNAL_TEMP.fullmatch(top))
  287. or top in {item + _ZIP_STAGING_ARTIFACT_SUFFIXES[0] for item in staged})
  288. def _abort_zip_update_if_dirty_tree() -> None:
  289. """Refuse to overlay a ZIP onto a dirty git checkout.
  290. See #87304.
  291. """
  292. from hermes_cli.update_cmd import _m
  293. # Settle an interrupted swap first: only its journal tells its staging/backup siblings apart from a
  294. # user's lookalike file, and once settled none are left to refuse the retry on.
  295. restore_interrupted_zip_swap(_m().PROJECT_ROOT)
  296. reason = _zip_overlay_block_reason(_m().PROJECT_ROOT)
  297. if reason is None:
  298. return
  299. print(f"✗ ZIP fallback refused: {reason}.")
  300. print(" Overlaying the ZIP would overwrite uncommitted edits and permanently delete untracked files.")
  301. print(_STASH_HINT)
  302. print(" To inspect: git status --porcelain")
  303. _record_stop("local_changes_blocked")
  304. _m().sys.exit(1)
  305. def _extract_zip_safely(zip_path: str, tmp_dir: str) -> None:
  306. """Extract, rejecting zip-slip AND symlink members: a source ZIP never legitimately contains
  307. symlinks, and a compromised mirror could use them to plant files anywhere."""
  308. import stat as _stat
  309. import zipfile
  310. with zipfile.ZipFile(zip_path, "r") as zf:
  311. tmp_dir_real = os.path.realpath(tmp_dir)
  312. for member in zf.infolist():
  313. member_path = os.path.realpath(os.path.join(tmp_dir, member.filename))
  314. if not member_path.startswith(tmp_dir_real + os.sep) and member_path != tmp_dir_real:
  315. raise ValueError(f"Zip-slip detected: {member.filename} escapes extraction directory")
  316. # Unix mode lives in the upper 16 bits of external_attr; mask to the file-type bits.
  317. if _stat.S_ISLNK((member.external_attr >> 16) & 0o170000):
  318. raise ValueError(f"ZIP contains unsupported symlink member: {member.filename}")
  319. zf.extractall(tmp_dir)
  320. def _archive_commit(zip_path: str) -> Optional[str]:
  321. """The commit a GitHub archive was made from: ``git archive`` stores it as the ZIP comment."""
  322. import zipfile
  323. with zipfile.ZipFile(zip_path) as zf:
  324. comment = zf.comment.decode("ascii", "replace").strip()
  325. return comment if re.fullmatch(r"[0-9a-f]{40}", comment) else None
  326. def _extracted_root(tmp_dir: str, branch: str) -> str:
  327. """GitHub ZIPs extract to ``hermes-agent-<branch>/``; fall back to the first non-``__MACOSX`` dir."""
  328. extracted = os.path.join(tmp_dir, f"hermes-agent-{branch}")
  329. if not os.path.isdir(extracted):
  330. for d in os.listdir(tmp_dir):
  331. candidate = os.path.join(tmp_dir, d)
  332. if os.path.isdir(candidate) and d != "__MACOSX":
  333. return candidate
  334. return extracted
  335. def _require_staging_space(extracted: str, entries: list[str], project_root: str) -> None:
  336. """Staging costs one extra tree copy; swaps are renames, so require the copy plus 20% headroom — not 2x,
  337. which would block updates on exactly the space-constrained machines that hit this path."""
  338. need = sum(
  339. # Two-phase replace (#76104). Phase 1 copies every entry — directories AND top-level files — to a
  340. # sibling staging path without touching anything live; phase 2 swaps them all in with
  341. # same-filesystem renames and rolls back every swap if any one fails. Replacing entries
  342. # one-at-a-time (the previous shape) meant an interruption partway left `agent/` new and `tools/`
  343. # stale — all files valid, the tree unbootable. Files matter as much as directories here: the repo
  344. # root holds 20 first-party modules (run_agent.py, cli.py, hermes_constants.py, ...). Check up front
  345. # so we fail with a clear message instead of running out mid-copy.
  346. os.path.getsize(os.path.join(dirpath, f))
  347. for entry in entries
  348. for dirpath, _dirs, files in os.walk(os.path.join(extracted, entry))
  349. for f in files
  350. ) + sum(os.path.getsize(os.path.join(extracted, e)) for e in entries if os.path.isfile(os.path.join(extracted, e)))
  351. required = int(need * 1.2)
  352. free = shutil.disk_usage(project_root).free
  353. if free < required:
  354. raise RuntimeError(
  355. f"not enough free disk space to stage the update safely "
  356. f"(need ~{required // (1024 * 1024)} MB, have {free // (1024 * 1024)} MB)"
  357. )
  358. def _link_or_copy_artifact(source: str, destination: str) -> None:
  359. """Hardlink where the filesystem allows (apps/desktop/node_modules is hundreds of MB, and a link stays
  360. valid after the swap unlinks the old tree; on Windows a link also succeeds on a locked Hermes.exe
  361. where copy2 raises); byte copy otherwise."""
  362. try:
  363. os.link(source, destination)
  364. except OSError:
  365. shutil.copy2(source, destination)
  366. def _graft_nested_artifacts(item: str, live: str, staging: str) -> None:
  367. """Clone the live build outputs under *item* into its staged copy so the swap keeps them.
  368. A path the ZIP ships wins over the live copy; a never-built install has nothing to graft."""
  369. for nested in _ZIP_PRESERVED_NESTED.get(item, ()):
  370. source = os.path.join(live, *nested.split("/"))
  371. destination = os.path.join(staging, *nested.split("/"))
  372. if os.path.lexists(destination) or not os.path.isdir(source):
  373. continue
  374. os.makedirs(os.path.dirname(destination), exist_ok=True)
  375. shutil.copytree(source, destination, symlinks=True, copy_function=_link_or_copy_artifact)
  376. def _stage_entries(extracted: str, entries: list[str], project_root: str,
  377. on_created=None) -> list[tuple[str, str]]:
  378. """Phase 1 for every entry; on failure nothing is live yet, so drop partial staging copies so a retry
  379. starts from the same free space. An entry is listed only once its staging copy is this run's: a copy
  380. that fails partway drops its own partial tree (``_stage_replacement``), and a pathname this run never
  381. created (a user's file there) is never ``_discard_staged``'s to delete (F78).
  382. ``on_created(index, staging)``: the journal's hook as each staging entry comes into existence."""
  383. staged: list[tuple[str, str]] = []
  384. try:
  385. for index, item in enumerate(entries):
  386. dst = os.path.join(project_root, item)
  387. staged.append((_stage_replacement(
  388. os.path.join(extracted, item), dst,
  389. None if on_created is None else (lambda path, i=index: on_created(i, path))), dst))
  390. # The source ZIP carries only source; the built outputs (#70337/#87331 release/, then
  391. # dist/, apps/desktop/node_modules and web_dist — #90495) exist only in the LIVE tree. Graft
  392. # them into the staged copy BEFORE the swap so the commit preserves them atomically.
  393. _graft_nested_artifacts(item, dst, staged[-1][0])
  394. except Exception:
  395. _discard_staged(staged)
  396. raise
  397. return staged
  398. def _drop_journal_if_clean(root: Path, entries: list[str], suffixes=(".hermes-update-staging",)) -> None:
  399. """The journal is the only record of the swap's siblings (``<entry><suffix>``): it goes only once
  400. every one of them is gone, else the next launch's recovery could not tell them from a user's file."""
  401. left = [item for item in entries if any(os.path.lexists(os.path.join(root, item + x)) for x in suffixes)]
  402. if left:
  403. print(f" ⚠ Could not remove the update's own copies of {', '.join(left)}; the next `hermes` launch "
  404. "removes them.")
  405. return
  406. (root / ZIP_SWAP_JOURNAL).unlink(missing_ok=True)
  407. def _journaled_stage_and_swap(extracted: str, entries: list[str], root: Path, target_sha) -> list:
  408. """Stage + swap under the ZIP swap journal and its owner lock (``_early_recovery``), so a kill at
  409. any point is finished or rolled back by the next launch and no staging/backup sibling leaks."""
  410. from hermes_cli import update_cmd_commit as _commit
  411. from hermes_cli.update_cmd import _UPDATE_CRITICAL_FILES, _m
  412. # A previous run killed mid-swap: settle it before staging over its leftovers. A journal it could
  413. # not settle is that swap's only record: never overwrite it with this run's.
  414. restore_interrupted_zip_swap(root)
  415. if (root / ZIP_SWAP_JOURNAL).exists():
  416. raise RuntimeError("an interrupted ZIP update could not be settled; see the warning above")
  417. with zip_swap_owner_lock(root, wait=10.0) as owned:
  418. if not owned:
  419. raise RuntimeError("another `hermes update` is swapping this install right now"
  420. if owned.reason == "busy" else f"no ZIP swap lock, no swap ({owned.reason})")
  421. # A leftover backup counts: _stage_replacement puts it back as the entry before the swap.
  422. # Each entry also carries the identities recovery needs before it may delete anything (review
  423. # Z1): its staging copy's, recorded as the copy comes into existence, and the live entry's (the
  424. # one its backup links or renames), recorded at the swapping phase.
  425. journal_entries = [[item, any(os.path.lexists(os.path.join(root, item + suffix))
  426. for suffix in ("", ".hermes-update-old")), "", ""] for item in entries]
  427. gen = os.urandom(6).hex()
  428. write_zip_swap_journal(root, "staging", journal_entries, gen)
  429. def record_staged(index: int, staging: str) -> None:
  430. # A directory's id must be durable before copytree fills it: a kill mid-fill then leaves a
  431. # partial tree recovery can prove is its own and delete. A file is already copied when this
  432. # runs, so its id rides the next directory's write (or the last entry's) instead of one
  433. # fsync'd rewrite per file (~9 ms each on ext4: ~1 s of a 123-entry stage, review K132361).
  434. journal_entries[index][2] = zip_entry_identity(staging)
  435. if index == len(entries) - 1 or os.path.isdir(os.path.join(extracted, entries[index])):
  436. write_zip_swap_journal(root, "staging", journal_entries, gen)
  437. try:
  438. staged = _stage_entries(extracted, entries, str(root), record_staged)
  439. except BaseException:
  440. _drop_journal_if_clean(root, entries) # _stage_entries dropped its copies, if it could
  441. raise
  442. # A failure past here leaves the journal: the caller's restore_interrupted_zip_swap (or the next
  443. # launch) settles it and drops every staging copy, so the retry's free-space check finds no litter.
  444. # Never discard staging first: a staging copy still on disk is what proves its entry was never
  445. # installed, so recovery must not delete whatever (a user's new file) now sits at that path.
  446. # TOCTOU re-check right before the swap: download + extract + staging can take minutes and
  447. # work created meanwhile would be destroyed. Our own staging siblings are filtered out.
  448. recheck_reason = _zip_overlay_block_reason(root, staged=entries, shipped=entries)
  449. if recheck_reason is not None:
  450. _discard_staged(staged)
  451. _drop_journal_if_clean(root, entries)
  452. print(f"✗ ZIP fallback aborted before the swap: {recheck_reason}.")
  453. print(" Files appeared in the checkout while the update was downloading; committing the swap would delete them.")
  454. print(_STASH_HINT)
  455. _record_stop("local_changes_blocked")
  456. _m().sys.exit(1)
  457. # Pre-commit gate: a target whose startup modules do not compile is refused untouched, judged
  458. # under the interpreter the target admits (``startup_syntax_error``, review N15).
  459. if broken := _commit.tree_syntax_error(Path(extracted), _UPDATE_CRITICAL_FILES):
  460. raise SyntaxError(f"{broken[0]}: {broken[1]}")
  461. # The commit point: tail + fleet restart owed before the first live rename.
  462. _commit.arm_commit_obligations(root, target_sha or "")
  463. for entry in journal_entries:
  464. entry[3] = zip_entry_identity(root / entry[0])
  465. write_zip_swap_journal(root, "swapping", journal_entries, gen)
  466. temps: dict[str, str] = {}
  467. def record_temp(tmp: str) -> None: # a backup copy's temp, journaled before its first byte
  468. temps[os.path.basename(tmp)] = zip_entry_identity(tmp, filling=True)
  469. write_zip_swap_journal(root, "swapping", journal_entries, gen, temps)
  470. # Committed: every temp already became its backup, so the record drops them (a backup the
  471. # cleanup then frees must never leave an inode that vouches for a later file at a temp name).
  472. _commit_staged_replacements(
  473. staged, on_committed=lambda: write_zip_swap_journal(root, "committed", journal_entries, gen), tag=gen,
  474. on_temp=record_temp)
  475. # Committed: the new tree is whole. A journal that cannot go now (AV/indexer holding it) says
  476. # "committed", which the next launch's recovery settles by keeping the new tree. It stays, too,
  477. # while a backup (or backup temp) the best-effort cleanup could not remove is still on disk:
  478. # recovery's own terminal check, else that backup is orphaned and wedges the retry (Q1/F79).
  479. with suppress(OSError):
  480. _drop_journal_if_clean(root, entries, (".hermes-update-staging", ".hermes-update-old",
  481. f".hermes-update-old.{gen}.tmp"))
  482. return staged
  483. def _zip_stop_class(exc: BaseException, *, downloaded: bool) -> str:
  484. """Closed stop token for a failed ZIP update: by exception type and errno, never its text."""
  485. import errno
  486. if getattr(exc, "errno", None) == errno.ENOSPC or (
  487. isinstance(exc, RuntimeError) and str(exc).startswith("not enough free disk space")):
  488. return "disk_full" # _require_staging_space's own refusal, or ENOSPC mid-copy
  489. if isinstance(exc, SyntaxError):
  490. return "target_syntax_error" # the pre-commit gate refused the extracted tree; nothing moved
  491. return "zip_failed" if downloaded else "download_failed"
  492. def _download_and_swap_zip(branch: str, zip_url: str, target_sha: str | None = None) -> Optional[str]:
  493. """Download the source ZIP for *branch* and two-phase swap it into the checkout; return the commit it
  494. installed: the archive's own, which must equal ``target_sha`` when one is pinned.
  495. ``sys.exit(1)`` on any failure; the install ends fully updated or fully rolled back.
  496. Two-phase: stage every entry (dirs AND top-level files) beside its target, then swap all in with
  497. same-filesystem renames, rolling back on failure — one-at-a-time replacement left a mixed, unbootable
  498. tree on interruption."""
  499. from hermes_cli.update_cmd import _m
  500. import tempfile
  501. from urllib.request import urlretrieve
  502. print("→ Downloading latest version...")
  503. tmp_dir = tempfile.mkdtemp(prefix="hermes-update-")
  504. downloaded = False
  505. try:
  506. zip_path = os.path.join(tmp_dir, f"hermes-agent-{branch}.zip")
  507. urlretrieve(zip_url, zip_path)
  508. downloaded = True
  509. print("→ Extracting...")
  510. _extract_zip_safely(zip_path, tmp_dir)
  511. # The installed identity comes from the downloaded bytes (``git archive``'s comment), pinned or
  512. # not: without it the restart debt is armed for '' and can never be proven discharged (S4).
  513. archived = _archive_commit(zip_path)
  514. if archived is None or (target_sha and archived != target_sha):
  515. raise ValueError(f"the archive names commit {archived or 'none'}, not "
  516. f"{target_sha or 'a full commit SHA'}; refusing to install unidentified bytes")
  517. target_sha = archived
  518. extracted = _extracted_root(tmp_dir, branch)
  519. entries = [i for i in os.listdir(extracted) if i not in _ZIP_PRESERVED_TOP_LEVEL]
  520. project_root = str(_m().PROJECT_ROOT)
  521. _require_staging_space(extracted, entries, project_root)
  522. staged = _journaled_stage_and_swap(extracted, entries, Path(project_root), target_sha)
  523. print(f"✓ Updated {len(staged)} items from ZIP")
  524. return target_sha
  525. except Exception as e: # health: allow BLE001 -- all-or-nothing boundary: any failure settles the journal, exits 1
  526. # The swap rolled itself back; a rollback that could not finish leaves the journal, which
  527. # this settles now (or the next launch's _early_recovery does) instead of leaking siblings.
  528. with suppress(Exception):
  529. restore_interrupted_zip_swap(_m().PROJECT_ROOT)
  530. if not (Path(_m().PROJECT_ROOT) / ZIP_SWAP_JOURNAL).exists():
  531. from hermes_cli import update_cmd_commit as _commit
  532. _commit.disarm_commit_obligations() # the old tree is whole again: nothing is owed
  533. print(f"✗ ZIP update failed: {e}")
  534. # Two-phase replace commits all or rolls all back, so no mixed tree here — don't push a needless reinstall.
  535. print(" Your existing install was left in place.")
  536. print(" Re-run `hermes update` to retry; if the agent won't start, reinstall from https://hermes-agent.nousresearch.com")
  537. _record_stop(_zip_stop_class(e, downloaded=downloaded))
  538. _m().sys.exit(1)
  539. finally:
  540. shutil.rmtree(tmp_dir, ignore_errors=True)
  541. def _update_via_zip(args, *, had_desktop_app_before_update: bool = False,
  542. target_sha: str | None = None, target_repository: str | None = None,
  543. completion_request=None) -> bool:
  544. """Update via ZIP when Windows git file I/O fails; dependency/build failures propagate.
  545. A supplied commit keeps the archive on the target selected before Git failed.
  546. """
  547. from hermes_cli.update_cmd import _m, _complete_source_update
  548. # The static archive would silently ignore --branch — the exact silent-divergence bug it exists to
  549. # prevent. Refuse rather than lie.
  550. branch = _m()._resolve_update_branch(args)
  551. if branch != "main":
  552. print(f"✗ --branch={branch} is not supported on the Windows ZIP-fallback update path.")
  553. print(
  554. " This path runs when git file I/O is broken on the system. "
  555. "Either resolve the git-side breakage (typically an antivirus "
  556. "or NTFS filter holding files open) and rerun `hermes update "
  557. f"--branch {branch}`, or update against main with `hermes update`."
  558. )
  559. _record_stop("branch_unsupported")
  560. _m().sys.exit(1)
  561. _abort_zip_update_if_dirty_tree()
  562. # Older callers lack the snapshot/receipt/lifecycle handoff. Refuse before swap.
  563. if completion_request is None:
  564. from hermes_cli._old_updater import stop_for_relaunch
  565. stop_for_relaunch(incomplete=True)
  566. if target_sha is not None and not re.fullmatch(r"[0-9a-f]{40}", target_sha):
  567. raise ValueError("ZIP update requires an exact full commit SHA")
  568. ref = target_sha if target_sha is not None else f"refs/heads/{branch}"
  569. repository = target_repository or "NousResearch/hermes-agent"
  570. if (not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository)
  571. or any(part in (".", "..") for part in repository.split("/"))):
  572. raise ValueError("ZIP update requires a GitHub owner/repository")
  573. installed = _download_and_swap_zip(branch, f"https://github.com/{repository}/archive/{ref}.zip", target_sha)
  574. completion_request["expected_sha"] = installed or target_sha
  575. completion_request["apply_mode"] = "zip"
  576. _complete_source_update(completion_request)
  577. return True