What my agents do while I sleep

Every night a scheduled job wakes up, reads a queue of pending work across my projects, and spawns one headless agent session per target to drain it. In the morning I read a report over coffee. That’s the pitch, and scheduling it is genuinely the easy part, any cron line can do that. What took actual design is the policy around it, because an unattended agent with write access is a very fast way to wake up to a mess.

The first law I settled on, the runner owns the safety envelope and the child owns the work. A headless session cannot mind its manners, it won’t maintain a lock, it won’t notice a sibling, it dies without cleaning up. So the runner does all of that on its behalf. It takes the claim on the target before spawning the child, refreshes the heartbeat on a timer while the child runs, and releases it always, crash included. Manners stop being the child’s job, which means they stop being a hope.

Second, skip, never fight. If the target has a live interactive session, a dirty tree, someone else’s claim, an entry marked as needing me, or two failed attempts already tonight, the runner skips it and logs why. The night never contends with the day. Contention is what mornings are for.

Third, nothing touches main while I sleep. Children commit to their own trees, and where pushing is enabled at all, the runner pushes the night’s work to an isolated per-night branch and restores whatever branch was checked out before. I review drained work the way I ‘d review a colleague’s branch, not by discovering it merged.

The rule I ‘d defend hardest though is the unconditional report. A report gets written even when there was nothing to do. This sounds trivial and it changes everything, because it converts silence into signal. An absent report can only mean the job died. Before this rule, a quiet morning meant either a quiet night or a broken scheduler, and I had to go check which. Automation you have to check up on is just work with extra steps.

And underneath it all, ceilings. A cap on children per night, a cap on retry rounds, a watchdog per child. I set them before the first unattended run, not after the first runaway, which I recommend as an ordering.

The morning read is the acceptance test for the whole thing. If the report can’t tell me what happened, what was skipped and why, and what needs me, inside two minutes, then the report is the bug. So far the bug list has been short. The coffee helps.