fix: hermes update no longer strands non-interactive updates on a parked branch with unmerged commits

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.
This commit is contained in:
Teknium
2026-08-21 13:41:25 -07:00
parent 2dcb623956
commit bbbc50acc2
5 changed files with 145 additions and 45 deletions
+11 -6
View File
@@ -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
+1
View File
@@ -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",
+79 -26
View File
@@ -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/<target_branch>`` (``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, <reason>) 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/<target_branch>``
(``git cherry`` reports no ``+`` lines).
- (True, "unmerged:<count>") 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, <reason>) — 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:<count>", "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],
@@ -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
)
+5 -2
View File
@@ -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 '<branch>' (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 '<branch>' (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 <branch>` 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