@expo/code-review-cli 0.4.0 → 0.5.1

package/README.md

@@ -26,7 +26,12 @@ flowchart TD
 ## Usage
 
 Run via `npx @expo/code-review-cli <command>` (or the `ecr` / `expo-code-review`
-binary once installed).
+binary once installed). On a repo that already has `.expo-code-review/` set up,
+getting model credentials for local runs is one command:
+
+```bash
+npx @expo/code-review-cli setup-auth
+```
 
 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
@@ -34,28 +39,30 @@ package.
 
 ### First-time setup
 
-Scaffold, add credentials, verify.
-
 ```bash
-# Scaffold .expo-code-review/ + a CI workflow (--no-workflow to skip)
+# 1. Scaffold .expo-code-review/ + a CI workflow (--no-workflow to skip)
 npx @expo/code-review-cli init
+# 2. Get model credentials — guided; prints the export lines for your shell config
+npx @expo/code-review-cli setup-auth
+# 3. Verify env, config, and credentials
+npx @expo/code-review-cli doctor
 ```
 
-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:
+`setup-auth` reads the repo's config and walks through each credential it needs:
+an OpenAI **API key** (the scaffolded default — it prints where to create the key
+and the exact restricted permissions to grant), and/or a **ChatGPT/Codex
+subscription** sign-in (it runs OpenCode's browser login and extracts the token
+for you). `doctor` offers to run it whenever a credential is missing.
 
-```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
-```
+In CI, store the same values as repo secrets (`OPENAI_API_KEY`; plus
+`CODEX_OAUTH_REFRESH_TOKEN` for the mixed setup) — the scaffolded workflow
+forwards them.
 
-Prefer an Anthropic **API key**, or **OpenAI/GPT** or another provider? See
-[Other providers & auth modes](#other-providers) at the bottom.
+**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)
 
@@ -103,6 +110,7 @@ is a ready example to adapt.
 | `ecr init [--no-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) + a CI workflow. |
 | `ecr init --monorepo` | …and add a `routing.jsonc` routing manifest (one default scope). |
 | `ecr init --scope <dir>` | Scaffold a per-team scope under `<dir>` and register it in the manifest. |
+| `ecr setup-auth [--yes]` | Walk through getting model credentials for local runs (ChatGPT sign-in and/or API keys), printing the `export` lines for your shell config. |
 | `ecr review [options]` | Review local changes and print an advisory review (default command). |
 | `ecr review --scope <name>` | Review only one routing scope over just that scope's changed files. |
 | `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
@@ -142,7 +150,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 +168,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 +193,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 +257,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 +277,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 +326,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 +335,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 +351,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 +366,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 +388,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 +478,74 @@ 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 exactly two permissions** — a *Restricted* key with
+    *Model capabilities*: **Responses → Request** and **Chat completions →
+    Request**; everything else (including *List models*) stays None. Create it
+    in a dedicated, budget-capped project. (`ecr setup-auth` prints these
+    instructions too.)
+  - **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/cli.js

@@ -4,6 +4,7 @@ import { dismissCommand } from "./commands/dismiss.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { initCommand } from "./commands/init.js";
 import { reviewCommand } from "./commands/review.js";
+import { setupAuthCommand } from "./commands/setup-auth.js";
 import { verifyConfigCommand } from "./commands/verify-config.js";
 const USAGE = `expo-code-review (ecr) — config-driven AI code reviewer
 
@@ -13,6 +14,7 @@ Usage:
   ecr dismiss --pr <n> <id...>     Hide a finding on a PR (see \`ecr dismiss --help\`).
   ecr undismiss --pr <n> <id...>   Restore a dismissed finding.
   ecr init [--monorepo] [--scope <dir>]   Scaffold .expo-code-review/ in this repo.
+  ecr setup-auth [--yes]   Walk through getting model credentials for local runs.
   ecr doctor [--list-scopes]   Check environment, config, credentials, and scopes.
   ecr verify-config [--expected <env>] [--json]   Refuse to run if a config could redirect the credential (CI guard).
 
@@ -47,6 +49,9 @@ async function main() {
         case "init":
             await initCommand(rest);
             break;
+        case "setup-auth":
+            await setupAuthCommand(rest);
+            break;
         case "doctor":
             await doctorCommand(rest);
             break;

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,12 @@
-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 readline from "node:readline/promises";
+import { setupAuthCommand } from "./setup-auth.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 +20,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 +64,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 +123,34 @@ 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}`);
+            }
+            // A missing credential has a guided fix — offer it right here when someone is
+            // at the terminal, rather than making them find the command in the README.
+            if (!readiness.ok) {
+                if (process.stdin.isTTY && process.stdout.isTTY) {
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+                    let runIt = false;
+                    try {
+                        const answer = (await rl.question("  Run `ecr setup-auth` to fix this now? [Y/n] "))
+                            .trim()
+                            .toLowerCase();
+                        runIt = answer === "" || answer === "y" || answer === "yes";
+                    }
+                    finally {
+                        rl.close();
+                    }
+                    if (runIt) {
+                        await setupAuthCommand([]);
+                    }
+                }
+                else {
+                    info("run `ecr setup-auth` for a guided credential setup");
+                }
+            }
         }
         catch (error) {
             line(false, `config invalid: ${errorMessage(error)}`);
@@ -139,14 +206,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).