update_cmd_stash.py 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735
  1. """Autostash handling for ``hermes update``: stash before the pull, restore/park/discard afterwards, warn about orphans.
  2. Split out of ``update_cmd.py``; names are re-imported there so ``hermes_cli.update_cmd.<name>`` still resolves/monkeypatches.
  3. Origin helpers are imported lazily per function (no cycle; test patches on the origin stay effective).
  4. """
  5. import logging
  6. import re
  7. from dataclasses import dataclass
  8. import subprocess
  9. from datetime import datetime, timedelta, timezone, UTC
  10. from pathlib import Path
  11. from typing import Optional
  12. from hermes_cli.update_cmd_common import _record_stop
  13. # Log-record parity with the origin module.
  14. logger = logging.getLogger("hermes_cli.update_cmd")
  15. #: Autostash subject contract: this prefix + UTC YYYYMMDD-HHMMSS stamp
  16. #: (producer _stash_local_changes_if_needed, consumer _warn_orphaned_update_autostashes).
  17. _AUTOSTASH_NAME_PREFIX = "hermes-update-autostash-"
  18. #: Age past which a leftover autostash is called out. Younger entries are normal
  19. #: (recent --keep-stash park); older ones are almost always forgotten.
  20. # Entries younger than this are normal (a parked stash from : the desktop updater's --keep-stash run minutes
  21. # ago); older ones are almost : always forgotten (#63717 problem 6: an orphan persisted 9+ days unnoticed).
  22. _AUTOSTASH_WARN_AGE_DAYS = 7
  23. _STASH_LEFT_IN_PLACE = " The stash was left in place. You can remove it manually after checking the result."
  24. #: This run's autostash until it is settled: (stash ref, stashed path count). Set when the
  25. #: update stashes local patches; cleared when they are restored, discarded or parked because
  26. #: the user asked for it, or once a failure verdict already named them. While it is set, no
  27. #: outcome may claim the update completed (#122557).
  28. _pending_autostash: Optional[tuple[str, int]] = None
  29. def _git_quiet(git_cmd: list[str], args: list[str], cwd: Path, **kwargs):
  30. """``subprocess.run`` of a git command with captured output; None when git cannot run."""
  31. from hermes_cli.update_custody import run_git
  32. try:
  33. return run_git(git_cmd, args, cwd=cwd, capture_output=True, **kwargs)
  34. except (OSError, subprocess.SubprocessError):
  35. return None
  36. def _intent_to_add_paths(porcelain_z: str) -> tuple[str, ...]:
  37. """Paths recorded with ``git add -N`` (intent-to-add), read from NUL-separated porcelain output.
  38. Such an entry carries the empty blob with zeroed stat data, so it is never "uptodate" and
  39. ``git stash push`` rejects the whole stash with ``Entry 'X' not uptodate. Cannot merge.`` - a dead
  40. end for the user, because that is the state an editor leaves behind when it shows a new file in
  41. diffs. Porcelain marks it ``" A"`` (in the worktree, absent from the index); a real staged add is
  42. ``"A "`` and an untracked file ``"??"``. Rename records carry a second, prefix-less field, which
  43. the leading ``" A"`` test cannot match.
  44. """
  45. return tuple(
  46. record[3:] for record in porcelain_z.split("\0")
  47. if len(record) > 3 and record[0] == " " and record[1] == "A"
  48. )
  49. def _git_paths_z(git_cmd: list[str], args: list[str], cwd: Path):
  50. """NUL-separated path listing as a set, or None when git failed (surrogateescape keeps odd filenames)."""
  51. result = _git_quiet(git_cmd, args, cwd, text=True, encoding="utf-8", errors="surrogateescape")
  52. if result is None or result.returncode != 0:
  53. return None
  54. return {path for path in result.stdout.split("\0") if path}
  55. def _reset_hard(git_cmd: list[str], cwd: Path) -> None:
  56. from hermes_cli.update_custody import run_git
  57. run_git(git_cmd, ["reset", "--hard", "HEAD"], cwd=cwd, capture_output=True)
  58. def _print_nonempty(text: str, prefix: str = "") -> None:
  59. if text.strip():
  60. print(f"{prefix}{text.strip()}")
  61. def _print_first_line(text: str) -> None:
  62. if text.strip():
  63. print(f" {text.strip().splitlines()[0]}")
  64. def _porcelain_records(porcelain_z: str) -> list[str]:
  65. """``status --porcelain -z`` records; a rename/copy's second (prefix-less) field is skipped."""
  66. fields, records = porcelain_z.split("\0"), []
  67. i = 0
  68. while i < len(fields):
  69. if len(fields[i]) > 3:
  70. records.append(fields[i])
  71. i += 1 if fields[i][0] not in "RC" else 2
  72. else:
  73. i += 1
  74. return records
  75. def _target_tree_paths(git_cmd: list[str], cwd: Path, refs) -> Optional[tuple[set[str], set[str]]]:
  76. """Casefolded (files, directories) the update can write, unioned over every *ref* that resolves;
  77. None when no ref resolves or a tree cannot be read. Casefolded so a case-insensitive filesystem's
  78. ``Config.py`` vs ``config.py`` still counts as a collision (over-stashing is always safe)."""
  79. files: set[str] = set()
  80. read_any = False
  81. for ref in dict.fromkeys(refs):
  82. resolved = _git_quiet(git_cmd, ["rev-parse", "-q", "--verify", f"{ref}^{{tree}}"], cwd)
  83. if resolved is None:
  84. return None
  85. if resolved.returncode:
  86. continue # e.g. no local branch of that name: it cannot be landed on
  87. paths = _git_paths_z(git_cmd, ["ls-tree", "-r", "--name-only", "-z", ref], cwd)
  88. if paths is None:
  89. return None
  90. files |= {p.casefold() for p in paths}
  91. read_any = True
  92. if not read_any:
  93. return None
  94. dirs = {p.rsplit("/", i)[0] for p in files for i in range(1, p.count("/") + 1)}
  95. return files, dirs
  96. def _untracked_collides(entry: str, files: set[str], dirs: set[str]) -> bool:
  97. """Whether the update could write where the untracked *entry* (a ``dir/`` record or a file) sits."""
  98. path = entry.rstrip("/").casefold()
  99. if path in files or path in dirs:
  100. return True
  101. parts = path.split("/")
  102. return any("/".join(parts[:i]) in files for i in range(1, len(parts)))
  103. @dataclass(frozen=True)
  104. class _LocalChanges:
  105. """What ``git status`` shows, split by what the update has to move out of its way."""
  106. porcelain: str
  107. tracked: bool # any modified/staged/deleted tracked path
  108. stash_untracked: tuple[str, ...] # untracked entries the update could overwrite
  109. leave_untracked: tuple[str, ...] # untracked entries no target touches: never moved
  110. @property
  111. def needs_moving(self) -> bool:
  112. return self.tracked or bool(self.stash_untracked)
  113. def _scan_local_changes(git_cmd: list[str], cwd: Path, untracked_targets=()) -> Optional[_LocalChanges]:
  114. """Local changes, or None when the tree is clean. An untracked file the update cannot write over
  115. blocks no pull or checkout, so with *untracked_targets* (every ref the update may land on) only the
  116. colliding ones are moved; without targets, or when a target tree is unreadable, all of them are."""
  117. from hermes_cli.update_cmd_git import _git_run
  118. # Explicit mode: status.showUntrackedFiles=no would hide every untracked entry, and an empty
  119. # leave-set means the stash takes them all.
  120. status = _git_run(git_cmd, ["status", "--porcelain", "-z", "--untracked-files=normal"], cwd, check=True)
  121. if not status.stdout.strip():
  122. return None
  123. records = _porcelain_records(status.stdout)
  124. untracked = [r[3:] for r in records if r.startswith("?? ")]
  125. trees = _target_tree_paths(git_cmd, cwd, untracked_targets) if untracked_targets and untracked else None
  126. collide = [u for u in untracked if trees is None or _untracked_collides(u, *trees)]
  127. return _LocalChanges(
  128. porcelain=status.stdout, tracked=len(untracked) < len(records),
  129. stash_untracked=tuple(collide), leave_untracked=tuple(u for u in untracked if u not in collide))
  130. def _target_would_move_head(git_cmd: list[str], cwd: Path, target_ref: str) -> bool:
  131. """True unless *target_ref* is HEAD or an ancestor of it (nothing to pull). An unresolvable
  132. target answers True: the update fails on it later, and asking first is the safe side."""
  133. probe = _git_quiet(git_cmd, ["merge-base", "--is-ancestor", f"{target_ref}^{{commit}}", "HEAD"], cwd)
  134. return probe is None or probe.returncode != 0
  135. def _literal(path: str, *magic: str) -> str:
  136. """Pathspec matching *path* byte-for-byte (relative to the checkout root git runs in)."""
  137. return f":({','.join(('literal', *magic))}){path}"
  138. def _ask_keep_local_changes(changes: _LocalChanges) -> bool:
  139. """The restore question, asked BEFORE anything moves: keeping means stash and re-apply after the
  140. update; declining discards now, so no stash entry is ever left behind. Closed stdin keeps them."""
  141. print("→ Local changes detected:")
  142. for line in (f" • tracked file edits: {'yes' if changes.tracked else 'none'}",
  143. f" • untracked files the update would overwrite: {len(changes.stash_untracked)}"):
  144. print(line)
  145. if changes.leave_untracked:
  146. print(f" ({len(changes.leave_untracked)} other untracked entr"
  147. f"{'y stays' if len(changes.leave_untracked) == 1 else 'ies stay'} in place either way.)")
  148. print("Keep these changes after updating? [Y/n] (n deletes them now)")
  149. try:
  150. response = input().strip().lower()
  151. except (EOFError, UnicodeDecodeError):
  152. response = ""
  153. return response not in {"n", "no"}
  154. def _discard_local_changes_before_update(
  155. git_cmd: list[str], cwd: Path, changes: _LocalChanges, *, checkout_move=None) -> None:
  156. """Delete exactly what would have been stashed: tracked edits and the colliding untracked entries."""
  157. from hermes_cli.update_cmd_git import _git_run, _no_move
  158. from hermes_cli.update_receipt import record_step
  159. with (checkout_move or _no_move)(revert=True): # every tracked change goes back to HEAD
  160. if changes.tracked:
  161. _git_run(git_cmd, ["reset", "--hard", "HEAD"], cwd, check=True)
  162. if changes.stash_untracked:
  163. _git_run(git_cmd, ["clean", "-f", "-d", "--", *(_literal(p) for p in changes.stash_untracked)],
  164. cwd, check=True)
  165. print("→ Discarded local changes (you chose not to keep them).")
  166. record_step("local_changes_stash", True, "discarded before update (user declined keeping them)")
  167. def _stash_local_changes_if_needed(
  168. git_cmd: list[str], cwd: Path, *, checkout_move=None, untracked_targets=(),
  169. ask_first: bool = False) -> Optional[str]:
  170. """Stash local changes before the update moves the checkout; the stash commit, or None when
  171. nothing needs moving. ``checkout_move`` binds the push (and its cleanup reset) to the paused
  172. gateways' tree gate; ``untracked_targets`` scopes untracked files (``_scan_local_changes``).
  173. ``ask_first`` asks whether to keep them; a "no" discards them instead of stashing (None)."""
  174. global _pending_autostash
  175. from hermes_cli.update_cmd_git import _git_run, _no_move
  176. _pending_autostash = None
  177. changes = _scan_local_changes(git_cmd, cwd, untracked_targets)
  178. if changes is None:
  179. return None
  180. if changes.leave_untracked:
  181. print(f"→ Leaving {len(changes.leave_untracked)} untracked entr"
  182. f"{'y' if len(changes.leave_untracked) == 1 else 'ies'} in place (the update does not touch them).")
  183. if not changes.needs_moving:
  184. return None
  185. if ask_first and not _ask_keep_local_changes(changes):
  186. _discard_local_changes_before_update(git_cmd, cwd, changes, checkout_move=checkout_move)
  187. return None
  188. status = subprocess.CompletedProcess([], 0, changes.porcelain, "")
  189. # Unmerged index entries (interrupted merge/rebase) make `git stash` fail with
  190. # "needs merge"; `git reset` drops only the index conflict state, not the tree.
  191. if _git_run(git_cmd, ["ls-files", "--unmerged"], cwd).stdout.strip():
  192. print("→ Clearing unmerged index entries from a previous conflict...")
  193. _git_quiet(git_cmd, ["reset"], cwd)
  194. # Intent-to-add entries are the other index state `git stash push` refuses (see
  195. # _intent_to_add_paths). Promoting them to real staged adds keeps their content and is lossless
  196. # for the user's work; after the restore they come back as staged additions, which is the closest
  197. # `git stash` can represent.
  198. intent_to_add = _intent_to_add_paths(status.stdout)
  199. if intent_to_add:
  200. print(f"→ Making {len(intent_to_add)} intent-to-add file(s) stashable...")
  201. add = _git_run(git_cmd, ["add", "--", *intent_to_add], cwd)
  202. if add.returncode != 0:
  203. _print_nonempty(add.stderr)
  204. stash_name = datetime.now(UTC).strftime(f"{_AUTOSTASH_NAME_PREFIX}%Y%m%d-%H%M%S")
  205. print("→ Local changes detected — stashing before update...")
  206. prev_stash = _git_run(git_cmd, ["rev-parse", "--verify", "refs/stash"], cwd).stdout.strip()
  207. with (checkout_move or _no_move)(revert=True): # push and reset put every tracked change back to HEAD
  208. stash_ref = _push_stash(git_cmd, cwd, stash_name, prev_stash, leave=changes.leave_untracked)
  209. _pending_autostash = (
  210. stash_ref, len(_porcelain_records(status.stdout)) - len(changes.leave_untracked))
  211. return stash_ref
  212. def _push_stash(git_cmd: list[str], cwd: Path, stash_name: str, prev_stash: str, leave=()) -> str:
  213. """``git stash push``; the stash commit. Raises when nothing was saved; resets tracked leftovers
  214. when a push saved everything but could not clean up. Untracked entries in *leave* stay on disk
  215. (an exclude pathspec: git never hashes them, which is what made a 55 GB stray dir take minutes)."""
  216. from hermes_cli.update_cmd_git import _git_run
  217. scope = ["--", ".", *(_literal(p, "exclude") for p in leave)] if leave else []
  218. push = _git_run(git_cmd, ["stash", "push", "--include-untracked", "-m", stash_name, *scope], cwd)
  219. _print_nonempty(push.stdout)
  220. stash_probe = _git_run(git_cmd, ["rev-parse", "--verify", "refs/stash"], cwd)
  221. stash_ref = stash_probe.stdout.strip()
  222. stash_created = stash_probe.returncode == 0 and bool(stash_ref) and stash_ref != prev_stash
  223. if push.returncode != 0:
  224. if not stash_created:
  225. # No entry created: changes NOT saved — bail before touching HEAD.
  226. print("✗ Could not stash local changes — update aborted.")
  227. _print_first_line(push.stderr)
  228. print(" Commit, stash, or clean up your local changes manually, then re-run `hermes update`.")
  229. print(" (An index entry from `git add -N` is the usual cause of this error; `git add` the")
  230. print(" paths it names, or `git reset` them, and the update will proceed.)")
  231. raise subprocess.CalledProcessError(push.returncode, push.args, output=push.stdout, stderr=push.stderr)
  232. # Non-zero but entry created: push saved everything yet couldn't delete some untracked files
  233. # (e.g. root-owned dir). Not a failure — continue.
  234. _print_nonempty(push.stderr)
  235. print(" ⚠ Some untracked files could not be removed from the working tree (permission denied).")
  236. print(" They were still saved to the stash and were left in place — the update will continue.")
  237. # A partially-failed push also skips cleanup of TRACKED modifications; they'd break the following
  238. # pull. Safe to reset: all is in the stash.
  239. _reset_hard(git_cmd, cwd)
  240. return stash_ref
  241. def _resolve_stash_selector(git_cmd: list[str], cwd: Path, stash_ref: str) -> Optional[str]:
  242. """Selector for the stash entry whose commit is *stash_ref*, as the bare index ``N``
  243. (git accepts it wherever ``stash@{N}`` is valid). Never ``stash@{N}`` itself: on native
  244. Windows the MSYS runtime strips the braces from git.exe's argv, so ``stash@{0}`` reaches git
  245. as ``stash@0`` and the drop fails (#87542)."""
  246. from hermes_cli.update_cmd_git import _git_run
  247. stash_list = _git_run(git_cmd, ["stash", "list", "--format=%gd %H"], cwd, check=True)
  248. for line in stash_list.stdout.splitlines():
  249. selector, _, commit = line.partition(" ")
  250. if commit.strip() == stash_ref:
  251. match = re.fullmatch(r"stash@\{(\d+)\}", selector.strip())
  252. return match.group(1) if match else selector.strip()
  253. return None
  254. def _clear_pending_autostash() -> None:
  255. """Forget this run's unsettled autostash after it was already reported (#122557)."""
  256. global _pending_autostash
  257. _pending_autostash = None
  258. def _unrestored_autostash_notice() -> Optional[str]:
  259. """What to tell the user while this run's autostash is unsettled (#122557), else ``None``.
  260. Used as the completion line (it is not a success line, so the update ends partial and
  261. exits non-zero) and printed by failure verdicts, which otherwise never name the stash.
  262. """
  263. if _pending_autostash is None:
  264. return None
  265. stash_ref, file_count = _pending_autostash
  266. return (f"⚠ hermes update stashed {file_count} local modification(s) and did NOT restore them.\n"
  267. f" Stash ref: {stash_ref}\n"
  268. f" Review with: git stash show --stat {stash_ref}\n"
  269. f" Re-apply with: git stash show -p {stash_ref} | git apply --3way")
  270. def _warn_orphaned_update_autostashes(git_cmd: list[str], cwd: Path) -> int:
  271. """Print a notice for update autostashes older than the warn threshold; return the count (0 on any git failure).
  272. Autostashes legitimately outlive a run (--keep-stash, failed restore) but nothing re-surfaces them.
  273. Deliberately NOT a GC: a stash may be the only copy of the user's work, so Hermes never drops one.
  274. Autostash entries legitimately outlive an update run (``--keep-stash`` parks them; a conflicted or
  275. failed restore preserves them for safety), but nothing ever re-surfaces them afterwards — they sit in
  276. ``git stash`` invisibly for weeks (#63717 problem 6). This prints a short notice naming the stale
  277. entries with recovery/cleanup guidance.
  278. """
  279. from hermes_cli.update_cmd_git import _git_run
  280. try:
  281. stash_list = _git_run(git_cmd, ["stash", "list", "--format=%gd %s"], cwd)
  282. if stash_list.returncode != 0:
  283. return 0
  284. cutoff = datetime.now(UTC) - timedelta(days=_AUTOSTASH_WARN_AGE_DAYS)
  285. stale: list[tuple[str, str]] = []
  286. for line in stash_list.stdout.splitlines():
  287. selector, _, subject = line.strip().partition(" ")
  288. pos = subject.find(_AUTOSTASH_NAME_PREFIX)
  289. if pos < 0:
  290. continue
  291. stamp = subject[pos + len(_AUTOSTASH_NAME_PREFIX):][:15] # "YYYYMMDD-HHMMSS"
  292. try:
  293. stash_time = datetime.strptime(stamp, "%Y%m%d-%H%M%S").replace(tzinfo=UTC)
  294. except ValueError:
  295. continue # age unknown — leave it alone rather than guess
  296. if stash_time < cutoff:
  297. stale.append((selector, stamp))
  298. if not stale:
  299. return 0
  300. print()
  301. print(
  302. f"⚠ {len(stale)} leftover update autostash entr"
  303. f"{'y is' if len(stale) == 1 else 'ies are'} more than "
  304. f"{_AUTOSTASH_WARN_AGE_DAYS} days old:"
  305. )
  306. for selector, stamp in stale:
  307. print(f" {selector} ({_AUTOSTASH_NAME_PREFIX}{stamp})")
  308. print(" These hold local changes stashed by earlier updates and never")
  309. print(" restored. Review with: git stash show -p <entry>")
  310. print(" Restore with: git stash apply <entry> Discard with: git stash drop <entry>")
  311. return len(stale)
  312. except Exception as exc:
  313. logger.debug("Autostash age check failed: %s", exc)
  314. return 0
  315. def _record_stash_disposition(outcome: str, stash_ref: str, detail: str = "", *, chosen: bool = False) -> None:
  316. """Note the autostash disposition in the update receipt so a parked stash is visible
  317. to automation reading receipts instead of stdout (#115363: an update that ended with
  318. local changes parked in the stash reported a bare success with no trace of them).
  319. A park the user did not ask for (``chosen``) keeps the stash unsettled (#122557)."""
  320. global _pending_autostash
  321. if outcome != "parked" or chosen:
  322. _pending_autostash = None
  323. from hermes_cli.update_receipt import record_step
  324. record_step(
  325. "local_changes_stash",
  326. outcome != "parked",
  327. f"{outcome}: {stash_ref}" + (f" ({detail})" if detail else ""),
  328. )
  329. def _print_stash_cleanup_guidance(stash_ref: str, stash_selector: Optional[str] = None) -> None:
  330. print(" Check `git status` first so you don't accidentally reapply the same change twice.")
  331. print(" Find the saved entry with: git stash list --format='%gd %H %s'")
  332. if stash_selector:
  333. print(f" Remove it with: git stash drop {stash_selector}")
  334. else:
  335. print(f" Look for commit {stash_ref}, then drop it by index with: git stash drop <N>")
  336. def _stash_apply_failed_only_on_existing_untracked(stderr: str) -> bool:
  337. """True when a ``git stash apply`` failure is ONLY about untracked files that already exist in the tree.
  338. Tail of the permission-denied class: push swept undeletable files into the stash but couldn't remove them;
  339. apply restores tracked changes, then refuses to overwrite those files and exits non-zero though nothing was lost.
  340. Any other error line (e.g. ``would be overwritten by merge``) means the tracked apply failed -> False.
  341. """
  342. saw_untracked_error = False
  343. for ln in (ln.strip() for ln in (stderr or "").splitlines() if ln.strip()):
  344. if "already exists, no checkout" in ln or "could not restore untracked files from stash" in ln:
  345. saw_untracked_error = True
  346. elif not ln.startswith(("warning:", "hint:")):
  347. return False
  348. return saw_untracked_error
  349. def _untracked_files_replaced_by_update(git_cmd: list[str], cwd: Path, stash_ref: str, stderr: str) -> list[str]:
  350. """Paths ``git stash apply`` refused ("<path> already exists, no checkout") because the update
  351. now tracks its own file there (``HEAD:<path>``) and the tree does not hold the stash's untracked
  352. copy (``<stash>^3``). An untracked occupant HEAD does not track is the #70127 file that could
  353. not be deleted at stash time, whatever its content now; it is never the update's."""
  354. from hermes_cli.update_custody import run_git
  355. replaced = []
  356. suffix = " already exists, no checkout"
  357. for ln in (stderr or "").splitlines():
  358. ln = ln.strip()
  359. if not ln.endswith(suffix):
  360. continue
  361. rel = ln[: -len(suffix)]
  362. tracked = run_git(git_cmd, ["cat-file", "-e", f"HEAD:{rel}"], cwd=cwd, capture_output=True, check=False)
  363. if tracked.returncode != 0:
  364. continue
  365. stashed = run_git(git_cmd, ["show", f"{stash_ref}^3:{rel}"], cwd=cwd, capture_output=True, check=False)
  366. try:
  367. current = (Path(cwd) / rel).read_bytes()
  368. except OSError:
  369. current = None
  370. if stashed.returncode != 0 or current != stashed.stdout:
  371. replaced.append(rel)
  372. return replaced
  373. def _park_stashed_changes(stash_ref: str) -> None:
  374. """Leave a pre-update autostash parked (``--keep-stash``, the desktop updater's mode): local source
  375. edits must never be silently re-applied onto updated code; the entry stays in ``git stash``."""
  376. print()
  377. print("ℹ️ Local changes were stashed before updating and were NOT re-applied (--keep-stash).")
  378. print(f" Stash ref: {stash_ref}")
  379. print(f" Restore manually with: git stash apply {stash_ref}")
  380. _record_stash_disposition("parked", stash_ref, "--keep-stash", chosen=True)
  381. def _git_untracked_paths(git_cmd: list[str], cwd: Path) -> set[str] | None:
  382. """Return untracked paths, or ``None`` when Git cannot enumerate them."""
  383. paths = _git_paths_z(git_cmd, ["ls-files", "--others", "--exclude-standard", "-z"], cwd)
  384. if paths is None:
  385. print(" ⚠ Could not enumerate untracked files while validating the restored stash.")
  386. return paths
  387. def _restored_python_paths(git_cmd: list[str], cwd: Path) -> tuple[str, ...] | None:
  388. """Restored ``.py`` paths changed from ``HEAD``; deliberately Python-only (entry scripts stay outside the health check)."""
  389. from hermes_cli.update_cmd import _git_untracked_paths
  390. paths = _git_paths_z(git_cmd, ["diff", "--name-only", "-z", "HEAD", "--", "*.py"], cwd)
  391. if paths is None:
  392. print(" ⚠ Could not enumerate tracked Python files restored from the stash.")
  393. return None
  394. untracked = _git_untracked_paths(git_cmd, cwd)
  395. if untracked is None:
  396. return None
  397. paths.update(path for path in untracked if path.endswith(".py"))
  398. return tuple(sorted(paths))
  399. #: Closed allowlist of suffixes that no Python import can load or read during startup.
  400. #: Everything else (.py, .so/.pyd/.dll/.dylib, .pyc, .pth, .egg-link, data files such as
  401. #: .json/.yaml/.toml that modules read on import, extensionless files) keeps the import check.
  402. _NON_RUNTIME_SUFFIXES = frozenset({
  403. ".md", ".mdx", ".rst", ".txt", ".adoc",
  404. ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico",
  405. })
  406. def _restore_is_non_runtime(git_cmd: list[str], cwd: Path, stash_ref: str) -> bool:
  407. """True only when every path the stash restores is demonstrably unable to change an import.
  408. The set is read from the stash commit itself (worktree and index changes against its base,
  409. renames split into delete + add, plus its untracked tree), never from the working tree,
  410. which also holds what the clean import probe wrote. Each path must have an allowlisted
  411. suffix, must not be a symlink, and may only sit in a directory ``HEAD`` already tracks, so
  412. the restore cannot create a namespace-package directory. Any Git failure counts as
  413. runtime-affecting.
  414. """
  415. restored: set[str] = set()
  416. for side in (stash_ref, f"{stash_ref}^2"): # worktree, index
  417. changed = _git_paths_z(
  418. git_cmd, ["diff", "--name-only", "--no-renames", "-z", f"{stash_ref}^1", side, "--"], cwd)
  419. if changed is None:
  420. return False
  421. restored |= changed
  422. has_untracked = _git_quiet(git_cmd, ["rev-parse", "-q", "--verify", f"{stash_ref}^3"], cwd)
  423. if has_untracked is None:
  424. return False
  425. if has_untracked.returncode == 0:
  426. untracked = _git_paths_z(git_cmd, ["ls-tree", "-r", "--name-only", "-z", f"{stash_ref}^3"], cwd)
  427. if untracked is None:
  428. return False
  429. restored |= untracked
  430. if not restored:
  431. return True
  432. head_dirs = _git_paths_z(git_cmd, ["ls-tree", "-r", "-d", "--name-only", "-z", "HEAD"], cwd)
  433. if head_dirs is None:
  434. return False
  435. for path in restored:
  436. parent = Path(path).parent.as_posix()
  437. if (Path(path).suffix.lower() not in _NON_RUNTIME_SUFFIXES or (cwd / path).is_symlink()
  438. or (parent != "." and parent not in head_dirs)):
  439. return False
  440. return True
  441. def _reject_unsafe_stash_restore(
  442. git_cmd: list[str], cwd: Path, stash_ref: str, preexisting_untracked: set[str], failing_target: str,
  443. detail: str | None, *, checkout_move=None,
  444. ) -> None:
  445. """Restore the clean updated tree, preserve the stash, and abort the update."""
  446. from hermes_cli.update_cmd import _git_untracked_paths
  447. from hermes_cli.update_cmd_git import _no_move
  448. print()
  449. print("✗ Restored local changes made the Hermes agent unexecutable.")
  450. print(f" Health check failed: {failing_target}")
  451. if detail:
  452. for line in str(detail).splitlines()[:6]:
  453. print(f" {line}")
  454. def _ok(result) -> bool:
  455. return result is not None and result.returncode == 0
  456. current_untracked = _git_untracked_paths(git_cmd, cwd)
  457. restored_untracked = current_untracked - preexisting_untracked if current_untracked is not None else set()
  458. with (checkout_move or _no_move)(revert=True):
  459. reset = _git_quiet(git_cmd, ["reset", "--hard", "HEAD"], cwd)
  460. clean = _git_quiet(git_cmd, ["clean", "-fd", "--", *sorted(restored_untracked)], cwd) if restored_untracked else None
  461. cleanup_ok = current_untracked is not None and _ok(reset) and (not restored_untracked or _ok(clean))
  462. if cleanup_ok:
  463. cleanup_ok = _ok(_git_quiet(git_cmd, ["diff", "--quiet", "HEAD", "--"], cwd))
  464. if cleanup_ok:
  465. print(" The clean updated tree has been restored; the gateway was not restarted.")
  466. else:
  467. print(" ⚠ The clean updated tree could not be fully restored automatically.")
  468. print(" Inspect `git status` and run `git reset --hard HEAD` before retrying.")
  469. print(" Platform connectivity alone does not mean the agent can execute turns.")
  470. print(f" Your local changes remain preserved in stash: {stash_ref}")
  471. print(f" Inspect them with: git stash show --stat {stash_ref}")
  472. print(f" Restore manually after fixing them: git stash apply {stash_ref}")
  473. _clear_pending_autostash() # named right above, and the update fails
  474. _record_stop("stash_restore_rejected")
  475. raise SystemExit(1)
  476. def _confirm_restore(stash_ref: str, input_fn) -> bool:
  477. """Interactive gate; a remote ``input_fn`` defaults to No (``[y/N]``), the local prompt to Yes."""
  478. remote_prompt = input_fn is not None
  479. prompt_suffix = "[y/N]" if remote_prompt else "[Y/n]"
  480. print()
  481. print("⚠ Local changes were stashed before updating.")
  482. print(" Restoring them may reapply local customizations onto the updated codebase.")
  483. print(" Review the result afterward if Hermes behaves unexpectedly.")
  484. print(f"Restore local changes now? {prompt_suffix}")
  485. if remote_prompt:
  486. response = input_fn(f"Restore local changes now? {prompt_suffix}", "n")
  487. else:
  488. try:
  489. response = input().strip().lower()
  490. except (EOFError, UnicodeDecodeError):
  491. response = "n" # closed stdin/encoding error must not crash mid-restore
  492. if response in {"y", "yes"} or (not remote_prompt and response == ""):
  493. return True
  494. print("Skipped restoring local changes.")
  495. print("Your changes are still preserved in git stash.")
  496. print(f"Restore manually with: git stash apply {stash_ref}")
  497. return False
  498. def _apply_stash(git_cmd: list[str], cwd: Path, stash_ref: str, checkout_move=None) -> list[str] | None:
  499. """``git stash apply``; the untracked paths the update replaced (empty on a full restore), or
  500. None (tree reset, stash kept) on conflicts or any failure other than the already-exists class.
  501. ``checkout_move`` binds the apply (and a conflict's reset) to the paused gateways' tree gate."""
  502. from hermes_cli.update_cmd_git import _no_move
  503. print("→ Restoring local changes...")
  504. with (checkout_move or _no_move)(stash_ref) as step:
  505. restore, conflicted_files = _apply_stash_step(git_cmd, cwd, stash_ref)
  506. # Tracked changes applied in full (the already-exists class refuses only untracked files):
  507. # the tree this changed is the restore's result, not a tear.
  508. step["whole"] = not conflicted_files and (
  509. restore.returncode == 0 or _stash_apply_failed_only_on_existing_untracked(restore.stderr))
  510. if step["whole"] and restore.returncode == 0:
  511. return []
  512. if step["whole"]:
  513. # Tracked changes applied; git refused to overwrite untracked files that already exist. That is
  514. # harmless only when the occupant IS the stashed copy (undeletable at stash time, #70127). When
  515. # the update added its own file at that path, the stash is the only copy of the user's file.
  516. replaced = _untracked_files_replaced_by_update(git_cmd, cwd, stash_ref, restore.stderr)
  517. if not replaced:
  518. print(" ⚠ Some stashed untracked files already exist in the working tree and were kept as-is.")
  519. return replaced
  520. print("✗ Update pulled new code, but restoring local changes hit conflicts.")
  521. _print_nonempty(restore.stdout)
  522. _print_nonempty(restore.stderr)
  523. if conflicted_files:
  524. print("\nConflicted files:")
  525. for f in conflicted_files.splitlines():
  526. print(f" • {f}")
  527. print("\nYour stashed changes are preserved — nothing is lost.")
  528. print(f" Stash ref: {stash_ref}")
  529. print("Working tree reset to clean state.")
  530. print(f"Restore your changes later with: git stash apply {stash_ref}")
  531. _record_stash_disposition("parked", stash_ref, "restore hit conflicts")
  532. return None # code update succeeded; cmd_update continues (deps, skills, gateway)
  533. def _apply_stash_step(git_cmd: list[str], cwd: Path, stash_ref: str):
  534. """``git stash apply`` and its conflicted paths. Any failure but the already-exists class is
  535. reset to the clean tree here, inside the bound step: conflict markers make hermes unrunnable,
  536. and the changes stay in the stash."""
  537. from hermes_cli.update_cmd_git import _git_run
  538. restore = _git_run(git_cmd, ["stash", "apply", stash_ref], cwd)
  539. unmerged = _git_run(git_cmd, ["diff", "--name-only", "--diff-filter=U"], cwd) # conflicts can exist even on rc 0
  540. conflicted_files = unmerged.stdout.strip()
  541. if conflicted_files or (restore.returncode != 0
  542. and not _stash_apply_failed_only_on_existing_untracked(restore.stderr)):
  543. _reset_hard(git_cmd, cwd)
  544. return restore, conflicted_files
  545. def _drop_restored_stash(git_cmd: list[str], cwd: Path, stash_ref: str) -> None:
  546. from hermes_cli.update_cmd_git import _git_run
  547. stash_selector = _resolve_stash_selector(git_cmd, cwd, stash_ref)
  548. if stash_selector is None:
  549. print("⚠ Local changes were restored, but Hermes couldn't find the stash entry to drop.")
  550. print(_STASH_LEFT_IN_PLACE)
  551. _print_stash_cleanup_guidance(stash_ref)
  552. return
  553. drop = _git_run(git_cmd, ["stash", "drop", stash_selector], cwd)
  554. if drop.returncode != 0:
  555. print("⚠ Local changes were restored, but Hermes couldn't drop the saved stash entry.")
  556. _print_nonempty(drop.stdout)
  557. _print_nonempty(drop.stderr)
  558. print(_STASH_LEFT_IN_PLACE)
  559. _print_stash_cleanup_guidance(stash_ref, stash_selector)
  560. def _restore_stashed_changes(
  561. git_cmd: list[str], cwd: Path, stash_ref: str, prompt_user: bool = False, input_fn=None, *,
  562. checkout_move=None,
  563. ) -> bool:
  564. from hermes_cli.update_cmd import _critical_module_import_failures, _git_untracked_paths, _restored_python_paths, _validate_python_files_syntax
  565. if prompt_user and not _confirm_restore(stash_ref, input_fn):
  566. _record_stash_disposition("parked", stash_ref, "restore declined", chosen=True)
  567. return False
  568. preexisting_untracked = _git_untracked_paths(git_cmd, cwd)
  569. if preexisting_untracked is None:
  570. print(" The stash was not restored because its cleanup baseline is unknown.")
  571. print(f" Restore manually with: git stash apply {stash_ref}")
  572. _record_stash_disposition("parked", stash_ref, "untracked baseline unknown")
  573. return False
  574. clean_import_failures = _critical_module_import_failures(cwd, report_runtime_errors=True)
  575. replaced = _apply_stash(git_cmd, cwd, stash_ref, checkout_move)
  576. if replaced is None:
  577. return False # disposition already recorded inside _apply_stash
  578. def reject(failing_target: str, detail) -> None:
  579. _reject_unsafe_stash_restore(
  580. git_cmd, cwd, stash_ref, preexisting_untracked, failing_target, detail, checkout_move=checkout_move)
  581. restored_python = _restored_python_paths(git_cmd, cwd)
  582. if restored_python is None:
  583. reject("restored Python source discovery", "could not determine which restored Python files require validation")
  584. syntax_ok, failing_path, syntax_error = _validate_python_files_syntax(cwd, restored_python)
  585. if not syntax_ok:
  586. reject(failing_path or "restored Python source", syntax_error)
  587. # Probe outcomes also move with install state between the two runs (launch preparation,
  588. # dependency sync), so a restore that cannot affect an import (docs, images) must not be
  589. # rejected on that difference (#130101). Anything else, including a native extension or
  590. # bytecode that shadows a healthy module, is still compared.
  591. non_runtime = _restore_is_non_runtime(git_cmd, cwd, stash_ref)
  592. for module, error in (() if non_runtime else
  593. _critical_module_import_failures(cwd, report_runtime_errors=True).items()):
  594. if clean_import_failures.get(module) != error:
  595. reject(f"agent import {module or 'unknown'}", error[1])
  596. break
  597. if replaced:
  598. # The restored tree is healthy, but dropping the stash would lose the user's copies.
  599. print(f"⚠ The update added {len(replaced)} file(s) where you had untracked files of the same name:")
  600. for path in replaced[:10]:
  601. print(f" {path}")
  602. print(" The updated files are in place; your versions are kept in the stash, which was NOT dropped.")
  603. print(f" Stash ref: {stash_ref}")
  604. print(f" Recover a file with: git show {stash_ref}^3:<path> > <path>.mine")
  605. _record_stash_disposition("parked", stash_ref, f"untracked files replaced by the update: {', '.join(replaced[:10])}")
  606. return False
  607. _drop_restored_stash(git_cmd, cwd, stash_ref)
  608. _record_stash_disposition("restored", stash_ref)
  609. print("⚠ Local changes were restored on top of the updated codebase.")
  610. print(" Review `git diff` / `git status` if Hermes behaves unexpectedly.")
  611. return True
  612. def _discard_stashed_changes(git_cmd: list[str], cwd: Path, stash_ref: str) -> bool:
  613. """Drop a pre-update stash without applying (non-interactive ``updates.non_interactive_local_changes: discard``).
  614. Unlike reset --hard + clean -fd this touches only what was stashed; ignored paths are never affected.
  615. Returns True if dropped, False on git failure (stash left in place).
  616. """
  617. from hermes_cli.update_cmd_git import _git_run
  618. stash_selector = _resolve_stash_selector(git_cmd, cwd, stash_ref)
  619. if stash_selector is None:
  620. print(
  621. "⚠ Configured to discard local changes on non-interactive update, "
  622. "but Hermes couldn't find the stash entry to drop."
  623. )
  624. _print_stash_cleanup_guidance(stash_ref)
  625. return False
  626. drop = _git_run(git_cmd, ["stash", "drop", stash_selector], cwd)
  627. if drop.returncode != 0:
  628. print("⚠ Configured to discard local changes, but Hermes couldn't drop the saved stash entry.")
  629. _print_first_line(drop.stderr)
  630. _print_stash_cleanup_guidance(stash_ref, stash_selector)
  631. _record_stash_disposition("parked", stash_ref, "configured discard failed")
  632. return False
  633. print("→ Discarded local source changes (updates.non_interactive_local_changes=discard).")
  634. _record_stash_disposition("discarded", stash_ref)
  635. return True