@expo/code-review-cli 0.4.0 → 0.5.0

package/README.md

@@ -41,21 +41,33 @@ Scaffold, add credentials, verify.
 npx @expo/code-review-cli init
 ```
 
-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:
+Then give it model credentials. **Default: an OpenAI API key** — the scaffolded
+config reviews with GPT via `auth.mode "api-key"`.
+
+Create the key in the OpenAI dashboard, scoped to the minimum the reviewer needs:
+
+- Put it in a **dedicated project** (not "Default project") so you can set a
+  monthly budget + alert on it and see the reviewer's spend in isolation.
+- Make it a **Restricted** key with exactly two permissions, both under *Model
+  capabilities*: **Responses (/v1/responses) → Request** and **Chat completions
+  (/v1/chat/completions) → Request**. Everything else — including *List models* —
+  stays **None** (the reviewer resolves model ids from its own catalog and only
+  ever makes inference requests).
 
 ```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...
+export OPENAI_API_KEY=sk-proj-...
 # Check env, config, and credentials
 npx @expo/code-review-cli doctor
 ```
 
-Prefer an Anthropic **API key**, or **OpenAI/GPT** or another provider? See
-[Other providers & auth modes](#other-providers) at the bottom.
+In CI, store the same key as the `OPENAI_API_KEY` repo secret (the scaffolded
+workflow forwards it).
+
+**Have a ChatGPT Plus/Pro (Codex) subscription? Use both.** The recommended
+production setup pairs the subscription (runs the default models at no marginal
+cost) with the usage-based key (covers only the pro-tier models the subscription
+excludes) — see [the mixed setup](#other-providers) below. Prefer
+**Anthropic/Claude** or another provider? Same section.
 
 ### Reviewing (already configured)
 
@@ -142,7 +154,7 @@ your-monorepo/
   // Central guardrails every scope inherits and CANNOT override.
   "defaults": {
     // The ONLY place auth/tokenEnv is honored (besides the root config.jsonc).
-    "auth": { "mode": "oauth", "provider": "anthropic", "tokenEnv": "ANTHROPIC_OAUTH_API_KEY" },
+    "auth": { "mode": "api-key", "provider": "openai", "tokenEnv": "OPENAI_API_KEY" },
     "enforceAgents": ["security"],            // always runs on every scope, roster or not
     "commentTag": "expo-ai-code-reviewer"     // per-scope markers derive from this
   },
@@ -160,7 +172,7 @@ your-monorepo/
 // server/www/.expo-code-review/config.jsonc  (the www team owns this)
 {
   // NO "auth" block — locked centrally; a tokenEnv here is rejected by loader + CI guard.
-  "model": "anthropic/claude-sonnet-5",
+  "model": "openai/gpt-5.5",
   "policy": { "includeSuggestions": false },
   "noise":  { "additionalIgnores": ["server/www/**/__generated__/**"] }
   // shared.md, coordinator.md, agents/*.md live beside this file — the www team's roster.
@@ -185,7 +197,7 @@ your-monorepo/
   the override swaps the root config/manifest against the *real* scope tree, it
   does not relocate the scopes themselves.**
 - **Passes budget** — `defaults`-level `budget` bounds total review time:
-  `totalPassesMinutes` (default 32) is split across active scopes (which run
+  `totalPassesMinutes` (default 55) is split across active scopes (which run
   sequentially in one `ecr ci`), clamped up to `minScopeMinutes` (default 5) so a
   single scope still gets a workable window. When enough scopes are active that the
   floor would overshoot the total, `ecr ci` keeps the floor but warns, and `ecr
@@ -249,7 +261,7 @@ Ownership is enforced with CODEOWNERS: `/.expo-code-review/routing.jsonc @your-i
   suppressed.
 
 Built on the [OpenCode](https://opencode.ai) SDK, which spawns the model provider
-and applies Anthropic prompt caching automatically.
+and applies the provider's prompt caching automatically.
 
 </details>
 
@@ -269,16 +281,17 @@ cache, in three places:
   a CI artifact) with the same totals plus per-pass `agentTokens`, the raw
   per-agent findings, coverage notes, and what the verifier dropped.
 
-**How the caching works.** Anthropic prompt caching is a *prefix match*: the
-provider caches the rendered prompt up to a marker, and any byte change anywhere
+**How the caching works.** Provider prompt caching is a *prefix match*: the
+provider caches the rendered prompt up to a point, and any byte change anywhere
 in that prefix invalidates everything after it. The reviewer is laid out so the
 prefix is stable — the system prompt (`shared.md` + the agent's own `.md`) is
 byte-identical for every chunk an agent reviews, while the volatile parts (the
 diff, file lists, PR metadata) travel in the user message *after* the prefix and
-never touch it. The first call per agent **writes** the cache (`cache write`,
-billed ~1.25× the input price); every later chunk in the run **reads** it
-(`cache read`, ~0.1× the input price). Cache entries live ~5 minutes and are
-refreshed on use, which comfortably covers a run's concurrent calls.
+never touch it. OpenAI caches automatically (no write premium; cached input is
+billed at a steep discount and shows up as `cache read`); Anthropic charges a
+small premium to **write** the cache (~1.25× input) and ~0.1× input to **read**
+it. Entries live minutes, refreshed on use — comfortably covering a run's
+concurrent calls.
 
 **Reading the numbers.** Hit rate = `cache read / (cache read + input)` — the
 share of prompt tokens served from cache instead of being reprocessed at full
@@ -317,7 +330,7 @@ show writes (there is nothing to re-read within the run).
 ---
 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
+model: openai/gpt-5.5-pro     # override the default model
 temperature: 0.1
 ---
 
@@ -326,14 +339,14 @@ temperature: 0.1
 
 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`.
+— correctness/security/consistency agents, a stronger model for security + the
+coordinator, and per-repo `noise.additionalIgnores`.
 
 `config.jsonc` (JSONC — comments + trailing commas supported):
 
 ```jsonc
 {
-  "model": "anthropic/claude-sonnet-5",       // default model for the specialists
+  "model": "openai/gpt-5.5",                  // default model for the specialists
   "policy": { "includeSuggestions": false },  // suppress suggestion-severity findings
   "chunk": { "maxChangedLines": 1000, "maxFiles": 20, "concurrency": 6 },
   "noise": { "additionalIgnores": ["packages/*/build/**"] },
@@ -342,8 +355,8 @@ per-repo `noise.additionalIgnores`.
               "skipLabel": "ai-review:skip" }, // "label" (only labeled PRs)
   "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": "ANTHROPIC_OAUTH_API_KEY" }
+  "auth": { "mode": "api-key", "provider": "openai",
+            "tokenEnv": "OPENAI_API_KEY" }
 }
 ```
 
@@ -357,14 +370,19 @@ Precedence: **`REVIEWER_MODEL` env** (global override) → per-file **frontmatte
 setup, and a developer can override everything locally.
 
 - **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.
+  reasoning-tier model — **`openai/gpt-5.5`** is the quality/speed sweet spot
+  (the scaffolded default). The **pro tier** finds more but is slower and more
+  expensive, so scope it to the highest-stakes agent: **security runs on
+  `openai/gpt-5.5-pro`** (set in `security.md` frontmatter), the rest on the default.
 - **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).
+  (e.g. `openai/gpt-5.4-mini`) is the most direct lever (a real recall tradeoff —
+  measure it).
+- **Every run logs which model actually answered each pass** — in the job log
+  (`Models used — …`), the Actions step summary table, and the run log's
+  `agentModels` — and warns loudly if a pass ran on a different model than
+  configured, so a provider-side substitution can never pass unnoticed.
 
 There is no automatic cross-provider "equivalent" fallback — that would silently
 change which model reviewed your code. Use an explicit override instead.
@@ -374,16 +392,32 @@ change which model reviewed your code. Use an explicit override instead.
 <details>
 <summary><b>Reliability</b> — never hangs, never silently drops work</summary>
 
-- **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).
+- **Per-task time caps** — chunk passes 15 min; coordinator 10 min. A global passes
+  budget (55 min) bounds all passes incl. the subdivision waves, fitting inside the
+  CI job's `timeout-minutes` (90).
+- **The cross-file pass is elastic** — it gets whatever is left of the passes budget
+  rather than a fixed cap, because it's the one pass whose scope can't be traded for
+  convergence: halving its file set deletes exactly the coverage it exists for. Chunk
+  passes run alongside it under their own caps, so a long cross-file pass doesn't
+  starve them.
 - **Tool-call cap** — a pass that makes too many `read`/`grep` calls without
   finishing is *wandering*, not converging; hitting the cap trips the soft landing.
+  The cross-file ceiling scales with the diff's file count (its diffs are inlined, so
+  tool calls go to *tracing*, not fetching).
+- **Stall detection** — a pass whose reply stops changing entirely (no new tool call,
+  no streamed text or reasoning, no token growth) has a wedged model request, not a
+  hard problem. After 4 min of silence it's abandoned and retried once from a clean
+  session, inside the same budget — instead of spending the whole cap on a dead
+  request. Progress lines say how long a reply has been silent, so this is legible in
+  the CI log.
 - **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** — 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
+  Tools are disabled for that request, so the salvage step can't resume investigating
+  instead of answering.
+- **Subdivide-on-timeout** — a reviewer 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 (the cross-file pass
+  skips straight to the fallback, which still sees the whole 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) — separate from the timeout path.
@@ -448,23 +482,72 @@ visible even in CI (where the run log is ephemeral).
 <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`
+The recommended setup is an OpenAI API key — see Usage above. Alternatives, all
+set in `config.auth` (credentials come from OpenCode):
+
+- **ChatGPT/Codex subscription (OAuth) + usage-based API key — the recommended
+  mix.** OpenAI permits subscription auth in third-party tools, and OpenCode
+  ships the plugin for it — so the reviewer runs its default models on the
+  subscription (zero marginal cost) and reserves the metered key for pro-tier
+  models the subscription doesn't offer (`gpt-5.5-pro` is subscription-excluded).
+  Use the per-provider map form:
+
+  ```jsonc
+  "auth": { "providers": {
+    "openai":     { "mode": "oauth",   "tokenEnv": "CODEX_OAUTH_REFRESH_TOKEN" },
+    "openai-api": { "mode": "api-key", "tokenEnv": "OPENAI_API_KEY", "upstream": "openai" }
+  } }
+  ```
+
+  `openai-api` is an alias the reviewer synthesizes in the OpenCode config
+  (`upstream` names the SDK it's backed by): agents reference `openai-api/gpt-5.5-pro`
+  in frontmatter while everything else stays on `openai/gpt-5.5`. Notes:
+
+  - **The oauth `tokenEnv` holds the refresh token** from an `opencode auth login`
+    ChatGPT sign-in (copy `.openai.refresh` out of OpenCode's `auth.json`) —
+    access tokens are short-lived, so the refresh token is the durable secret and
+    OpenCode mints access tokens on demand. Refresh-token reuse across runs is
+    verified, so a static CI secret works.
+  - **The API key needs the same two permissions** as the default setup above
+    (Responses + Chat completions → Request; all else None), in a budget-capped
+    project.
+  - **In CI**, set the `ECR_EXPECTED_TOKEN_ENV` repo variable to the
+    comma-separated set of both env names
+    (`CODEX_OAUTH_REFRESH_TOKEN,OPENAI_API_KEY`) and pass both secrets in the
+    workflow.
+  - **Auditability**: every pass logs which provider/model answered it (job log,
+    step summary, run log), so the subscription/API split is visible per run.
+    One caveat: OpenCode can't price alias models (they're config-declared), so
+    pro passes report `$0` in the run log's cost column — token counts are
+    correct, and the OpenAI project dashboard is the source of truth for spend.
+- **Anthropic / Claude (API key)** — set `auth.provider` to `"anthropic"`, point
+  `tokenEnv` at the env var holding a Console API key (e.g. `ANTHROPIC_API_KEY`),
+  and use `anthropic/...` model ids; the key is sent as `x-api-key`. Note that
+  Claude Pro/Max **subscription** tokens cannot be used here: Anthropic prohibits
+  them in third-party tools, and OpenCode has no Anthropic OAuth support — only an
+  API key works.
+- **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).)*
+  e.g. `REVIEWER_MODEL=google/gemini-3-pro`. It overrides every agent's model
+  and uses your OpenCode login, so no `auth` block is needed. *(Per-agent
+  provider mixing beyond the alias mechanism above 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.
 
+**Setup errors fail fast, with the fix in the message.** A bad credential or model id
+would otherwise fail every pass identically — a run that spends its whole budget
+rediscovering one fixable thing, then reports N coverage gaps. So before any pass runs:
+
+- **The credential's shape is checked.** OpenCode refuses a malformed credential by
+  dropping the provider entirely, which then surfaces as "model not found" for every
+  model, with nothing pointing at the credential. A truncated value, surrounding
+  whitespace, or a token that can't work for the configured `auth.mode` is rejected
+  by name.
+- **Configured model ids are checked against the running server**, so a typo or an id
+  the provider doesn't have is reported once, up front, with the close matches.
+- **`ecr doctor` reports the `opencode` version actually in use** and warns when a
+  different one is first on your `PATH` — runs use the version this package pins.
+
 </details>

package/build/commands/ci.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { loadAuthFromRoot, loadReviewConfig, loadScopeConfig } from "../config/load.js";
+import { loadAuthFromRoot, loadReviewConfig, loadScopeConfig, tokenEnvMismatch, } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopedCommentTag, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
 import { repoRoot, run } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
@@ -128,9 +128,12 @@ async function runLegacyCi(repo, prNumber, cwd, agents, route, bypassTriggerGate
     // bash guard is a text sweep (layer 2) and can't see through JSON escapes; this
     // check compares the tokenEnv the loader actually honors.
     const expectedTokenEnv = process.env.ECR_EXPECTED_TOKEN_ENV;
-    if (expectedTokenEnv && config.auth.tokenEnv !== expectedTokenEnv) {
-        process.stderr.write(`CI reviewer: auth.tokenEnv "${config.auth.tokenEnv ?? "(none)"}" != ECR_EXPECTED_TOKEN_ENV "${expectedTokenEnv}"; refusing to run.\n`);
-        return;
+    if (expectedTokenEnv) {
+        const mismatch = tokenEnvMismatch(config.auth, expectedTokenEnv);
+        if (mismatch) {
+            process.stderr.write(`CI reviewer: ${mismatch}; refusing to run.\n`);
+            return;
+        }
     }
     // Config-driven trigger policy (.expo-code-review/config.jsonc → review): decide
     // whether this PR should be reviewed at all (bypassed by a manual /review).
@@ -225,8 +228,9 @@ async function runRoutedCi(manifest, repo, prNumber, cwd, agents, route, scopesF
     const expectedTokenEnv = process.env.ECR_EXPECTED_TOKEN_ENV;
     if (expectedTokenEnv) {
         const honored = loadAuthFromRoot(rootConfig, manifest);
-        if (honored.tokenEnv !== expectedTokenEnv) {
-            process.stderr.write(`CI reviewer: honored auth.tokenEnv "${honored.tokenEnv ?? "(none)"}" != ECR_EXPECTED_TOKEN_ENV "${expectedTokenEnv}"; refusing to run.\n`);
+        const mismatch = tokenEnvMismatch(honored, expectedTokenEnv);
+        if (mismatch) {
+            process.stderr.write(`CI reviewer: honored ${mismatch}; refusing to run.\n`);
             return;
         }
     }

package/build/commands/doctor.js

@@ -1,8 +1,10 @@
-import { loadReviewConfig, loadScopeConfig, loadAuthFromRoot, hasConfig, resolveConfigDir, } from "../config/load.js";
+import { loadReviewConfig, loadScopeConfig, loadAuthFromRoot, hasConfig, resolveConfigDir, tokenEnvMismatch, } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
 import { checkProviderAuth } from "../core/auth.js";
+import { opencodeBinSource } from "../core/opencode.js";
 import { git, onPath, repoRoot, run } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
+import path from "node:path";
 const USAGE = `ecr doctor — check environment, config, and credentials
 
 Usage:
@@ -16,6 +18,19 @@ ownership over tracked files, and comment-tag uniqueness.
 Options:
   --list-scopes   Print the routing scope table (name, dir, paths, agents, tag)
 `;
+/**
+ * `opencode --version`, run from `binDir` if given (so the bundled CLI can be asked
+ * directly) or from PATH otherwise. Null when it can't be determined — a version we
+ * can't read is worth staying quiet about, not failing over.
+ */
+async function opencodeVersion(binDir) {
+    const command = binDir ? path.join(binDir, "opencode") : "opencode";
+    const { stdout, code } = await run(command, ["--version"], { check: false });
+    if (code !== 0) {
+        return null;
+    }
+    return stdout.trim().split("\n")[0]?.trim() || null;
+}
 /** Preflight checks so a broken setup surfaces clearly instead of silently no-opping. */
 export async function doctorCommand(argv = []) {
     if (argv.includes("-h") || argv.includes("--help")) {
@@ -47,10 +62,32 @@ export async function doctorCommand(argv = []) {
     if (process.env.ECR_CONFIG_DIR) {
         info(`ECR_CONFIG_DIR override active: root config.jsonc and routing.jsonc read from ${resolveConfigDir(root)} (scope subtrees stay repo-root-relative)`);
     }
-    const opencodeInstalled = await onPath("opencode");
+    // The SDK spawns a bare `opencode`, so the version that actually runs is a PATH
+    // lookup. Report which one wins and whether it matches the version this package
+    // pins: a stale global install against a newer SDK rejects model ids the SDK
+    // considers valid (`ProviderModelNotFoundError`), which is otherwise a baffling
+    // failure that only reproduces on one machine. `startOpencode` prepends our own
+    // bin dir so the pinned one wins at runtime — this just makes the drift visible.
+    const bin = opencodeBinSource();
+    const opencodeInstalled = (await onPath("opencode")) || bin.pinned;
     line(opencodeInstalled, opencodeInstalled
-        ? "opencode CLI found on PATH"
-        : "opencode CLI NOT on PATH (install `opencode-ai`, or add node_modules/.bin to PATH)");
+        ? "opencode CLI available"
+        : "opencode CLI NOT found (install `opencode-ai`, or add node_modules/.bin to PATH)");
+    if (opencodeInstalled) {
+        const pinnedVersion = bin.pinned ? await opencodeVersion(bin.dir) : null;
+        const pathVersion = await opencodeVersion(null);
+        if (pinnedVersion) {
+            line(true, `opencode ${pinnedVersion} (bundled with this reviewer; used at runtime)`);
+            if (pathVersion && pathVersion !== pinnedVersion) {
+                warn(`a different opencode ${pathVersion} is first on your PATH — runs use the bundled ${pinnedVersion}, ` +
+                    `but other tooling (and \`opencode\` by hand) will use ${pathVersion}`);
+            }
+        }
+        else if (pathVersion) {
+            warn(`using opencode ${pathVersion} from PATH — this reviewer's own \`opencode-ai\` dependency could not be ` +
+                `resolved, so the CLI and SDK versions can drift (a stale CLI rejects model ids the SDK accepts)`);
+        }
+    }
     line(await onPath("git"), "git found on PATH");
     // `gh` is only needed for `ecr ci` (posting PR comments), so treat it as
     // informational (ℹ) rather than a hard failure for local `ecr review` users.
@@ -84,6 +121,11 @@ export async function doctorCommand(argv = []) {
             line(rootConfig.agents.every((a) => Boolean(a.promptText.trim())), "all agent prompt files resolved and non-empty");
             const readiness = checkProviderAuth(rootConfig);
             line(readiness.ok, `auth: ${readiness.detail}`);
+            // A suspicious-but-not-provably-broken credential: worth saying, never a failure
+            // (the shape rules are heuristics — see checkOauthTokenShape).
+            if (readiness.warning) {
+                warn(`auth: ${readiness.warning}`);
+            }
         }
         catch (error) {
             line(false, `config invalid: ${errorMessage(error)}`);
@@ -139,14 +181,18 @@ export async function doctorCommand(argv = []) {
         // auth singleton: exactly one honored source (defaults.auth or root config auth).
         const auth = loadAuthFromRoot(rootConfig, manifest);
         const hasManifestAuth = Boolean(manifest.defaults.auth);
-        line(true, `auth singleton: honored from ${hasManifestAuth ? "routing.jsonc defaults.auth" : "root config.jsonc"} (${auth.mode}/${auth.provider})`);
-        if (auth.tokenEnv) {
-            const expected = process.env.ECR_EXPECTED_TOKEN_ENV;
-            if (expected && expected !== auth.tokenEnv) {
-                line(false, `auth.tokenEnv "${auth.tokenEnv}" != ECR_EXPECTED_TOKEN_ENV "${expected}"`);
+        line(true, `auth singleton: honored from ${hasManifestAuth ? "routing.jsonc defaults.auth" : "root config.jsonc"} ` +
+            `(${auth.map((entry) => `${entry.mode}/${entry.provider}`).join(", ")})`);
+        const expected = process.env.ECR_EXPECTED_TOKEN_ENV;
+        if (expected) {
+            const mismatch = tokenEnvMismatch(auth, expected);
+            if (mismatch) {
+                line(false, `auth: ${mismatch}`);
             }
-            else {
-                line(Boolean(process.env[auth.tokenEnv]), `auth token env ${auth.tokenEnv} is ${process.env[auth.tokenEnv] ? "set" : "NOT set"}`);
+        }
+        for (const entry of auth) {
+            if (entry.tokenEnv) {
+                line(Boolean(process.env[entry.tokenEnv]), `auth token env ${entry.tokenEnv} (${entry.provider}) is ${process.env[entry.tokenEnv] ? "set" : "NOT set"}`);
             }
         }
         // Owner-table dry run over tracked files (graft 4).

package/build/commands/verify-config.js

@@ -14,15 +14,17 @@ The canonical pre-review guard (ships with the CLI). It sweeps EVERY
 plain recursive walk (skipping node_modules/.git, so a staged-but-unreferenced
 config can't hide from git's index), parses each with the real comment-aware JSONC
 parser (never regex-scraping), and refuses to run (exit 1) when:
-  • auth.tokenEnv (config) / defaults.auth.tokenEnv (routing.jsonc) appears more
-    than once, or in a non-root file, or — with --expected / ECR_EXPECTED_TOKEN_ENV
-    set — differs from the expected name or is absent (count must be exactly one);
+  • a tokenEnv (auth.tokenEnv, or any auth.providers.<id>.tokenEnv; routing.jsonc:
+    same under defaults.auth) appears in a non-root file, in more than one root
+    file, twice under the same name, or — with --expected / ECR_EXPECTED_TOKEN_ENV
+    set (comma-separated) — the declared set differs from the expected set;
   • a non-root config declares auth, breakGlass, or commentTag (root-locked keys);
   • any file fails to parse (fail-closed), reporting the parse error.
 Exit 0 = safe to run the review.
 
 Options:
-  --expected <ENV_NAME>   Require tokenEnv to equal this (else ECR_EXPECTED_TOKEN_ENV).
+  --expected <ENVS>       Require the declared tokenEnv set to equal this
+                          comma-separated set (else ECR_EXPECTED_TOKEN_ENV).
   --json                  Emit {ok, findings:[{file, problem}]} on stdout.
 `;
 const CONFIG_FILENAMES = new Set(["config.jsonc", "config.json", ROUTING_FILENAME]);
@@ -63,22 +65,38 @@ function asObject(value) {
         ? value
         : undefined;
 }
+/** Every tokenEnv an auth block names — legacy single, or one per providers entry. */
+function collectTokenEnvs(auth) {
+    if (!auth) {
+        return [];
+    }
+    const found = [];
+    if (typeof auth.tokenEnv === "string") {
+        found.push(auth.tokenEnv);
+    }
+    const providers = asObject(auth.providers);
+    for (const entry of Object.values(providers ?? {})) {
+        const tokenEnv = asObject(entry)?.tokenEnv;
+        if (typeof tokenEnv === "string") {
+            found.push(tokenEnv);
+        }
+    }
+    return found;
+}
 /** Read the security-relevant declarations from a parsed config/routing object. */
 function extractFacts(file, parsed) {
     if (path.basename(file) === ROUTING_FILENAME) {
         // routing.jsonc locks auth under defaults.auth (defaults.auth.tokenEnv).
         const defaults = asObject(parsed.defaults);
-        const auth = asObject(defaults?.auth);
         return {
-            tokenEnv: typeof auth?.tokenEnv === "string" ? auth.tokenEnv : undefined,
+            tokenEnvs: collectTokenEnvs(asObject(defaults?.auth)),
             declaresAuth: Boolean(defaults) && "auth" in defaults,
             declaresBreakGlass: false, // routing.jsonc has no breakGlass concept
             declaresCommentTag: Boolean(defaults) && "commentTag" in defaults,
         };
     }
-    const auth = asObject(parsed.auth);
     return {
-        tokenEnv: typeof auth?.tokenEnv === "string" ? auth.tokenEnv : undefined,
+        tokenEnvs: collectTokenEnvs(asObject(parsed.auth)),
         declaresAuth: "auth" in parsed,
         declaresBreakGlass: "breakGlass" in parsed,
         declaresCommentTag: "commentTag" in parsed,
@@ -113,8 +131,8 @@ export async function verifyConfig(root, options = {}) {
             continue;
         }
         const facts = extractFacts(file, object);
-        if (facts.tokenEnv !== undefined) {
-            tokenEnvOccurrences.push({ file: rel(file), value: facts.tokenEnv, isRoot });
+        for (const value of facts.tokenEnvs) {
+            tokenEnvOccurrences.push({ file: rel(file), value, isRoot });
         }
         if (!isRoot) {
             const locked = [];
@@ -135,38 +153,58 @@ export async function verifyConfig(root, options = {}) {
             }
         }
     }
-    // tokenEnv must appear at most once, only in a root-owned file.
+    // tokenEnvs may only be declared in root-owned files…
     for (const occurrence of tokenEnvOccurrences.filter((o) => !o.isRoot)) {
         findings.push({
             file: occurrence.file,
             problem: `tokenEnv "${occurrence.value}" is declared outside the root config; only a root-owned config.jsonc/config.json or routing.jsonc may name the forwarded credential`,
         });
     }
-    if (tokenEnvOccurrences.length > 1) {
+    // …and all in ONE root file (multiple entries in one auth block are fine —
+    // that's the multi-provider map — but split across files there is no single
+    // honored source and a stale/staged second file could smuggle a credential).
+    const rootOccurrences = tokenEnvOccurrences.filter((o) => o.isRoot);
+    const rootFiles = [...new Set(rootOccurrences.map((o) => o.file))];
+    if (rootFiles.length > 1) {
         findings.push({
-            file: tokenEnvOccurrences.map((o) => o.file).join(", "),
-            problem: `tokenEnv is declared in ${tokenEnvOccurrences.length} files; it must appear exactly once, in a root-owned config`,
+            file: rootFiles.join(", "),
+            problem: `tokenEnv is declared in ${rootFiles.length} root files; all credential env names must live in ONE root-owned config`,
         });
     }
-    // With an expectation set, exactly one root occurrence equal to it is required.
+    // Duplicate names within a file are a config bug worth failing on too: two auth
+    // entries forwarding the same env var means one of them is misconfigured.
+    const seen = new Set();
+    for (const occurrence of rootOccurrences) {
+        if (seen.has(occurrence.value)) {
+            findings.push({
+                file: occurrence.file,
+                problem: `tokenEnv "${occurrence.value}" is declared more than once; each credential env name must appear exactly once`,
+            });
+        }
+        seen.add(occurrence.value);
+    }
+    // With an expectation set, the declared names must equal the expected SET
+    // exactly (comma-separated; order-insensitive). A missing name is as much a
+    // finding as an extra one — a PR must not add, drop, or repoint credentials.
     const expected = options.expected;
     if (expected) {
-        const rootOccurrences = tokenEnvOccurrences.filter((o) => o.isRoot);
-        if (rootOccurrences.length === 0) {
+        const expectedSet = expected
+            .split(",")
+            .map((name) => name.trim())
+            .filter(Boolean)
+            .sort();
+        const declared = [...seen].sort();
+        if (declared.length === 0) {
             findings.push({
                 file: path.join(CONFIG_DIRNAME, "config.jsonc"),
-                problem: `no tokenEnv found, but an expected value "${expected}" is set — exactly one root-owned tokenEnv is required`,
+                problem: `no tokenEnv found, but expected "${expectedSet.join(", ")}" — the root-owned config must name exactly those credential env(s)`,
             });
         }
-        else {
-            for (const occurrence of rootOccurrences) {
-                if (occurrence.value !== expected) {
-                    findings.push({
-                        file: occurrence.file,
-                        problem: `tokenEnv "${occurrence.value}" != expected "${expected}" — a PR must not repoint which secret is forwarded to the model provider`,
-                    });
-                }
-            }
+        else if (JSON.stringify(declared) !== JSON.stringify(expectedSet)) {
+            findings.push({
+                file: rootFiles.join(", ") || path.join(CONFIG_DIRNAME, "config.jsonc"),
+                problem: `declared tokenEnv set [${declared.join(", ")}] != expected [${expectedSet.join(", ")}] — a PR must not add, drop, or repoint which secrets are forwarded to model providers`,
+            });
         }
     }
     return { ok: findings.length === 0, findings };