fix(worktree): force checkout so retry recovers from a dirty worktree

refresh checked out the task branch without Force before hard-resetting
to base. A prior attempt's leftover uncommitted changes -- a killed
container, or a stage that edits files before ever reaching a commit --
made go-git's default MergeReset checkout refuse to reconcile them, even
with HEAD already on the correct branch and the target commit unmoved.
The fallback then made it worse: any checkout failure was assumed to
mean the branch didn't exist yet, so it retried with Create: true, which
failed with a much more confusing error since the branch did exist --
"a branch named ... already exists" -- masking the real cause and
parking the retry with the same unhelpful message every time.

Reproduced directly against a live deployment's actual broken worktree
(modified tracked file, untracked file, branch already checked out) and
confirmed retry then succeeds and correctly restores to base.

Force is safe unconditionally here: refresh hard-resets to base a few
lines later regardless of what checkout leaves behind.

Closes #523
This commit is contained in:
sam committed 2026-08-15 11:22:22 +10:00
1 parent d83f5a9be3
commit 05944b6fd3
2 files changed
+67 -2

No files matched your search

+11 -2
View File
@@ -164,10 +164,19 @@ func (m *Manager) refresh(ctx context.Context, dir, base, branch string) error {
if err != nil {
return fmt.Errorf("open worktree: %w", err)
}
// Force discards whatever the working tree looks like right now: an
// interrupted prior attempt (killed container, a stage that edits
// files before ever reaching commit) can leave local modifications
// that make go-git's default MergeReset refuse to reconcile them, even
// onto a commit HEAD is already on. That refusal used to surface as
// "branch already exists" from the fallback below, which mis-assumed
// any checkout failure meant the branch didn't exist yet. Force is
// safe here regardless of cause: the hard reset to base a few lines
// down is about to discard the working tree anyway.
ref := plumbing.NewBranchReferenceName(branch)
if err := wt.Checkout(&git.CheckoutOptions{Branch: ref}); err != nil {
if err := wt.Checkout(&git.CheckoutOptions{Branch: ref, Force: true}); err != nil {
// The branch does not exist yet in this worktree.
if err := wt.Checkout(&git.CheckoutOptions{Branch: ref, Create: true}); err != nil {
if err := wt.Checkout(&git.CheckoutOptions{Branch: ref, Create: true, Force: true}); err != nil {
return fmt.Errorf("checkout branch %s: %w", branch, err)
}
}
+56
View File
@@ -215,6 +215,62 @@ func TestPrepareIsIdempotent(t *testing.T) {
}
}
// TestPrepareRecoversFromADirtyWorktreeOnRetry reproduces a real retry
// failure seen in production: a task that got interrupted mid-stage (killed
// container, or a stage that edits files before ever reaching commit)
// leaves uncommitted local changes -- a modified tracked file plus an
// untracked one -- sitting in the worktree. HEAD is already on the correct
// branch (this is not the "no sentinel" case above). refresh's checkout,
// without Force, resets in git's MergeReset mode, which can fail to
// reconcile a working tree that differs from HEAD even when the target
// commit hasn't moved -- and did fail here with
// `checkout branch <branch>: a branch named "refs/heads/<branch>" already
// exists`, since the fallback that mis-assumes "checkout failed means the
// branch doesn't exist yet" then collides with the branch that, in fact,
// already exists. Retry must recover from this on its own; a worktree that
// refresh is about to hard-reset to base has no reason to fail here at all.
func TestPrepareRecoversFromADirtyWorktreeOnRetry(t *testing.T) {
ctx := context.Background()
host := newLocalRemote(t, "acme", "todo")
m := newManager(t, host)
dir, branch, err := m.Prepare(ctx, "acme", "todo", testBase, 9, "fix: retry robustness", "", "bug")
if err != nil {
t.Fatalf("first Prepare() error = %v", err)
}
// Simulate an interrupted attempt: a tracked file edited but never
// committed, plus a new file the agent created and never added.
if err := os.WriteFile(filepath.Join(dir, "README.md"), []byte("seed\nedited, uncommitted\n"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "scratch.txt"), []byte("uncommitted new file\n"), 0o600); err != nil {
t.Fatal(err)
}
dir2, branch2, err := m.Prepare(ctx, "acme", "todo", testBase, 9, "fix: retry robustness", "", "bug")
if err != nil {
t.Fatalf("retry Prepare() on a dirty worktree error = %v, want recovery", err)
}
if dir2 != dir || branch2 != branch {
t.Errorf("retry Prepare() = (%q, %q), want the same (%q, %q)", dir2, branch2, dir, branch)
}
// refresh hard-resets to base immediately after checkout succeeds, so
// the tracked file's uncommitted edit must be gone -- restored to
// base, not merged in. (An untracked leftover like scratch.txt is real
// git's job for `git clean`, not `reset --hard`, and is harmless here:
// it doesn't block the retry, which is the only thing this test cares
// about.)
content, err := os.ReadFile(filepath.Join(dir, "README.md"))
if err != nil {
t.Fatal(err)
}
if string(content) != "seed\n" {
t.Errorf("README.md = %q, want the base commit's content restored", content)
}
}
// An interrupted clone leaves a directory with no sentinel. Prepare must
// discard it rather than trying to reuse a half-built worktree.
func TestPrepareDiscardsDirectoryWithoutSentinel(t *testing.T) {