Skip to content

Lanes

An agent asked to fix a red build has two ways to make it green. It can fix the code, or it can add continue-on-error: true to .github/workflows/ci.yml. To git, both are an ordinary push to the issue branch. Lanes tell them apart:

An agent may change what CI checks, never how CI checks.

A fix, a new test, a new lint finding: that is what CI checks, and the push goes through. A workflow file, the test runner’s config, a coverage threshold: that is how CI checks, and a human looks first.

Lanes are part of the guardrails and on by default. To see them stop a real pipeline edit on your machine, run the pipeline-guard demo.

Every file a push changes falls in one lane, the highest that matches. The push takes the highest lane of any of its files.

LaneFilesWhat happens
humanguardrails.lanes.human (default below)The push waits for your approval. merge_pr never merges the pull request.
second_opinionguardrails.lanes.second_opinion (default: none)The push goes through. merge_pr waits for an approving review from a reviewer on a different backend.
autoeverything elseUnchanged.

The default human lane is short on purpose. It lists the files that decide how a change is checked, not what it does:

.github/** .gitlab-ci.yml .circleci/**
.itervox/** !.itervox/handoff/** WORKFLOW.md
CODEOWNERS .github/CODEOWNERS
jest.config.* vitest.config.* pytest.ini .coveragerc codecov.yml
.golangci.yml Makefile

.itervox/handoff/ is left out because every run commits its handoff there. package.json, pyproject.toml and go.mod are left out too: by path, their test sections cannot be told apart from their dependency lists.

guardrails:
lanes:
human: [".github/**", ".gitlab-ci.yml", ".circleci/**", ".itervox/**", "!.itervox/handoff/**",
"WORKFLOW.md", "CODEOWNERS", ".github/CODEOWNERS", "jest.config.*", "vitest.config.*",
"pytest.ini", ".coveragerc", "codecov.yml", ".golangci.yml", "Makefile",
"tox.ini", "scripts/ci/**"] # your own
second_opinion: ["internal/auth/**", "migrations/**"]
  • Leave human out to keep the default.
  • Setting human replaces the default, so copy it to keep it.
  • human: [] turns the human lane off.

Patterns are gitignore-style, over paths relative to the repository root:

  • * and ? match within one directory, ** spans any number, […] is a class;
  • a pattern with no / matches that name at any depth (Makefile matches services/api/Makefile); one with a / is anchored at the root;
  • a pattern that matches a directory matches everything under it;
  • !pattern excludes what an earlier pattern of the same lane matched;
  • matching is case-sensitive.

A pattern that names no path, or does not parse, is a startup error.

guardrails.lanes is read when the daemon loads its configuration, so a change applies from the next reload. See the guardrails reference.

The guardrails put a pre-push hook on every run Itervox starts. For each ref the agent pushes, the hook lists the changed files through git (git diff --name-only -z --no-renames) and looks each one up in the lanes.

  • A branch the remote already has: the files that changed since the remote tip and that differ from the base branch. Merging the base branch in, as the guardrails tell agents to do, does not count as changing what the base changed.
  • A new branch: the files that differ from its merge base with the base branch. The base is the pull request’s base (the blocker’s branch for a stacked PR, else workspace.base_branch), then agent.base_branch, origin/HEAD, origin/main and main. The first one found wins.
  • Renames count as a deletion plus an addition, so moving a workflow file away is caught too.
  • If the files cannot be listed, the push is treated as human lane.

The lanes come from the policy the daemon writes for the run, built from the daemon’s own WORKFLOW.md and settings files. An edit to WORKFLOW.md or .itervox/ on the issue branch does not change the lanes of that run; it is itself a human-lane change.

A human-lane push is held like an approval command. It shows as Pipeline change on the dashboard (in the Needs-attention row and the issue’s Now panel), in the desktop app, on your phone and as a tracker comment, with the files it changes (up to ten, then “and N more”):

Pipeline change: the agent wants to push changes to .github/workflows/ci.yml (git push origin refs/heads/itervox/eng-1)

  • Reply approve to let that push through once. New commits ask again.
  • Any other reply, or dismissing it, refuses the push. The agent is told your reply, so “fix the code, not the pipeline” reaches it.
  • The agent cannot answer its own request.
  • A tmux session started with New session has no approval channel: the push is refused and the agent is told to ask you.

While the push waits, the run’s idle timeout is suspended, so the agent is not failed for being quiet. agent.turn_timeout_ms still bounds the wait.

A pipeline change, from the held push to the code fix

Needs attention panel with one row: DEMO-1, Pipeline change: the agent wants to push changes to .github/workflows/ci.yml, awaiting reply, with Reply and Open buttons Needs attention panel with one row: DEMO-1, Pipeline change: the agent wants to push changes to .github/workflows/ci.yml, awaiting reply, with Reply and Open buttons
The held push appears in Needs attention on the dashboard, with the files and the git command.
The issue's Now panel: the agent is pushing the branch, Waiting for approval, a Pipeline change badge listing .github/workflows/ci.yml and Makefile, and the changed files The issue's Now panel: the agent is pushing the branch, Waiting for approval, a Pipeline change badge listing .github/workflows/ci.yml and Makefile, and the changed files
The issue's Now panel says what the run waits for and lists the pipeline files.
The Needs-attention row opened for reply: the Pipeline change notice with its two files, and the reply box containing approve The Needs-attention row opened for reply: the Pipeline change notice with its two files, and the reply box containing approve
Reply approve to let this one push through. Itervox still will not merge the pull request.
The same reply box with the text: Rejected: fix the code, not the pipeline. The CI config stays as it is. The same reply box with the text: Rejected: fix the code, not the pipeline. The CI config stays as it is.
Or reject it with a reason. The agent is told your reply.
The Now panel after the rejection: the agent is fixing the total in cart.go and leaving the CI config as it is; changed files are cart.go and cart_test.go The Now panel after the rejection: the agent is fixing the total in cart.go and leaving the CI config as it is; changed files are cart.go and cart_test.go
The agent fixes the code instead. A push that only changes code takes the auto lane and goes through.

The daemon records each issue’s pushes that reached the human or second_opinion lane in .itervox/push_lanes.json. The record survives restarts and is dropped when the issue is done. merge_pr checks it before anything else:

Recorded lanemerge_pr
humanrefused with lane_human, even after you approved the push. Merging a pipeline change is a human’s job.
second_opinionrefused with lane_second_opinion until a reviewer whose backend (claude, codex, …) did not write the change records an approving verdict after the last such push.
noneunchanged

itervox doctor (and itervox config show) print a Lanes section:

Lanes
human: .github/**, WORKFLOW.md
second_opinion: off
WARNING: implementer: verify check test runs `make test`, defined by Makefile, which the agent can change without a human; add it to guardrails.lanes.human

It shows the globs in effect ((default) when human is not set, off for an empty list), warns when the human lane or the guardrails are off, and warns when a signed check runs a command whose definition (Makefile, package.json, tox.ini, a script by relative path, …) is outside the human lane. None of this changes the exit code.

The same rule works in CI, for any agent, with or without the daemon. itervox referee lanes (or the standalone referee binary) sorts a pull request’s files into the same three lanes and exits with the result:

Terminal window
git fetch --no-tags origin main
itervox referee lanes --base origin/main [--head HEAD] [--policy .referee.yml] [--json]
ExitLane
0auto
10second_opinion
20human
2an error (bad ref, malformed policy); never 0

Its policy is .referee.yml, read from the base ref (git show <base>:.referee.yml), never from the branch being judged. A pull request that edits the policy is judged by the old one, and the policy file is always in the human lane. Without a policy file, the human lane is the same default as above.

In GitHub Actions, use the referee Action with mode: lanes. Its fail-on input (human, second_opinion or never) decides which lanes fail the step, and its lane output names the result. If you run Itervox in CI with the GitHub Action, its safer CI mode also refuses a run whose WORKFLOW.md, .itervox/settings.jsonc or .itervox/agents/ differ from the base branch, so a branch cannot relax the lanes it is judged by. See referee for the Action, the policy format and an example workflow that requires a label on human-lane pull requests.

  • Lanes are path patterns. A test-runner setting inside a file that is not in the human lane (package.json’s jest key, pyproject.toml’s [tool.pytest], a conftest.py that skips tests, a test marked skip) is not seen. itervox referee audit reports common ones in CI; code review still matters.
  • Runs on SSH worker hosts are not guarded in this version.
  • Sessions you start by hand are never touched by the shims and the pre-push hook. The itervox hook PreToolUse hook asks before an edit of a human-lane file in your own Claude Code session (Codex: denies).