a deterministic infrastructure, a non-deterministic agent

i’m working on caduceus this weekend. it’s an issue-to-pr pipeline for a github repo. the daemon polls for tagged issues, claims them, creates a worktree, and runs an agent on the code. the agent reads the issue, makes changes, opens a pull request. that’s the whole product.

the daemon and the agent are separate processes. they don’t share a library. they don’t import each other. the daemon knows how to spawn a subprocess, read its output, enforce a timeout. that’s it. the agent is whatever the subprocess turns out to be.

i built it the wrong way first. one process. the agent loop, the polling, the github integration, the worktree management, the retry logic, all in one binary. it worked. then i wanted to swap the agent from one harness to another and i had to recompile the whole daemon. every change to the agent loop meant recompiling the daemon. that should have told me something. it did, eventually.

the agent loop will change

the agent loop will change. it always changes. the model that was hot this month will be deprecated next month. the harness will be rewritten. the prompt format will shift. the tool-use interface will change. the agent loop is the interesting part of an agent system. it’s also the part with the shortest half-life.

your infrastructure doesn’t have to be interesting. it has to survive.

the split

so i split caduceus into two processes. the daemon owns everything boring: polling, queue, claims, worktrees, timeouts, retries, github. the agent owns everything interesting: reading files, writing code, interpreting issues. the two halves communicate through a path, a flag, a transcript file, and an exit code. no library. no SDK. no harness-specific types in the daemon’s code.

the daemon passes the agent a --context-json argument containing the issue text and run id. the agent writes its output to a transcript file. the agent exits with code 0 on success or non-zero on failure. that’s the whole contract.

the daemon doesn’t know what an agent is. it knows what an agent does: it writes files and exits.

the air-gap

the agent is air-gapped. the daemon clears the environment (cmd.env_clear()) before spawning. no GITHUB_TOKEN. no ~/.ssh/. no shell history. no git config user.email. the agent cannot push, cannot comment, cannot gh pr create. it can write files inside its worktree. that’s all it can do.

the air-gap is not security theater. it’s what lets the daemon trust the agent. if the agent had the daemon’s github token, the daemon couldn’t trust that the agent wouldn’t do something the daemon shouldn’t have done. by clearing the environment and passing only what’s explicitly needed, the daemon can verify what the agent can and can’t do without watching it.

the failure path is boring

when the agent hangs, the daemon doesn’t. the agent runs under a tokio task with a CancellationToken. if the agent doesn’t exit within the timeout, the daemon cancels the task, kills the subprocess, releases the claim, cleans the worktree, and moves on to the next issue. the next run is fresh. no leaked state. no orphan worktree. no zombie process.

when the agent panics, the daemon’s response is the same as for a successful run, with a different exit code. the failure path is boring. it’s the same code path as a successful run. boring is a feature, not a bug. the daemon is the part that’s allowed to be boring.

what survives

when the agent loop changes — and it will — the daemon doesn’t. swap the agent for opencode. swap it for codex. swap it for a python script you wrote in an afternoon. the daemon doesn’t notice. the daemon doesn’t care. the contract is “an agent process that reads files and exits with a code.” that’s a contract any harness can honor.

the framework-as-library pattern optimizes for code reuse and a unified mental model. the daemon-and-worker pattern optimizes for survival. survival is the better optimization target.

write the boring parts so they can survive any agent, including the one you haven’t written yet. the agent loop will change. it always does. when it does, you don’t want to be the person whose infrastructure was welded to the last one.