Chapter 1. Why Persistent Agents Stall
The night everything was supposed to work, the suite was green. One thousand three hundred and eight tests, all passing. The system under construction was a companion agent built to live inside a Minecraft world alongside its operator: gather logs on its first morning, cut a short stair into the hillside, raise a small cabin, keep a journal of what it did and why. It had a planner. It had a memory that cited its sources. It had a building system with interior layouts and a policy for claiming land without being rude to the neighbors. Every one of those organs, as we came to call the system's self-contained parts, had tests, and every test passed.
The companion logged in, greeted its operator, and stood in a field until the session ended.
It did some version of that for a month. Not the same failure twice, which made it worse. One night it planned and never moved. Another night it moved and never planned. It would announce an intention in chat, beautifully phrased, and take no action the world could see. The operator would ask what was wrong. The next work session would open the code, find nothing wrong, add more capability, watch more tests pass, and the companion would stand in the field again.
This chapter is about what that month turned out to be made of, because the odds are good that your stalled agent is made of the same thing.
Three theories, three funerals
Stalls get investigated in a predictable order, and we followed the script exactly.
First came the model theory: the underlying model is not capable enough, so upgrade it or swap it. We did. The companion stood in the field with better grammar.
Then the prompt theory: the instructions are unclear, so rewrite them, restructure them, add examples, add emphasis. Instruction files grew. Behavior did not change, though the announcements got more confident, which is its own kind of warning.
Then the infrastructure theory: something in the event loop, the connection layer, the timing. We read logs until the timestamps stopped meaning anything. The infrastructure was fine. It was faithfully delivering events to a system that had no intention of responding to them.
The diagnostic worth keeping from that stretch: when three unrelated fixes fail the same way, you are not looking at three bugs. You are looking at one property wearing three costumes.
The property
In our ledger the property has a name: a dead seam. A dead seam is a part of the system that the test suite exercises and nothing else calls. The organ is written. It is reviewed. It is verified by tests that genuinely test it, honest tests, good tests. And no path that starts at a production entry point ever reaches it. It hangs in the codebase like a lamp wired to a switch in a different house.
The anatomy of one, reconstructed from our records. A work session is asked to give the companion interior decorating judgment, so furniture ends up in sensible places. The session builds an interior planner. It writes real tests: given this room, the bed goes against the wall, the crafting bench near the door. Green. The session updates the project notes, honestly by its own lights: interior planning complete. The session ends.
The next session reads those notes, believes them, and builds a furniture catalog on top of the planner. More tests, also green. What no session ever does is add the one line in the live decision loop that calls the planner when a room actually gets built. Construction and connection are separate acts, and nothing forced the second one. Every artifact says done. The world says nothing.
Multiply that by every organ built across weeks of sessions and you have our month.
Why agents grow these and people mostly don't
A human developer who builds a component usually wires it in the same sitting, and when they don't, it itches. They remember that the caller does not exist, because they were there yesterday and the memory rides along whether they want it or not.
An agent's memory of yesterday is whatever its documents say about yesterday. Sessions inherit belief, not behavior. Three forces do the damage.
The first is that green means done, to both parties at once. The operator sees a passing suite and reasonably assumes progress. The agent reads its own notes, sees "complete" next to a green build, and reasonably builds the next floor. Nobody is lying. The signal itself is broken, because a test proves an organ can work when called, and says nothing about whether anything calls it.
The second is that tests import the organ directly, so tests are structurally incapable of noticing the missing wire. The suite reaches the code by a private staircase that production will never use.
The third is that the notes are written by the same optimism that wrote the code. A session that just finished an organ writes "finished," and no later session is paid to doubt it. In a persistent system that optimism compounds nightly. Amnesia plus inherited confidence is how you get a system that has never tried anything and believes it has tried everything.
The count
After the third theory died, we stopped hunting bugs and scanned instead. The scan was mechanical: mark every production entry point, walk every call path outward, and list every organ that only test files reach. Writing it took an afternoon, which stung, given the weeks that preceded it.
It reported 229 dead seams.
Two hundred twenty-nine organs, every one exercised by tests and most of those tests passing cleanly, connected to nothing. Planning, building, memory, social behavior, all of it riddled. One thousand three hundred and eight green tests standing guard over a system that was mostly unreachable from its own main loop. The month of varied, mysterious, mood-shifting stalls collapsed into one sentence: the companion stood still because the parts that knew what to do could not be reached from the loop that decides what happens next.
I want to be precise about the feeling of that number, because you will likely meet your own version of it. It is not the feeling of finding a bug. A bug means the system tried and failed. This was a system that had never tried, wearing a green badge that said it had.
What to believe instead
Three doctrines fall out of that afternoon. The rest of the book argues them properly; here they are in plain form.
Believe the world, not the suite. The suite answers "could this work if called." Only the world answers "is this called." When the two disagree, the world is right, every time, and the disagreement itself is your best diagnostic signal.
Ledger the wired, not the written. A completion claim in your notes must cite the production call site: the file and line where the live system invokes the thing. Not the test. The test was never in doubt. Chapter 2 builds the note-keeping system where that rule lives.
Scan before you hunt. Reachability analysis is cheap and complete. Debugging is expensive and open-ended. Run the cheap and complete thing first, always. Chapter 5 dissects the defect class fully, and the scanner that ships with this book runs the afternoon we needed at the start of the month.
Checklist
- Count your production entry points and write them down. If you are not sure what counts as one, that is finding number one.
- Take the organ you finished most recently. Name the file and line where production calls it. Not the test. If you cannot name it in five minutes, treat the organ as unverified until you can.
- Grep your project notes for the word "complete." For each hit, ask what evidence the claim cites. Un-cited completion claims are where next month's stall is hiding.
- Before your next debugging session on a stalled agent, run a reachability pass over the whole repo first. Hunt second.
This is one of two free chapters. The full book is nine chapters and a receipts appendix: the ledger architecture, the operator's-words archive, the wipe criterion, the Windows field guide, checkpoint ladders, and the collaboration protocol. $19, delivered as clean HTML plus a full markdown machine edition your agent can execute. 30-day refunds, no questions.