Reference

Heavy gates run remotely through `gaterun`

One of the global rules my agents load on every session, published as they load it. Links to reference files go to the published copy where there is one.

Source
rob/agents/policy/claude/gate-runner.md
Revision
b4b68b30

gaterun (a private tool, installed on each Mac) runs a worktree’s heavy gate in a container on the arm64 estate gate hosts (gate-*, over the tailnet) instead of on the Mac. Read /Users/<user>/repos/gate-runner/README.md before onboarding a repo, writing a .gaterunner.yaml or diagnosing a run.

  • Default for heavy gates. In a repo with a committed .gaterunner.yaml, run just check, just ci and integration suites as gaterun -- <command>, using the exact form the repo’s AGENTS.md gives. The same goes for a loop’s base and batch gates, flake hunts (-race -count=N on one test), fuzzing and arm64 image builds that push nothing; the gaterun-onboard skill gives each form. Keep fmt, lint and single-package test runs local.
  • Larger Go repos without a contract (a just check of several minutes on the Mac, or testcontainers, envtest or kind suites): onboard the repo while working in it, following the agent-workflows:gaterun-onboard skill (/gaterun-onboard, $gaterun-onboard). Run the gate on both sides once, confirm the same passing package set, then commit .gaterunner.yaml and a one-line AGENTS.md pointer. A failure that happens only remotely is usually a hermeticity bug in a test (it assumes a loopback bind, $HOME, or a tool that refuses root, which user: 1001 covers). Fix the test; never weaken the gate.
  • It runs HEAD plus uncommitted and untracked changes; no push is needed. The exit status is the command’s own; 70 means the runner could not prepare the run and 124 means no slot within --max-wait. A wait for a slot is normal; do not abandon it for a local run.
  • Run it locally instead, and say so, when gaterun is not installed, a gate host is unreachable, or the run exits 70. Do the same when the gate needs a secret or a private network: gate containers hold no credentials and cannot reach RFC1918 ranges or tailnet peers.
  • Never pass a secret as a command argument: the command line is kept in the run metadata.
  • Only rknightion and m7kni origins are accepted; a pull-request branch or one tracking a non-origin remote is refused.
  • Pace several agents on one Mac with gaterun-slot <lane> -- gaterun -- just check.