Auto-Rebasing AI Workspaces
Keep agent branches current when their base moves, without losing review control.
Goal
Understand branch drift in AI workflows, rebase dependent work safely, and use Treq auto-rebase without treating a successful rebase as an approval.
What branch drift is
Branch drift happens when main or a stack parent moves while an agent branch still points at an older commit. The branch still builds against yesterday's code. Merging it later surfaces conflicts and behavioral surprises that would have been cheaper to fix earlier.
AI branches drift faster than typical human branches because agents finish drafts quickly, then wait in a review queue while other merges continue.
Stack drift examples
Day 1
main @ A
└── auth/schema @ B
└── auth/api @ C # based on B
Day 2 after schema review edits
main @ A
└── auth/schema @ B' # rewritten during review
└── auth/api @ C # still based on B ← drifted
Independent parallel branches drift against main the same way:
# agent branch created Monday
git log --oneline origin/main..HEAD
# Wednesday, after several merges to main
git fetch origin
git merge-base --is-ancestor origin/main HEAD || echo "branch has drifted"
Safe rebasing
Rebase only branches whose rewrite policy you control. Use a lease when force-pushing:
git fetch origin
git rebase origin/main
# resolve conflicts, run tests
git push --force-with-lease
For a stack, restack from the changed layer upward:
git switch auth/api
git rebase auth/schema
git push --force-with-lease origin auth/api
After every rebase:
- Read the new diff against the intended base.
- Re-run the relevant tests.
- Treat conflict resolutions as new code under review.
git diff origin/main...HEAD
npm test
Do not rebase a branch other people are building on unless they expect force pushes.
Review implications
Auto-rebase changes commits under an open review. Reviewers must know when a diff moved. A green rebase means Git applied patches. It does not mean the conflict resolutions are correct.
Pause upper-layer review while the lower layer is still being rewritten. Restacking onto an unstable base creates repeated review churn.
Treq implementation
Treq records each workspace's target_branch. When that target moves, Treq rebases dependent workspaces onto the new commit in stack order. It skips a workspace that already descends from the target and records the target commit used by a successful rebase.
Conflicts stop the clean flow. Resolve the lowest conflict first, then let dependents update. You can send conflict resolution instructions to an agent from the review UI. See Workspaces and Changes and Reviews.
Pending working-copy edits can block or complicate synchronization. Commit, move, or discard them before relying on an automatic rebase result.
Common failure cases
Rebase succeeds, behavior breaks. A conflict marker resolution kept the wrong side. Re-read conflicted files and add a regression test.
Force push without lease. Concurrent updates on the remote branch can be overwritten. Always prefer --force-with-lease.
Rebasing during an active agent session. The agent may write files while history rewrites. Stop the agent or wait until it finishes before rebasing that workspace.
Deep stacks with a noisy root. Frequent root rewrites punish every dependent layer. Stabilize the root before adding height.