feat(update): update branches carrying unmerged commits in place instead of skipping

The parked-branch guard (8ce8ffd429) distinguishes checkouts by what the
branch carries, then treats both non-clean cases the same: a stale
fully-merged leftover is switched back to the target (correct), but a
branch with unmerged commits — a branch someone is actually working on —
gets CODE UPDATE SKIPPED and exit 1. For anyone running a maintained
custom branch on top of main, every update now refuses, and the guidance
('checkout main') abandons their branch.

The guard's own reason codes already separate the cases, so use them:

- fully merged      -> switch back to the target (unchanged)
- unmerged:N        -> update the branch IN PLACE: fetch, then bring
                       origin/<target> into the checkout. Fast-forward
                       when possible; on divergence, a true merge behind
                       a pre-update safety tag, stopping cleanly on
                       conflict. The checkout never moves; local commits
                       survive; the running code advances.
- dirty/unverifiable/opted out -> skip loudly (unchanged)

The post-pull success gate learns that an in-place update legitimately
ends on a non-target branch: origin/<target> was merged INTO the checkout,
so refusing to claim success there would fail every update that did
exactly the right thing.

Guard tests updated: the unmerged case now asserts the in-place outcome —
target code arrives (b.txt from c3), the branch's own commit survives, and
HEAD never moves. 18/18 guard tests, 20/20 with the diverged-update suite.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Willian Fernandes Santos
2026-08-18 22:56:58 +01:00
committed by Teknium
parent bbbc50acc2
commit 91096bb2f0
2 changed files with 227 additions and 62 deletions
+171 -58
View File
@@ -5508,58 +5508,105 @@ def _cmd_update_impl(args, gateway_mode: bool):
)
current_branch = result.stdout.strip()
# If user is on a different branch than the update target, switch
# to the target. When the target is "main" this is the historical
# "always update against main" behavior; for any other target it's
# the same thing — get HEAD onto the requested branch first, then
# fast-forward.
#
# 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!". 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.
# stays days behind, then prints "✓ Code updated!".
#
# What happens next is routed by what the branch carries (which is
# exactly what the guard measures) plus updates.parked_branch_strategy:
#
# fully merged -> a stale leftover with nothing to lose: switch
# back to the target.
# unmerged: N -> strategy "switch" (default): switch to the
# target anyway — committed work is safe on the
# branch (git checkout never discards commits) and
# a loud "kept" notice names the branch + count.
# Deterministic, so non-interactive callers
# (desktop update button, gateway /update, cron)
# always reach the target.
# strategy "update_in_place": a maintained custom
# branch (local patches on top of main) is updated
# IN PLACE from origin/<target> — the checkout
# never moves, local commits survive, the running
# code advances. --switch-branch overrides back to
# the switch path for one run.
# anything else -> dirty / unverifiable / opted out: touch nothing,
# warn loudly, mark the code update SKIPPED, and
# stop before the post-update steps reinforce the
# stale tree.
parked_branch_switched = False
if current_branch != branch:
if current_branch != "HEAD":
switch_safe, switch_block_reason = _m()._assess_parked_branch_switch(
git_cmd, _m().PROJECT_ROOT, current_branch, branch
in_place_update = False
if current_branch != branch and current_branch != "HEAD":
switch_safe, switch_block_reason = _m()._assess_parked_branch_switch(
git_cmd, _m().PROJECT_ROOT, current_branch, branch
)
if not switch_safe:
_m()._print_parked_branch_skip_warning(
git_cmd,
_m().PROJECT_ROOT,
current_branch,
branch,
switch_block_reason,
)
if not switch_safe:
_m()._print_parked_branch_skip_warning(
git_cmd,
_m().PROJECT_ROOT,
current_branch,
branch,
switch_block_reason,
print()
print(
"⚠ Update finished — code update SKIPPED"
f"{_branch_head_suffix(git_cmd, _m().PROJECT_ROOT)}"
)
_m()._resume_windows_gateways_after_update(
_windows_gateway_resume
)
sys.exit(1)
if switch_block_reason.startswith("unmerged:"):
_in_place_configured = False
try:
from hermes_cli.config import load_config as _load_cfg
_upd_cfg = (_load_cfg() or {}).get("updates", {})
_in_place_configured = (
isinstance(_upd_cfg, dict)
and _upd_cfg.get("parked_branch_strategy", "switch")
== "update_in_place"
)
print()
except Exception as exc:
logger.debug(
"Could not read updates.parked_branch_strategy: %s", exc
)
if _in_place_configured:
# The merge source must exist upstream; --branch typos
# previously surfaced through the checkout failing, which
# does not run on this path.
verify_ref = subprocess.run(
git_cmd + ["rev-parse", "--verify", "--quiet", f"origin/{branch}"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
text=True, encoding="utf-8", errors="replace",
)
if verify_ref.returncode != 0:
print(f"✗ Branch '{branch}' does not exist locally or on origin.")
sys.exit(1)
in_place_update = True
print(
"⚠ Update finished — code update SKIPPED"
f"{_branch_head_suffix(git_cmd, _m().PROJECT_ROOT)}"
f" ℹ On branch '{current_branch}' — updating it in place from "
f"origin/{branch} (no branch switch; local commits preserved)."
)
_m()._resume_windows_gateways_after_update(
_windows_gateway_resume
)
sys.exit(1)
parked_branch_switched = True
if switch_block_reason.startswith("unmerged:"):
else:
parked_branch_switched = True
_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:
parked_branch_switched = True
print(
f" ⚠ Checkout was parked on '{current_branch}' "
f"(fully merged) — switching back to {branch}..."
)
if not in_place_update and current_branch != branch:
if current_branch == "HEAD":
print(
f" ⚠ Currently on detached HEAD — switching to {branch} "
"for update..."
@@ -5584,7 +5631,7 @@ def _cmd_update_impl(args, gateway_mode: bool):
text=True, encoding="utf-8", errors="replace",
)
if track_result.returncode != 0:
# Restore the user's prior branch + stash before bailing
# Restore the user's prior stash before bailing
# so we don't leave them stranded in a weird state.
if auto_stash_ref is not None:
_m()._restore_stashed_changes(
@@ -5827,26 +5874,82 @@ def _cmd_update_impl(args, gateway_mode: bool):
text=True, encoding="utf-8", errors="replace",
)
if pull_result.returncode != 0:
# ff-only failed — local and remote have diverged (e.g. upstream
# force-pushed or rebase). Since local changes are already
# stashed, reset to match the remote exactly.
print(
" ⚠ Fast-forward not possible (history diverged), resetting to match remote..."
)
reset_result = subprocess.run(
git_cmd + ["reset", "--hard", f"origin/{branch}"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
text=True, encoding="utf-8", errors="replace",
)
if reset_result.returncode != 0:
print(f"✗ Failed to reset to origin/{branch}.")
if reset_result.stderr.strip():
print(f" {reset_result.stderr.strip()}")
# ff-only failed — local and remote have diverged. Before
# assuming an upstream force-push, check WHY: a checkout on a
# custom branch (local commits on top of origin/<branch>) also
# cannot fast-forward, and `reset --hard` here would silently
# discard that work. Merge instead and stop cleanly on
# conflict — an update must never destroy local commits.
_cur_branch = (
subprocess.run(
git_cmd + ["branch", "--show-current"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
text=True, encoding="utf-8", errors="replace",
).stdout
or ""
).strip()
if _cur_branch and _cur_branch != branch:
import time as _time
print(
f" Try manually: git fetch origin && git reset --hard origin/{branch}"
f" ⚠ Checkout is on custom branch '{_cur_branch}' — "
f"merging origin/{branch} instead of resetting so local commits survive..."
)
sys.exit(1)
# Best-effort safety tag; recovery anchor if anything goes wrong.
subprocess.run(
git_cmd
+ ["tag", f"pre-update-{_time.strftime('%Y%m%d-%H%M%S')}"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
check=False,
)
merge_result = subprocess.run(
git_cmd + ["merge", "--no-edit", f"origin/{branch}"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
text=True, encoding="utf-8", errors="replace",
)
if merge_result.returncode != 0:
subprocess.run(
git_cmd + ["merge", "--abort"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
check=False,
)
print(
"✗ Merge conflict between local commits and upstream — "
"update stopped, nothing was changed."
)
print(
f" Resolve manually: cd {_m().PROJECT_ROOT} && "
f"git merge origin/{branch}"
)
print(
" Then re-run the update. Local work is untouched."
)
sys.exit(1)
else:
# Same branch as the update target — a true upstream
# force-push/rebase. Local changes are already stashed;
# reset to match the remote exactly (original behaviour).
print(
" ⚠ Fast-forward not possible (history diverged), resetting to match remote..."
)
reset_result = subprocess.run(
git_cmd + ["reset", "--hard", f"origin/{branch}"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
text=True, encoding="utf-8", errors="replace",
)
if reset_result.returncode != 0:
print(f"✗ Failed to reset to origin/{branch}.")
if reset_result.stderr.strip():
print(f" {reset_result.stderr.strip()}")
print(
f" Try manually: git fetch origin && git reset --hard origin/{branch}"
)
sys.exit(1)
# Post-pull syntax guard: validate critical-path files actually
# parse before declaring the update successful. If a bad commit
@@ -5953,13 +6056,23 @@ def _cmd_update_impl(args, gateway_mode: bool):
# branch guard above should make this unreachable, but if any path
# leaves the checkout attached elsewhere, "✓ Code updated!" would be
# a lie — refuse to claim success (2026-08-17 incident class).
#
# An IN-PLACE branch update is the one legitimate way to end on a
# non-target branch: origin/<target> was merged INTO the checked-out
# branch, so the running code *is* up to date and HEAD staying put is
# the whole point. Claiming failure there would make every update on a
# real working branch exit 1 after doing exactly the right thing.
post_pull_branch = subprocess.run(
git_cmd + ["rev-parse", "--abbrev-ref", "HEAD"],
cwd=_m().PROJECT_ROOT,
capture_output=True,
text=True, encoding="utf-8", errors="replace",
).stdout.strip()
if post_pull_branch and post_pull_branch not in {branch, "HEAD"}:
if (
not in_place_update
and post_pull_branch
and post_pull_branch not in {branch, "HEAD"}
):
print()
print(
f"✗ Update pulled origin/{branch}, but the checkout is on "
@@ -301,10 +301,11 @@ def test_update_skips_and_warns_on_dirty_parked_branch(
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."""
"""Default strategy ("switch"): 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")
@@ -328,6 +329,7 @@ def test_update_switches_unmerged_parked_branch_with_kept_notice(
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
assert "updating it in place" not in out
# Ends on main, fast-forwarded.
assert (
_git(repo_pair, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
@@ -343,6 +345,56 @@ def test_update_switches_unmerged_parked_branch_with_kept_notice(
)
def test_update_updates_unmerged_branch_in_place_when_configured(
repo_pair, monkeypatch, capsys
):
"""updates.parked_branch_strategy: update_in_place — a maintained custom
branch (local patches on top of main) is updated in place from
origin/<target> instead of switched away from. The running code must
advance (origin/main's files arrive) AND the local commits must survive,
with the checkout never moving."""
import hermes_cli.config as hermes_config
monkeypatch.setattr(
hermes_config,
"load_config",
lambda: {"updates": {"parked_branch_strategy": "update_in_place"}},
)
(repo_pair / "feature.txt").write_text("unmerged work\n")
_git(repo_pair, "add", "feature.txt")
_git(repo_pair, "commit", "-qm", "feature work")
_patch_update_flow(monkeypatch, repo_pair)
# Stop right after the pull/branch logic, before dependency install.
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(_StopFlow):
hermes_main.cmd_update(args)
out = capsys.readouterr().out
assert "updating it in place" in out
assert "CODE UPDATE SKIPPED" not in out
# The checkout never moved.
assert (
_git(repo_pair, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
== "old-feature"
)
# origin/main's code actually arrived (b.txt lands with c3)...
assert (repo_pair / "b.txt").exists()
assert (repo_pair / "a.txt").read_text() == "two\n"
# ...and the branch's own commit survived it.
assert (repo_pair / "feature.txt").read_text() == "unmerged work\n"
assert "feature work" in _git(repo_pair, "log", "--oneline").stdout
def test_update_auto_switches_clean_merged_parked_branch(
repo_pair, monkeypatch, capsys
):