From 37792c9ec0c8d939a0261486e9d5d4bac7e772c8 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 15 Aug 2026 11:22:22 +1000 Subject: [PATCH] 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 --- internal/worktree/worktree.go | 13 +++++-- internal/worktree/worktree_test.go | 56 ++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 2 deletions(-) diff --git a/internal/worktree/worktree.go b/internal/worktree/worktree.go index 24f348ca1..5d6863a39 100644 --- a/internal/worktree/worktree.go +++ b/internal/worktree/worktree.go @@ -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) } } diff --git a/internal/worktree/worktree_test.go b/internal/worktree/worktree_test.go index 37898e3c3..b788c8bc4 100644 --- a/internal/worktree/worktree_test.go +++ b/internal/worktree/worktree_test.go @@ -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 : a branch named "refs/heads/" 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) {