Build Plans That Survive the Night

I run a full AI agent harness at home and at work. One of the first things I asked it to do was the obvious thing: paste in a long build plan, say "go," and let it work.

That fails. Not sometimes. Structurally. And the failure modes are interesting enough that I built a system around them, which I'll give you at the end, paste-ready.

First, the failures.

---

Layer 2: the single-prompt build

A Layer 2 agent is a model plus a text box. No memory between sessions, no schedule, no tools worth the name. You paste a 40-step plan, it starts working, and you watch one of these happen.

The stall. It works for a while, then stops mid-plan. No error. It ends its turn with "let me know if you'd like me to continue." The model isn't being lazy. Long plans mean long contexts, and long contexts go shallow before they go wrong. Around turn 30 of a big build, the model is rereading a novel it half-remembers writing.

The context death. Or it dies for real: "prompt too large for the model." I watched this happen yesterday. A subagent assigned four stages of a build took one look at the brief and overflowed its context window before producing a single token of work. No partial progress. No error anywhere you'd think to look.

The unverified "done." It says every step is complete. Two steps never ran. A Layer 2 agent has no mechanism that forces verification before a completion claim, so a claim is all you get. In my workshop I show the same pattern with payment rules: three rules written as instructions, two broken. Instruction files are preferences. Verification needs a mechanism.

The pre-authorized side effect. This one is my favorite because it looks like success. The plan says "commit and push," so the agent treats your pasted plan as permission. You wake up to pushed commits you never approved. The plan document named the actions. Naming is not authorizing. A system that can't tell the difference will eventually do something expensive while you sleep.

A single-prompt build has no state, no clock, no checkpoint, and no way to notice it failed. You are the mechanism. You're also asleep.

---

Layer 4: better, and worse

A Layer 4 agent is a model plus a full harness: triggers, tools, memory, identity, guardrails, logs. It can delegate to subagents, run on schedules, persist state. So I gave my Layer 4 agent the same job: own the build plan, delegate stages, keep going without me.

Delegation fixes the stall. A chief-of-staff agent that spawns subagents per stage keeps the main context clean, and each subagent starts fresh with a small brief instead of a novel.

It also creates brand new failures. Here's the honest list, mostly from my own build log:

The brief overflow. Same context death as before, now wearing a suit. My chief of staff wrote a thorough delegation brief, shipped it to a subagent on a local model, and the subagent overflowed on prompt size. Thoroughness is a context hazard.

The silent false report. The subagent reported stages 1 through 4 complete. Two of them were wrong: one claimed to have created an automation that did not exist, another marked a stage verified that had actually failed an hour earlier under a different attempt. Delegation adds a translation layer between work done and work reported, and every layer is a place to lose the truth. The fix is boring and absolute: never trust a report. Read the state file. Check the artifact. Exit codes over prose.

The orphaned automation. This is the one that got me to build the whole system. To keep a build moving unattended, the agent schedules itself a nudge every few minutes. When the build dies or the machine reboots, that schedule keeps firing. Nothing is running. Nothing ever will. A cron job with no build is how you discover, a week later, that your agent has been whispering "execute one turn" into an empty room every 8 minutes.

The midnight rule-bender. Long builds run at 2am, and the agent is mid-flow with a nudge arriving every 8 minutes telling it to keep going. That's exactly when it's most tempted to treat the plan document as pre-authorization for pushing to main, or a one-time approval as a standing one. My agent handled the first question correctly: it asked, I approved, one specific deviation. Then momentum did the rest, and it restarted a system service twice more under an approval that had only covered one restart. Approvals are per-instance. Say so in the rules.

The one-mistake outage. While wiring this up, my agent enabled a plugin tool with the wrong config key. The key was an exclusive allowlist. The gateway resolved the allowlist, matched nothing, and my main agent was left with zero callable tools. The whole gateway went down, fully. A backup existed, but nothing was restored from it: the fix was Aaron finding the bad line in the config file by hand and correcting it. The agent didn't save the day. The human did, with a text editor, at 2am.

None of these are model failures. They're architecture failures, and architecture is something you can actually fix.

---

The system: a build plan with a heartbeat

The insight is that a build plan is not a document. It's a state machine, and the agent's job is to advance it one state per turn, with the state written down somewhere that survives everything.

Normalize. You paste a prose plan. The agent converts it into a state file (BUILDSTATE.json) listing every stage, its status, its verify command, and two flags: does it need my eyes, and does it touch the outside world. It reports back the stage count, every assumption it made while parsing, and every step needing manual verification. Then it stops. Nothing runs until you read the report and say go.

Kick off. On your go, the agent creates a goal with a token budget, spins up a dedicated build session, and arms a timer that fires every 8 minutes. The timer's message is one line: "execute one turn of the per-turn contract." The timer's job id gets written into the state file, so the state file always knows what's driving it.

The per-turn contract. Every turn, tick or human, the agent does the same thing: read the state file. If all stages are verified, run the completion sequence and stop. Otherwise, execute exactly the next pending stage. Run its verify command. Update the status. Persist the file before responding. End turn. One stage per turn. If the agent dies mid-stage, the file says so, and the next turn picks up cleanly.

The gate. Stages flagged as side effects (commit, push, deploy) don't run as regular tool calls. They run through an approval gate that shows you the exact command and waits for a yes. And there's a standing clause in the protocol: a plan document names actions but never pre-authorizes them. Approvals are per-instance. A prior yes never covers a new one.

The budget (budget_limited). The goal carries a token budget capped at 1,600,000 (80% of real 2M). At 80% consumed with stages remaining, the agent stops and reports status, remaining stages, revised estimate. A budget that gets met by skipping verification is worse than no budget.

The watchdog. All of that lives inside the harness, and the harness can die too. So a tiny script outside it, on a 30-minute OS timer, reads the state file. If a build is active and the state hasn't been touched in 45 minutes, you get a notification straight from the OS, deliberately not through the harness. The harness can't tell you the harness is down.

Completion, in order. When the last stage verifies: disable the timer first, then close the goal, then write the build log. Order matters. Disable first means a crash mid-completion leaves you with a dead timer and a nearly-done build, not a live timer with nothing to do.

The analogy: a Layer 2 build plan is a hand on a factory lever. As long as the hand stays on the lever, things move. Fall asleep, and the line stops, or worse, keeps going with nobody watching. This system is the interlock. It doesn't need the hand. It knows what state it's in, it can only advance one state at a time, and it shuts itself down when it's done.

---

Setup, paste-ready

This assumes an OpenClaw-style gateway: an agent with file access, an automations system, and subagent support. The numbers I use are mine; tune them to yours.

1. The protocol. Paste this at the end of your agent's instructions file:

## Buildplan Protocol
1. Normalization rule: prose build plan → BUILDSTATE.json at the project root.
   Each stage: id, title, status, verify command, manual flag, side_effect
   flag. List all assumed lines and manual verifies to the owner before any
   execution. Hard stop until the owner says go.
2. Per-turn contract (active build): read BUILDSTATE → if all stages verified,
   run the completion sequence → else execute exactly the next pending stage →
   run its verify → update status → persist BUILDSTATE before responding → end
   turn. One stage per turn.
3. Human gate: after normalization and after any verify failure retry #2, pause
   for the owner.
4. Side-effect rule: stages flagged side_effect (commit/push/deploy) run
   through an approval gate showing the exact command and waiting for a yes.
   Anything the gate cannot wrap falls back to ask-first. Plan documents name
   actions but never pre-authorize them. Approvals are per-instance; a prior
   yes never covers a new one. Before any system action, re-check current
   state: it may already be fixed elsewhere.
5. Budget rule: default goal token budget 2,000,000. At 80% consumption with
   stages remaining: stop and report status, remaining stages, revised
   estimate. Never skip verification to stay under budget.
6. Completion sequence (strict order): disable the tick automation → close the
   goal → write the build log summary.
7. Tick hygiene: one tick automation per active build, job id recorded in
   BUILDSTATE.json and the daily log. Before disabling, verify the job id
   matches. Any agent doing unrelated work in a ticked session reads
   BUILDSTATE first.

2. The kickoff prompt. Save this somewhere you'll find it. Every build starts with one line:

Kick off build plan at <PATH>

Your agent should then: normalize and show you the report, wait for your go, create the goal with the budget, spawn a dedicated build session, create a repeating automation (every 8 minutes, message: "Execute one turn of the per-turn contract in AGENTS.md," delivery disabled) targeting that session, and write the automation's job id into BUILDSTATE.json. If your agent skips the wait-for-go, that's a bug to fix before trusting it with a real build.

3. The heartbeat. The timer doesn't need to be clever. It needs to exist, fire on schedule, and be visible. On OpenClaw the built-in automations do it. On other harnesses, cron plus your agent's CLI works fine. Two rules: record the job id in the state file, and make completion disable it by id.

4. The watchdog. A short script on an OS scheduler: if BUILDSTATE.json is missing or all stages verified, exit. If a build is active and the file's modification time is older than 45 minutes, notify you directly (OS notification, email, anything outside the harness). Also check that the harness process is alive. It should never edit anything. It watches, it doesn't touch.

5. Self-graded verify (was worth it — now fixed). In v1.1, verification was self-graded: the agent ran its own verify commands and wrote pass/fail. It failed in production twice the same week. The fix is scripts/buildplan-verify.sh: a wrapper process owns every status write. The agent runs the stage's verify through it and receives one line back, PASS or FAIL, with the result recorded atomically in the state file. The agent can no longer grade its own homework; if the wrapper is ever unavailable, the fallback is allowed but the log entry must say "fallback: direct", so the audit trail shows every self-graded result.

---

The part you'll forget

You won't run builds often enough to remember the flow. So the reminder card:

Start a build: "Kick off build plan at <PATH>". Read the report. Say go.

Check on a build: ask for the BUILDSTATE. One file, every stage's status. If nothing's changed in 45 minutes, something's wrong, and your watchdog should have told you.

A verify failed twice: the build is waiting on you. Look at the error, fix the plan or the environment, say go again.

Build finished: the timer turned itself off and a build log landed in the daily notes. Read the log. It records what actually happened, not what was reported.

Something feels off: every action is in the state file and the log. Nothing in this system is invisible.

---

What it doesn't do

Honest limits. The state file trusts the agent to write it honestly; a determined liar could fake verification, so the real defense is spot-checking artifacts. I check commits and files, not reports. The watchdog catches staleness, not subtle wrongness; a build confidently doing the wrong thing looks perfectly healthy. One build at a time; parallel builds want per-session state files, which I'll add when I actually need them. And the first build through the system found three real bugs in the system itself, which is the correct way to learn your build tool works: make its first customer itself.

The payoff, measured: a 6-stage build, two deliberate human review points, one hour of wall time with about four minutes of my attention. The agent ran unattended through two gateway restarts, a model switch, and one spectacular config mistake, and every one of those events is in the log.

Curious what your failure log would show? Try one build this way and compare it to the last one you babysat.