Skip to content

The agent that grows with you

fix(update): a damaged .git no longer strands paused gateways

Teknium99cc712bf370
diff --git a/hermes_cli/update_cmd_git.py b/hermes_cli/update_cmd_git.py
index 701dc8e2d24..c4b2e5c750a 100644
--- a/hermes_cli/update_cmd_git.py
+++ b/hermes_cli/update_cmd_git.py
@@ -496,11 +496,23 @@ def _has_http_code(stderr: str, *codes: str) -> bool:
return any(f"HTTP {code}" in stderr or f"returned error: {code}" in stderr for code in codes)
+def _damaged_checkout_message() -> str:
+ from hermes_cli.update_cmd_maint import _REINSTALL_ONE_LINER
+
+ return ("✗ This Hermes checkout's git data is damaged (git no longer recognizes its .git folder),"
+ " so it cannot be updated in place.\n"
+ " Run the installer again to repair it; it moves the damaged checkout aside and keeps"
+ f" your config and chats:\n {_REINSTALL_ONE_LINER[sys.platform == 'win32']}")
+
+
# Ordered (predicate, diagnosis): curl reports HTTP errors as ``unable to access '<url>': ... error: 429``,
# so rate-limit/outage checks must run BEFORE the generic "unable to access" check. An anonymous fetch
# answered with HTTP 401 ("could not read Username") is GitHub during an outage (or a renamed/private
-# repo), not a user credentials problem.
+# repo), not a user credentials problem. A diagnosis may be a callable when it depends on the host.
_FETCH_FAILURE_RULES = (
+ # The updater only fetches when .git exists, so this is a .git git rejects (empty dir, lost HEAD):
+ # no retry can work and the ZIP fallback cannot tell user edits apart, but the installer can.
+ (lambda s: "not a git repository" in s, _damaged_checkout_message),
(lambda s: _has_http_code(s, "429") or "rate limit" in s.lower(),
"✗ GitHub is rate limiting requests or having an outage (HTTP 429) — try again in 5 minutes."),
(lambda s: _has_http_code(s, "500", "502", "503", "504"),
@@ -526,7 +538,8 @@ _FETCH_FAILURE_RULES = (
def _classify_fetch_failure(stderr: str) -> str:
"""Map git-fetch stderr to a one-line diagnosis (caller also prints the raw first line)."""
- return next((message for matches, message in _FETCH_FAILURE_RULES if matches(stderr)), "✗ Failed to fetch updates from origin.")
+ message = next((message for matches, message in _FETCH_FAILURE_RULES if matches(stderr)), "✗ Failed to fetch updates from origin.")
+ return message() if callable(message) else message
def _print_fetch_failure(stderr: str) -> None:
diff --git a/hermes_cli/update_pause_record.py b/hermes_cli/update_pause_record.py
index 88d57fc076f..c5816f887f8 100644
--- a/hermes_cli/update_pause_record.py
+++ b/hermes_cli/update_pause_record.py
@@ -356,6 +356,20 @@ def _deps_hold_resume(root: Path) -> bool:
return False
+def _paused_on_unreadable_head(token: dict) -> bool:
+ """Every pause in the set already found HEAD unreadable and none bound a tree move since.
+
+ The gateways were serving exactly this tree when they stopped, and no step of the update wrote
+ a file (``_checkout_move`` records its targets/paths before git writes), so restarting them
+ leaves the tree as they knew it. Without this a ``.git`` git rejects (an empty ``HEAD``) kept
+ the set stopped on every later launch, since no update can fetch until the checkout is repaired.
+ """
+ baselines = token.get("baselines") or []
+ return bool(baselines) and all(
+ b.get("pre_sha") is None and not (b.get("move_targets") or b.get("move_paths") or b.get("landed"))
+ for b in baselines)
+
+
def tree_is_whole(token: dict, root: Path | None = None) -> tuple[bool, str]:
"""May paused gateways start on this checkout now? ``(verdict, reason when not)``."""
from hermes_cli._early_recovery import interrupted_pull_marker
@@ -365,6 +379,8 @@ def tree_is_whole(token: dict, root: Path | None = None) -> tuple[bool, str]:
return False, "the checkout is mid-pull (interrupted-pull marker present)"
head = head_sha(root)
if head is None:
+ if _paused_on_unreadable_head(token):
+ return True, ""
return False, "the checkout HEAD is unreadable"
baselines = token.get("baselines") or []
at_head = [b for b in baselines if b.get("pre_sha") == head]
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 951b062e3c9..f87f8072e20 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -979,13 +979,15 @@ function Stage-Repository {
if (-not (Ensure-Git)) { Fail "no pinned Git artifact for this Windows architecture" unsupported_platform }
# An interrupted clone from an older installer can leave a .git with no
# initial commit, where stash/checkout abort ("You do not have the initial
- # commit yet", #40998). Move it aside -- never delete it, it may hold
- # something the user wants -- and clone fresh below.
+ # commit yet", #40998); a killed update or a sync tool can leave one git
+ # rejects outright (empty HEAD, a gitdir: file pointing nowhere), where
+ # `hermes update` cannot fetch. Move it aside -- never delete it, it may
+ # hold something the user wants -- and clone fresh below.
if (Test-Path (Join-Path $InstallDir ".git")) {
Invoke-Native { git -C $InstallDir rev-parse --verify HEAD 2>$null } | Out-Null
if ($LASTEXITCODE) {
$broken = "$InstallDir.broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
- Write-Warn "$InstallDir has no commits (interrupted clone); moving it aside to $broken"
+ Write-Warn "$InstallDir is not a usable git checkout (interrupted clone or damaged .git); moving it aside to $broken"
Move-Item -LiteralPath $InstallDir -Destination $broken
}
}
diff --git a/scripts/install.sh b/scripts/install.sh
index 395208bdf3c..ff31933e43c 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -711,12 +711,14 @@ stage_repository() {
local pinned=false channel="" release="" origin
# An interrupted clone from an older installer can leave a .git with no
# initial commit, where stash/checkout abort ("You do not have the
- # initial commit yet", #40998). Move it aside -- never delete it, it may
- # hold something the user wants -- and clone fresh below.
- if [ -d "$INSTALL_DIR/.git" ] && ! git -C "$INSTALL_DIR" rev-parse --verify HEAD >/dev/null 2>&1; then
+ # initial commit yet", #40998); a killed update or a sync tool can leave
+ # one git rejects outright (empty HEAD, a gitdir: file pointing nowhere),
+ # where `hermes update` cannot fetch. Move it aside -- never delete it, it
+ # may hold something the user wants -- and clone fresh below.
+ if [ -e "$INSTALL_DIR/.git" ] && ! git -C "$INSTALL_DIR" rev-parse --verify HEAD >/dev/null 2>&1; then
local broken
broken="${INSTALL_DIR}.broken-$(date -u +%Y%m%d-%H%M%S)"
- log_warn "$INSTALL_DIR has no commits (interrupted clone); moving it aside to $broken"
+ log_warn "$INSTALL_DIR is not a usable git checkout (interrupted clone or damaged .git); moving it aside to $broken"
mv "$INSTALL_DIR" "$broken" || fail "cannot move $INSTALL_DIR aside" filesystem_error
fi
if [ -d "$INSTALL_DIR/.git" ]; then
diff --git a/tests/hermes_cli/test_update_fetch_failure_classifier.py b/tests/hermes_cli/test_update_fetch_failure_classifier.py
index ff23dc9f053..a9ecdfd684d 100644
--- a/tests/hermes_cli/test_update_fetch_failure_classifier.py
+++ b/tests/hermes_cli/test_update_fetch_failure_classifier.py
@@ -7,6 +7,9 @@ classifier must call out rate limiting / outages explicitly, and the raw
stderr line must always be printed alongside the diagnosis.
"""
+import os
+import subprocess
+
from hermes_cli import update_cmd
@@ -78,6 +81,17 @@ class TestClassifyFetchFailure:
assert "SSH authentication failed" in msg
assert "https://github.com/NousResearch/hermes-agent.git" in msg
+ def test_a_git_dir_git_rejects_names_the_installer_repair(self, tmp_path):
+ # The updater fetches only when .git exists; git rejecting it (here an empty .git) cannot
+ # be retried away, and the generic "Failed to fetch" left users with no way out.
+ (tmp_path / ".git").mkdir()
+ stderr = subprocess.run(["git", "fetch", "origin"], cwd=tmp_path, capture_output=True, check=False,
+ text=True, encoding="utf-8", errors="replace",
+ env={**os.environ, "GIT_CEILING_DIRECTORIES": str(tmp_path.parent)}).stderr
+ msg = update_cmd._classify_fetch_failure(stderr)
+ assert "damaged" in msg
+ assert "hermes-agent.nousresearch.com/install." in msg
+
def test_ssh_host_key_failure_reports_ssh_auth(self):
msg = update_cmd._classify_fetch_failure(
"@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n"
diff --git a/tests/hermes_cli/test_update_pause_record.py b/tests/hermes_cli/test_update_pause_record.py
index 98b6c457e7a..438ee45ad7f 100644
--- a/tests/hermes_cli/test_update_pause_record.py
+++ b/tests/hermes_cli/test_update_pause_record.py
@@ -132,6 +132,26 @@ def test_resume_waits_for_a_whole_tree(tmp_path):
assert pause_record.tree_is_whole(token, root) == (True, "")
+def test_a_set_paused_on_an_already_unreadable_head_resumes_until_a_move_is_bound(tmp_path):
+ """A .git git rejects (HEAD lost) before the pause: the gateways were serving this exact tree
+ and nothing the update did could write it, so the set resumes instead of waiting for a repair
+ no update can make. A bound move, or a HEAD that was readable at the pause, still holds it."""
+ root = tmp_path / "checkout"
+ root.mkdir()
+ _git(root, "init", "-q")
+ (root / "a.py").write_text("v1\n", encoding="utf-8")
+ _git(root, "add", ".")
+ _git(root, "commit", "-qm", "v1")
+ readable_at_pause = pause_record.stamp_tree({"resume_needed": True}, root)
+ (root / ".git" / "HEAD").unlink()
+
+ token = pause_record.stamp_tree({"resume_needed": True}, root)
+ assert pause_record.tree_is_whole(token, root) == (True, "")
+ token["baselines"][0]["move_targets"] = ["0" * 40]
+ assert pause_record.tree_is_whole(token, root) == (False, "the checkout HEAD is unreadable")
+ assert pause_record.tree_is_whole(readable_at_pause, root) == (False, "the checkout HEAD is unreadable")
+
+
def test_an_update_adopting_an_orphan_never_certifies_the_tree_it_left_torn(tmp_path, monkeypatch):
root = tmp_path / "checkout"
root.mkdir()
diff --git a/tests/scripts/install/test_install_sh_repository_stage.py b/tests/scripts/install/test_install_sh_repository_stage.py
index a5cc90ac878..67fa42de191 100644
--- a/tests/scripts/install/test_install_sh_repository_stage.py
+++ b/tests/scripts/install/test_install_sh_repository_stage.py
@@ -146,11 +146,19 @@ def test_pinned_fresh_clone_publishes_nothing_when_the_pin_fails(tmp_path):
assert not list(tmp_path.glob(".hermes-clone-*"))
-def test_commitless_checkout_is_moved_aside_and_recloned(tmp_path):
[email protected]("damage", ["commitless", "lost_head", "dangling_gitdir_file"])
+def test_unusable_checkout_is_moved_aside_and_recloned(tmp_path, damage):
+ """An interrupted clone, or a .git a killed update left unreadable (the state `hermes update`
+ tells the user to repair by rerunning the installer): moved aside, never deleted, then cloned."""
origin = _origin(tmp_path / "origin")
install = tmp_path / "install"
install.mkdir()
- _git(install, "init", "-q")
+ if damage == "dangling_gitdir_file":
+ (install / ".git").write_text(f"gitdir: {tmp_path / 'gone'}\n")
+ else:
+ _git(install, "init", "-q")
+ if damage == "lost_head":
+ (install / ".git" / "HEAD").unlink()
(install / "keep").write_text("user file")
result = _stage(tmp_path, origin)
assert result.returncode == 0, result.stdout + result.stderr