overnight-agent-guardrails

Overnight agent guardrails

Use this when a user wants to leave a coding agent running unattended and needs the run to be bounded, resumable and checkable afterwards.

When this applies

• "leave it running overnight", "run this unattended", "let it work while I sleep"
• a run that kept going and produced hours of output nobody verified
• wanting a hard ceiling on what one unattended run can cost

What to do

The four scripts ship inside this skill directory, so there is nothing to fetch. Refer to them as $SKILL_DIR below, meaning the folder this file is in.

1. Wrap the existing loop in the runaway guard. It exits nonzero when the run should stop, so it belongs in the while condition:

   while "$SKILL_DIR/runaway-guard" --max-iters 40 --max-minutes 480; do
     ... one bounded unit of work ...
   done
   

   At least one cap is required. It refuses to start with none, because an unbounded loop is the thing it exists to prevent.

2. Put the project's real checks behind the gate, so unchecked work is never accepted:

   "$SKILL_DIR/verify-gate" "npm test" "npm run lint"
   

   Nonzero means stop or escalate, rather than piling more work on a broken base.

3. Write the handoff file at the end of every unit of work, rewritten and not appended. HANDOFF.md in this directory is the template. A fresh run reads that one file and continues.

4. Record events as you go with "$SKILL_DIR/nightlog", then produce the summary with "$SKILL_DIR/morning-brief". The verdict lands on the first line.

Notes

• touch $NIGHTSHIFT_DIR/STOP halts a running loop by hand. That is the whole kill switch.
• There is no daemon. State is one counter directory you can delete to reset.
• Everything is MIT and about 300 lines of bash. Reading it takes ten minutes.