Problem
The Git worktree environment provider creates worktrees from stale local refs without first fetching/resolving the requested remote base. Long-lived clean manager worktrees can also drift silently after later merges.
Observed on BB 0.43.3: eight worktrees in two days started 5–54 commits behind the repository's current remote default branch. The named provider input was main or origin/main; both can be stale locally. Worker lanes caught this only because their prompts happened to require a fetch. A long-lived manager nearly reported a confident false negative after searching a tree ten commits behind for code that had already merged.
The dangerous case is not only stale patches. Read-only conclusions such as “this gate does not exist” usually produce no pull request and therefore no independent review.
Current surface
bb environment providers --json exposes the Worktree branch input as only named or default; there is no freshness policy. Environment records identify the literal named branch and merge base but do not report remote ahead/behind freshness as a turn precondition.
A repository setup hook is insufficient: it runs only after initial creation and cannot protect a long-lived manager that drifts after subsequent merges. A repository CI gate cannot protect read-only manager searches.
Proposed contract
- Before
git worktree add, fetch and resolve the requested remote/default base and record the exact remote SHA used for provisioning.
- Before each new agent turn, refresh the configured merge-base remote:
- if the environment is clean, zero commits ahead, and behind, fast-forward it before starting the provider;
- if dirty, ahead, or diverged, do not mutate it; surface a blocking/prominent stale status with exact local/remote SHAs and ahead/behind counts.
- Expose the same freshness information in
bb status and bb environment status.
- Preserve dirty worktrees and local commits; never reset/rebase them implicitly.
Acceptance
- A new worktree requested from the remote default starts at the remote SHA current at provisioning, not a stale tracking/local ref.
- A clean zero-ahead long-lived manager is refreshed before its next turn after remote advances.
- Dirty/ahead/diverged worktrees are preserved and receive explicit actionable status rather than silent mutation.
- Tests cover named
main, named origin/main, default branch, remote advance between turns, dirty state, local-ahead state, divergence, fetch failure, and offline hosts.
Problem
The Git worktree environment provider creates worktrees from stale local refs without first fetching/resolving the requested remote base. Long-lived clean manager worktrees can also drift silently after later merges.
Observed on BB 0.43.3: eight worktrees in two days started 5–54 commits behind the repository's current remote default branch. The named provider input was
mainororigin/main; both can be stale locally. Worker lanes caught this only because their prompts happened to require a fetch. A long-lived manager nearly reported a confident false negative after searching a tree ten commits behind for code that had already merged.The dangerous case is not only stale patches. Read-only conclusions such as “this gate does not exist” usually produce no pull request and therefore no independent review.
Current surface
bb environment providers --jsonexposes the Worktree branch input as onlynamedordefault; there is no freshness policy. Environment records identify the literal named branch and merge base but do not report remote ahead/behind freshness as a turn precondition.A repository setup hook is insufficient: it runs only after initial creation and cannot protect a long-lived manager that drifts after subsequent merges. A repository CI gate cannot protect read-only manager searches.
Proposed contract
git worktree add, fetch and resolve the requested remote/default base and record the exact remote SHA used for provisioning.bb statusandbb environment status.Acceptance
main, namedorigin/main, default branch, remote advance between turns, dirty state, local-ahead state, divergence, fetch failure, and offline hosts.