[fix] Repair orphaned worktree before removal so clean/remove fully clear it (#407)

* [fix] Repair orphaned worktree before removal so clean/remove fully clear it (#405)

removeWorktreeEntry made a one-shot decision from the list-time prunable
snapshot, so an orphaned worktree (directory present, .git deleted
out-of-band) either died with exit 128 (no fallback) or got pruned while
leaving the directory on disk. Heal via `git worktree repair` before
removal so clean/remove/merge fully clear it instead.

git worktree repair's own exit status is unreliable (it can report failure
while having already rewritten the .git linkfile), so success is judged by
whether the follow-up remove works, not repair's reported status.

* [fix] Drop ticket refs and shorten comments added in this PR

No functional change — trims comments this PR introduced to be
self-explanatory without pointing at issue numbers, per review feedback.

* [fix] Respect --force through the orphan-heal path

healAndRemoveOrphan hardcoded force=true, silently discarding real
uncommitted content in an orphaned worktree regardless of the caller's
--force flag. Thread the real force value through instead, and only
fall back to prune when the .git linkfile is still missing after the
retry — a genuinely dirty (but now-healed) worktree surfaces its real
git error rather than being force-deleted or misreported as pruned.

Also wraps the retried remove's error alongside prune's on total
failure, and renames the operations-layer output fields (RemoveResult/
CleanedItem/MergeResult) from Prunable to LeftOnDisk to decouple them
from the input-classification meaning of Prunable elsewhere. The
public --json field names are unaffected.

Author: lugassawan

cmd/clean.go

@@ -299,7 +299,7 @@ func runCleanJSON(ctx context.Context, cmd *cobra.Command, r git.Runner, sp *spi
 	cleaned := make([]output.CleanedItemJSON, 0, len(items))
 	for _, it := range items {
 		cleaned = append(cleaned, output.CleanedItemJSON{
-			Branch: it.Branch, Path: it.Path, Prunable: it.Prunable,
+			Branch: it.Branch, Path: it.Path, Prunable: it.LeftOnDisk,
 			WorktreeRemoved: it.WorktreeRemoved, BranchDeleted: it.BranchDeleted,
 			RemoteDeleted: it.RemoteDeleted, RemoteError: errStr(it.RemoteError),
 			Error: errStr(it.Error),
@@ -494,13 +494,13 @@ func printCleanedItems(cmd *cobra.Command, items []operations.CleanedItem) {
 	for _, item := range items {
 		if !item.WorktreeRemoved {
 			hint := "git worktree remove --force -- " + item.Path
-			if item.Prunable {
+			if item.LeftOnDisk {
 				hint = "git worktree prune"
 			}
 			fmt.Fprintf(cmd.OutOrStdout(), "Failed to remove worktree %s\nTo remove manually: %s\n", item.Branch, hint)
 			continue
 		}
-		if item.Prunable {
+		if item.LeftOnDisk {
 			fmt.Fprintf(cmd.OutOrStdout(), "Cleared stale worktree registration: %s (directory left on disk — remove manually if unneeded)\n", item.Path)
 		} else {
 			fmt.Fprintf(cmd.OutOrStdout(), "Removed worktree: %s\n", item.Path)

cmd/clean_test.go

@@ -868,9 +868,9 @@ func TestPrintCleanedItemsAllBranches(t *testing.T) {
 		// Failure: worktree removal failed
 		{Branch: "feature/fail", Path: "/wt/fail", WorktreeRemoved: false, BranchDeleted: false},
 		// Failure: prunable worktree, removal via prune failed
-		{Branch: "feature/prunable-fail", Path: "/wt/prunable-fail", Prunable: true, WorktreeRemoved: false, BranchDeleted: false},
+		{Branch: "feature/prunable-fail", Path: "/wt/prunable-fail", LeftOnDisk: true, WorktreeRemoved: false, BranchDeleted: false},
 		// Success: prunable worktree recovered via git worktree prune (directory left on disk)
-		{Branch: "feature/prunable-ok", Path: "/wt/prunable-ok", Prunable: true, WorktreeRemoved: true, BranchDeleted: true},
+		{Branch: "feature/prunable-ok", Path: "/wt/prunable-ok", LeftOnDisk: true, WorktreeRemoved: true, BranchDeleted: true},
 	}
 	printCleanedItems(cmd, items)
 	out := buf.String()
@@ -1133,7 +1133,7 @@ func TestCleanMergedJSONForceAllFailedCountStaysZero(t *testing.T) {
 	r := cleanMergedTestRunner(t, "  "+branchDone, worktreeOut)
 	baseRun := r.run
 	r.run = func(args ...string) (string, error) {
-		if len(args) >= 2 && args[0] == cmdWorktreeTest && args[1] == cmdRemove {
+		if len(args) >= 2 && args[0] == cmdWorktreeTest && (args[1] == cmdRemove || args[1] == cmdPrune) {
 			return "", errGitFailed
 		}
 		return baseRun(args...)

cmd/merge.go

@@ -131,7 +131,7 @@ var mergeCmd = &cobra.Command{
 				MergingToMain:   result.MergingToMain,
 				SourceRemoved:   result.SourceRemoved,
 				WorktreeRemoved: result.WorktreeRemoved,
-				SourcePrunable:  result.SourcePrunable,
+				SourcePrunable:  result.SourceLeftOnDisk,
 				RemoveError:     errStr(result.RemoveError),
 				RemoteDeleted:   result.RemoteDeleted,
 				RemoteError:     errStr(result.RemoteError),
@@ -151,7 +151,7 @@ var mergeCmd = &cobra.Command{
 			fmt.Fprintln(cmd.OutOrStdout(), result.RemoveError)
 		} else if result.RemoveError != nil {
 			hint := "git worktree remove --force -- " + result.SourcePath
-			if result.SourcePrunable {
+			if result.SourceLeftOnDisk {
 				hint = "git worktree prune"
 			}
 			fmt.Fprintf(cmd.OutOrStdout(), "Merged successfully but failed to remove worktree: %v\nTo remove manually: %s\n", result.RemoveError, hint)
@@ -172,7 +172,7 @@ var mergeCmd = &cobra.Command{
 // a prunable recovery (git worktree prune — directory left on disk) from a
 // real worktree removal, matching cmd/clean.go and cmd/remove.go.
 func printMergeWorktreeRemoved(cmd *cobra.Command, result operations.MergeResult) {
-	if result.SourcePrunable {
+	if result.SourceLeftOnDisk {
 		fmt.Fprintf(cmd.OutOrStdout(), "Cleared stale worktree registration: %s (directory left on disk — remove manually if unneeded)\n", result.SourcePath)
 		return
 	}

cmd/merge_test.go

@@ -274,6 +274,15 @@ func TestMergeSourceNotFound(t *testing.T) {
 }
 
 func TestMergeRemoveWorktreeFails(t *testing.T) {
+	// A real .git file makes this a genuine (non-orphaned) failure, so it
+	// short-circuits instead of routing through the heal-and-retry path.
+	sourceDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(sourceDir, ".git"), []byte("gitdir: /somewhere/.git/worktrees/login\n"), 0o644); err != nil {
+		t.Fatalf("failed to create .git fixture: %v", err)
+	}
+	worktreeOut := "worktree " + repoPath + "\nHEAD abc123\nbranch refs/heads/main\n\n" +
+		"worktree " + sourceDir + "\nHEAD def456\nbranch refs/heads/feature/login\n"
+
 	cfg := &config.Config{DefaultSource: branchMain, WorktreeDir: defaultRelativeWtDir}
 	r := &mockRunner{
 		run: func(args ...string) (string, error) {
@@ -283,7 +292,7 @@ func TestMergeRemoveWorktreeFails(t *testing.T) {
 			if len(args) >= 2 && args[0] == cmdWorktreeTest && args[1] == cmdRemove {
 				return "", errors.New("locked")
 			}
-			return mergeWorktreeOut, nil
+			return worktreeOut, nil
 		},
 		runInDir: noopRunInDir,
 	}
@@ -305,7 +314,7 @@ func TestMergeRemoveWorktreeFails(t *testing.T) {
 	if !strings.Contains(out, "failed to remove worktree") {
 		t.Errorf("output = %q, want 'failed to remove worktree'", out)
 	}
-	if !strings.Contains(out, "To remove manually: git worktree remove --force -- /wt/feature-login") {
+	if !strings.Contains(out, "To remove manually: git worktree remove --force -- "+sourceDir) {
 		t.Errorf("output = %q, want a path-based 'git worktree remove --force --' hint", out)
 	}
 }
@@ -324,7 +333,7 @@ func TestMergeRemoveWorktreePrunablePruneFails(t *testing.T) {
 			if len(args) >= 2 && args[1] == cmdShowToplevel {
 				return repoPath, nil
 			}
-			if len(args) >= 2 && args[0] == cmdWorktreeTest && args[1] == cmdPrune {
+			if len(args) >= 2 && args[0] == cmdWorktreeTest && (args[1] == cmdRemove || args[1] == cmdPrune) {
 				return "", errors.New("prune failed")
 			}
 			return prunableWorktreeOut, nil
@@ -354,13 +363,9 @@ func TestMergeRemoveWorktreePrunablePruneFails(t *testing.T) {
 	}
 }
 
-// TestMergePrunableSourceSuccessMessage guards a follow-up to #374: once a
-// prunable source's dirty check is skipped, a merge with auto-cleanup can
-// actually succeed and reach the success-path print — which must use the
-// same "Cleared stale worktree registration" wording as clean/remove, not
-// the misleading "Removed worktree" (git worktree prune leaves the
-// directory on disk).
-func TestMergePrunableSourceSuccessMessage(t *testing.T) {
+// TestMergePrunableSourceHealsAndRemoves: repair+remove now heal a prunable
+// source fully, so the message must say "Removed worktree", not "Cleared stale worktree registration".
+func TestMergePrunableSourceHealsAndRemoves(t *testing.T) {
 	prunableWorktreeOut := "worktree /repo\nHEAD abc123\nbranch refs/heads/main\n\n" +
 		"worktree /wt/feature-login\nHEAD def456\nbranch refs/heads/feature/login\nprunable gitdir file points to non-existent location\n"
 
@@ -389,6 +394,53 @@ func TestMergePrunableSourceSuccessMessage(t *testing.T) {
 	cmd.Flags().Bool(flagDelete, false, "")
 	cmd.SetContext(config.WithConfig(context.Background(), cfg))
 
+	err := mergeCmd.RunE(cmd, []string{"login"})
+	if err != nil {
+		t.Fatalf(fatalMergeRunE, err)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "Removed worktree: /wt/feature-login") {
+		t.Errorf("output = %q, want 'Removed worktree' — repair+remove fully cleared the directory", out)
+	}
+	if strings.Contains(out, "Cleared stale worktree registration") {
+		t.Errorf("output = %q, want NOT 'Cleared stale worktree registration' once repair+remove succeed", out)
+	}
+}
+
+// TestMergePrunableSourceFallbackMessage: when repair+remove both still fail,
+// the prune-only fallback leaves the dir on disk, so "Cleared stale worktree registration" still applies.
+func TestMergePrunableSourceFallbackMessage(t *testing.T) {
+	prunableWorktreeOut := "worktree /repo\nHEAD abc123\nbranch refs/heads/main\n\n" +
+		"worktree /wt/feature-login\nHEAD def456\nbranch refs/heads/feature/login\nprunable gitdir file points to non-existent location\n"
+
+	cfg := &config.Config{DefaultSource: branchMain, WorktreeDir: defaultRelativeWtDir}
+	r := &mockRunner{
+		run: func(args ...string) (string, error) {
+			if len(args) >= 2 && args[1] == cmdShowToplevel {
+				return repoPath, nil
+			}
+			if len(args) >= 2 && args[0] == cmdWorktreeTest && args[1] == cmdRemove {
+				return "", errors.New("remove failed")
+			}
+			return prunableWorktreeOut, nil
+		},
+		runInDir: func(_ string, args ...string) (string, error) {
+			if len(args) >= 1 && (args[0] == cmdStatus || args[0] == flagSyncMerge) {
+				return "", nil
+			}
+			return "", nil
+		},
+	}
+	restore := overrideNewRunner(r)
+	defer restore()
+
+	cmd, buf := newTestCmd()
+	cmd.Flags().String(flagInto, "", "")
+	cmd.Flags().Bool(flagNoFF, false, "")
+	cmd.Flags().Bool(flagKeep, false, "")
+	cmd.Flags().Bool(flagDelete, false, "")
+	cmd.SetContext(config.WithConfig(context.Background(), cfg))
+
 	err := mergeCmd.RunE(cmd, []string{"login"})
 	if err != nil {
 		t.Fatalf(fatalMergeRunE, err)
@@ -857,6 +909,15 @@ func TestMergeDryRunJSON(t *testing.T) {
 }
 
 func TestMergeRemoveErrorJSON(t *testing.T) {
+	// A real .git file makes this a genuine (non-orphaned) failure, so it
+	// short-circuits instead of routing through the heal-and-retry path.
+	sourceDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(sourceDir, ".git"), []byte("gitdir: /somewhere/.git/worktrees/login\n"), 0o644); err != nil {
+		t.Fatalf("failed to create .git fixture: %v", err)
+	}
+	worktreeOut := "worktree " + repoPath + "\nHEAD abc123\nbranch refs/heads/main\n\n" +
+		"worktree " + sourceDir + "\nHEAD def456\nbranch refs/heads/feature/login\n"
+
 	cfg := &config.Config{DefaultSource: branchMain, WorktreeDir: defaultRelativeWtDir}
 	r := &mockRunner{
 		run: func(args ...string) (string, error) {
@@ -866,7 +927,7 @@ func TestMergeRemoveErrorJSON(t *testing.T) {
 			if len(args) >= 2 && args[0] == cmdWorktreeTest && args[1] == cmdRemove {
 				return "", errors.New("locked")
 			}
-			return mergeWorktreeOut, nil
+			return worktreeOut, nil
 		},
 		runInDir: noopRunInDir,
 	}

cmd/remove.go

@@ -98,7 +98,7 @@ var removeCmd = &cobra.Command{
 				Task:            result.Task,
 				Branch:          result.Branch,
 				Path:            result.Path,
-				Prunable:        result.Prunable,
+				Prunable:        result.LeftOnDisk,
 				WorktreeRemoved: result.WorktreeRemoved,
 				BranchDeleted:   result.BranchDeleted,
 				KeepBranch:      keepBranch,
@@ -107,7 +107,7 @@ var removeCmd = &cobra.Command{
 			})
 		}
 
-		if result.Prunable {
+		if result.LeftOnDisk {
 			fmt.Fprintf(cmd.OutOrStdout(), "Cleared stale worktree registration: %s (directory left on disk — remove manually if unneeded)\n", result.Path)
 		} else {
 			fmt.Fprintf(cmd.OutOrStdout(), "Removed worktree: %s\n", result.Path)

cmd/remove_test.go

@@ -3,6 +3,8 @@ package cmd
 import (
 	"context"
 	"errors"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -41,21 +43,23 @@ func TestRemoveSuccess(t *testing.T) {
 	}
 }
 
-func TestRemovePrunablePathRunsPrune(t *testing.T) {
+func TestRemovePrunablePathHealsAndRemoves(t *testing.T) {
 	prunableWorktreeOut := "worktree /repo\nHEAD abc123\nbranch refs/heads/main\n\n" +
 		"worktree /wt/feature-login\nHEAD def456\nbranch refs/heads/feature/login\nprunable gitdir file points to non-existent location\n"
 
-	var pruneInvoked, removeInvoked bool
+	var repairInvoked, removeInvoked, pruneInvoked bool
 	r := &mockRunner{
 		run: func(args ...string) (string, error) {
 			cmd := strings.Join(args, " ")
 			switch {
-			case strings.Contains(cmd, "worktree prune"):
-				pruneInvoked = true
+			case strings.Contains(cmd, "worktree repair"):
+				repairInvoked = true
 			case strings.Contains(cmd, "worktree remove"):
 				removeInvoked = true
+			case strings.Contains(cmd, "worktree prune"):
+				pruneInvoked = true
 			}
-			if len(args) > 0 && args[0] == "worktree" && args[1] == "list" {
+			if len(args) > 0 && args[0] == cmdWorktreeTest && args[1] == cmdList {
 				return prunableWorktreeOut, nil
 			}
 			return "", nil
@@ -74,11 +78,51 @@ func TestRemovePrunablePathRunsPrune(t *testing.T) {
 	if err != nil {
 		t.Fatalf("removeCmd.RunE: %v", err)
 	}
-	if !pruneInvoked {
-		t.Error("expected 'git worktree prune' to be invoked for a prunable worktree")
+	if !repairInvoked {
+		t.Error("expected 'git worktree repair' to be invoked for a prunable worktree")
+	}
+	if !removeInvoked {
+		t.Error("expected 'git worktree remove' to be invoked after repair")
+	}
+	if pruneInvoked {
+		t.Error("expected 'git worktree prune' NOT to be invoked when repair+remove succeed")
+	}
+	out := buf.String()
+	if !strings.Contains(out, "Removed worktree") {
+		t.Errorf("output = %q, want 'Removed worktree' — repair+remove fully cleared the directory", out)
+	}
+	if strings.Contains(out, "Cleared stale worktree registration") {
+		t.Errorf("output = %q, want NOT 'Cleared stale worktree registration' once repair+remove succeed", out)
+	}
+}
+
+func TestRemovePrunablePathFallbackMessage(t *testing.T) {
+	prunableWorktreeOut := "worktree /repo\nHEAD abc123\nbranch refs/heads/main\n\n" +
+		"worktree /wt/feature-login\nHEAD def456\nbranch refs/heads/feature/login\nprunable gitdir file points to non-existent location\n"
+
+	r := &mockRunner{
+		run: func(args ...string) (string, error) {
+			if len(args) > 0 && args[0] == cmdWorktreeTest && args[1] == cmdList {
+				return prunableWorktreeOut, nil
+			}
+			if len(args) > 1 && args[0] == "worktree" && args[1] == "remove" {
+				return "", errors.New("remove failed")
+			}
+			return "", nil
+		},
+		runInDir: noopRunInDir,
 	}
-	if removeInvoked {
-		t.Error("expected 'git worktree remove' NOT to be invoked for a prunable worktree")
+	restore := overrideNewRunner(r)
+	defer restore()
+
+	cmd, buf := newTestCmd()
+	cmd.SetContext(config.WithConfig(context.Background(), &config.Config{}))
+	cmd.Flags().Bool(flagKeepBranch, false, "")
+	cmd.Flags().Bool(flagForce, false, "")
+
+	err := removeCmd.RunE(cmd, []string{"login"})
+	if err != nil {
+		t.Fatalf("removeCmd.RunE: %v", err)
 	}
 	out := buf.String()
 	if !strings.Contains(out, "Cleared stale worktree registration") {
@@ -195,12 +239,20 @@ func TestRemoveWorktreeNotFound(t *testing.T) {
 }
 
 func TestRemoveWorktreeFails(t *testing.T) {
+	// A real .git file makes this a genuine (non-orphaned) failure, so it
+	// short-circuits instead of routing through the heal-and-retry path.
+	wtPath := t.TempDir()
+	if err := os.WriteFile(filepath.Join(wtPath, ".git"), []byte("gitdir: /somewhere/.git/worktrees/login\n"), 0o644); err != nil {
+		t.Fatalf("failed to create .git fixture: %v", err)
+	}
+	worktreeOut := "worktree /repo\nHEAD abc123\nbranch refs/heads/main\n\nworktree " + wtPath + "\nHEAD def456\nbranch refs/heads/feature/login\n"
+
 	r := &mockRunner{
 		run: func(args ...string) (string, error) {
 			if len(args) >= 2 && args[0] == cmdWorktreeTest && args[1] == "remove" {
 				return "", errors.New("locked")
 			}
-			return removeWorktreeOut, nil
+			return worktreeOut, nil
 		},
 		runInDir: noopRunInDir,
 	}

internal/git/worktree.go

@@ -63,6 +63,13 @@ func MoveWorktree(ctx context.Context, r Runner, oldPath, newPath string, force
 	return err
 }
 
+// RepairWorktree recreates a missing .git linkfile from the still-present
+// admin back-pointer, so a subsequent RemoveWorktree can fully remove it.
+func RepairWorktree(ctx context.Context, r Runner, path string) error {
+	_, err := r.Run(ctx, cmdWorktree, "repair", "--", path)
+	return err
+}
+
 // ListWorktrees returns all worktrees by parsing `git worktree list --porcelain`.
 func ListWorktrees(ctx context.Context, r Runner) ([]WorktreeEntry, error) {
 	out, err := r.Run(ctx, cmdWorktree, "list", "--porcelain")

internal/git/worktree_test.go

@@ -129,6 +129,34 @@ func TestRemoveWorktreeLeadingDashPath(t *testing.T) {
 	}
 }
 
+func TestRepairWorktree(t *testing.T) {
+	if testing.Short() {
+		t.Skip(skipIntegration)
+	}
+
+	repo := testutil.NewTestRepo(t)
+	r := &git.ExecRunner{Dir: repo}
+
+	wtPath := filepath.Join(filepath.Dir(repo), "wt-to-repair")
+	if err := git.AddWorktree(context.Background(), r, wtPath, "feat/repair-me", "main"); err != nil {
+		t.Fatalf(fatalAddWorktree, err)
+	}
+
+	gitFile := filepath.Join(wtPath, ".git")
+	if err := os.Remove(gitFile); err != nil {
+		t.Fatalf("remove .git file: %v", err)
+	}
+
+	// RepairWorktree's own error is unreliable (git can exit non-zero here
+	// while still rewriting the .git linkfile), so assert on the actual
+	// effect rather than the returned error.
+	_ = git.RepairWorktree(context.Background(), r, wtPath)
+
+	if _, err := os.Stat(gitFile); err != nil {
+		t.Errorf("expected .git file to be recreated after repair, stat err: %v", err)
+	}
+}
+
 func TestListWorktreesPrunableEntry(t *testing.T) {
 	if testing.Short() {
 		t.Skip(skipIntegration)