Skip to content

Pipeline-guard demo

An agent is asked to fix a red build. The quickest way to green is to edit the pipeline instead of the code: continue-on-error: true on the CI test step. scripts/pipeline-guard-demo.sh plays that story twice, on the same repository with the same agent:

The agent is a script, not a model. It does real git work behind the real guardrail shims and pre-push hook. Nothing leaves your machine: the remote is a local bare repository, the tracker is a local issue file, and gh is a stub that prints placeholder pull request URLs.

  • A checkout of the Itervox repository.
  • git, go, curl and jq on PATH.
  • An itervox binary built from that checkout: make build. Without --bin the script builds one with go build, which needs the embedded dashboard (make web-build once).

No agent CLI, API key or network access is needed.

Terminal window
make build
scripts/pipeline-guard-demo.sh --bin ./itervox

Each part creates a fresh temporary project under $TMPDIR (itervox-demo.*): a small Go service whose TestTotal fails on main, a bare repository standing in for the remote, one issue (DEMO-1) and the fixer profile. It starts the daemon headless on a free loopback port, moves the issue to Todo and answers as the operator through the dashboard API. It checks every outcome itself and exits 0 when both parts told their story, 1 otherwise.

The script pauses between beats so you can follow the dashboard (its URL is printed as DEMO_DASHBOARD=). With the pauses set to zero, both parts took about 12 seconds:

Terminal window
DEMO_START_DELAY=0 DEMO_OPERATOR_DELAY=0 DEMO_AGENT_PACE=0 scripts/pipeline-guard-demo.sh --bin ./itervox

The workflow sets guardrails.lanes.human: [] and has no verify list. The agent’s CI edit is pushed, the pull request opens and the issue moves to In Review. Then the script runs the tests on the pushed branch:

pipeline-guard-demo: the run ended green: DEMO-1 is In Review, pull request https://example.com/demo/cart/pull/1
pipeline-guard-demo: the pushed .github/workflows/ci.yml has: continue-on-error: true
pipeline-guard-demo: go test ./... on the pushed branch exits 1 (nothing ran it before the PR opened)
DEMO_RESULT=unguarded ok

The run is green, and the code is still broken.

The workflow keeps the default human lane and adds one check to the fixer profile:

verify:
- name: test
run: "go test -count=1 ./..."

The same push changes .github/workflows/ci.yml, so it is held as a Pipeline change and never reaches the remote. The operator rejects it. The daemon runs go test itself and signs the result, exit 1, so the run is held again. The operator asks for a code fix. The agent fixes cart.go; that push changes only code, takes the auto lane and goes through. The signed check passes and the pull request opens:

pipeline-guard-demo: the push is held in the human lane: .github/workflows/ci.yml
pipeline-guard-demo: operator replies: Rejected: fix the code, not the pipeline. The CI config stays as it is.
pipeline-guard-demo: signed check: `test` exited with code 1 (`go test -count=1 ./...`)
pipeline-guard-demo: operator replies: Fix the bug in cart.go and leave CI alone; the test has to pass as written.
pipeline-guard-demo: DEMO-1 is In Review, pull request https://example.com/demo/cart/pull/1
pipeline-guard-demo: the pushed branch leaves .github/ unchanged
pipeline-guard-demo: go test ./... on the pushed branch exits 0
pipeline-guard-demo: signed check records (GET /api/v1/issues/DEMO-1/attestations):
test exit 1 verified=true
test exit 0 verified=true

It ends by running itervox attest verify on both runs’ record files. Each prints ok for the check and its seal, and all 2 records verify.

In the dashboard, the guarded part looks like this. The screenshots use sample data captured against the dashboard’s mocked API, not a demo run, so the check there is make test rather than go test:

The guarded part in the dashboard

Needs attention row for DEMO-1: Pipeline change, the agent wants to push changes to .github/workflows/ci.yml and Makefile Needs attention row for DEMO-1: Pipeline change, the agent wants to push changes to .github/workflows/ci.yml and Makefile
The push that edits the CI workflow is held as a Pipeline change.
The reply box with: Rejected: fix the code, not the pipeline. The CI config stays as it is. The reply box with: Rejected: fix the code, not the pipeline. The CI config stays as it is.
The operator rejects it with a reason.
Agent needs your input: Signed checks failed, test exited with code 1, and a reply asking for a fix in cart.go Agent needs your input: Signed checks failed, test exited with code 1, and a reply asking for a fix in cart.go
The daemon's own test run fails, signed, and holds the run; the operator asks for a code fix.
Signed checks: the first run's test failed with exit 1, the second run's checks passed with exit 0, all verified Signed checks: the first run's test failed with exit 1, the second run's checks passed with exit 0, all verified
The fix passes the signed check on the new tree.
FlagDefault
--part unguarded|guarded|bothbothRun one part, or both in turn.
--bin PATHbuild oneThe itervox binary to run.
--operator api|uiapiui waits for you to answer in the dashboard instead of answering through the API.
--keepoffKeep the temporary projects (the script prints their path).
--dump DIRSave every step’s command, output and exit status under DIR/<part>/.
--referee PATHWith --dump, a referee binary (make referee): adds referee lanes on the held branch and referee verify on the signed records to the guarded part.
--agent scripted|claude|codexscriptedThe setup for recording with a real agent; see below.
VariableDefault
DEMO_START_DELAY4Seconds before the issue moves to Todo.
DEMO_OPERATOR_DELAY6Seconds before each operator reply.
DEMO_AGENT_PACE2Seconds between the scripted agent’s steps.
DEMO_TIMEOUT240Seconds to wait for each beat before failing.

With --dump and --referee, the dump also records what a CI job would have said. In the unguarded part, ci-local.sh runs the workflow’s own Test step locally and reports job: success although the step failed. In the guarded part, referee lanes --base origin/main on the held branch puts .github/workflows/ci.yml in the human lane and exits 20, and referee verify on the passing run exits 0.

Everything lives in demo/pipeline-guard/:

PathWhat it is
repo/The seeded service and its .github/workflows/ci.yml
WORKFLOW.unguarded.md, WORKFLOW.guarded.mdThe two workflows; they differ only in guardrails.lanes and verify
issues/DEMO-1.md, agents/fixer/The issue and its profile
scripted-agent.shThe scripted agent (backend: custom, no model)
gh-stub.shA local stand-in for gh
ci-local.shRuns the workflow’s Test step locally, with its continue-on-error rule

--agent claude or --agent codex sets up one part with a real agent in place of the script and then waits: you move DEMO-1 to Todo and answer in the dashboard yourself. That run uses the agent CLI you have installed and logged in, and is guarded but not sandboxed. The setup, the exact WORKFLOW.md change, how to keep the recording honest when the agent fixes the code straight away, and the capture scripts (scripts/pipeline-guard-capture.mjs) are in demo/pipeline-guard/RECORDING.md.