feat(backends)!: replace gemini with agy; publish runner images weekly

[KE7]

Replaces the gemini mutation backend with agy (Google's Antigravity CLI),
fixes the runner-image publish workflow so the images actually get
refreshed, and adds a pull-request check that builds and probes every image.

Both changes are independent of the credential-projection work explored on
impl/auth-two-modes. That branch's central idea — giving each candidate a
private copy of the operator's credential — is not adopted here: nothing in
this branch changes how the sandbox authenticates. agy gets the same
whole-$HOME helix-auth-agy mount every other backend already gets.

agy replaces gemini

BREAKING: agent.backend = "gemini" is no longer accepted. Migrate to
"agy" and run helix sandbox login agy; existing helix-auth-gemini
volumes are no longer read.

The migration touches the backend registry, argv construction and output
parsing, the config Literal and CLI --backend choice, a new
docker/agy.Dockerfile, the publish-runners matrices, and every doc, skill,
and test reference. Unlike gemini, agy propagates agent.effort
(--effort low|medium|high) instead of warning that the knob is ignored.

Two things are deliberately claimed no more strongly than they have been
established:

• The credential path the status probe tests
  ($HOME/.gemini/antigravity-cli/antigravity-oauth-token) was derived by
  tracing the CLI's own file opens, not confirmed against a completed
  sign-in. logout therefore removes only ~/.gemini/antigravity-cli,
  never the shared ~/.gemini root.
• agy gets no BACKEND_AUTH_ENV row: naming ambient credential variables
  would assert a shape nobody here has observed. Its --output-format json
  envelope, on the other hand, has been captured (agy 1.1.27): a single
  object with conversation_id, status, response, error (on failure),
  duration_seconds, num_turns, and a usage block of input_tokens /
  output_tokens / thinking_tokens / cache_read_tokens / total_tokens.
  _normalise_usage_stats now maps thinking_tokens to the reasoning
  counter, cache_read_tokens to the cache-read counter, and
  conversation_id to session_id; before this those two token counts were
  always charged as 0. The envelope has no cost field, so cost_usd stays 0
  for agy, and no per-tool event list, so _TRANSCRIPT_TOOL_COUNTERS still
  has no agy entry. The budget tests' agy fixtures are the captured envelope
  rather than an illustrative one.

Argv grammar. agy's -p/--print (alias --prompt) takes the prompt
as its value; it is not a boolean flag like claude's. The argv therefore
puts every other flag first and ends with --print <prompt> as the final
pair. Verified against agy 1.1.27: the old order (--print --output-format json ... <prompt>) exits 2 with --print took "--output-format" as its prompt, while --output-format json --print "<prompt>" --bogus fails only
on --bogus, proving the prompt is consumed as the flag's value. The unit
test now pins --print as the second-to-last element and the prompt as the
last, instead of only asserting "--print" in args. (An earlier revision of
this description claimed --print was boolean after a probe against
agy 1.1.17, which silently ran "--output-format" as the prompt instead of
erroring; that claim was wrong.)

Print timeout. agy's --print-timeout is a Go time.Duration flag
defaulting to 5m0s; when it expires the headless run stops, and per agy's
changelog a mid-turn expiry returns partial output with only a stderr
warning, so a cut-off mutation can look like a finished one. There is no
disable value: 0 and -1s both fail immediately with timeout waiting for response, -1 without a unit is an invalid duration, and no environment
variable or settings key overrides the flag. The argv therefore passes the
largest duration Go can represent, 2562047h47m16.854775807s
(math.MaxInt64 nanoseconds, ~292 years), which agy 1.1.27 accepts and
completes a turn under; 2562048h is rejected, so this is the ceiling of
the flag's type. The maximum was chosen over a 24h cap because every other
backend runs its subprocess with no timeout at all
(test_no_timeout_in_subprocess), and this keeps agy on the same policy.
The flag sits among the leading flags, ahead of the closing --print <prompt> pair; the argv tests pin it to exactly one occurrence, immediately
followed by the value, before --print.

Runner images get published on a schedule

The images were only ever published on a v* tag. The last successful
publish was v0.2.1 on 2026-05-10, so latest had been drifting behind the
agent CLIs' own releases for months. The one attempt to refresh it, a manual
dispatch from feat/agy-backend on 2026-08-24, failed at the manifest step
with can't push with no tags specified, because a non-default branch
produced no tag to push.

Three changes to publish-runners.yml, no new files:

• Weekly schedule trigger (Mondays 12:00 UTC, inside the
  "before 6am on monday" America/Los_Angeles window Renovate uses in chore: add Renovate configuration for automated dependency updates #54). A scheduled run is on
  main, so it publishes latest through the existing tagging rules.
• Verify as node. The post-publish smoke test now runs each CLI's
  version probe as the unprivileged user every agent container runs as, not
  as root. Root cannot see an installer that leaves its binary under /root,
  which is exactly the bug agy.Dockerfile has to work around; this makes
  that class of bug fail the publish instead of the first real run.
• Branch dispatch gets a tag. A single resolve-tag job now decides the
  tag every later job builds against and publishes: the version for a v*
  tag, latest on main, and the branch name (slashes replaced) anywhere
  else. It replaces the two copied shell snippets that previously made the
  same choice and never handled the branch case.

Runner images get a pull-request check

publish-runners.yml pushes latest before it verifies, so a broken
Dockerfile reaches latest before anything notices, and a backend added in
a PR (like agy here) has no published image to probe at all. A new
runner-images.yml workflow closes both gaps: on any PR touching
docker/**, src/helix/backends.py, or the workflow itself, each matrix
leg builds the base image and one backend image from this checkout, then
runs the CLI's version probe as node. No layer cache, so each run installs
the CLI versions a release build would. It is 42 lines of plain YAML with no
bake file or test module.

Gates

• uv run python -m pytest — 985 passed
• uv run ruff check src/ tests/ — clean
• uv run mypy --strict src/helix/ — clean
• actionlint .github/workflows/runner-images.yml — clean
• actionlint .github/workflows/publish-runners.yml — no new findings (the
  four pre-existing SC2046 warnings on the imagetools create lines are
  unchanged from main)
• git diff --shortstat origin/main...HEAD — 17 files changed, 426 insertions(+), 295 deletions(-)

Dockerfile build proof. docker/agy.Dockerfile was built from this
branch (--no-cache, linux/arm64) and exercised as the unprivileged user:

$ docker run --rm --user node --network none --security-opt no-new-privileges <image> sh -lc 'agy --version'
1.1.21
$ ... sh -lc 'id'
uid=1000(node) gid=1000(node) groups=1000(node)

The /opt copy is load-bearing, not cosmetic: /root is mode 0700, and
invoking the installer's own /root/.local/bin/agy as node gives
Permission denied.

🤖 Generated with Claude Code

https://claude.ai/code/session_015HBBoDVQK7baNMQBhgRkh4