A merge queue for one

FlowPilots is built by one person running several coding-agent sessions in parallel, each in its own git worktree. That sounds like a superpower until two sessions finish an hour apart and both try to land on the same branch. The second one rebases onto a moving target, the conflict resolution happens at the worst possible moment, and the test suite runs against a tree nobody actually reviewed. Big teams solve this with a merge queue. It turns out a team of one with parallel agents needs exactly the same thing.

A single-writer landing strip

The queue is local: a lock directory and a set of refs inside the repo's own .git, no server anywhere. A session that finishes its work does not merge. It enqueues: the branch is rebased onto the integration branch under a lock, any conflict is resolved inside the session that owns the context, and the result is parked as a queue ref with its prepared commit recorded. Then the session detaches and goes away.

A small daemon drains the queue every two minutes. One item at a time, it rebases the prepared branch onto integration, runs the full gate suite, and only a green gate lands. The daemon is the single writer; nothing else ever advances integration. The main branch then follows integration fast-forward-only, behind a rolling backup ref, so a bad landing can always be rewound.

A ladder for conflicts, cheapest rung first

Most conflicts a parallel-session setup produces are mechanical: two sessions appended to the same changelog, both regenerated the same lockfile or generated client. The drain resolves those in order of cost: custom merge drivers for append-only files first, then regeneration for generated artifacts, then git's own recorded resolutions, and only then an isolated resolver session with a scoped view of the two sides. Anything still unresolved parks for a human. The queue's own scripts are the exception: a conflict that touches the machinery always parks, because the machinery must never rewrite itself mid-flight.

What it buys

Every landing passed the whole gate on the exact tree that landed. Sessions never race, never merge by hand, and never leave a half-rebased branch behind. And the history stays legible: one logical change per commit, in the order the queue accepted them, which is the property that makes the audit trail worth reading. The same doctrine that runs the product - stage the move, gate it, record it - turned out to be the right way to run the repo, too.

All posts