A Swarm Is a Distributed System, Not a Team

Three agents, three problems, one pot of coffee. You dispatch them and go get a refill. This is the good part, the part the feed promised: work happening in parallel while you stand at the counter. You come back twenty minutes later to collect it.

One agent's fix has landed on top of another agent's commit. A second agent's change is on a branch that no longer exists. A third finished cleanly, and you cannot tell which of the four copies of the repo on your disk it finished in. Nothing crashed. Every agent reported success. And you have less working code than when you left.

The agents were fine. That is the part worth sitting with before this series goes any further. Not one of them was too dim to do its task. They did their tasks. The mess is not in any single agent. It is in what happens between them, and it has a name that predates the word "agent" by forty years.

You did not dispatch a team. You deployed a distributed system. And you deployed it with no coordinator, because you assumed the coordinator was one of them.

Operating Conditions

Name the setup honestly, because the vocabulary is doing you harm. You have several agents, one repository, one machine. That sounds like a team in a room. It is not.

Underneath those agents, by default, sits one working tree, one HEAD, one index, one build directory. That is the whole problem in one sentence. The agents feel like coworkers you are directing. They are actually several processes writing to the same shared state, with no lock, no queue, and no manager, and the manager was supposed to be you.

The word "agent" is the disguise. It is a warm word. It suggests intent, judgment, a little person who knows what the other little people are doing. None of that is true at the filesystem. At the filesystem there are N writers and one set of files, and the files do not know an "agent" from a cron job. Strip the word away and you are left with the oldest problem in computing: concurrent writers, shared state, no coordination. We have known how that fails since before most of us were typing.

Failure Modes

Every classic distributed-systems failure comes back the moment you run the second agent. Not as a metaphor. As the actual failure, with the actual mechanism.

Race condition. Two agents read the same file, both decide what it should say, both write. The one who writes last wins, and neither knew the other was there. Your team of three just held an election nobody announced.

Lost write. Agent A stages a file. Agent B, sharing the tree, modifies it and commits the whole thing. A's change is now folded into a commit under B's message, or it is gone. It was real work. It is not in the history. Nobody deleted it. It was overwritten by someone who could not see it.

Last-write-wins on history. A shared HEAD is a single mutable pointer. git commit --amend and git rebase assume that pointer is a fixed target you own. Between two turns it is not. It moves. The tool that assumes it owns HEAD is the tool that welds your fix onto a stranger's commit.

Split brain. Two agents get the same task, form two different theories, build two different fixes on two different branches. Both are internally correct. Both cannot land. You find out at merge, which is the most expensive possible moment to find out.

Read that list again and notice what is not on it: "the model was not smart enough." None of these is a reasoning failure. A perfect agent, flawless at its own task, hits every one of them, because none of them is about the task. They are about the shared write.

Root Cause

The enemy is not the model. The enemy is shared mutable state.

Say it plainly, because the whole series turns on it. Every failure above is two writers touching the same thing with no coordination between them. The counter both agents increment. The file both agents edit. The HEAD both agents commit onto. The branch one agent deletes while another is still standing on it. In each case the fix is not a smarter writer. It is fewer writers on that one piece of state.

This is why "just use a better model" does not touch the problem, and why the next model will not either. A better agent writes better code faster. It has no more idea than the current one that a sibling process is editing the same file, because that information is not in the file, and the file is all it can see. Intelligence per agent does not buy you coordination between agents. Nothing about being smart tells a writer that someone else is also writing.

The coordinator you assumed the swarm had does not exist. There is no adult in the room. That chair was open the whole time, and it is yours.

System Status

That is the mental model this series runs on, and every post after this one is a specific instance of it. One writer amends over another's commit. One agent reports done and the branch it committed to is already gone. Five agents build the same feature on the wrong branch because the thing they all trusted for "which branch" was shared mutable state that drifted underneath them. Different mechanisms. Same root. Shared writes with no coordinator.

The fix, every time, is never a smarter agent. It is fewer shared writers: one writer per branch, one owner per hot file, one integrator at the end, and a coordinator who is a person. That is the boring, forty-year-old answer, and it scales down to one developer at a desk with three agents and a coffee. You do not need a control plane for three writers. You need to stop pretending they are a team and start treating them as what they are, a distributed system that will fail exactly where the writes overlap.

The next three posts are the three places they overlap most, and what each one actually costs.

Tell me the first time a swarm ate your work. Not "it got confused." The specific write that clobbered the other write. That is the part that transfers, and it is the part nobody posts.

Further Reading

• It Said Deployed: the single-agent version of the same lie, a "done" reported over a 404.
• The Amend That Landed on Someone Else's Commit (Part 2): the shared writer, in detail.
• It Said Done, and Deleted the Branch (Part 3): when the commit is real but you cannot reach it.
• Five Agents Built It on the Wrong Branch (Part 4): the dispatch that trusted a stale HEAD.