From bbbc50acc23694ba1d356f467f358da3244e93de Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Fri, 21 Aug 2026 13:41:25 -0700 Subject: [PATCH] fix: hermes update no longer strands non-interactive updates on a parked branch with unmerged commits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A clean checkout parked on a feature branch now always switches to the update target. Unmerged commits are safe on the branch (git checkout never discards committed work) and get a loud 'kept' notice naming the branch, count, and the checkout command to resume the work. Previously the update hard-skipped with exit 1 — a dead end for the desktop update button, gateway /update, and cron, which have no way to resolve a skip. Dirty trees (uncommitted changes) still skip loudly, and the updates.auto_switch_parked_branch: false opt-out still pins the branch. --- hermes_cli/config_defaults.py | 17 ++- hermes_cli/main.py | 1 + hermes_cli/update_cmd.py | 105 +++++++++++++----- .../test_update_parked_branch_guard.py | 60 ++++++++-- website/docs/getting-started/updating.md | 7 +- 5 files changed, 145 insertions(+), 45 deletions(-) diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py index f0d96d9e0d..d47082eb12 100644 --- a/hermes_cli/config_defaults.py +++ b/hermes_cli/config_defaults.py @@ -3253,12 +3253,17 @@ DEFAULT_CONFIG = { "non_interactive_local_changes": "stash", # When `hermes update` finds the source checkout parked on a feature # branch (left behind by tooling or a manual checkout), switch back - # to the update target automatically — but only when the branch is - # clean and every commit on it is already merged into the target. - # When it is not safe, the code update is SKIPPED with a loud - # warning instead of pretending success (2026-08-17 incident: - # "✓ Code updated!" printed while the checkout stayed days behind - # main on a stale branch). Set false to never auto-switch. + # to the update target automatically whenever the working tree is + # clean. Committed-but-unmerged work is safe — `git checkout` never + # discards commits; the branch keeps them and the update prints a + # loud notice naming the branch and count. This keeps non- + # interactive updates (desktop update button, gateway /update, + # cron) working: they have no way to resolve a skip. Only a DIRTY + # tree (uncommitted changes) blocks the switch — the code update is + # then SKIPPED with a loud warning instead of pretending success + # (2026-08-17 incident: "✓ Code updated!" printed while the + # checkout stayed days behind main on a stale branch). Set false to + # never auto-switch. "auto_switch_parked_branch": True, # Refresh an already-installed cua-driver during `hermes update`. # The refresh is best-effort and macOS-only. Turn this off if the diff --git a/hermes_cli/main.py b/hermes_cli/main.py index 9f5e1ec934..448261c6c2 100644 --- a/hermes_cli/main.py +++ b/hermes_cli/main.py @@ -4902,6 +4902,7 @@ _LAZY_COMMAND_EXPORTS = { "_print_curator_first_run_notice", "_print_curator_recent_run_notice", "_print_fts_optimize_available_notice", + "_print_parked_branch_kept_notice", "_print_parked_branch_skip_warning", "_print_stash_cleanup_guidance", "_print_update_completion", diff --git a/hermes_cli/update_cmd.py b/hermes_cli/update_cmd.py index f7a0239298..cb24f093f8 100644 --- a/hermes_cli/update_cmd.py +++ b/hermes_cli/update_cmd.py @@ -1004,14 +1004,23 @@ def _assess_parked_branch_switch( autostashed, ran its post-update steps and printed "✓ Code updated!" while the running code stayed days behind main. The guard's contract: - - safe (True, "") only when the working tree + index are clean AND every - commit on the parked branch is already contained in - ``origin/`` (``git cherry`` reports no ``+`` lines). - - anything else — dirty tree, unmerged commits, git errors, or the - ``updates.auto_switch_parked_branch: false`` config opt-out — returns - (False, ) and the caller must NOT touch the branch. + - (True, "") when the working tree + index are clean AND every commit on + the parked branch is already contained in ``origin/`` + (``git cherry`` reports no ``+`` lines). + - (True, "unmerged:") when the tree is clean but the branch has + commits not yet in the target. Switching is safe — ``git checkout`` + never discards committed work and the branch keeps the commits — but + the caller must print a LOUD notice naming the branch and count so the + work is not forgotten. This is what non-interactive callers (desktop + update button, gateway /update, cron) rely on: they have no way to + resolve a skip, so a clean checkout must always reach the target. + - (False, ) — dirty tree, git errors, or the + ``updates.auto_switch_parked_branch: false`` config opt-out — and the + caller must NOT touch the branch. A dirty tree is the one genuinely + unsafe case: uncommitted work would have to ride an autostash across + branches, which is how the 2026-08-17 incident started. - Reasons: "disabled", "dirty", "unmerged:", "unverifiable". + Block reasons: "disabled", "dirty", "unverifiable". """ try: from hermes_cli.config import load_config @@ -1047,7 +1056,10 @@ def _assess_parked_branch_switch( line for line in cherry.stdout.splitlines() if line.startswith("+") ] if unmerged: - return False, f"unmerged:{len(unmerged)}" + # Clean tree: switching is safe (checkout keeps the commits on the + # branch). The reason string tells the caller to print the loud + # "branch kept with N unmerged commit(s)" notice. + return True, f"unmerged:{len(unmerged)}" return True, "" @@ -1074,12 +1086,6 @@ def _print_parked_branch_skip_warning( if reason == "dirty": why = "the working tree has uncommitted changes" - elif reason.startswith("unmerged:"): - count = reason.split(":", 1)[1] - why = ( - f"the branch has {count} commit(s) not merged into " - f"origin/{target_branch}" - ) elif reason == "disabled": why = "updates.auto_switch_parked_branch is set to false in config.yaml" else: @@ -1109,6 +1115,35 @@ def _print_parked_branch_skip_warning( print(bar) +def _print_parked_branch_kept_notice( + current_branch: str, target_branch: str, unmerged_count: str +) -> None: + """LOUD notice printed when a clean parked branch with unmerged commits + is auto-switched back to the update target. + + Non-interactive callers (desktop update button, gateway /update, cron) + cannot resolve a skip, so a clean checkout always proceeds to the + target — but the unmerged work must be impossible to miss. The commits + are untouched: ``git checkout`` never discards committed work; the + branch keeps them until the user returns. + """ + bar = "=" * 68 + print() + print(bar) + print( + f"⚠ Checkout was parked on '{current_branch}' with " + f"{unmerged_count} commit(s) not merged into origin/{target_branch}." + ) + print( + f" Switching to {target_branch} so the update can proceed — your " + f"commit(s) are safe on '{current_branch}'." + ) + print() + print(" To pick the work back up later:") + print(f" git checkout {current_branch}") + print(bar) + + def _print_update_completion(message: str) -> None: """Print an update outcome plus, when the dashboard launched this run with an action id, a terminal receipt line the Desktop can match after @@ -5482,10 +5517,13 @@ def _cmd_update_impl(args, gateway_mode: bool): # Parked-branch guard (2026-08-17 live incident): the checkout can be # left parked on a stale feature branch by earlier tooling. Blindly # stash-switch-pull-switch-back "updates" main while the running code - # stays days behind, then prints "✓ Code updated!". Only auto-switch - # when the parked branch is clean AND fully merged into the target; - # otherwise warn loudly, mark the code update SKIPPED, and stop - # before the post-update steps reinforce the stale tree. + # stays days behind, then prints "✓ Code updated!". A CLEAN parked + # branch always switches to the target (committed work is safe on + # the branch; unmerged commits get a loud "kept" notice) — this is + # what non-interactive callers (desktop update button, gateway + # /update, cron) rely on. Only a dirty tree / opt-out / git failure + # warns loudly, marks the code update SKIPPED, and stops before the + # post-update steps reinforce the stale tree. parked_branch_switched = False if current_branch != branch: if current_branch != "HEAD": @@ -5510,10 +5548,17 @@ def _cmd_update_impl(args, gateway_mode: bool): ) sys.exit(1) parked_branch_switched = True - print( - f" ⚠ Checkout was parked on '{current_branch}' " - f"(fully merged) — switching back to {branch}..." - ) + if switch_block_reason.startswith("unmerged:"): + _m()._print_parked_branch_kept_notice( + current_branch, + branch, + switch_block_reason.split(":", 1)[1], + ) + else: + print( + f" ⚠ Checkout was parked on '{current_branch}' " + f"(fully merged) — switching back to {branch}..." + ) else: print( f" ⚠ Currently on detached HEAD — switching to {branch} " @@ -5624,10 +5669,18 @@ def _cmd_update_impl(args, gateway_mode: bool): input_fn=gw_input_fn, ) if parked_branch_switched: - print( - f" ✓ Checkout was parked on '{current_branch}' (fully " - f"merged) — switched back to {branch}." - ) + if switch_block_reason.startswith("unmerged:"): + _count = switch_block_reason.split(":", 1)[1] + print( + f" ✓ Checkout was parked on '{current_branch}' — " + f"switched back to {branch}; {_count} unmerged " + f"commit(s) kept on '{current_branch}'." + ) + else: + print( + f" ✓ Checkout was parked on '{current_branch}' (fully " + f"merged) — switched back to {branch}." + ) elif current_branch not in {branch, "HEAD"}: subprocess.run( git_cmd + ["checkout", current_branch], diff --git a/tests/hermes_cli/test_update_parked_branch_guard.py b/tests/hermes_cli/test_update_parked_branch_guard.py index f4670643e8..75318b3385 100644 --- a/tests/hermes_cli/test_update_parked_branch_guard.py +++ b/tests/hermes_cli/test_update_parked_branch_guard.py @@ -118,8 +118,12 @@ def test_untracked_file_blocks_auto_switch(repo_pair): assert reason == "dirty" -def test_unmerged_commits_block_auto_switch(repo_pair): - """Commits on the parked branch not contained in origin/main → skip.""" +def test_unmerged_commits_switch_with_kept_notice(repo_pair): + """Commits on the parked branch not in origin/main: still safe to switch + (checkout keeps them on the branch) — reason carries the count so the + caller prints the loud 'kept' notice. Non-interactive callers (desktop + update button, gateway /update, cron) depend on this: they cannot + resolve a skip.""" (repo_pair / "feature.txt").write_text("unmerged work\n") _git(repo_pair, "add", "feature.txt") _git(repo_pair, "commit", "-qm", "feature work") @@ -127,7 +131,7 @@ def test_unmerged_commits_block_auto_switch(repo_pair): safe, reason = update_cmd._assess_parked_branch_switch( GIT, repo_pair, "old-feature", "main" ) - assert safe is False + assert safe is True assert reason == "unmerged:1" @@ -175,7 +179,7 @@ def test_missing_origin_ref_is_unverifiable(repo_pair): def test_skip_warning_names_branch_behind_count_and_commands(repo_pair, capsys): update_cmd._print_parked_branch_skip_warning( - GIT, repo_pair, "old-feature", "main", "unmerged:1" + GIT, repo_pair, "old-feature", "main", "dirty" ) out = capsys.readouterr().out assert "CODE UPDATE SKIPPED" in out @@ -192,6 +196,16 @@ def test_skip_warning_dirty_reason(repo_pair, capsys): assert "uncommitted changes" in out +def test_kept_notice_names_branch_count_and_recovery(capsys): + update_cmd._print_parked_branch_kept_notice("old-feature", "main", "3") + out = capsys.readouterr().out + assert "parked on 'old-feature'" in out + assert "3 commit(s) not merged into origin/main" in out + assert "safe on 'old-feature'" in out + assert "git checkout old-feature" in out + assert "CODE UPDATE SKIPPED" not in out + + # --------------------------------------------------------------------------- # Summary branch/HEAD visibility # --------------------------------------------------------------------------- @@ -284,24 +298,48 @@ def test_update_skips_and_warns_on_dirty_parked_branch( assert stashes == "" -def test_update_skips_on_unmerged_parked_branch(repo_pair, monkeypatch, capsys): +def test_update_switches_unmerged_parked_branch_with_kept_notice( + repo_pair, monkeypatch, capsys +): + """Clean tree + unmerged commits: the update proceeds (non-interactive + callers like the desktop update button cannot resolve a skip), prints + the loud 'kept' notice, ends on main fast-forwarded to origin/main, and + the commits stay on the parked branch untouched.""" (repo_pair / "feature.txt").write_text("unmerged work\n") _git(repo_pair, "add", "feature.txt") _git(repo_pair, "commit", "-qm", "feature work") + feature_sha = _git(repo_pair, "rev-parse", "old-feature").stdout.strip() _patch_update_flow(monkeypatch, repo_pair) + + class _StopFlow(Exception): + pass + + monkeypatch.setattr( + hermes_main, + "_abort_dependency_sync_if_self_locked", + lambda *a, **k: (_ for _ in ()).throw(_StopFlow()), + ) args = SimpleNamespace(branch=None, yes=False, force=False, force_venv=False) - with pytest.raises(SystemExit) as exc_info: + with pytest.raises(_StopFlow): hermes_main.cmd_update(args) - assert exc_info.value.code == 1 out = capsys.readouterr().out - assert "CODE UPDATE SKIPPED" in out - assert "1 commit(s) not merged" in out - assert "✓ Code updated!" not in out + assert "1 commit(s) not merged into origin/main" in out + assert "safe on 'old-feature'" in out + assert "CODE UPDATE SKIPPED" not in out + # Ends on main, fast-forwarded. assert ( _git(repo_pair, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip() - == "old-feature" + == "main" + ) + head = _git(repo_pair, "rev-parse", "HEAD").stdout.strip() + remote = _git(repo_pair, "rev-parse", "origin/main").stdout.strip() + assert head == remote + # The unmerged commit is still exactly where it was, on the branch. + assert ( + _git(repo_pair, "rev-parse", "old-feature").stdout.strip() + == feature_sha ) diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md index 0353e9540e..35604ce5eb 100644 --- a/website/docs/getting-started/updating.md +++ b/website/docs/getting-started/updating.md @@ -44,9 +44,12 @@ If your local checkout is on a different branch, Hermes auto-stashes any uncommi ### Checkout parked on a feature branch -If the source checkout was left sitting on a feature branch (by tooling, a worktree experiment, or a manual checkout), `hermes update` only switches it back to the update target automatically when that is provably safe: the working tree is clean **and** every commit on the parked branch is already contained in `origin/main` (`git cherry` reports nothing unmerged). In that case the update says so — `Checkout was parked on '' (fully merged) — switched back to main` — and stays on `main` afterwards. +If the source checkout was left sitting on a feature branch (by tooling, a worktree experiment, or a manual checkout), `hermes update` switches it back to the update target automatically whenever the working tree is clean: -When the parked branch has uncommitted changes or unmerged commits, Hermes does **not** touch it. The code update is marked **SKIPPED** with a loud warning naming the branch, how far behind `origin/main` it is, and the exact commands to resolve — instead of pretending the update succeeded. The completion line always shows the actual branch and HEAD (`✓ Update complete! [main @ 30fcf9580]`) so drift is visible at a glance. Set `updates.auto_switch_parked_branch: false` in `config.yaml` to disable the auto-switch entirely (the skip warning still fires). +- **Branch fully merged** (every commit already contained in `origin/main` — `git cherry` reports nothing unmerged): the update says so — `Checkout was parked on '' (fully merged) — switched back to main` — and stays on `main` afterwards. +- **Branch has unmerged commits** but the tree is clean: the update still switches to `main` so the update can proceed — this is what non-interactive callers (the desktop update button, gateway `/update`, cron) rely on, since they have no way to resolve a skip. Your commits are untouched: `git checkout` never discards committed work, and the update prints a loud notice naming the branch and commit count, plus the `git checkout ` command to pick the work back up later. + +When the parked branch has **uncommitted changes** (dirty tree), Hermes does **not** touch it. The code update is marked **SKIPPED** with a loud warning naming the branch, how far behind `origin/main` it is, and the exact commands to resolve — instead of pretending the update succeeded. The completion line always shows the actual branch and HEAD (`✓ Update complete! [main @ 30fcf9580]`) so drift is visible at a glance. Set `updates.auto_switch_parked_branch: false` in `config.yaml` to disable the auto-switch entirely (the skip warning still fires). ### Local changes on non-interactive updates