| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735 |
- """Autostash handling for ``hermes update``: stash before the pull, restore/park/discard afterwards, warn about orphans.
- Split out of ``update_cmd.py``; names are re-imported there so ``hermes_cli.update_cmd.<name>`` still resolves/monkeypatches.
- Origin helpers are imported lazily per function (no cycle; test patches on the origin stay effective).
- """
- import logging
- import re
- from dataclasses import dataclass
- import subprocess
- from datetime import datetime, timedelta, timezone, UTC
- from pathlib import Path
- from typing import Optional
- from hermes_cli.update_cmd_common import _record_stop
- # Log-record parity with the origin module.
- logger = logging.getLogger("hermes_cli.update_cmd")
- #: Autostash subject contract: this prefix + UTC YYYYMMDD-HHMMSS stamp
- #: (producer _stash_local_changes_if_needed, consumer _warn_orphaned_update_autostashes).
- _AUTOSTASH_NAME_PREFIX = "hermes-update-autostash-"
- #: Age past which a leftover autostash is called out. Younger entries are normal
- #: (recent --keep-stash park); older ones are almost always forgotten.
- # Entries younger than this are normal (a parked stash from : the desktop updater's --keep-stash run minutes
- # ago); older ones are almost : always forgotten (#63717 problem 6: an orphan persisted 9+ days unnoticed).
- _AUTOSTASH_WARN_AGE_DAYS = 7
- _STASH_LEFT_IN_PLACE = " The stash was left in place. You can remove it manually after checking the result."
- #: This run's autostash until it is settled: (stash ref, stashed path count). Set when the
- #: update stashes local patches; cleared when they are restored, discarded or parked because
- #: the user asked for it, or once a failure verdict already named them. While it is set, no
- #: outcome may claim the update completed (#122557).
- _pending_autostash: Optional[tuple[str, int]] = None
- def _git_quiet(git_cmd: list[str], args: list[str], cwd: Path, **kwargs):
- """``subprocess.run`` of a git command with captured output; None when git cannot run."""
- from hermes_cli.update_custody import run_git
- try:
- return run_git(git_cmd, args, cwd=cwd, capture_output=True, **kwargs)
- except (OSError, subprocess.SubprocessError):
- return None
- def _intent_to_add_paths(porcelain_z: str) -> tuple[str, ...]:
- """Paths recorded with ``git add -N`` (intent-to-add), read from NUL-separated porcelain output.
- Such an entry carries the empty blob with zeroed stat data, so it is never "uptodate" and
- ``git stash push`` rejects the whole stash with ``Entry 'X' not uptodate. Cannot merge.`` - a dead
- end for the user, because that is the state an editor leaves behind when it shows a new file in
- diffs. Porcelain marks it ``" A"`` (in the worktree, absent from the index); a real staged add is
- ``"A "`` and an untracked file ``"??"``. Rename records carry a second, prefix-less field, which
- the leading ``" A"`` test cannot match.
- """
- return tuple(
- record[3:] for record in porcelain_z.split("\0")
- if len(record) > 3 and record[0] == " " and record[1] == "A"
- )
- def _git_paths_z(git_cmd: list[str], args: list[str], cwd: Path):
- """NUL-separated path listing as a set, or None when git failed (surrogateescape keeps odd filenames)."""
- result = _git_quiet(git_cmd, args, cwd, text=True, encoding="utf-8", errors="surrogateescape")
- if result is None or result.returncode != 0:
- return None
- return {path for path in result.stdout.split("\0") if path}
- def _reset_hard(git_cmd: list[str], cwd: Path) -> None:
- from hermes_cli.update_custody import run_git
- run_git(git_cmd, ["reset", "--hard", "HEAD"], cwd=cwd, capture_output=True)
- def _print_nonempty(text: str, prefix: str = "") -> None:
- if text.strip():
- print(f"{prefix}{text.strip()}")
- def _print_first_line(text: str) -> None:
- if text.strip():
- print(f" {text.strip().splitlines()[0]}")
- def _porcelain_records(porcelain_z: str) -> list[str]:
- """``status --porcelain -z`` records; a rename/copy's second (prefix-less) field is skipped."""
- fields, records = porcelain_z.split("\0"), []
- i = 0
- while i < len(fields):
- if len(fields[i]) > 3:
- records.append(fields[i])
- i += 1 if fields[i][0] not in "RC" else 2
- else:
- i += 1
- return records
- def _target_tree_paths(git_cmd: list[str], cwd: Path, refs) -> Optional[tuple[set[str], set[str]]]:
- """Casefolded (files, directories) the update can write, unioned over every *ref* that resolves;
- None when no ref resolves or a tree cannot be read. Casefolded so a case-insensitive filesystem's
- ``Config.py`` vs ``config.py`` still counts as a collision (over-stashing is always safe)."""
- files: set[str] = set()
- read_any = False
- for ref in dict.fromkeys(refs):
- resolved = _git_quiet(git_cmd, ["rev-parse", "-q", "--verify", f"{ref}^{{tree}}"], cwd)
- if resolved is None:
- return None
- if resolved.returncode:
- continue # e.g. no local branch of that name: it cannot be landed on
- paths = _git_paths_z(git_cmd, ["ls-tree", "-r", "--name-only", "-z", ref], cwd)
- if paths is None:
- return None
- files |= {p.casefold() for p in paths}
- read_any = True
- if not read_any:
- return None
- dirs = {p.rsplit("/", i)[0] for p in files for i in range(1, p.count("/") + 1)}
- return files, dirs
- def _untracked_collides(entry: str, files: set[str], dirs: set[str]) -> bool:
- """Whether the update could write where the untracked *entry* (a ``dir/`` record or a file) sits."""
- path = entry.rstrip("/").casefold()
- if path in files or path in dirs:
- return True
- parts = path.split("/")
- return any("/".join(parts[:i]) in files for i in range(1, len(parts)))
- @dataclass(frozen=True)
- class _LocalChanges:
- """What ``git status`` shows, split by what the update has to move out of its way."""
- porcelain: str
- tracked: bool # any modified/staged/deleted tracked path
- stash_untracked: tuple[str, ...] # untracked entries the update could overwrite
- leave_untracked: tuple[str, ...] # untracked entries no target touches: never moved
- @property
- def needs_moving(self) -> bool:
- return self.tracked or bool(self.stash_untracked)
- def _scan_local_changes(git_cmd: list[str], cwd: Path, untracked_targets=()) -> Optional[_LocalChanges]:
- """Local changes, or None when the tree is clean. An untracked file the update cannot write over
- blocks no pull or checkout, so with *untracked_targets* (every ref the update may land on) only the
- colliding ones are moved; without targets, or when a target tree is unreadable, all of them are."""
- from hermes_cli.update_cmd_git import _git_run
- # Explicit mode: status.showUntrackedFiles=no would hide every untracked entry, and an empty
- # leave-set means the stash takes them all.
- status = _git_run(git_cmd, ["status", "--porcelain", "-z", "--untracked-files=normal"], cwd, check=True)
- if not status.stdout.strip():
- return None
- records = _porcelain_records(status.stdout)
- untracked = [r[3:] for r in records if r.startswith("?? ")]
- trees = _target_tree_paths(git_cmd, cwd, untracked_targets) if untracked_targets and untracked else None
- collide = [u for u in untracked if trees is None or _untracked_collides(u, *trees)]
- return _LocalChanges(
- porcelain=status.stdout, tracked=len(untracked) < len(records),
- stash_untracked=tuple(collide), leave_untracked=tuple(u for u in untracked if u not in collide))
- def _target_would_move_head(git_cmd: list[str], cwd: Path, target_ref: str) -> bool:
- """True unless *target_ref* is HEAD or an ancestor of it (nothing to pull). An unresolvable
- target answers True: the update fails on it later, and asking first is the safe side."""
- probe = _git_quiet(git_cmd, ["merge-base", "--is-ancestor", f"{target_ref}^{{commit}}", "HEAD"], cwd)
- return probe is None or probe.returncode != 0
- def _literal(path: str, *magic: str) -> str:
- """Pathspec matching *path* byte-for-byte (relative to the checkout root git runs in)."""
- return f":({','.join(('literal', *magic))}){path}"
- def _ask_keep_local_changes(changes: _LocalChanges) -> bool:
- """The restore question, asked BEFORE anything moves: keeping means stash and re-apply after the
- update; declining discards now, so no stash entry is ever left behind. Closed stdin keeps them."""
- print("→ Local changes detected:")
- for line in (f" • tracked file edits: {'yes' if changes.tracked else 'none'}",
- f" • untracked files the update would overwrite: {len(changes.stash_untracked)}"):
- print(line)
- if changes.leave_untracked:
- print(f" ({len(changes.leave_untracked)} other untracked entr"
- f"{'y stays' if len(changes.leave_untracked) == 1 else 'ies stay'} in place either way.)")
- print("Keep these changes after updating? [Y/n] (n deletes them now)")
- try:
- response = input().strip().lower()
- except (EOFError, UnicodeDecodeError):
- response = ""
- return response not in {"n", "no"}
- def _discard_local_changes_before_update(
- git_cmd: list[str], cwd: Path, changes: _LocalChanges, *, checkout_move=None) -> None:
- """Delete exactly what would have been stashed: tracked edits and the colliding untracked entries."""
- from hermes_cli.update_cmd_git import _git_run, _no_move
- from hermes_cli.update_receipt import record_step
- with (checkout_move or _no_move)(revert=True): # every tracked change goes back to HEAD
- if changes.tracked:
- _git_run(git_cmd, ["reset", "--hard", "HEAD"], cwd, check=True)
- if changes.stash_untracked:
- _git_run(git_cmd, ["clean", "-f", "-d", "--", *(_literal(p) for p in changes.stash_untracked)],
- cwd, check=True)
- print("→ Discarded local changes (you chose not to keep them).")
- record_step("local_changes_stash", True, "discarded before update (user declined keeping them)")
- def _stash_local_changes_if_needed(
- git_cmd: list[str], cwd: Path, *, checkout_move=None, untracked_targets=(),
- ask_first: bool = False) -> Optional[str]:
- """Stash local changes before the update moves the checkout; the stash commit, or None when
- nothing needs moving. ``checkout_move`` binds the push (and its cleanup reset) to the paused
- gateways' tree gate; ``untracked_targets`` scopes untracked files (``_scan_local_changes``).
- ``ask_first`` asks whether to keep them; a "no" discards them instead of stashing (None)."""
- global _pending_autostash
- from hermes_cli.update_cmd_git import _git_run, _no_move
- _pending_autostash = None
- changes = _scan_local_changes(git_cmd, cwd, untracked_targets)
- if changes is None:
- return None
- if changes.leave_untracked:
- print(f"→ Leaving {len(changes.leave_untracked)} untracked entr"
- f"{'y' if len(changes.leave_untracked) == 1 else 'ies'} in place (the update does not touch them).")
- if not changes.needs_moving:
- return None
- if ask_first and not _ask_keep_local_changes(changes):
- _discard_local_changes_before_update(git_cmd, cwd, changes, checkout_move=checkout_move)
- return None
- status = subprocess.CompletedProcess([], 0, changes.porcelain, "")
- # Unmerged index entries (interrupted merge/rebase) make `git stash` fail with
- # "needs merge"; `git reset` drops only the index conflict state, not the tree.
- if _git_run(git_cmd, ["ls-files", "--unmerged"], cwd).stdout.strip():
- print("→ Clearing unmerged index entries from a previous conflict...")
- _git_quiet(git_cmd, ["reset"], cwd)
- # Intent-to-add entries are the other index state `git stash push` refuses (see
- # _intent_to_add_paths). Promoting them to real staged adds keeps their content and is lossless
- # for the user's work; after the restore they come back as staged additions, which is the closest
- # `git stash` can represent.
- intent_to_add = _intent_to_add_paths(status.stdout)
- if intent_to_add:
- print(f"→ Making {len(intent_to_add)} intent-to-add file(s) stashable...")
- add = _git_run(git_cmd, ["add", "--", *intent_to_add], cwd)
- if add.returncode != 0:
- _print_nonempty(add.stderr)
- stash_name = datetime.now(UTC).strftime(f"{_AUTOSTASH_NAME_PREFIX}%Y%m%d-%H%M%S")
- print("→ Local changes detected — stashing before update...")
- prev_stash = _git_run(git_cmd, ["rev-parse", "--verify", "refs/stash"], cwd).stdout.strip()
- with (checkout_move or _no_move)(revert=True): # push and reset put every tracked change back to HEAD
- stash_ref = _push_stash(git_cmd, cwd, stash_name, prev_stash, leave=changes.leave_untracked)
- _pending_autostash = (
- stash_ref, len(_porcelain_records(status.stdout)) - len(changes.leave_untracked))
- return stash_ref
- def _push_stash(git_cmd: list[str], cwd: Path, stash_name: str, prev_stash: str, leave=()) -> str:
- """``git stash push``; the stash commit. Raises when nothing was saved; resets tracked leftovers
- when a push saved everything but could not clean up. Untracked entries in *leave* stay on disk
- (an exclude pathspec: git never hashes them, which is what made a 55 GB stray dir take minutes)."""
- from hermes_cli.update_cmd_git import _git_run
- scope = ["--", ".", *(_literal(p, "exclude") for p in leave)] if leave else []
- push = _git_run(git_cmd, ["stash", "push", "--include-untracked", "-m", stash_name, *scope], cwd)
- _print_nonempty(push.stdout)
- stash_probe = _git_run(git_cmd, ["rev-parse", "--verify", "refs/stash"], cwd)
- stash_ref = stash_probe.stdout.strip()
- stash_created = stash_probe.returncode == 0 and bool(stash_ref) and stash_ref != prev_stash
- if push.returncode != 0:
- if not stash_created:
- # No entry created: changes NOT saved — bail before touching HEAD.
- print("✗ Could not stash local changes — update aborted.")
- _print_first_line(push.stderr)
- print(" Commit, stash, or clean up your local changes manually, then re-run `hermes update`.")
- print(" (An index entry from `git add -N` is the usual cause of this error; `git add` the")
- print(" paths it names, or `git reset` them, and the update will proceed.)")
- raise subprocess.CalledProcessError(push.returncode, push.args, output=push.stdout, stderr=push.stderr)
- # Non-zero but entry created: push saved everything yet couldn't delete some untracked files
- # (e.g. root-owned dir). Not a failure — continue.
- _print_nonempty(push.stderr)
- print(" ⚠ Some untracked files could not be removed from the working tree (permission denied).")
- print(" They were still saved to the stash and were left in place — the update will continue.")
- # A partially-failed push also skips cleanup of TRACKED modifications; they'd break the following
- # pull. Safe to reset: all is in the stash.
- _reset_hard(git_cmd, cwd)
- return stash_ref
- def _resolve_stash_selector(git_cmd: list[str], cwd: Path, stash_ref: str) -> Optional[str]:
- """Selector for the stash entry whose commit is *stash_ref*, as the bare index ``N``
- (git accepts it wherever ``stash@{N}`` is valid). Never ``stash@{N}`` itself: on native
- Windows the MSYS runtime strips the braces from git.exe's argv, so ``stash@{0}`` reaches git
- as ``stash@0`` and the drop fails (#87542)."""
- from hermes_cli.update_cmd_git import _git_run
- stash_list = _git_run(git_cmd, ["stash", "list", "--format=%gd %H"], cwd, check=True)
- for line in stash_list.stdout.splitlines():
- selector, _, commit = line.partition(" ")
- if commit.strip() == stash_ref:
- match = re.fullmatch(r"stash@\{(\d+)\}", selector.strip())
- return match.group(1) if match else selector.strip()
- return None
- def _clear_pending_autostash() -> None:
- """Forget this run's unsettled autostash after it was already reported (#122557)."""
- global _pending_autostash
- _pending_autostash = None
- def _unrestored_autostash_notice() -> Optional[str]:
- """What to tell the user while this run's autostash is unsettled (#122557), else ``None``.
- Used as the completion line (it is not a success line, so the update ends partial and
- exits non-zero) and printed by failure verdicts, which otherwise never name the stash.
- """
- if _pending_autostash is None:
- return None
- stash_ref, file_count = _pending_autostash
- return (f"⚠ hermes update stashed {file_count} local modification(s) and did NOT restore them.\n"
- f" Stash ref: {stash_ref}\n"
- f" Review with: git stash show --stat {stash_ref}\n"
- f" Re-apply with: git stash show -p {stash_ref} | git apply --3way")
- def _warn_orphaned_update_autostashes(git_cmd: list[str], cwd: Path) -> int:
- """Print a notice for update autostashes older than the warn threshold; return the count (0 on any git failure).
- Autostashes legitimately outlive a run (--keep-stash, failed restore) but nothing re-surfaces them.
- Deliberately NOT a GC: a stash may be the only copy of the user's work, so Hermes never drops one.
- Autostash entries legitimately outlive an update run (``--keep-stash`` parks them; a conflicted or
- failed restore preserves them for safety), but nothing ever re-surfaces them afterwards — they sit in
- ``git stash`` invisibly for weeks (#63717 problem 6). This prints a short notice naming the stale
- entries with recovery/cleanup guidance.
- """
- from hermes_cli.update_cmd_git import _git_run
- try:
- stash_list = _git_run(git_cmd, ["stash", "list", "--format=%gd %s"], cwd)
- if stash_list.returncode != 0:
- return 0
- cutoff = datetime.now(UTC) - timedelta(days=_AUTOSTASH_WARN_AGE_DAYS)
- stale: list[tuple[str, str]] = []
- for line in stash_list.stdout.splitlines():
- selector, _, subject = line.strip().partition(" ")
- pos = subject.find(_AUTOSTASH_NAME_PREFIX)
- if pos < 0:
- continue
- stamp = subject[pos + len(_AUTOSTASH_NAME_PREFIX):][:15] # "YYYYMMDD-HHMMSS"
- try:
- stash_time = datetime.strptime(stamp, "%Y%m%d-%H%M%S").replace(tzinfo=UTC)
- except ValueError:
- continue # age unknown — leave it alone rather than guess
- if stash_time < cutoff:
- stale.append((selector, stamp))
- if not stale:
- return 0
- print()
- print(
- f"⚠ {len(stale)} leftover update autostash entr"
- f"{'y is' if len(stale) == 1 else 'ies are'} more than "
- f"{_AUTOSTASH_WARN_AGE_DAYS} days old:"
- )
- for selector, stamp in stale:
- print(f" {selector} ({_AUTOSTASH_NAME_PREFIX}{stamp})")
- print(" These hold local changes stashed by earlier updates and never")
- print(" restored. Review with: git stash show -p <entry>")
- print(" Restore with: git stash apply <entry> Discard with: git stash drop <entry>")
- return len(stale)
- except Exception as exc:
- logger.debug("Autostash age check failed: %s", exc)
- return 0
- def _record_stash_disposition(outcome: str, stash_ref: str, detail: str = "", *, chosen: bool = False) -> None:
- """Note the autostash disposition in the update receipt so a parked stash is visible
- to automation reading receipts instead of stdout (#115363: an update that ended with
- local changes parked in the stash reported a bare success with no trace of them).
- A park the user did not ask for (``chosen``) keeps the stash unsettled (#122557)."""
- global _pending_autostash
- if outcome != "parked" or chosen:
- _pending_autostash = None
- from hermes_cli.update_receipt import record_step
- record_step(
- "local_changes_stash",
- outcome != "parked",
- f"{outcome}: {stash_ref}" + (f" ({detail})" if detail else ""),
- )
- def _print_stash_cleanup_guidance(stash_ref: str, stash_selector: Optional[str] = None) -> None:
- print(" Check `git status` first so you don't accidentally reapply the same change twice.")
- print(" Find the saved entry with: git stash list --format='%gd %H %s'")
- if stash_selector:
- print(f" Remove it with: git stash drop {stash_selector}")
- else:
- print(f" Look for commit {stash_ref}, then drop it by index with: git stash drop <N>")
- def _stash_apply_failed_only_on_existing_untracked(stderr: str) -> bool:
- """True when a ``git stash apply`` failure is ONLY about untracked files that already exist in the tree.
- Tail of the permission-denied class: push swept undeletable files into the stash but couldn't remove them;
- apply restores tracked changes, then refuses to overwrite those files and exits non-zero though nothing was lost.
- Any other error line (e.g. ``would be overwritten by merge``) means the tracked apply failed -> False.
- """
- saw_untracked_error = False
- for ln in (ln.strip() for ln in (stderr or "").splitlines() if ln.strip()):
- if "already exists, no checkout" in ln or "could not restore untracked files from stash" in ln:
- saw_untracked_error = True
- elif not ln.startswith(("warning:", "hint:")):
- return False
- return saw_untracked_error
- def _untracked_files_replaced_by_update(git_cmd: list[str], cwd: Path, stash_ref: str, stderr: str) -> list[str]:
- """Paths ``git stash apply`` refused ("<path> already exists, no checkout") because the update
- now tracks its own file there (``HEAD:<path>``) and the tree does not hold the stash's untracked
- copy (``<stash>^3``). An untracked occupant HEAD does not track is the #70127 file that could
- not be deleted at stash time, whatever its content now; it is never the update's."""
- from hermes_cli.update_custody import run_git
- replaced = []
- suffix = " already exists, no checkout"
- for ln in (stderr or "").splitlines():
- ln = ln.strip()
- if not ln.endswith(suffix):
- continue
- rel = ln[: -len(suffix)]
- tracked = run_git(git_cmd, ["cat-file", "-e", f"HEAD:{rel}"], cwd=cwd, capture_output=True, check=False)
- if tracked.returncode != 0:
- continue
- stashed = run_git(git_cmd, ["show", f"{stash_ref}^3:{rel}"], cwd=cwd, capture_output=True, check=False)
- try:
- current = (Path(cwd) / rel).read_bytes()
- except OSError:
- current = None
- if stashed.returncode != 0 or current != stashed.stdout:
- replaced.append(rel)
- return replaced
- def _park_stashed_changes(stash_ref: str) -> None:
- """Leave a pre-update autostash parked (``--keep-stash``, the desktop updater's mode): local source
- edits must never be silently re-applied onto updated code; the entry stays in ``git stash``."""
- print()
- print("ℹ️ Local changes were stashed before updating and were NOT re-applied (--keep-stash).")
- print(f" Stash ref: {stash_ref}")
- print(f" Restore manually with: git stash apply {stash_ref}")
- _record_stash_disposition("parked", stash_ref, "--keep-stash", chosen=True)
- def _git_untracked_paths(git_cmd: list[str], cwd: Path) -> set[str] | None:
- """Return untracked paths, or ``None`` when Git cannot enumerate them."""
- paths = _git_paths_z(git_cmd, ["ls-files", "--others", "--exclude-standard", "-z"], cwd)
- if paths is None:
- print(" ⚠ Could not enumerate untracked files while validating the restored stash.")
- return paths
- def _restored_python_paths(git_cmd: list[str], cwd: Path) -> tuple[str, ...] | None:
- """Restored ``.py`` paths changed from ``HEAD``; deliberately Python-only (entry scripts stay outside the health check)."""
- from hermes_cli.update_cmd import _git_untracked_paths
- paths = _git_paths_z(git_cmd, ["diff", "--name-only", "-z", "HEAD", "--", "*.py"], cwd)
- if paths is None:
- print(" ⚠ Could not enumerate tracked Python files restored from the stash.")
- return None
- untracked = _git_untracked_paths(git_cmd, cwd)
- if untracked is None:
- return None
- paths.update(path for path in untracked if path.endswith(".py"))
- return tuple(sorted(paths))
- #: Closed allowlist of suffixes that no Python import can load or read during startup.
- #: Everything else (.py, .so/.pyd/.dll/.dylib, .pyc, .pth, .egg-link, data files such as
- #: .json/.yaml/.toml that modules read on import, extensionless files) keeps the import check.
- _NON_RUNTIME_SUFFIXES = frozenset({
- ".md", ".mdx", ".rst", ".txt", ".adoc",
- ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico",
- })
- def _restore_is_non_runtime(git_cmd: list[str], cwd: Path, stash_ref: str) -> bool:
- """True only when every path the stash restores is demonstrably unable to change an import.
- The set is read from the stash commit itself (worktree and index changes against its base,
- renames split into delete + add, plus its untracked tree), never from the working tree,
- which also holds what the clean import probe wrote. Each path must have an allowlisted
- suffix, must not be a symlink, and may only sit in a directory ``HEAD`` already tracks, so
- the restore cannot create a namespace-package directory. Any Git failure counts as
- runtime-affecting.
- """
- restored: set[str] = set()
- for side in (stash_ref, f"{stash_ref}^2"): # worktree, index
- changed = _git_paths_z(
- git_cmd, ["diff", "--name-only", "--no-renames", "-z", f"{stash_ref}^1", side, "--"], cwd)
- if changed is None:
- return False
- restored |= changed
- has_untracked = _git_quiet(git_cmd, ["rev-parse", "-q", "--verify", f"{stash_ref}^3"], cwd)
- if has_untracked is None:
- return False
- if has_untracked.returncode == 0:
- untracked = _git_paths_z(git_cmd, ["ls-tree", "-r", "--name-only", "-z", f"{stash_ref}^3"], cwd)
- if untracked is None:
- return False
- restored |= untracked
- if not restored:
- return True
- head_dirs = _git_paths_z(git_cmd, ["ls-tree", "-r", "-d", "--name-only", "-z", "HEAD"], cwd)
- if head_dirs is None:
- return False
- for path in restored:
- parent = Path(path).parent.as_posix()
- if (Path(path).suffix.lower() not in _NON_RUNTIME_SUFFIXES or (cwd / path).is_symlink()
- or (parent != "." and parent not in head_dirs)):
- return False
- return True
- def _reject_unsafe_stash_restore(
- git_cmd: list[str], cwd: Path, stash_ref: str, preexisting_untracked: set[str], failing_target: str,
- detail: str | None, *, checkout_move=None,
- ) -> None:
- """Restore the clean updated tree, preserve the stash, and abort the update."""
- from hermes_cli.update_cmd import _git_untracked_paths
- from hermes_cli.update_cmd_git import _no_move
- print()
- print("✗ Restored local changes made the Hermes agent unexecutable.")
- print(f" Health check failed: {failing_target}")
- if detail:
- for line in str(detail).splitlines()[:6]:
- print(f" {line}")
- def _ok(result) -> bool:
- return result is not None and result.returncode == 0
- current_untracked = _git_untracked_paths(git_cmd, cwd)
- restored_untracked = current_untracked - preexisting_untracked if current_untracked is not None else set()
- with (checkout_move or _no_move)(revert=True):
- reset = _git_quiet(git_cmd, ["reset", "--hard", "HEAD"], cwd)
- clean = _git_quiet(git_cmd, ["clean", "-fd", "--", *sorted(restored_untracked)], cwd) if restored_untracked else None
- cleanup_ok = current_untracked is not None and _ok(reset) and (not restored_untracked or _ok(clean))
- if cleanup_ok:
- cleanup_ok = _ok(_git_quiet(git_cmd, ["diff", "--quiet", "HEAD", "--"], cwd))
- if cleanup_ok:
- print(" The clean updated tree has been restored; the gateway was not restarted.")
- else:
- print(" ⚠ The clean updated tree could not be fully restored automatically.")
- print(" Inspect `git status` and run `git reset --hard HEAD` before retrying.")
- print(" Platform connectivity alone does not mean the agent can execute turns.")
- print(f" Your local changes remain preserved in stash: {stash_ref}")
- print(f" Inspect them with: git stash show --stat {stash_ref}")
- print(f" Restore manually after fixing them: git stash apply {stash_ref}")
- _clear_pending_autostash() # named right above, and the update fails
- _record_stop("stash_restore_rejected")
- raise SystemExit(1)
- def _confirm_restore(stash_ref: str, input_fn) -> bool:
- """Interactive gate; a remote ``input_fn`` defaults to No (``[y/N]``), the local prompt to Yes."""
- remote_prompt = input_fn is not None
- prompt_suffix = "[y/N]" if remote_prompt else "[Y/n]"
- print()
- print("⚠ Local changes were stashed before updating.")
- print(" Restoring them may reapply local customizations onto the updated codebase.")
- print(" Review the result afterward if Hermes behaves unexpectedly.")
- print(f"Restore local changes now? {prompt_suffix}")
- if remote_prompt:
- response = input_fn(f"Restore local changes now? {prompt_suffix}", "n")
- else:
- try:
- response = input().strip().lower()
- except (EOFError, UnicodeDecodeError):
- response = "n" # closed stdin/encoding error must not crash mid-restore
- if response in {"y", "yes"} or (not remote_prompt and response == ""):
- return True
- print("Skipped restoring local changes.")
- print("Your changes are still preserved in git stash.")
- print(f"Restore manually with: git stash apply {stash_ref}")
- return False
- def _apply_stash(git_cmd: list[str], cwd: Path, stash_ref: str, checkout_move=None) -> list[str] | None:
- """``git stash apply``; the untracked paths the update replaced (empty on a full restore), or
- None (tree reset, stash kept) on conflicts or any failure other than the already-exists class.
- ``checkout_move`` binds the apply (and a conflict's reset) to the paused gateways' tree gate."""
- from hermes_cli.update_cmd_git import _no_move
- print("→ Restoring local changes...")
- with (checkout_move or _no_move)(stash_ref) as step:
- restore, conflicted_files = _apply_stash_step(git_cmd, cwd, stash_ref)
- # Tracked changes applied in full (the already-exists class refuses only untracked files):
- # the tree this changed is the restore's result, not a tear.
- step["whole"] = not conflicted_files and (
- restore.returncode == 0 or _stash_apply_failed_only_on_existing_untracked(restore.stderr))
- if step["whole"] and restore.returncode == 0:
- return []
- if step["whole"]:
- # Tracked changes applied; git refused to overwrite untracked files that already exist. That is
- # harmless only when the occupant IS the stashed copy (undeletable at stash time, #70127). When
- # the update added its own file at that path, the stash is the only copy of the user's file.
- replaced = _untracked_files_replaced_by_update(git_cmd, cwd, stash_ref, restore.stderr)
- if not replaced:
- print(" ⚠ Some stashed untracked files already exist in the working tree and were kept as-is.")
- return replaced
- print("✗ Update pulled new code, but restoring local changes hit conflicts.")
- _print_nonempty(restore.stdout)
- _print_nonempty(restore.stderr)
- if conflicted_files:
- print("\nConflicted files:")
- for f in conflicted_files.splitlines():
- print(f" • {f}")
- print("\nYour stashed changes are preserved — nothing is lost.")
- print(f" Stash ref: {stash_ref}")
- print("Working tree reset to clean state.")
- print(f"Restore your changes later with: git stash apply {stash_ref}")
- _record_stash_disposition("parked", stash_ref, "restore hit conflicts")
- return None # code update succeeded; cmd_update continues (deps, skills, gateway)
- def _apply_stash_step(git_cmd: list[str], cwd: Path, stash_ref: str):
- """``git stash apply`` and its conflicted paths. Any failure but the already-exists class is
- reset to the clean tree here, inside the bound step: conflict markers make hermes unrunnable,
- and the changes stay in the stash."""
- from hermes_cli.update_cmd_git import _git_run
- restore = _git_run(git_cmd, ["stash", "apply", stash_ref], cwd)
- unmerged = _git_run(git_cmd, ["diff", "--name-only", "--diff-filter=U"], cwd) # conflicts can exist even on rc 0
- conflicted_files = unmerged.stdout.strip()
- if conflicted_files or (restore.returncode != 0
- and not _stash_apply_failed_only_on_existing_untracked(restore.stderr)):
- _reset_hard(git_cmd, cwd)
- return restore, conflicted_files
- def _drop_restored_stash(git_cmd: list[str], cwd: Path, stash_ref: str) -> None:
- from hermes_cli.update_cmd_git import _git_run
- stash_selector = _resolve_stash_selector(git_cmd, cwd, stash_ref)
- if stash_selector is None:
- print("⚠ Local changes were restored, but Hermes couldn't find the stash entry to drop.")
- print(_STASH_LEFT_IN_PLACE)
- _print_stash_cleanup_guidance(stash_ref)
- return
- drop = _git_run(git_cmd, ["stash", "drop", stash_selector], cwd)
- if drop.returncode != 0:
- print("⚠ Local changes were restored, but Hermes couldn't drop the saved stash entry.")
- _print_nonempty(drop.stdout)
- _print_nonempty(drop.stderr)
- print(_STASH_LEFT_IN_PLACE)
- _print_stash_cleanup_guidance(stash_ref, stash_selector)
- def _restore_stashed_changes(
- git_cmd: list[str], cwd: Path, stash_ref: str, prompt_user: bool = False, input_fn=None, *,
- checkout_move=None,
- ) -> bool:
- from hermes_cli.update_cmd import _critical_module_import_failures, _git_untracked_paths, _restored_python_paths, _validate_python_files_syntax
- if prompt_user and not _confirm_restore(stash_ref, input_fn):
- _record_stash_disposition("parked", stash_ref, "restore declined", chosen=True)
- return False
- preexisting_untracked = _git_untracked_paths(git_cmd, cwd)
- if preexisting_untracked is None:
- print(" The stash was not restored because its cleanup baseline is unknown.")
- print(f" Restore manually with: git stash apply {stash_ref}")
- _record_stash_disposition("parked", stash_ref, "untracked baseline unknown")
- return False
- clean_import_failures = _critical_module_import_failures(cwd, report_runtime_errors=True)
- replaced = _apply_stash(git_cmd, cwd, stash_ref, checkout_move)
- if replaced is None:
- return False # disposition already recorded inside _apply_stash
- def reject(failing_target: str, detail) -> None:
- _reject_unsafe_stash_restore(
- git_cmd, cwd, stash_ref, preexisting_untracked, failing_target, detail, checkout_move=checkout_move)
- restored_python = _restored_python_paths(git_cmd, cwd)
- if restored_python is None:
- reject("restored Python source discovery", "could not determine which restored Python files require validation")
- syntax_ok, failing_path, syntax_error = _validate_python_files_syntax(cwd, restored_python)
- if not syntax_ok:
- reject(failing_path or "restored Python source", syntax_error)
- # Probe outcomes also move with install state between the two runs (launch preparation,
- # dependency sync), so a restore that cannot affect an import (docs, images) must not be
- # rejected on that difference (#130101). Anything else, including a native extension or
- # bytecode that shadows a healthy module, is still compared.
- non_runtime = _restore_is_non_runtime(git_cmd, cwd, stash_ref)
- for module, error in (() if non_runtime else
- _critical_module_import_failures(cwd, report_runtime_errors=True).items()):
- if clean_import_failures.get(module) != error:
- reject(f"agent import {module or 'unknown'}", error[1])
- break
- if replaced:
- # The restored tree is healthy, but dropping the stash would lose the user's copies.
- print(f"⚠ The update added {len(replaced)} file(s) where you had untracked files of the same name:")
- for path in replaced[:10]:
- print(f" {path}")
- print(" The updated files are in place; your versions are kept in the stash, which was NOT dropped.")
- print(f" Stash ref: {stash_ref}")
- print(f" Recover a file with: git show {stash_ref}^3:<path> > <path>.mine")
- _record_stash_disposition("parked", stash_ref, f"untracked files replaced by the update: {', '.join(replaced[:10])}")
- return False
- _drop_restored_stash(git_cmd, cwd, stash_ref)
- _record_stash_disposition("restored", stash_ref)
- print("⚠ Local changes were restored on top of the updated codebase.")
- print(" Review `git diff` / `git status` if Hermes behaves unexpectedly.")
- return True
- def _discard_stashed_changes(git_cmd: list[str], cwd: Path, stash_ref: str) -> bool:
- """Drop a pre-update stash without applying (non-interactive ``updates.non_interactive_local_changes: discard``).
- Unlike reset --hard + clean -fd this touches only what was stashed; ignored paths are never affected.
- Returns True if dropped, False on git failure (stash left in place).
- """
- from hermes_cli.update_cmd_git import _git_run
- stash_selector = _resolve_stash_selector(git_cmd, cwd, stash_ref)
- if stash_selector is None:
- print(
- "⚠ Configured to discard local changes on non-interactive update, "
- "but Hermes couldn't find the stash entry to drop."
- )
- _print_stash_cleanup_guidance(stash_ref)
- return False
- drop = _git_run(git_cmd, ["stash", "drop", stash_selector], cwd)
- if drop.returncode != 0:
- print("⚠ Configured to discard local changes, but Hermes couldn't drop the saved stash entry.")
- _print_first_line(drop.stderr)
- _print_stash_cleanup_guidance(stash_ref, stash_selector)
- _record_stash_disposition("parked", stash_ref, "configured discard failed")
- return False
- print("→ Discarded local source changes (updates.non_interactive_local_changes=discard).")
- _record_stash_disposition("discarded", stash_ref)
- return True
|