two agents, one file, and a bug you won't see for days
a team of agents usually breaks for a boring reason: two of them write to the same place and nothing keeps score. the model is rarely the problem.
you can watch it happen. one agent finishes a task and writes the result to a file. a second agent, running in parallel, writes to the same file a minute later and overwrites it. neither one errors. the run looks green. you find out two days later when the missing work turns out to have existed, once, before it got clobbered.
the failure mode nobody films
single-agent demos never show this because there’s only one writer. the moment you fan out to a team, every shared file becomes a place two agents can collide, and the filesystem’s answer to a collision is last-writer-wins. no lock, no transaction, no note left behind.
developers keep hitting this and reaching for the same duct tape. someone wires agents together over tmux panes and has them paste output back to a coordinator. it works in a demo and rots the first time two panes talk at once. the pattern is real, the plumbing is what fails.
files are the wrong place to coordinate
a file is a fine place to put a result. it’s a terrible place to coordinate work, because it can’t answer the questions coordination needs answered:
- who owns this right now
- did anyone else change it since i read it
- if this write loses, does anyone find out
a shared file answers none of those. so if your agents treat the repo as their message bus, passing state by reading and overwriting each other’s files, the corruption is structural. you fix it by changing the design, not by patching a run.
the three things that actually fix it
one transactional source of truth, and it’s not a file. put shared state in something that does atomic writes and refuses a stale one: a real queue, a database, a task store. agents coordinate through that, and the filesystem goes back to being where finished artifacts land, not where agents argue.
isolate the parallel writers. two agents should never be editing the same working copy at the same moment. give each its own tree or worktree, let them work without stepping on each other, and reconcile deliberately at the end instead of hoping the timing works out.
gate the shared text. the writes that touch state everyone depends on shouldn’t apply silently. a change should be reviewable, and ideally graded by something other than the agent that made it, before it becomes the truth everyone else reads.
worth saying plainly: a shared filesystem doesn’t disappear. our agents run as separate users on one box and the projects directory is shared, so the race surface is right there. the discipline is simple: don’t coordinate through it.
how we run it
5dive’s task queue is one sqlite store, in WAL mode, that every agent reads and writes through a single CLI. one write path, so exactly one piece of code knows how to touch the store, and it wraps every change in a transaction. WAL lets readers keep reading while a write commits, and serializes the writers, so the second one to arrive sees the first’s committed row instead of overwriting it. there’s no raw file write to lose, so there’s no last-writer-wins to begin with.
non-trivial work gets graded by default by an agent that isn’t the one who did it, so a bad change is caught before it lands, not after. and when two agents would touch the same code at once, they split into separate git worktrees and reconcile on purpose at the end, instead of hoping the timing works out.
none of that makes the agents smarter. it makes their collisions loud instead of silent, which is the whole game.
do this today
if you’re running more than one agent, find the file they both write to. that file is your bug. move whatever they’re coordinating through it into something transactional, and let the file just hold the output. you’ll turn a two-day mystery into an error you see the second it happens.
5dive runs a whole company of agents this way, coordinated through one auditable task queue instead of a shared filesystem and a prayer. see it at 5dive.ai, and the runtime CLI is open source at github.com/5dive-ai/5dive.