fix(worktree): never let doctor reclaim delete the main worktree

[getappz]

Summary

• Incident 2026-07-25: agentflare git doctor --reclaim deleted an entire canonical checkout (.git, all source) plus every linked worktree nested under it (.worktrees/task/*), including two with real uncommitted work. Root cause: reclaim() in crates/flare-git-core/src/doctor.rs treated the main/canonical worktree exactly like any linked worktree -- any HealthFlag it happened to pick up (MissingUpstream, Stale, etc.) made it a std::fs::remove_dir_all target. Because linked worktrees live nested under the main one (.worktrees/<name>), deleting the main worktree cascaded and destroyed them too, bypassing their own individually-correct dirty-check protection.
• git worktree list always lists the main worktree first (documented, stable git behavior) -- tags that lane (LaneHealth::is_main_worktree) and hard-skips it in reclaim() unconditionally, even under --force, matching how real git worktree remove already refuses to ever remove the main worktree.
• Regression test reproduces the exact incident shape in a temp repo: a main worktree naturally flagged MissingUpstream (but clean) plus a dirty linked worktree nested under it; asserts the main worktree, its .git, and the linked worktree all survive reclaim(..., force=false). Verified the test actually catches the bug by temporarily reverting the guard and confirming it fails with exactly the pre-fix symptom.

Follow-ups (filed as item #348, not addressed here)

• is_dirty() did not flag the actual main worktree as dirty in the live incident despite real uncommitted modifications -- couldn't reproduce post-incident since the tree was gone; needs its own investigation.
• snapshot_before(repo_root, ...) (crates/flare-git-core/src/snapshot.rs) writes its pre-destructive safety-net commit as a ref inside repo_root/.git -- for the main-worktree case, that's the exact tree being deleted, so the safety net gives zero protection against the one failure mode it most needs to cover. Worth relocating snapshot storage outside any single lane's own directory.

Test plan

• cargo test -p flare-git-core -- 116 passed, 0 failed
• cargo clippy -p flare-git-core --all-targets --all-features -- -D warnings -- clean
• cargo fmt -- clean
• Confirmed the new regression test fails (reproducing the incident) when the is_main_worktree guard is temporarily removed, and passes with it restored

Summary by CodeRabbit

• Bug Fixes
  • Protected the main worktree from accidental reclamation, even when forced.
  • Preserved nested linked worktrees during cleanup.
  • Improved worktree health reporting by identifying the main worktree explicitly.

[coderabbitai]

📝 Walkthrough

Walkthrough

The doctor scan now marks the canonical worktree in each LaneHealth entry. Reclaim skips that worktree even with force enabled, and a regression test verifies nested linked worktrees are preserved.

Changes

Main worktree protection

Layer / File(s)	Summary
Worktree health marker crates/flare-git-core/src/doctor.rs	LaneHealth records whether a lane is the canonical worktree, and scan populates the field for existing and missing paths.
Reclaim guard and regression test crates/flare-git-core/src/doctor.rs	reclaim skips the canonical worktree, while the regression test verifies that it and a nested linked worktree remain present.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• getappz/agentflare#305: Adds the existing doctor scan/reclaim flow extended by this change.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: preventing doctor reclaim from deleting the main worktree.
Description check	✅ Passed	The description covers the required Summary and Test plan sections and is sufficiently complete, though Notes for reviewers are not explicitly formatted.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch task/348

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (2)

crates/flare-git-core/src/doctor.rs (2)

572-668: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Also cover --force in the regression test.

The doc comment on is_main_worktree and the PR intent both emphasize the main worktree must be protected "regardless of flags or --force", but this test only calls reclaim(&repo.path, &report, false). Since the guard sits before the force/dirty checks, a force=true call would currently pass too, but the explicit "even under --force" guarantee isn't actually exercised by any test.

✅ Suggested additional assertion

         assert!(
             !reclaimed.contains(&main_name),
             "main worktree must never be reported as reclaimed"
         );
+
+        let reclaimed_forced = reclaim(&repo.path, &report, true);
+        assert!(
+            repo.path.exists() && repo.path.join(".git").exists(),
+            "main worktree must survive reclaim even with --force"
+        );
+        assert!(
+            !reclaimed_forced.contains(&main_name),
+            "main worktree must never be reclaimed, even with --force"
+        );
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/flare-git-core/src/doctor.rs` around lines 572 - 668, Extend
reclaim_never_deletes_the_main_worktree_even_when_flagged to exercise reclaim
with force=true, while preserving the existing setup and survival assertions.
Ensure the test explicitly verifies that the main worktree remains present and
is not included in the reclaimed results under --force.

---

271-294: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Consider git worktree remove as defense-in-depth instead of raw remove_dir_all.

Reclaim still deletes linked worktrees via std::fs::remove_dir_all + a follow-up worktree prune, bypassing git's own built-in refusal to remove the main worktree. The new is_main_worktree boolean is now the only safeguard against a repeat of this incident; using git worktree remove [--force] here would give a second, git-native line of defense (and drop the need for the separate prune call), for future lane types or flag combinations that might not correctly set is_main_worktree.

♻️ Sketch of using git's own removal

         let path = Path::new(&lane.path);
         if path.exists() {
             if let Err(e) = crate::snapshot::snapshot_before(
                 repo_root,
                 &format!("doctor reclaim {}", lane.name),
             ) {
                 eprintln!(
                     "doctor: snapshot failed before reclaiming {}: {}",
                     lane.name, e
                 );
                 continue;
             }
-            match std::fs::remove_dir_all(path) {
-                Ok(()) => {
-                    let _ = crate::shell::run_in(repo_root, &["worktree", "prune"]);
-                    reclaimed.push(lane.name.clone());
-                }
-                Err(e) => {
-                    eprintln!("doctor: failed to reclaim '{}': {}", lane.name, e);
-                }
-            }
+            let mut args = vec!["worktree", "remove"];
+            if force {
+                args.push("--force");
+            }
+            args.push(&lane.path);
+            match crate::shell::run_in(repo_root, &args) {
+                Ok(_) => reclaimed.push(lane.name.clone()),
+                Err(e) => eprintln!("doctor: failed to reclaim '{}': {}", lane.name, e),
+            }
         } else {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/flare-git-core/src/doctor.rs` around lines 271 - 294, Replace the raw
std::fs::remove_dir_all and follow-up worktree prune in the reclaim flow with
Git’s worktree removal command, using the appropriate force behavior for
reclaiming lanes. Preserve the existing success handling that records reclaimed
lanes and the failure logging, while relying on git worktree remove to protect
the main worktree; update the surrounding match to handle the command result.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@crates/flare-git-core/src/doctor.rs`:
- Around line 572-668: Extend
reclaim_never_deletes_the_main_worktree_even_when_flagged to exercise reclaim
with force=true, while preserving the existing setup and survival assertions.
Ensure the test explicitly verifies that the main worktree remains present and
is not included in the reclaimed results under --force.
- Around line 271-294: Replace the raw std::fs::remove_dir_all and follow-up
worktree prune in the reclaim flow with Git’s worktree removal command, using
the appropriate force behavior for reclaiming lanes. Preserve the existing
success handling that records reclaimed lanes and the failure logging, while
relying on git worktree remove to protect the main worktree; update the
surrounding match to handle the command result.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6845df32-fb09-46f0-a15c-40aefde183f3

📥 Commits

Reviewing files that changed from the base of the PR and between 7fadab2 and 76c97ad.

📒 Files selected for processing (1)

• crates/flare-git-core/src/doctor.rs