@expo/code-review-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,26 +1,95 @@
-# expo-code-review
+# @expo/code-review-cli
 
 A config-driven, multi-agent AI code reviewer. Specialist agents review a diff in
 parallel; a coordinator consolidates their findings into one structured review.
-Runs the same engine locally (advisory) and in CI (posts a PR comment).
+The same engine runs locally (advisory) and in CI (posts one PR comment). The CLI
+is the **engine** — each repo supplies its own agents and settings under
+`.expo-code-review/`, so behavior is configured per-repo, not baked in.
+
+> **Status: experimental.** Comment-only and non-blocking — it never blocks a merge
+> and never auto-approves. See [`ROADMAP.md`](./ROADMAP.md).
+
+Inspired in part by Cloudflare's [_How we built our AI code review bot_](https://blog.cloudflare.com/ai-code-review/).
+
+```mermaid
+flowchart TD
+  SRC["Source<br/>local git · GitHub PR (gh)"] --> FILTER["Noise filter<br/>drop lockfiles · generated · binary"]
+  FILTER --> CHUNK["Chunk<br/>by changed lines (large diffs only)"]
+  CHUNK --> AGENTS["Agents (parallel)<br/>each .md in agents/ · read·grep·glob·list"]
+  CHUNK --> XCUT["Cross-cutting pass<br/>multi-file issues (large diffs)"]
+  AGENTS --> COORD["Coordinator<br/>dedupe · re-judge · decide"]
+  XCUT --> COORD
+  COORD --> VERIFY["Verify<br/>quote-ground · adversarially verify criticals"]
+  VERIFY --> REPORT["Reporter<br/>one PR comment (CI) · terminal (local)"]
+```
 
-> **Status: experimental.** Phase 1 is **comment-only and non-blocking** — it
-> never blocks a merge and never auto-approves. The package is incubated inside
-> `eas-cli` for fast iteration and is intended to graduate into its own repo; see
-> [`ROADMAP.md`](./ROADMAP.md).
+## Usage
 
-The CLI is the **engine**. Each repo supplies its own agents and settings under
-`.expo-code-review/`, so behavior is configured per-repo, not baked in.
+Run via `npx @expo/code-review-cli <command>` (or the `ecr` / `expo-code-review`
+binary once installed).
+
+Reviewing a PR (`--pr`/`ci`) needs the GitHub CLI — `brew install gh && gh auth login`.
+Everything else the reviewer needs (including the `opencode` runtime) ships with the
+package.
+
+### First-time setup
+
+Scaffold, add credentials, verify.
+
+```bash
+# Scaffold .expo-code-review/ + a CI workflow (--no-workflow to skip)
+npx @expo/code-review-cli init
+```
 
-## How it works
+Then give it model credentials. **Recommended: a Claude Pro/Max subscription** — the
+scaffolded config uses OAuth by default, so just mint a token and export it under the
+env var your `config.jsonc`'s `auth.tokenEnv` names:
 
+```bash
+# Mint a Claude Pro/Max token (prints an sk-ant-oat… token)
+claude setup-token
+# Export it under the env var your config.jsonc's auth.tokenEnv names
+export ANTHROPIC_OAUTH_API_KEY=sk-ant-oat...
+# Check env, config, and credentials
+npx @expo/code-review-cli doctor
 ```
-diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coordinator ─▶ reporter
-(git / gh)     drop lockfiles,  by       each agent reviews    dedupe,        one PR comment
-               generated,       changed  every chunk +         re-judge,      (CI) or terminal
-               binary files     lines    a cross-cutting pass   decide         output (local)
+
+Prefer an Anthropic **API key**, or **OpenAI/GPT** or another provider? See
+[Other providers & auth modes](#other-providers) at the bottom.
+
+### Reviewing (already configured)
+
+```bash
+# Review working-tree changes; prints here, posts nothing
+ecr review
+# Review a GitHub PR by number (preview only)
+ecr review --pr 4057
+# …and post it as the PR comment
+ecr review --pr 4057 --post
 ```
 
+In CI it runs automatically from the scaffolded workflows — by label or a `/review`
+comment (see **CI usage**). From Claude Code (or another agent), add a slash command
+that runs it; eas-cli's
+[`/expo-review`](https://github.com/expo/eas-cli/blob/main/.claude/commands/expo-review.md)
+is a ready example to adapt.
+
+### Command reference
+
+| Command | What it does |
+| --- | --- |
+| `ecr init [--no-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) + a CI workflow. |
+| `ecr review [options]` | Review local changes and print an advisory review (default command). |
+| `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
+| `ecr doctor` | Check environment, config, and model credentials. |
+
+(When developing this repo itself, use `bun run src/cli.ts <command>`.)
+
+---
+
+<details>
+<summary><b>How it works</b></summary>
+
 - **Source** — local git (working tree, staged, or a ref range) or a GitHub PR
   (diff + metadata fetched over the `gh` API).
 - **Noise filter** — drops lockfiles, generated bundles/maps, snapshots, files
@@ -33,6 +102,8 @@ diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coo
   run in parallel with read-only repo tools (`read`/`grep`/`glob`/`list`).
 - **Coordinator** — a single pass that dedupes, re-judges severity, and produces
   the final `{ decision, findings, summary }`.
+- **Verify** — quote-grounds every finding against the real file and adversarially
+  verifies criticals, so a confident-but-wrong finding doesn't ship.
 - **Reporter** — posts/updates a single fingerprinted PR comment (CI), or prints
   a grouped summary (local). Findings below the configured severity floor are
   suppressed.
@@ -40,19 +111,10 @@ diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coo
 Built on the [OpenCode](https://opencode.ai) SDK, which spawns the model provider
 and applies Anthropic prompt caching automatically.
 
-## Commands
+</details>
 
-Run via the workspace during incubation (`yarn workspace expo-code-review dev …`),
-or as the `ecr` / `expo-code-review` binary once built/installed.
-
-| Command | What it does |
-| --- | --- |
-| `ecr review [options]` | Review local changes and print an advisory review (default command). |
-| `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
-| `ecr init [--with-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) in this repo. |
-| `ecr doctor` | Check environment, config, and model credentials. |
-
-### `ecr review` options
+<details>
+<summary><b><code>ecr review</code> options</b></summary>
 
 ```
 --base <ref>       Base ref to diff against (default: merge-base with default branch)
@@ -70,18 +132,14 @@ or as the `ecr` / `expo-code-review` binary once built/installed.
 -h, --help         Show help
 ```
 
-Reviewing a PR without checking it out — preview, then optionally post:
-
-```bash
-ecr review --pr 4057            # print the review here; posts nothing
-ecr review --pr 4057 --post     # re-run and post it as the PR comment
-```
-
 `--pr` uses the PR's diff (authoritative) but reads your checked-out files for
 surrounding context; for full fidelity, `gh pr checkout <n>` first and run a plain
 `ecr review`.
 
-## Configuration — `.expo-code-review/`
+</details>
+
+<details>
+<summary><b>Configuration — <code>.expo-code-review/</code></b></summary>
 
 ```
 .expo-code-review/
@@ -101,14 +159,19 @@ surrounding context; for full fidelity, `gh pr checkout <n>` first and run a pla
 ---
 description: One line the router uses to decide relevance.
 alwaysRun: true        # run even when the router would skip this agent
-model: anthropic/claude-sonnet-5     # override the default model (e.g. haiku for the coordinator)
+model: anthropic/claude-sonnet-5     # override the default model
 temperature: 0.1
 ---
 
 # Agent instructions in Markdown…
 ```
 
-### `config.jsonc`
+For a real-world example, see eas-cli's
+[`.expo-code-review/`](https://github.com/expo/eas-cli/tree/main/.expo-code-review)
+— correctness/security/consistency agents, Opus for security + the coordinator, and
+per-repo `noise.additionalIgnores`.
+
+`config.jsonc` (JSONC — comments + trailing commas supported):
 
 ```jsonc
 {
@@ -119,142 +182,115 @@ temperature: 0.1
   "breakGlass": { "marker": "/skip-review" }, // PR body marker that skips the review
   "commentTag": "expo-ai-code-reviewer",      // hidden tag used to find/update the comment
   "auth": { "mode": "oauth", "provider": "anthropic",
-            "tokenEnv": "DO_NOT_USE_EXPERIMENTAL_ANTHROPIC_API_KEY" }
+            "tokenEnv": "ANTHROPIC_OAUTH_API_KEY" }
 }
 ```
 
-JSONC (comments + trailing commas) is supported.
+</details>
 
-## Authentication
+<details>
+<summary><b>Model selection</b></summary>
 
-Model credentials come from OpenCode. Two modes, set in `config.auth`:
+Precedence: **`REVIEWER_MODEL` env** (global override) → per-file **frontmatter
+`model:`** → **`config.jsonc` `model`** (the default). So a repo can run a mixed
+setup, and a developer can override everything locally.
 
-- **`api-key`** — the token in `tokenEnv` is copied into the provider's API-key
-  env var (e.g. `ANTHROPIC_API_KEY`).
-- **`oauth`** — a Claude Pro/Max token (from `claude setup-token`, an
-  `sk-ant-oat…` token, *not* an x-api-key) is written into an isolated OpenCode
-  `auth.json` as a bearer credential, so it uses the native subscription path.
-
-Set **`REVIEWER_MODEL`** to override the model for every agent and use your own
-OpenCode login instead of the repo's configured credentials — handy locally
-(e.g. `REVIEWER_MODEL=openai/gpt-5.4-mini-fast`). There is no shared fallback key;
-if a run fails for lack of credentials, authenticate a provider in OpenCode.
-
-Run `ecr doctor` to diagnose setup.
-
-## Model selection
-
-Models are resolved with this precedence: **`REVIEWER_MODEL` env** (global override)
-→ per-file **frontmatter `model:`** → **`config.jsonc` `model`** (the default). So a
-repo can run a mixed setup, and a developer can override everything locally.
-
-Rules of thumb for the reviewer's workload:
-
-- **Specialist agents** (correctness/security/consistency) do the real bug-finding
-  and benefit from a reasoning-tier model — **Sonnet** is the quality/speed sweet
-  spot (the default for correctness/consistency). **Opus** finds more but is slower
-  and more rate-limited, which makes large-PR timeouts worse — so scope it to the
-  one agent where the extra threat-model reasoning pays off most: **security runs on
-  Opus** (set in `security.md` frontmatter), the rest on Sonnet. This keeps the
-  latency/rate-limit cost to a single agent, and the timeout handling (subdivide +
-  per-fetch deadline) keeps a slow Opus pass from hanging the run.
-- **The coordinator** only consolidates text (no repo tools), so a fast, cheap
-  model — **Haiku** — fits well and keeps the serial tail short. Set it in
-  `coordinator.md` frontmatter.
+- **Specialist agents** (correctness/security/consistency) benefit from a
+  reasoning-tier model — **Sonnet** is the quality/speed sweet spot (default for
+  correctness/consistency). **Opus** finds more but is slower and more
+  rate-limited, so scope it to the highest-stakes agent: **security runs on Opus**
+  (set in `security.md` frontmatter), the rest on Sonnet.
+- **The coordinator** makes the final call (dedupe / re-judge / decide) — worth a
+  strong model; set it in `coordinator.md` frontmatter.
 - If latency/timeouts dominate on big PRs, moving the specialists to a faster model
   is the most direct lever (a real recall tradeoff — measure it).
 
-Example mixed setup:
-
-```jsonc
-// config.jsonc
-"model": "anthropic/claude-sonnet-5"        // default: specialists + cross-file pass
-```
-```markdown
-<!-- security.md frontmatter -->  → Opus for the highest-stakes agent
----
-model: anthropic/claude-opus-4-8
----
-
-<!-- coordinator.md frontmatter --> → Haiku for the text-only consolidation
----
-model: anthropic/claude-haiku-4-5-20251001
----
-```
-
 There is no automatic cross-provider "equivalent" fallback — that would silently
 change which model reviewed your code. Use an explicit override instead.
 
-## Reliability
+</details>
 
-A review must never hang, silently produce nothing, or present an unreviewed
-change as "looks good":
+<details>
+<summary><b>Reliability</b> — never hangs, never silently drops work</summary>
 
-- **Per-task time caps** — focused chunk passes get 15 min; the cross-cutting pass
-  gets 25 min; the coordinator gets 10 min. A global passes budget (32 min) bounds
-  all passes incl. the subdivision waves below, so everything fits inside the CI
-  job's `timeout-minutes` (60), since the coordinator + verification run afterward.
+- **Per-task time caps** — chunk passes 15 min; cross-cutting 25 min; coordinator
+  10 min. A global passes budget (32 min) bounds all passes incl. the subdivision
+  waves, fitting inside the CI job's `timeout-minutes` (60).
 - **Tool-call cap** — a pass that makes too many `read`/`grep` calls without
-  finishing is *wandering*, not converging (the usual cause of a non-convergent
-  timeout). Hitting the cap trips the same soft landing as the time cap.
+  finishing is *wandering*, not converging; hitting the cap trips the soft landing.
 - **Soft landing on timeout** — at either cap, the run is interrupted and the agent
   is asked to return the findings it already has, rather than discarding its work.
-- **Subdivide-on-timeout — the reviewer never silently drops work.** If a pass
-  times out with nothing to show, its chunk is split in half and the halves are
-  re-reviewed (recursively, down to a single file). A chunk that won't converge at
-  13 files almost always converges at 6. If even a single file won't converge, a
-  fast **no-tools fallback** reviews just its inlined diff (a lighter review, but
-  never nothing). Only if *that* can't finish inside the budget is a coverage gap
-  reported — and it is always reported, never silent.
+- **Subdivide-on-timeout** — a pass that times out with nothing to show has its
+  chunk split in half and the halves re-reviewed (recursively, down to a single
+  file), then a fast **no-tools fallback** over the inlined diff. Only a genuinely
+  un-reducible pass reports a coverage gap — and it is always reported, never silent.
 - **Parse failures are retried** (same session, then once in a bounded fresh
-  session); that is separate from the timeout path above.
-- **A failed run never reads as "Approve"** — if every pass fails, the review says
-  it could not complete (treat as unreviewed); if some passes fail, the decision
-  is never a clean approve, and the coordinator is told coverage was reduced.
-- **The coordinator can't sink the run** — if the consolidation step fails, findings
-  are merged deterministically and still posted, rather than thrown away.
-- **Coverage notes** — passes that timed out or failed are listed so a real
-  coverage gap is never silent (routine noise filtering is *not* flagged — it's
-  expected and stays in the run log).
-- **CI always gets a terminal state** — on any failure the PR gets a comment saying
-  the reviewer didn't run, not a stuck reaction and silence.
-
-## CI usage
-
-`ecr init --with-workflow` scaffolds a `pull_request` workflow. In this repo the
-reviewer runs via two workflows, split along a clean line: **comments = one-shot
-actions, labels = persistent configuration.**
-
-- **`expo-code-review-command.yml`** — one-shot `/review` comments (maintainers):
-  - `/review` — run once now; the router picks the agents
-  - `/review all` — run once with every agent
-  - `/review correctness security` — run once with just those agents
-
-  These never change configuration.
-- **`expo-code-review.yml`** — continuous review, configured by **labels**:
-  - `ai-review` — auto-review every push; the router picks the agents
-  - `ai-review:all` — auto-review with every agent
-  - `ai-review:<agent>` — auto-review with only those agents (e.g.
-    `ai-review:security`); combine several to widen the set
-  - `ai-review:skip` — never auto-review this PR (opt-out)
-- **`expo-code-review-dismiss.yml`** — dismiss/restore a finding on a PR (maintainers):
-  - `/dismiss <id> [<id> …] [-- reason]` — hide finding(s); they move to a collapsed
-    "Dismissed" section and stay dismissed across re-reviews
-  - `/undismiss <id> …` — restore them
-
-  Each finding shows a short `` `id:…` `` in the comment. Dismissal is a **display
-  filter only** — the reviewer still analyzes the code every run, and a `critical`
-  or `secrets` finding can never be hidden this way. (Also: an inline
-  `expo-code-review-ignore` comment on/above a line suppresses that line's findings,
-  same critical/secrets carve-out.)
-
-These workflows are comment-only (they never fail the PR's checks). For security,
-they build/run only the trusted base ref (never the PR head) — see the comment at
-the top of each file.
-
-## Run logs
+  session) — separate from the timeout path.
+- **A failed run never reads as "Approve"** — all passes fail → "could not
+  complete"; some fail → never a clean approve, and coverage-reduced.
+- **The coordinator can't sink the run** — if consolidation fails, findings are
+  merged deterministically and still posted.
+- **Coverage notes** — passes that timed out/failed are listed (routine noise
+  filtering is *not* flagged — it's expected and stays in the run log).
+- **CI always gets a terminal state** — on any failure the PR gets a "didn't run"
+  comment, not a stuck reaction and silence.
+
+</details>
+
+<details>
+<summary><b>CI usage</b></summary>
+
+`ecr init --with-workflow` scaffolds a `pull_request` workflow. Split along a clean
+line: **comments = one-shot actions, labels = persistent configuration.**
+
+- **command workflow** — one-shot `/review` comments (maintainers): `/review`
+  (router picks agents), `/review all`, `/review correctness security`. Never
+  changes configuration.
+- **auto workflow** — continuous review, configured by **labels**: `ai-review`
+  (router), `ai-review:all`, `ai-review:<agent>` (e.g. `ai-review:security`;
+  combine to widen), `ai-review:skip` (opt-out).
+- **dismiss workflow** — `/dismiss <id> [… -- reason]` / `/undismiss <id>`
+  (maintainers). Each finding shows a short `` `id:…` ``. Dismissal is a **display
+  filter only** — the reviewer still analyzes everything, and a `critical`/`secrets`
+  finding can never be hidden. (An inline `expo-code-review-ignore` comment on/above
+  a line does the same, with the same critical/secrets carve-out.)
+
+These workflows are comment-only (they never fail the PR's checks). The engine runs
+as the published package via `npx`, so no PR-controlled code is built.
+
+</details>
+
+<details>
+<summary><b>Run logs</b></summary>
 
 Each run appends a JSON line to `.expo-code-review/.runs/reviews.jsonl` with the
 inputs, decision, finding count, duration, per-agent cost, and aggregate token
-usage (including prompt-cache read/write counts) — for auditing and measuring
+usage (incl. prompt-cache read/write counts) — for auditing and measuring
 cost/latency/cache reuse over time.
+
+</details>
+
+<a id="other-providers"></a>
+<details>
+<summary><b>Other providers & auth modes</b></summary>
+
+The recommended setup is a Claude Pro/Max subscription (OAuth) — see Usage above.
+Alternatives, all set in `config.auth` (credentials come from OpenCode):
+
+- **Anthropic API key** — set `auth.mode` to `"api-key"` and point `tokenEnv` at the
+  env var holding the key (e.g. `ANTHROPIC_API_KEY`); it's sent as `x-api-key`. Omit
+  the `auth` block entirely to fall back to OpenCode's own login / `ANTHROPIC_API_KEY`.
+- **OAuth (Pro/Max)** — `tokenEnv` holds an `sk-ant-oat…` token from
+  `claude setup-token` (*not* an x-api-key); it's written to an isolated OpenCode
+  `auth.json` as a bearer credential, using the native subscription path.
+- **OpenAI / GPT, or another provider** — the current path is the `REVIEWER_MODEL`
+  env override: `opencode auth login` once (pick the provider), then run with
+  e.g. `REVIEWER_MODEL=openai/gpt-5.4-mini-fast`. It overrides every agent's model
+  and uses your OpenCode login, so no `auth` block is needed. *(First-class
+  per-provider config — Anthropic/OpenAI/others in `config.jsonc`, and mixing them
+  per agent — is on the [roadmap](./ROADMAP.md).)*
+
+There is no shared fallback key; if a run fails for lack of credentials, authenticate
+a provider in OpenCode. `ecr doctor` diagnoses setup.
+
+</details>

package/build/commands/init.js

@@ -9,12 +9,12 @@ const TEMPLATES_DIR = fileURLToPath(new URL('../../templates/', import.meta.url)
 const USAGE = `ecr init — scaffold .expo-code-review/ in the current repo
 
 Usage:
-  ecr init [--with-workflow] [--force]
+  ecr init [--no-workflow] [--force]
 
 Options:
-  --with-workflow   Also write .github/workflows/expo-code-review.yml
-  --force           Overwrite existing files
-  -h, --help        Show this help
+  --no-workflow   Skip writing the CI workflow (.github/workflows/expo-code-review.yml)
+  --force         Overwrite existing files
+  -h, --help      Show this help
 `;
 export async function initCommand(argv) {
     if (argv.includes('-h') || argv.includes('--help')) {
@@ -32,7 +32,10 @@ export async function initCommand(argv) {
 /** Scaffold .expo-code-review/ (and optionally the CI workflow) into the repo. */
 async function scaffold(argv) {
     const force = argv.includes('--force');
-    const withWorkflow = argv.includes('--with-workflow');
+    // The CI workflow is scaffolded by default (most repos adopting this want it);
+    // `--no-workflow` opts out. `--with-workflow` is still accepted as a no-op for
+    // back-compat.
+    const withWorkflow = !argv.includes('--no-workflow');
     const root = (await repoRoot()) ?? process.cwd();
     const configDir = path.join(root, CONFIG_DIRNAME);
     // Create only the config dir; let copyInto create prompts/ so it reports
@@ -70,8 +73,8 @@ async function scaffold(argv) {
         '  2. Configure a model provider in OpenCode (or set REVIEWER_MODEL).',
         '  3. Run `ecr doctor`, then `ecr review`.',
         withWorkflow
-            ? '  4. Add the model-key secret referenced by the workflow.'
-            : '  4. Run `ecr init --with-workflow` to add the CI workflow.',
+            ? '  4. Add the model-key secret referenced by the workflow, then add an `ai-review` label to a PR.'
+            : '  4. (No CI workflow written — re-run without `--no-workflow` to add it.)',
         '',
     ].join('\n'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/cli.ts",
     "test:unit": "bun test",
+    "release": "bash scripts/release.sh",
     "prepublishOnly": "rimraf build && tsc -p tsconfig.build.json"
   },
   "dependencies": {

package/templates/config.jsonc

@@ -31,14 +31,16 @@
   // HTML marker used to find + update the single PR comment. Keep it stable.
   "commentTag": "expo-ai-code-reviewer",
 
-  // How model credentials are provided.
-  //   "api-key": tokenEnv holds a provider API key (sent as x-api-key). If you
-  //              omit `auth`, OpenCode's own login / ANTHROPIC_API_KEY is used.
+  // How model credentials are provided. Default: a Claude Pro/Max subscription.
   //   "oauth":   tokenEnv holds a Claude Pro/Max OAuth token (from
   //              `claude setup-token`); it's injected as a bearer credential.
+  //   "api-key": tokenEnv holds a provider API key (sent as x-api-key). If you
+  //              omit `auth`, OpenCode's own login / ANTHROPIC_API_KEY is used.
+  // For OpenAI/GPT or another provider, omit `auth` and set REVIEWER_MODEL after an
+  // `opencode auth login` for that provider.
   "auth": {
-    "mode": "api-key",
+    "mode": "oauth",
     "provider": "anthropic",
-    "tokenEnv": "ANTHROPIC_API_KEY"
+    "tokenEnv": "ANTHROPIC_OAUTH_API_KEY"
   }
 }

package/templates/workflow.yml

@@ -2,12 +2,13 @@ name: AI code review
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
 
-# Comment-only: needs to read the repo and write PR comments.
+# Comment-only: read the repo, write PR comments (issue comments API).
 permissions:
   contents: read
   pull-requests: write
+  issues: write
 
 concurrency:
   group: ai-code-review-${{ github.event.pull_request.number }}
@@ -16,28 +17,53 @@ concurrency:
 jobs:
   review:
     runs-on: ubuntu-latest
+    # Opt-in per PR: only run when the `ai-review` label is present. Remove this
+    # line to review every PR automatically.
+    if: contains(join(github.event.pull_request.labels.*.name, ','), 'ai-review')
+    # Backstop so a stalled review fails fast instead of hanging.
+    timeout-minutes: 60
     # A reviewer failure must never fail the PR's checks.
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
-          fetch-depth: 0
+          # Shallow is enough — the reviewer gets the diff from the API (`gh`).
+          fetch-depth: 1
 
-      - uses: actions/setup-node@v4
+      # SECURITY: this workflow checks out the PR's code, including
+      # .expo-code-review/config.jsonc, whose auth.tokenEnv names the env var the CLI
+      # forwards as the model credential. Refuse to run unless it's the expected value
+      # (below / repo var ECR_EXPECTED_TOKEN_ENV) so a PR can't repoint it at another
+      # secret in the runner. Keep this in sync with auth.tokenEnv in config.jsonc.
+      - name: Guard config.jsonc tokenEnv
+        env:
+          EXPECTED: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'ANTHROPIC_OAUTH_API_KEY' }}
+        run: |
+          values=$(grep -oE '"tokenEnv"[[:space:]]*:[[:space:]]*"[A-Za-z0-9_]+"' .expo-code-review/config.jsonc | sed -E 's/.*"([A-Za-z0-9_]+)"$/\1/')
+          count=$(printf '%s\n' "$values" | grep -c .)
+          if [ "$count" != "1" ] || [ "$values" != "$EXPECTED" ]; then
+            echo "::error::.expo-code-review/config.jsonc auth.tokenEnv must be \"$EXPECTED\" (found: \"${values:-none}\"). Refusing to run so a PR can't redirect which secret is forwarded to the model provider."
+            exit 1
+          fi
+
+      - uses: actions/setup-node@v5
         with:
           node-version: 24
+          # The reviewer runs via npx and never installs with a package manager, so
+          # disable setup-node's auto package-manager cache (its post step would try
+          # to save an empty cache and error).
+          package-manager-cache: false
 
       - name: Run AI review
-        # Requires the `expo-code-review` package to be published to npm. Until
-        # then, vendor the CLI or run it from a checkout instead of via npx.
-        # npx installs the CLI and its bundled `opencode` binary and puts them on
-        # PATH for this process.
-        run: npx --yes expo-code-review@latest ci
+        # npx installs @expo/code-review-cli and its bundled `opencode` binary and
+        # puts them on PATH for this process. Pin @latest to a version to freeze it.
+        run: npx --yes -p "@expo/code-review-cli@latest" ecr ci
         continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # OpenCode reads ANTHROPIC_API_KEY. Source it from a dedicated,
-          # code-review-scoped secret. Swap for your provider's key/var.
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY_FOR_CODE_REVIEW }}
-          # Optional: override the model for every agent.
+          # Claude Pro/Max OAuth token (from `claude setup-token`) — the env var
+          # named by auth.tokenEnv in config.jsonc. Store it as a repo secret.
+          # (For an API key instead, set auth.mode "api-key" and pass that key here.)
+          ANTHROPIC_OAUTH_API_KEY: ${{ secrets.ANTHROPIC_OAUTH_API_KEY }}
+          # Optional: override the model for every agent (uses your OpenCode login).
           REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}