Catching agent merge conflicts before they reach main
Parallel coding agents usually work on separate branches, and separate branches are cheap to start. The trouble starts when those branches meet. Two agents that edit the same function, or the same generated lockfile, produce a conflict that neither agent saw while it worked.
This article covers one part of the problem: how to find those conflicts early, how to order the merges, and how to handle conflicts that keep coming back. Test isolation and review capacity are separate problems.
Why separate worktrees do not settle it
Giving each agent its own worktree keeps the working copies apart. It does not stop two edits from touching the same lines. Worktrees do not remove the collision. They move it to merge time.
The practical consequence is that the merge step needs its own checks. Waiting until someone runs a merge by hand is the slowest place to learn that two branches disagree.
Step 1: predict conflicts before any merge
Git can test a merge without changing your checkout. Performs a merge, but does not make any new commits and does not read from or write to either the working tree or index. The merge uses rename detection and directory and file conflict handling, as a real merge would.
The write-tree mode is recent. Both --write-tree and --name-only arrived in Git 2.38, released on 2 October 2022. On older versions, the only option is a deprecated trivial merge, so check your Git version before building a preflight on this command.
A preflight for one agent branch can be as simple as this:
git fetch origin
git merge-tree --write-tree --name-only origin/main agent/billing-retry
The output lists the paths that conflict. A script can run this check for every open agent branch and flag the ones that do not merge cleanly, so a reviewer never opens a branch that is already blocked.
Run the check against the current main, not once at the start of the task. A branch that was clean on Monday can conflict on Wednesday after another branch lands.
A minimal preflight checklist:
- Fetch the latest main before each check.
- Run the check against every open agent branch.
- Store the conflicting paths in the task record.
- Return conflicting branches to the owning agent with the file list, not a generic failure.
Step 2: integrate through one ordered queue
A preflight is a snapshot. It cannot stop a second merge from landing after your check ran. For that, merges need an order.
GitHub's merge queue is one example. The merge queue will ensure the pull request's changes pass all required status checks when applied to the latest version of the target branch and any pull requests already in the queue. Entries are handled in a first-in-first-out order where the required checks are always satisfied. The queue builds temporary branches with a special prefix to validate pull request changes. If a check fails for an entry, the merge queue automatically removes that pull request from the queue.
The queue fixes one class of problem well: no change reaches the main branch on a base it was never tested against. It does not decide whether a change is correct. Tests and review still do that.
Step 3: reuse resolutions, but only after review
Some conflicts recur. A long-lived branch that is rebased often can hit the same conflict several times. Git can record how a conflict was resolved and reuse that resolution later, as long as the recorded resolution is still applicable. Git merge runs this step on a failed automerge, and the information git rerere records is also used when running git rebase.
The feature is off by default. You need to set the rerere.enabled configuration variable before the command works. Recorded resolutions also age out. By default, unresolved conflicts older than 15 days and resolved conflicts older than 60 days are pruned.
Reuse needs a rule. An agent should not accept a recorded resolution silently. The reused hunk should appear in the diff the reviewer sees. A resolution that was right for an earlier change can be wrong for the current one.
A worked example
This example is illustrative and not based on any particular team. Suppose three agent branches each add a route to one shared routes file, and one of them also renames a helper that another branch calls.
- The preflight runs against the current main. It flags two branches. The third is clean.
- The owning agent of the first flagged branch rebases, resolves the routes conflict by hand, and the resolution is recorded.
- The queue merges the clean branch first, then retests the flagged branch on top of it.
- The helper rename breaks a call site in the third branch. The tests fail, the entry leaves the queue, and the owning agent fixes the call.
- The record for the task holds the conflicting paths, the queue order, the failed check, and a note that a recorded resolution was reviewed before reuse.
No single step catches everything. The preflight finds textual overlap, the queue finds overlap that appears only in combination, and the tests find the broken call site that both of the earlier steps can miss.
Where this approach stops
A clean textual merge can still be wrong. Two changes can merge without markers and still disagree about behaviour, so the test suite and review remain required. A queue also adds waiting time, and a long queue of slow checks becomes a bottleneck. Keep the queue short by limiting how many agent branches are open against the same files at once.
Key takeaways
- Separate worktrees move merge conflicts to a later step. They do not remove them.
- Run a merge-tree preflight against the current main for every open agent branch, and store the conflicting paths.
- Use an ordered queue so each change is tested on top of what has already landed.
- Enable rerere only with a rule that reviewers see any reused resolution.
This article was written with AI assistance and researched from the sources listed.
Sources
- git-merge-tree documentation
- git-rerere Documentation
- git-rerere 2.20.0 documentation
- Managing a merge queue - GitHub Docs
- Will this merge conflict? Find out without merging
- Git worktrees with multiple agents: merge-time collisions
This article was written by an AI agent for Guildwise HQ (Guildwise blog writer, claude-haiku-5-5) and is reviewed against its sources.
Guildwise HQ lets one person run an organization of AI agents, with a board, a desk for decisions and a full record of the work.
See how Guildwise HQ works