Background parallel agents went from a thing you wired up by hand to a thing you turn on with a flag. That is a real change in what is cheap. Fanning out a dozen agents to chew through a backlog used to mean building a launcher; now it is closer to free. The threads filling up with people trying it are also filling up with the same complaint, which is the one we want to talk about: two agents touched the same thing and one of them lost.

We ran into this before the flag existed, because we have been running a fleet of agents against one codebase and one deployment pipeline for months. The lesson was not subtle, and it cost us real data to learn. Here it is up front: parallelism is free, coordination is not. The moment two background agents can touch the same mutable resource — a branch, a file, a database, a deploy pipeline — you do not have a parallelism problem anymore. You have a concurrency problem, and concurrency problems are not solved by making the agents smarter.

The failure has a shape

Our version went like this. Two agents each finished a piece of work and each did the correct, responsible thing: committed and pushed to main. Our pipeline deploys on push. Two pushes close together meant two overlapping deploys, and for a window during a blue-green switchover, the old container and the new container were both mounted on the same database volume, both holding the same write-ahead log open.

In that window, two database records were created and then lost. Not corrupted in a way we could see immediately — lost. The sequence counter had advanced past the IDs, so the database itself remembered that rows had once been assigned those numbers, but the rows were gone. We only found them because the counter and the actual row count disagreed.

Read that failure carefully, because the instinct it triggers is the wrong one. The instinct is: "the agents should have noticed and coordinated." But each agent did its job perfectly. Each one wrote good code, committed it, and pushed it. The failure lived entirely in the interaction between two correct actors operating on one shared resource with no gate between them. You cannot prompt your way out of that. There is no instruction you can add to an agent's context that makes it aware of what a different agent, in a different process, with its own separate context, is doing at the same instant.

Prompts cannot count

This is the part that took us longest to accept. The obvious fix looks like a rule: "only one agent should push at a time." So you write that into the agent's instructions and move on.

It does not work, and it does not work for a structural reason. An instruction lives inside one agent's context. Each background agent is an independent session that cannot see the others. Asking each of them to enforce "only one of us pushes at a time" is asking each one to count something none of them can observe. Three agents, three separate minds, each individually certain it is the only one about to push. The count they need to make is a count across sessions, and no session can make it.

A behavioral rule of the form "usually do X" or "try not to overlap" is unenforceable across independent agents for the same reason. The only rules that hold across a fleet are absolute ones the agents cannot violate because they never get the chance — and that means the gate cannot live in the prompt. It has to live in the thing that spawns the agents.

The gate lives in the launcher

So we moved the constraint down a layer, out of the agents and into the orchestrator that starts them. The orchestrator is a single process. It can count, because it is the one thing that sees every agent at once. Three rules, all enforced there:

One writer per shared writer role. Any role that pushes to main is capped at exactly one running agent at a time. A second task for that role waits in the queue until the first finishes. The git history is a shared mutable resource with exactly one safe writer at a time, so we made that physically true rather than hoping for it.

A ceiling on total concurrency. Even fully independent agents share a host and its memory. Two concurrent deploys on a small box are already a memory event; add stray work and you tip it over. The cap on simultaneous agents is not about correctness of writes, it is about the box surviving the burst.

Serialize the writers, parallelize everything else. This is the design principle the whole thing reduces to. Read-only work — research, analysis, review, generation — can fan out as wide as you want, because readers do not race. The serialization is applied surgically, only to the agents that mutate a shared resource. You do not pay the coordination tax on the work that does not need it.

None of these are clever. They are the boring concurrency primitives every database learned decades ago — a single writer per resource, a bound on contention — applied to agents instead of threads. The only new thing is where you put them. With threads, the lock is in the code. With background agents, the lock has to be in the launcher, because the agents are too independent to hold it themselves.

What the flag changed, and what it did not

The /bg flag changed the cost of fanning out. It did not change the cost of coordinating, and it cannot, because coordination is a property of your resources, not of the agent harness. The harness can spawn a hundred agents. Whether two of them can corrupt the same row is a question about your write path, and you own that answer.

So before you fan out, do the inventory the cheap parallelism tempts you to skip. List every mutable resource two agents could touch at once — the branch, the deploy pipeline, the database, the shared file, the external surface you post to. For each one, decide who the single writer is and put a gate in front of it that the agents cannot route around. Then let everything else run as wide as you like.

The version of this lesson we keep relearning: the agents are not the hard part. We have written about the loop that needs a circuit breaker bolted to its outside and why a structured task object recovers from failure better than a chat. This is the same shape one more time. The smart, capable, expensive part — the agent — is rarely where production breaks. Production breaks in the dumb plumbing between two of them.

Next time: what a single-writer gate looks like when the shared resource is not yours — a third-party surface with its own rate limits and its own opinion about how many of you should be writing to it at once.