ci: add Antigravity PR reviewer (self-hosted, Ultra)

.github/agy-review.md

@@ -0,0 +1,35 @@
+# Review Style Guide (example)
+
+Copy this to **`.github/agy-review.md`** in any repo that uses the Antigravity PR
+reviewer (a dedicated filename, so it never collides with an existing `GEMINI.md`
+or `AGENTS.md`). Everything here is fed to the reviewer as project-specific rules
+to enforce. Delete what does not apply and add your own. Override the path with
+the `STYLE_GUIDE` env var in the workflow if you prefer a different location.
+
+## Priorities (in order)
+
+1. Correctness and data integrity.
+2. Security: validate all external input at boundaries; no secrets in code, logs,
+   or error messages; prefer allowlists.
+3. Clear error handling: typed results over panics/`unwrap` on untrusted input.
+4. Tests accompany behavior changes.
+
+## Conventions
+
+- Conventional Commits (`feat|fix|docs|refactor|test|chore|perf|build|ci`).
+- Match surrounding code style; smallest correct change; reuse existing utilities.
+- No emojis in code, comments, commits, or docs.
+- Public APIs and non-obvious decisions are documented in the same change.
+
+## What to flag as BLOCKING
+
+- Unvalidated external input reaching a sink (SQL, shell, filesystem, network).
+- Hardcoded credentials or tokens.
+- Breaking changes to a public API or on-disk/wire format without a version bump.
+- Silent failure paths (swallowed errors, ignored return values).
+
+## What to keep as SUGGESTION / NITPICK
+
+- Naming, structure, and readability.
+- Missing tests for non-critical paths.
+- Performance ideas without a measurement (note: profile before optimizing).

.github/workflows/antigravity-review.yml

@@ -0,0 +1,80 @@
+# Antigravity PR Review -- copy this file (and the scripts/ dir) into any repo.
+# Runs a Gemini review on a self-hosted runner using your `agy` OAuth session,
+# so it draws on your Google AI Ultra limits instead of a paid API key.
+#
+# Requires a self-hosted runner registered with the label `agy` on a machine
+# where `agy` is logged in. See ../../README.md for the full setup.
+name: Antigravity PR Review
+
+on:
+  pull_request:
+    types: [opened, reopened]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  review:
+    # SECURITY GATE (a self-hosted runner on a PUBLIC repo executes on real hardware
+    # and spends the owner's Google AI Ultra quota, so "who can start a run" is the
+    # primary control):
+    #  - pull_request: only from a branch in THIS repo. A FORK PR must never schedule
+    #    work on the self-hosted host. GitHub's "require approval for outside
+    #    collaborators" setting is belt-and-suspenders, not the gate — its default only
+    #    covers *first-time* contributors, so a returning outside contributor would
+    #    otherwise get a runner.
+    #  - issue_comment: only `/agy-review` from someone with write access
+    #    (OWNER/MEMBER/COLLABORATOR), so a stranger cannot trigger execution by
+    #    commenting. `scripts/agy-review.sh` re-checks this defensively.
+    if: >-
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request != null &&
+       startsWith(github.event.comment.body, '/agy-review') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+    # Concurrency at the JOB level (NOT workflow level): a job skipped by the `if:`
+    # above never enters the group, so an unrelated `issue_comment` on the PR (e.g.
+    # another review bot commenting) can't cancel an in-progress review. And
+    # cancel-in-progress:false means a second *real* review queues behind the first
+    # instead of killing it. Fixes the race where any comment on the PR aborted the
+    # running review mid-`agy`.
+    concurrency:
+      group: agy-review-${{ github.event.pull_request.number || github.event.issue.number }}
+      cancel-in-progress: false
+    runs-on: [self-hosted, agy]
+    steps:
+      # Check out the DEFAULT BRANCH, never the PR head. This job runs the checked-out
+      # `scripts/agy-review.sh` on a self-hosted runner with a token in the environment,
+      # so taking those scripts from the PR would let the reviewed change rewrite its own
+      # reviewer. The review content is unaffected: the diff is fetched from the API by
+      # `gh pr diff`, not from the working tree. Consequence worth knowing: a PR that
+      # edits the reviewer or the style guide is reviewed by the version already on main.
+      - name: Check out repo (for the style guide + scripts)
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 1
+          # Repo-wide rule (PR #319): no checkout persists credentials. Nothing here
+          # performs an authenticated git network operation — `gh` uses GH_TOKEN.
+          persist-credentials: false
+
+      - name: Run Antigravity review
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # --- optional overrides (uncomment to change) ---
+          # AGY_MODEL: gemini-3-pro        # default: agy's configured model
+          AGY_EFFORT: high                 # low|medium|high
+          # Diff budget. The prompt is passed to agy as a SINGLE argv string, and Linux
+          # caps one argument at MAX_ARG_STRLEN = 32 * PAGE_SIZE = 128 KiB (this is a
+          # separate, much lower ceiling than ARG_MAX). 90 KB leaves room for the
+          # instruction boilerplate + style guide; the script enforces the total cap.
+          MAX_DIFF_BYTES: "90000"
+          # STYLE_GUIDE: .github/agy-review.md   # style guide, loaded if present
+        run: |
+          chmod +x scripts/agy-review.sh scripts/_agy_print.sh
+          scripts/agy-review.sh

CHANGELOG.md

@@ -14,6 +14,37 @@ cycle-accurate core later replaced.
 
 ## [Unreleased]
 
+### Added
+
+- Antigravity PR reviewer (`.github/workflows/antigravity-review.yml` +
+  `scripts/agy-review.sh`): an automated first-pass code review on a self-hosted
+  runner, driven by the `agy` CLI's OAuth session (Google AI Ultra, no metered
+  API key). Runs on PR open/reopen and on an `/agy-review` comment from a
+  contributor with write access, and replaces its own prior comment each run.
+  Review priorities live in `.github/agy-review.md`. CI-only — no crate, no
+  shipped artifact, and no emulation-core change.
+
+### Security
+
+- The reviewer executes on the maintainer's own hardware with a token in scope,
+  so its trigger and execution paths are gated accordingly: fork PRs cannot
+  schedule the job, the automation scripts are checked out from the default
+  branch rather than the PR head (a PR cannot rewrite its own reviewer), `agy`
+  is launched with `GH_TOKEN`/`GITHUB_TOKEN` removed from its environment, the
+  `script(1)` fallback quotes its argv with `printf %q` instead of interpolating
+  env-settable flags into a shell string, the conversation-database fallback is
+  removed outright (agy's store is shared per-user, so it could copy an unrelated
+  session into a public comment, and agy exposes no per-invocation store to scope
+  it to), and prior-comment cleanup is restricted to comments authored by the
+  workflow's own bot. The trust boundary is "`agy` only ever sees a same-repo
+  diff", enforced by two checks because neither trigger is covered by one: the
+  workflow rejects fork PRs on `pull_request`, and the script rejects them again
+  on the `issue_comment` path, where the payload carries no head-repo field and
+  `/agy-review` on a fork PR would otherwise feed in an external diff.
+  Authorizing the commenter is not the same as trusting the diff. `agy --sandbox`
+  is explicitly *not* part of that boundary — upstream reports it can be
+  auto-approved away — and the invocation site says so.
+
 ## [2.2.2] - 2026-07-21 - "Conduit" (libretro buildbot 10/10 + CI supply-chain hardening + single-source toolchain)
 
 A **build, distribution, and CI-integrity patch**. It carries RustyNES onto

scripts/_agy_print.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#
+# _agy_print.sh -- inner helper for the script(1) PTY fallback in agy-review.sh.
+# Only used when `unbuffer` (from the `expect` package) is unavailable.
+#
+# Invoked as:  _agy_print.sh <prompt_file> [agy flags...]
+# (agy-review.sh passes it through `script -qfec` so agy runs attached to a PTY,
+# working around agy issue #76 where `-p` drops stdout on a non-TTY.)
+set -euo pipefail
+prompt_file="$1"; shift
+exec "${AGY_BIN:-agy}" "$@" --print "$(cat "$prompt_file")"