Skip to content

fix(git): keep HEAD on a live branch while renaming a worktree branch - #1088

Draft
agent-manager-bots[bot] wants to merge 1 commit into
mainfrom
fix/rename-branch-head-race
Draft

agent-manager-bots[bot] wants to merge 1 commit into
mainfrom
fix/rename-branch-head-race

Conversation

@agent-manager-bots

Copy link
Copy Markdown
Contributor

TestRenameWorktreeBranchLetsAgentKeepWorking failed on main in run 43958080305 (test-linux, merge of #1063) with fatal: ambiguous argument 'HEAD': unknown revision from the helper agent, and passed on the next main run. The failure is real product behavior that the test catches, so this fixes the rename.

Root cause

RenameWorktreeBranch ran git branch -m old new. Git does that in steps: it deletes refs/heads/old, writes refs/heads/new, then repoints each worktree HEAD. Between the first and last step the worktree HEAD names a branch that does not exist. Any git command running in that worktree at that moment (the test's agent loop runs git status and git rev-parse HEAD, a real agent does the same) fails. The window is short, so it shows up roughly once in a few hundred CI runs. TestPendingRenameLetsAgentKeepWorking in internal/execution goes through the same function with the same agent loop, so it shares this cause.

Fix

The rename now:

  1. copies the branch with git branch -c, which carries the branch config and reflog like -m does
  2. locks the old ref at the copied tip (git update-ref --stdin with verify and prepare)
  3. points the worktree HEAD at the copy with git symbolic-ref
  4. releases the lock and deletes the old ref only at that tip, plus its branch.<old>.* config

HEAD names an existing branch at every step. A commit that moves the old ref before the lock makes the rename stop and drop the copy, and the agent's commit stays on its branch. Product behavior is the same: a display-name change still renames the worktree branch.

A commit running at the exact moment of the rename can still be refused with git's usual cannot lock ref, as it could with git branch -m. The rename is refused the same way and reported to the session.

Tests

New TestRenameWorktreeBranchNeverLeavesHeadOnAMissingBranch installs a reference-transaction hook that reads the worktree HEAD after every ref change during a rename. It fails 50/50 on main and passes 50/50 with this change. It also checks the branch config moved and the old config is gone.

Stress, same commands before (main at d8d389f) and after:

Command main this PR
go test -race -count=200 -run '^TestRenameWorktreeBranchLetsAgentKeepWorking$' ./internal/git 0/200 failed 0/200 failed
4 of go test -race -count=100 -run <same> ./internal/git in parallel 0/400 0/400
go test -race -count=100 -cpu=1,4 -run <same> ./internal/git 0/200 0/200
go test -race -count=100 -run '^TestPendingRenameLetsAgentKeepWorking$' ./internal/execution 0/100 0/100
new hook test, -count=50 50/50 failed 0/50 failed
local amplified run: 500 renames back and forth while 4 loops run git rev-parse --abbrev-ref HEAD in the worktree, 5 times 3006 of 48527 reads failed 0 of 102103 reads failed
local amplified run: 300 renames while a loop commits in the worktree, 3 times commits lost from HEAD in 3/3 none lost in 3/3

The plain test loop never hit the window locally, which matches its CI rate. The two amplified runs were throwaway tests and are not part of this PR. The rename was also checked on a reftable repo.

go build ./..., go vet ./... and go test -race -p 4 ./internal/git ./internal/sessioncmd ./internal/execution ./internal/ui/dialogs/apply pass.

Not covered: the Windows Permission denied on .git/config seen in run 42834593853 comes from config rewrites and is a separate issue.

git branch -m deletes the old ref before it repoints the worktree HEAD.
A git command running in the worktree in that gap reads HEAD as a
missing branch and fails with "ambiguous argument 'HEAD'". That is what
TestRenameWorktreeBranchLetsAgentKeepWorking hit on main CI run
43958080305.

The rename now copies the branch (config and reflog come along), locks
the old ref at the copied tip, points HEAD at the copy, then deletes the
old ref at that tip. HEAD names an existing branch at every step. A
commit that moves the old ref before the lock makes the rename stop and
drop the copy, so no commit is left behind on the old branch.

A reference-transaction hook test checks HEAD after every ref change of
a rename. It fails on the old code and passes now.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant