fix(checkup): don't fail setup when a stale checkup/issue-* branch already exists (#1338)

[sohni-tagirisa]

Summary

Fixes #1338. pdd checkup aborted during worktree setup when a stale checkup/issue-N branch already existed. _setup_worktree (pdd/agentic_checkup_orchestrator.py) deleted the branch but ignored the result of _delete_branch and set has_branch = False unconditionally — so when the delete failed, git worktree add -b failed with "a branch named ... already exists" and the whole checkup died.

Root cause

A crashed or out-of-band-cleaned-up prior run can leave checkup/issue-N registered to a worktree directory that no longer exists. git branch -D then refuses:

error: Cannot delete branch 'checkup/issue-7' checked out at '<gone path>'

That failure was swallowed, and the subsequent git worktree add -b:

fatal: a branch named 'checkup/issue-7' already exists
→ _setup_worktree returns (None, "Failed to create worktree: ...")

Fix

• Add _prune_worktrees and call git worktree prune before handling the branch, so a branch registered to a removed worktree dir can be deleted/recreated.
• Honor _delete_branch's return value; only clear has_branch on success.
• If the branch is still undeletable after pruning (genuinely checked out in a live worktree), return a clear, actionable error naming the conflicting worktree instead of the cryptic Failed to create worktree.

How I tested it

I reproduced the failure against the real _setup_worktree with a temp git repo (branch registered to a worktree dir then rmtree'd) — pre-fix it returned (None, "Failed to create worktree: ... a branch named 'checkup/issue-7' already exists"). After the fix:

scenario	before	after
stale branch (worktree dir removed)	❌ Failed to create worktree	✅ branch reset, fresh worktree created
plain leftover branch (not checked out)	✅	✅ (unchanged)
branch checked out in a live worktree	❌ cryptic "Failed to create worktree"	✅ clear error: which worktree to remove

Pinned by TestSetupWorktreeStaleBranch (3 real-git tests). Full tests/test_agentic_checkup_orchestrator.py + tests/test_checkup_pr_mode.py → 324 passed; git diff --check origin/main clean.

Note on pdd fix: this sandbox has no LLM API key, so the LLM-driven pdd fix autonomous flow can't run here. I diagnosed the failure by reproducing it against the real _setup_worktree, fixed the code directly, and added a regression test — the same end state pdd fix would have produced.

🤖 Generated with Claude Code

[Serhan-Asad]

/heal

[Serhan-Asad]

The failing required check is auto-heal, not the unit tests or CodeQL.

The /heal run reached Cloud Build 9f37c7e2-e0c1-4553-893b-2ff1359bf524, and the failure is:

metadata staging verification failed: missing .pdd/meta/agentic_checkup_orchestrator_python.json

pdd-cli generated metadata for agentic_checkup_orchestrator, but .gitignore ignores .pdd/meta/*.json unless each file is explicitly whitelisted, so the generated metadata file was skipped during staging. To unblock this PR, add/whitelist .pdd/meta/agentic_checkup_orchestrator_python.json or adjust the auto-heal metadata staging rule.

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[RyanTanuki]

/gcbrun

[RyanTanuki]

/heal

[RyanTanuki]

/heal

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[gltanaka]

Do not merge as-is.

The stale removed-worktree failure is real on main, so some fix is needed. I reproduced the base failure with _setup_worktree: a removed registered worktree leaves checkup/issue-* undeletable, then git worktree add -b fails with fatal: a branch named ... already exists.

The blocker is the PR-mode fallback. After _delete_branch fails in _setup_pr_worktree, the code keeps has_branch=True and later intends to recover with git worktree add --force, but before that it still runs:

git fetch <remote> pull/<pr>/head:<branch_name> --force

If <branch_name> is still checked out in a live worktree, Git refuses to update it:

fatal: refusing to fetch into branch 'refs/heads/checkup/pr-...' checked out at '...'

I reproduced this against this PR's actual _setup_pr_worktree; it returns Failed to fetch PR #77... before it ever reaches the forced worktree-add fallback. The test at tests/test_checkup_pr_mode.py mocks subprocess.run and returns success for the fetch path, so it cannot catch this real Git behavior.

Required changes:

1. Fix the PR-mode branch-deletion-failure path. After pruning, if the PR branch is still checked out in another live worktree, do not fetch into that checked-out branch. Either return a clear actionable error for the live-worktree case, or fetch to an independent temp ref / unique branch / detached worktree and create the checkup worktree from that safe ref.
2. Add a real-git regression for _setup_pr_worktree that creates a local refs/pull/<n>/head, leaves the scoped checkup/pr-* branch checked out in a live worktree, and exercises the fetch step. The current mock-only test is insufficient.
3. Reconcile this PR with the duplicate stale-checkup-branch work in #1281/#1299. If #1339 is the PR to keep, keep the diff focused and remove unrelated generated example/architecture churn unless it is required by auto-heal.

Verdict: the underlying bug needs a fix, but #1339 should not merge in its current form.

[Serhan-Asad]

/heal

[sohni-tagirisa]

Tuesday, Jun 2nd

[Serhan-Asad]

/heal

[gltanaka]

Still do not merge as-is.

I re-tested the updated head (6fb36f40183f0437539fd7201f5947d572f500e1). The PR-mode blocker from the previous review is still present in pdd/agentic_checkup_orchestrator.py: after _delete_branch fails, _setup_pr_worktree still runs the fetch into the checked-out local branch before the forced worktree-add fallback can execute:

git fetch <remote> pull/<pr>/head:<branch_name> --force

With a real local repo and a real local refs/pull/77/head, leaving the scoped checkup/pr-* branch checked out in another live worktree still returns:

Failed to fetch PR #77 ... fatal: refusing to fetch into branch 'refs/heads/checkup/pr-77-...' checked out at '.../live-wt'

So the intended git worktree add --force recovery path is unreachable for the live-worktree PR-mode case.

The PR's new tests still pass, but they are mocked too broadly around subprocess.run; they return success for the fetch command and therefore do not exercise this Git behavior.

Required changes are unchanged:

1. In _setup_pr_worktree, if pruning does not let the PR branch be deleted, do not fetch into that checked-out branch. Either return a clear actionable live-worktree conflict error, or fetch to a safe independent ref/unique branch and create the checkup worktree from that.
2. Add a real-git regression that creates a local refs/pull/<n>/head, leaves the scoped checkup/pr-* branch checked out in another live worktree, and verifies the fetch/setup behavior.
3. Keep or justify the generated prompt/example/architecture churn separately from the stale-branch fix.

Other status: the normal unit/regression/CodeQL checks and auto-heal are green, but there is also a failed heal workflow check caused by authorization (sohni-tagirisa is not a pdd_cloud collaborator). Regardless, the code blocker above is enough to hold the merge.

[Serhan-Asad]

/heal

[gltanaka]

Still not ready to merge.

The latest commit fixes the fresh PR setup path I previously flagged: with resume_existing=False, a live checkup/pr-* worktree now returns a clear actionable conflict before git fetch, and the new real-git tests cover that path.

However, the same fetch-into-live-branch failure still exists in the PR-mode resume path. _run_agentic_checkup_orchestrator_inner calls:

_setup_pr_worktree(cwd, pr_owner, pr_repo, pr_number, quiet, resume_existing=True)

when a saved PR worktree path is missing. In that mode _setup_pr_worktree skips the delete/conflict branch, then still runs:

git fetch <remote> pull/<pr>/head:<branch_name> --force

If the scoped checkup/pr-* branch is checked out in another live worktree, Git still refuses the fetch. I reproduced this against the updated head 9dc0a7c1f7683aba39808d8190d0cf351d5d57a6; it still returns the old cryptic form:

Failed to fetch PR #77 ... fatal: refusing to fetch into branch 'refs/heads/checkup/pr-77-...' checked out at '.../live-wt'

Required change:

• Apply the same live-worktree conflict guard to the resume_existing=True path before fetching, or otherwise avoid fetching into a checked-out branch in that mode too. Add a real-git regression for resume_existing=True with a local refs/pull/<n>/head and the scoped branch checked out in another live worktree.

Verification I ran locally:

• New targeted tests on this PR: TestSetupWorktreeStaleBranch, TestSetupPrWorktreeStaleBranch, and TestSetupPrWorktreeStaleBranchRealGit all pass (8 passed).
• Fresh PR setup live-worktree repro now returns the expected clear conflict.
• PR resume setup live-worktree repro still fails with the old fetch error.

There is also still a failed heal workflow check due to authorization (sohni-tagirisa is not a pdd_cloud collaborator), while the normal unit/regression/CodeQL checks and auto-heal are green.

[sohni-tagirisa]

Addressed the remaining change request around the PR resume path.

What changed:

• _setup_pr_worktree(..., resume_existing=True) now checks whether the scoped PR checkup branch is still checked out in another live worktree before fetching into it.
• If the branch is live elsewhere, setup returns an actionable error that points to the holding worktree and suggests git worktree remove <path>.
• Added a real-git regression test covering resume_existing=True with a live worktree holding the target branch, asserting that we fail before the fetch and do not surface the cryptic refusing to fetch into branch ... checked out error.

Verification run locally:

• python -m py_compile pdd/agentic_checkup_orchestrator.py
• python -m pytest tests/test_checkup_pr_mode.py::TestSetupPrWorktreeStaleBranch tests/test_checkup_pr_mode.py::TestSetupPrWorktreeStaleBranchRealGit -q -> 6 passed
• python -m pytest tests/test_agentic_checkup_orchestrator.py::TestSetupWorktreeStaleBranch -q -> 3 passed
• python -m pytest tests/test_checkup_pr_mode.py tests/test_agentic_checkup_orchestrator.py -q -> 330 passed
• git diff --check origin/main...HEAD

Current PR head: ae096e851a4b59076c08dc1eab5d1f67eb150b92.

Current remote checks: CodeQL analysis checks pass. heal / auto-heal are still failing because the actor is not authorized as a pdd_cloud collaborator, so the auto-heal job is blocked before running the build/test workflow. A pdd_cloud collaborator will need to authorize or trigger /heal for that external gate.

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[Serhan-Asad]

/heal

[gltanaka]

The previously blocking live-worktree fetch paths are fixed.

I verified the updated head (827e44ed23aa38677c1ae000e058bda6c6e1b314) against both repros:

• Fresh PR setup (resume_existing=False) with the scoped checkup/pr-* branch checked out in another live worktree now returns a clear actionable conflict before fetching.
• PR resume setup (resume_existing=True) now does the same; it no longer falls through to Failed to fetch PR ... refusing to fetch into branch ....

Targeted regression tests also pass locally:

TestSetupWorktreeStaleBranch
TestSetupPrWorktreeStaleBranch
TestSetupPrWorktreeStaleBranchRealGit
9 passed

All current reported checks are green, including unit tests, public CLI regression, CodeQL, and auto-heal. Approved.