Headless agent runs in CI need receipts

A headless agent run is safe when it leaves receipts a reviewer can read without asking anyone a single question. A headless agent run is an agent session a script or CI job starts with nobody watching the output, like Claude Code, Anthropic's coding agent, kicked off by a cron line at 03:00. The catch is simple: when you take the human out of the loop, you keep every consequence. So the run has to explain itself, because there is no one at the terminal to explain it for you.

That sounds like a tax. It is closer to a swap. The person who used to watch the screen did four jobs, and each one now needs a written stand-in.

Write the explanation, not just the run

The cheap part of going headless is removing the human. The expensive part shows up later, when something breaks and there is no record of what the run intended or touched.

Think of every safety check as a slice of swiss cheese with holes in it. The human watching the terminal was one whole slice. Headless removes that slice entirely, so the remaining slices, written precedence, replay transcripts, connector cards, have to line up or the holes go all the way through.

Another prompt template will not cover that gap. A script that runs while you sleep needs its contract written while you are awake. The good news: the contract is short, and most of it lives in files your tools already read.

Give each absent job a receipt

Here is the swap, one missing human job at a time. Each fix replaces something a person used to do by hand.

Permission creep. Approvals turn into muscle memory long before a run goes headless, and then that muscle memory gets scripted. The Claude Code getting started guide covers hooks, but precedence is yours to write. Put a supremacy clause at the top of CLAUDE.md: which hooks win, which folders need human eyes, where temporary overrides live. The unattended session inherits a written policy instead of inventing one.

Replay gaps. CI happily merges a green check nobody read. The commands ran; the story of why never got recorded. The Codex quickstart gets a job scripted in minutes, which is exactly why the transcript rule has to be yours. Use a replay sandwich: in AGENTS.md, mandate an intent line, then the full command transcript, then a diff summary before any PR opens. A reviewer replays the run from the artifact, not from a memory nobody has.

Connector blast radius. A connector you wired for one pipeline tends to serve every pipeline after it, reaching data nobody put on the diagram. The Model Context Protocol specification defines what a connector can do, not what your CI job should be allowed to touch. Write one connector card per MCP server: allowed actions, forbidden actions, an owner by name, and a rollback. When the 03:00 run misbehaves, the on-call knows what "off" looks like.

Handoff blur. Headless parents spawn child agents, and the summary that comes back quietly drops the paths the children edited. Require a child receipt block: every child returns the paths it touched, the commands it ran, and the tests proving its guards still hold. The PR carries receipts, not a paraphrase.

Here is the boundary file the pipeline reads first. Paste it, then adapt the globs to your repo.

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

The Cursor agent docs describe the interactive version of this contract. Headless runs want the same fences with none of the conversation. The same receipts discipline carries over to test code the agent regenerates, which is where stop using CSS selectors in E2E tests picks up. If you are setting team standards for this, agentic coding governance is the topic to start from.

Build a gate the reviewer can pass alone

A headless PR should answer four questions without a single Slack message. If the answers are all in the PR, the missing human was a convenience you removed, not a control you lost.

Run this checklist before you let any unattended PR merge.

• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.
• Forked agent work lists parent and child responsibilities.
• Red-folder paths received explicit human acknowledgement.

Keep the decisions that need an owner

Receipts make a run auditable. They do not make architecture choices for you. Agents speed up execution, not ownership, so the decisions with real blast radius, threat models, customer promises, rollout timing, stay with the people who answer for them.

A useful habit: run two clocks, one for how fast you ship and one for how well you can explain what shipped. Headless runs only speed up the first clock, and teams that watch only that one pay the difference later.

Common questions

• Are headless agent runs in CI safe for production repos? They are exactly as safe as their receipts. A headless run needs written precedence, a mandated replay transcript, connector cards with named owners, and child receipts for any delegated work. With those four in place, the missing human is a removed convenience, not a removed control. Without them, you have a change you can rerun but not audit.

• What should a headless run log for reviewers? The replay sandwich: an intent line saying what the run was for, the full command transcript, and a diff summary, plus which MCP connectors fired. A reviewer should be able to reconstruct the whole run from the PR alone. If they cannot do that, the run produced a change but not evidence, and the two are different things.

• Who owns an MCP connector that a CI job uses? A named person on the connector card, listed next to the allowed actions, the forbidden actions, and a rollback path. Ownership by team alias rots fast because pipelines outlive the people who wrote them. The card exists so the on-call engineer at 03:00 is reading a name and a rollback, not guessing at what the connector was ever allowed to reach.

• What is the smallest first step? Add the replay sandwich rule to AGENTS.md and stop there for a week. It is the single artifact that separates a pipeline you can audit from one you can only rerun. Once intent, transcript, and diff land in every PR, the connector cards and child receipts are easy follow-ups because the habit of writing things down already exists.

Start with one receipt

Take your most recent headless merge and try to answer the four gate questions from the artifacts alone; every Slack message you reach for is a missing receipt. If you want the full unattended-run contract with gates and rollout order, our training walks teams through it.