@expo/code-review-cli 0.5.0 → 0.5.2

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,34 +39,24 @@ 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
-```
-
-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
-export OPENAI_API_KEY=sk-proj-...
-# Check env, config, and credentials
+# 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
 ```
 
-In CI, store the same key as the `OPENAI_API_KEY` repo secret (the scaffolded
-workflow forwards it).
+`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.
+
+In CI, store the same values as repo secrets (`OPENAI_API_KEY`; plus
+`CODEX_OAUTH_ACCESS_TOKEN` for the mixed setup) — the scaffolded workflow
+forwards them.
 
 **Have a ChatGPT Plus/Pro (Codex) subscription? Use both.** The recommended
 production setup pairs the subscription (runs the default models at no marginal
@@ -115,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. |
@@ -348,7 +344,7 @@ coordinator, and per-repo `noise.additionalIgnores`.
 {
   "model": "openai/gpt-5.5",                  // default model for the specialists
   "policy": { "includeSuggestions": false },  // suppress suggestion-severity findings
-  "chunk": { "maxChangedLines": 1000, "maxFiles": 20, "concurrency": 6 },
+  "chunk": { "maxChangedLines": 1000, "maxFiles": 20 },  // concurrency defaults: 6 (API key) / 3 (subscription)
   "noise": { "additionalIgnores": ["packages/*/build/**"] },
   "review": { "trigger": "all",               // which PRs `ecr ci` reviews: "all"
               "label": "ai-review",            // (default, except ai-review:skip) or
@@ -410,6 +406,15 @@ change which model reviewed your code. Use an explicit override instead.
   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.
+- **Rate limits are detected and waited out, not fought.** The reviewer watches the
+  OpenCode server's own log for provider 429s (hard evidence, per run). A stall
+  *with* recent 429 evidence is throttling, not a wedge — the pass waits in 90s
+  beats (without consuming its one retry) instead of re-sending its whole context
+  into a limited account; explicit 429 errors retry on a slow 15s/45s/90s schedule.
+  Subscription (oauth) runs also default to `concurrency` 3 instead of 6, since one
+  account may be serving several PRs' reviews at once. Rate-limit events are
+  reported in the job log and the run log (`rateLimitEvents`), so throttling is a
+  visible fact about a run, never a mystery slowdown.
 - **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.
   Tools are disabled for that request, so the salvage step can't resume investigating
@@ -494,7 +499,7 @@ set in `config.auth` (credentials come from OpenCode):
 
   ```jsonc
   "auth": { "providers": {
-    "openai":     { "mode": "oauth",   "tokenEnv": "CODEX_OAUTH_REFRESH_TOKEN" },
+    "openai":     { "mode": "oauth",   "tokenEnv": "CODEX_OAUTH_ACCESS_TOKEN" },
     "openai-api": { "mode": "api-key", "tokenEnv": "OPENAI_API_KEY", "upstream": "openai" }
   } }
   ```
@@ -503,17 +508,22 @@ set in `config.auth` (credentials come from OpenCode):
   (`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.
+  - **The oauth `tokenEnv` holds the ACCESS token** from an `opencode auth login`
+    ChatGPT sign-in (`ecr setup-auth` extracts it) — a plain bearer, valid for
+    days, with no rotation involvement. Do **not** use the refresh token as a
+    shared secret: refresh tokens are single-use (rotation), so a static copy is
+    spent by its first use and the sign-in dies with it. Access tokens expire
+    (~10 days observed), so CI secrets need periodic re-minting — see the
+    token-rotator item in the [roadmap](./ROADMAP.md); `doctor` and the run
+    preflight warn before expiry.
+  - **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
+    (`CODEX_OAUTH_ACCESS_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.

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/doctor.js

@@ -1,5 +1,7 @@
 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";
@@ -126,6 +128,29 @@ export async function doctorCommand(argv = []) {
             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)}`);

package/build/commands/setup-auth.js

@@ -0,0 +1,217 @@
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { hasConfig, loadReviewConfig } from "../config/load.js";
+import { jwtExpiryMs } from "../core/auth.js";
+import { opencodeBinSource } from "../core/opencode.js";
+import { errorMessage } from "../core/util.js";
+const USAGE = `ecr setup-auth — set up model credentials for local runs
+
+Reads this repo's .expo-code-review/config.jsonc auth entries and walks through
+getting each credential:
+  • a ChatGPT/Codex subscription (oauth/openai): runs the bundled
+    \`opencode auth login\` (interactive; opens your browser), then prints the
+    \`export <tokenEnv>=…\` line to add to your shell config. An existing
+    OpenCode ChatGPT sign-in is reused instead of re-authenticating.
+  • an API key (api-key entries): prints where to create the key, the exact
+    permissions it needs, and the export line to fill in.
+
+Without a repo config, it offers the recommended ChatGPT/Codex subscription flow
+with the default env name.
+
+Options:
+  --yes   Skip confirmation prompts (still interactive during the login itself).
+`;
+export function planFromAuth(auth) {
+    const plan = { manualKeys: [], unsupported: [] };
+    for (const entry of auth) {
+        if (entry.mode === "oauth" && entry.provider === "openai" && entry.tokenEnv) {
+            plan.chatgptLogin = { tokenEnv: entry.tokenEnv };
+        }
+        else if (entry.mode === "api-key" && entry.tokenEnv) {
+            plan.manualKeys.push({
+                provider: entry.provider,
+                tokenEnv: entry.tokenEnv,
+                upstream: entry.upstream,
+            });
+        }
+        else if (entry.mode === "oauth") {
+            plan.unsupported.push(entry);
+        }
+        // api-key without tokenEnv relies on OpenCode's own login — nothing to set up.
+    }
+    return plan;
+}
+/** Where OpenCode's own (non-isolated) auth.json lives. */
+export function opencodeAuthJsonPath(env = process.env) {
+    const dataHome = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+    return path.join(dataHome, "opencode", "auth.json");
+}
+/**
+ * The stored ChatGPT sign-in's ACCESS token, if OpenCode has a live one. The
+ * refresh token deliberately never leaves OpenCode's store: refresh tokens are
+ * SINGLE-USE (rotation) and OpenCode is their sole legitimate consumer — a copy
+ * in a shell config or CI secret dies on the next rotation and can take the
+ * whole sign-in with it. The access token is a plain bearer that stays valid for
+ * days and never touches rotation.
+ */
+async function readStoredAccessToken() {
+    try {
+        const raw = await readFile(opencodeAuthJsonPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        const openai = parsed.openai;
+        if (openai?.type !== "oauth" || !openai.access) {
+            return null;
+        }
+        const expiresMs = jwtExpiryMs(openai.access) ?? 0;
+        // An expired stored token means the sign-in needs redoing anyway.
+        return expiresMs > Date.now() ? { token: openai.access, expiresMs } : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function confirm(question, skip) {
+    if (skip) {
+        return true;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The line to paste into a shell config. Single-quoted: tokens never contain '. */
+export function exportLine(tokenEnv, value) {
+    return `export ${tokenEnv}='${value}'`;
+}
+export async function setupAuthCommand(argv = []) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const yes = argv.includes("--yes");
+    const out = (line = "") => process.stdout.write(`${line}\n`);
+    const err = (line = "") => process.stderr.write(`${line}\n`);
+    try {
+        // Plan from the repo config when there is one; otherwise offer the
+        // recommended subscription flow with the default env name.
+        let plan;
+        if (hasConfig(process.cwd())) {
+            const config = await loadReviewConfig(process.cwd());
+            plan = planFromAuth(config.auth);
+        }
+        else {
+            err("No .expo-code-review config here — setting up the default ChatGPT/Codex flow.");
+            plan = planFromAuth([
+                { provider: "openai", mode: "oauth", tokenEnv: "CODEX_OAUTH_ACCESS_TOKEN" },
+            ]);
+        }
+        if (!plan.chatgptLogin && plan.manualKeys.length === 0 && plan.unsupported.length === 0) {
+            out("This repo's auth config needs no local credential setup (OpenCode's own login covers it).");
+            return;
+        }
+        const exports = [];
+        if (plan.chatgptLogin) {
+            const { tokenEnv } = plan.chatgptLogin;
+            if (process.env[tokenEnv]) {
+                err(`✓ ${tokenEnv} is already set in this shell — skipping the ChatGPT sign-in.`);
+            }
+            else {
+                let stored = await readStoredAccessToken();
+                if (stored) {
+                    err(`Found a live ChatGPT sign-in in OpenCode (access token valid ` +
+                        `${Math.max(1, Math.round((stored.expiresMs - Date.now()) / 86_400_000))} more day(s)).`);
+                    if (!(await confirm(`Use it for ${tokenEnv}?`, yes))) {
+                        stored = null;
+                    }
+                }
+                if (!stored) {
+                    err("This will run the bundled `opencode auth login` (interactive).");
+                    err("When it prompts:");
+                    err("  1. select the provider:  OpenAI");
+                    err("  2. select the method:    Sign in with ChatGPT  (Codex subscription)");
+                    err("  3. your browser opens — sign in and authorize.");
+                    if (!(await confirm("Run it now?", yes))) {
+                        err("Skipped the ChatGPT sign-in.");
+                    }
+                    else {
+                        const binDir = opencodeBinSource().dir;
+                        const opencode = binDir ? path.join(binDir, "opencode") : "opencode";
+                        const result = spawnSync(opencode, ["auth", "login"], { stdio: "inherit" });
+                        if (result.status !== 0) {
+                            throw new Error(`\`opencode auth login\` exited with ${result.status ?? "a signal"}; nothing was changed.`);
+                        }
+                        stored = await readStoredAccessToken();
+                        if (!stored) {
+                            throw new Error("The login finished but no live ChatGPT sign-in was stored — did you select " +
+                                'OpenAI → "Sign in with ChatGPT"? Re-run `ecr setup-auth` to try again.');
+                        }
+                    }
+                }
+                if (stored) {
+                    // The ACCESS token: a plain bearer, valid for days, no rotation involved.
+                    // (The refresh token stays in OpenCode's store — it is single-use, and
+                    // copying it anywhere kills it on the next rotation.)
+                    exports.push(exportLine(tokenEnv, stored.token));
+                    err(`Note: this access token expires in ~${Math.max(1, Math.round((stored.expiresMs - Date.now()) / 86_400_000))} day(s); ` +
+                        `re-run \`ecr setup-auth\` then to refresh it (your OpenCode sign-in stays valid).`);
+                }
+            }
+        }
+        for (const key of plan.manualKeys) {
+            if (process.env[key.tokenEnv]) {
+                err(`✓ ${key.tokenEnv} is already set in this shell — skipping.`);
+                continue;
+            }
+            const upstream = key.upstream ?? key.provider;
+            err("");
+            err(`${key.tokenEnv} (${key.provider}) is an API key — create it by hand:`);
+            if (upstream === "openai") {
+                err("  https://platform.openai.com/api-keys — in a dedicated project (set a");
+                err("  monthly budget), as a RESTRICTED key with exactly two permissions, both");
+                err("  under Model capabilities: Responses → Request, Chat completions → Request.");
+                err("  Everything else (including List models) stays None.");
+            }
+            else if (upstream === "anthropic") {
+                err("  https://console.anthropic.com/settings/keys — a workspace-scoped key");
+                err("  with a spend limit is all the reviewer needs.");
+            }
+            else {
+                err(`  mint a key for the "${upstream}" provider.`);
+            }
+            exports.push(exportLine(key.tokenEnv, "<paste the key here>"));
+        }
+        for (const entry of plan.unsupported) {
+            err("");
+            err(`auth for "${entry.provider}" is mode "oauth", which has no automated setup flow here` +
+                (entry.provider === "anthropic"
+                    ? " — and cannot work: Anthropic prohibits subscription tokens in third-party tools. Use an API key instead."
+                    : `. Set ${entry.tokenEnv ?? "its token env"} manually.`));
+        }
+        if (exports.length > 0) {
+            const rc = process.env.SHELL?.includes("zsh") ? "~/.zshrc" : "your shell config";
+            err("");
+            err(`Add ${exports.length === 1 ? "this line" : "these lines"} to ${rc}:`);
+            out("");
+            for (const line of exports) {
+                out(`    ${line}`);
+            }
+            out("");
+            err(`Then restart your shell (or \`source ${rc}\`) and run \`ecr doctor\` to verify.`);
+        }
+        else {
+            err("");
+            err("Nothing to add — run `ecr doctor` to verify your setup.");
+        }
+    }
+    catch (error) {
+        err(`setup-auth failed: ${errorMessage(error)}`);
+        process.exitCode = 1;
+    }
+}

package/build/config/schema.js

@@ -38,10 +38,15 @@ export const ReviewConfigSchema = z.object({
         maxChangedLines: z.number().int().positive().default(1000),
         // Secondary guard so a chunk isn't an absurd number of tiny-diff files.
         maxFiles: z.number().int().positive().default(20),
-        // Max concurrent reviewer calls across all agents/chunks.
-        concurrency: z.number().int().positive().default(6),
+        // Max concurrent reviewer calls across all agents/chunks. Unset ⇒ resolved
+        // from the auth mode: 6 for API-key runs, 3 when a subscription (oauth)
+        // credential is configured — one ChatGPT account handles six parallel
+        // streams poorly (requests get parked = the stall signature), and several
+        // PRs may be reviewing on the same credential at once. An explicit value
+        // here always wins. See effectiveConcurrency in core/review.ts.
+        concurrency: z.number().int().positive().optional(),
     })
-        .default({ maxChangedLines: 1000, maxFiles: 20, concurrency: 6 }),
+        .default({ maxChangedLines: 1000, maxFiles: 20 }),
     noise: z
         .object({
         additionalIgnores: z.array(z.string()).default([]),

package/build/core/auth.js

@@ -74,6 +74,31 @@ export function checkOauthTokenShape(provider, token, tokenEnv) {
             detail: `${tokenEnv} holds only ${token.length} characters, too short to be a real ${provider} token — it looks truncated. ${fix}`,
         };
     }
+    // A ChatGPT access token carries its own expiry — check it up front, so a
+    // lapsed credential is one clear message instead of N failed passes, and a
+    // nearly-lapsed one warns before it bites mid-run.
+    if (provider === "openai" && isJwtAccessToken(token)) {
+        const expires = jwtExpiryMs(token);
+        if (expires !== null) {
+            const remainingMs = expires - Date.now();
+            if (remainingMs <= 0) {
+                return {
+                    ok: false,
+                    detail: `${tokenEnv} holds a ChatGPT access token that EXPIRED ${Math.ceil(-remainingMs / 86_400_000)} day(s) ago. ` +
+                        `Mint a fresh one (\`ecr setup-auth\`, or your token-rotator job) and update ${tokenEnv}.`,
+                };
+            }
+            if (remainingMs < 3 * 86_400_000) {
+                return {
+                    ...ok,
+                    detail: `oauth for ${provider}; token env ${tokenEnv} is set`,
+                    warning: `${tokenEnv}'s ChatGPT access token expires in ${Math.max(1, Math.round(remainingMs / 3_600_000))}h — ` +
+                        `re-mint it soon (\`ecr setup-auth\`, or your token-rotator job).`,
+                };
+            }
+        }
+        return { ...ok, detail: `oauth for ${provider}; token env ${tokenEnv} is set` };
+    }
     // Only anthropic's formats are known well enough to say anything about.
     if (provider !== "anthropic") {
         return ok;
@@ -241,20 +266,45 @@ export function checkProviderAuth(config, env = process.env) {
         ...(warnings.length > 0 ? { warning: warnings.join("; ") } : {}),
     };
 }
+/** A ChatGPT access token is a JWT (three base64url segments); refresh tokens are opaque. */
+export function isJwtAccessToken(token) {
+    return token.startsWith("eyJ") && token.split(".").length === 3;
+}
+/** A JWT's `exp` claim as epoch ms, decoded (not verified) — null when unreadable. */
+export function jwtExpiryMs(token) {
+    const payload = token.split(".")[1];
+    if (!payload) {
+        return null;
+    }
+    try {
+        const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        return typeof claims.exp === "number" ? claims.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * The auth.json entry for one oauth credential. Provider-shaped:
- * - openai: the durable secret is the REFRESH token (a ChatGPT/Codex sign-in's
- *   access tokens live ~1h, shorter than a worst-case run), so store it with
- *   `expires: 0` and let OpenCode's codex plugin mint access tokens on demand.
+ * The auth.json entry for one oauth credential. Shaped by what the token IS:
+ * - a JWT (an ACCESS token, e.g. from `ecr setup-auth` or a rotator job): use it
+ *   as-is and never refresh — refresh tokens are SINGLE-USE (rotation), so a
+ *   static/shared secret must not participate in rotation at all. Expiry comes
+ *   from the JWT's own `exp` claim so OpenCode trusts it exactly as long as it
+ *   is valid.
+ * - an opaque openai token (a REFRESH token): store it with `expires: 0` and let
+ *   OpenCode's codex plugin mint the access token. Only safe when this run is
+ *   the token's SOLE consumer — a value shared across runs/repos dies on first
+ *   rotation (learned the hard way).
  * - everything else: the token IS the access credential (e.g. long-lived
  *   setup-token style bearers), far-future expiry so OpenCode never tries to
  *   refresh a credential that has no refresh half.
  */
 export function oauthAuthJsonEntry(provider, token) {
-    if (provider === "openai") {
+    if (provider === "openai" && !isJwtAccessToken(token)) {
         return { type: "oauth", access: "", refresh: token, expires: 0 };
     }
-    return { type: "oauth", access: token, refresh: "", expires: Date.now() + YEAR_MS };
+    const expires = isJwtAccessToken(token) ? jwtExpiryMs(token) : null;
+    return { type: "oauth", access: token, refresh: "", expires: expires ?? Date.now() + YEAR_MS };
 }
 /**
  * Prepare model credentials for the OpenCode server from the repo's auth entries

package/build/core/opencode.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import path from "node:path";
 import { createOpencode } from "@opencode-ai/sdk";
+import { RateLimitWatch } from "./throttle.js";
 import { toolMap } from "./tools.js";
 import { errorMessage, sleep } from "./util.js";
 /** Sum token usage across attempts (for per-task/run totals). */
@@ -175,7 +176,9 @@ export async function startOpencode(config) {
         port: 0,
         config: config,
     });
-    return { client, url: server.url, close: () => server.close() };
+    // Watch THIS server's log for provider throttle evidence (prepareAuth has already
+    // pointed XDG_DATA_HOME at the run's isolated dir when auth is injected).
+    return { client, url: server.url, close: () => server.close(), rateLimit: new RateLimitWatch() };
 }
 /** `provider/model` as the server reported it, or undefined if it reported neither. */
 export function formatModel(providerID, modelID) {
@@ -357,17 +360,26 @@ const FINALIZE_STALL_MS = 60 * 1000;
 // Breathing room before the retry: if the silence came from provider-side throttling
 // or backoff, reconnecting instantly is the worst move.
 const STALL_RETRY_BACKOFF_MS = 20 * 1000;
+// When the account is provably rate-limited, wait in longer beats: re-sending the
+// pass's whole context into a throttled account only deepens the limit. Several
+// waits fit inside a pass budget, and each is long enough for a limit window to move.
+const RATE_LIMIT_WAIT_MS = 90 * 1000;
 // Only retry when enough of the pass's budget remains for the fresh attempt to
 // plausibly finish; otherwise go straight to the soft landing.
 const STALL_RETRY_MIN_REMAINING_MS = STALL_MS + 60 * 1000;
 /**
- * What to do about a stalled attempt: start over from a clean session, or stop and
- * try to salvage findings. Exactly ONE retry, and only with enough budget left for it
- * to land — a second wedged attempt would just spend the rest of the pass's window,
+ * What to do about a stalled attempt: WAIT (the account is provably rate-limited —
+ * see core/throttle.ts — so patience beats re-sending the context; waits don't
+ * consume the one retry), start over from a clean session, or stop and salvage
+ * findings. Exactly ONE wedged retry, and only with enough budget left for it to
+ * land — a second wedged attempt would just spend the rest of the pass's window,
  * which is the failure this whole mechanism exists to end. Exported for tests.
  */
-export function stallAction(attempt, remainingMs) {
-    return attempt === 0 && remainingMs > STALL_RETRY_MIN_REMAINING_MS ? "retry" : "soft-land";
+export function stallAction(wedgedRetries, remainingMs, rateLimited = false) {
+    if (rateLimited && remainingMs > STALL_RETRY_MIN_REMAINING_MS) {
+        return "wait";
+    }
+    return wedgedRetries === 0 && remainingMs > STALL_RETRY_MIN_REMAINING_MS ? "retry" : "soft-land";
 }
 const FINALIZE_PROMPT = "You have reached your time budget. STOP investigating now — do NOT read, grep, " +
     "glob, list, or open any more files, and do not call any tools. Based ONLY on " +
@@ -551,6 +563,7 @@ export async function promptAgent(handle, args) {
             throw finalizeError;
         }
     };
+    let wedgedRetries = 0;
     for (let attempt = 0;; attempt++) {
         const session = unwrap(await handle.client.session.create({
             body: { title: attempt === 0 ? args.title : `${args.title}-retry${attempt}` },
@@ -578,11 +591,27 @@ export async function promptAgent(handle, args) {
             // wedged request to answer. Exactly one retry, and only when enough budget
             // remains for it to land; after that the finalize is still worth a try as the
             // only remaining salvage (in eas-cli#4084 the session did respond once aborted).
+            //
+            // EXCEPT when the server log shows the account is rate-limited: then the
+            // silence is throttling, not a wedge, and the patient move is to wait —
+            // re-sending the pass's whole context would deepen the limit. Waits repeat
+            // (never consuming the one wedged retry) until the evidence goes stale or
+            // the pass runs out of room, both bounded by the pass deadline.
             if (error instanceof NoProgress) {
                 await abortQuietly(handle, session.id);
                 absorb(error);
+                await handle.rateLimit.check();
                 const remaining = deadline - Date.now();
-                if (stallAction(attempt, remaining) === "retry") {
+                const action = stallAction(wedgedRetries, remaining, handle.rateLimit.recentlyLimited());
+                if (action === "wait") {
+                    args.onActivity?.(`provider is rate-limiting this account (429 in the server log; ` +
+                        `${handle.rateLimit.events} so far) — waiting ${Math.round(RATE_LIMIT_WAIT_MS / 1000)}s ` +
+                        `instead of retrying (${Math.round(remaining / 60000)}m of budget left)`);
+                    await sleep(RATE_LIMIT_WAIT_MS);
+                    continue;
+                }
+                if (action === "retry") {
+                    wedgedRetries++;
                     args.onActivity?.(`stalled — no output for ${Math.round(error.idleMs / 1000)}s; ` +
                         `retrying once from a clean session (${Math.round(remaining / 60000)}m of budget left)`);
                     await sleep(STALL_RETRY_BACKOFF_MS);
@@ -606,6 +635,18 @@ const CORRECTIVE = "\n\nIMPORTANT: your previous reply could not be parsed. Repl
 const CORRECTIVE_WAIT_MS = 2 * 60 * 1000;
 /** Backoff (ms) before the 2nd and 3rd attempt of a transient-failing model call. */
 const TRANSIENT_BACKOFF_MS = [2_000, 8_000];
+/**
+ * Rate limits need patience, not persistence: a limited account stays limited for
+ * tens of seconds to minutes, so the 2s/8s schedule just burns the retries. Shared
+ * subscription credentials (several PRs reviewing at once) make this the common
+ * transient, hence the dedicated, slower schedule.
+ */
+const RATE_LIMIT_BACKOFF_MS = [15_000, 45_000, 90_000];
+const RATE_LIMIT_ERROR = /\b429\b|rate.?limit|too many requests/i;
+/** A transient error that is specifically a provider rate limit. */
+export function isRateLimitError(error) {
+    return !(error instanceof AgentTimeoutError) && RATE_LIMIT_ERROR.test(errorMessage(error));
+}
 /**
  * A transient, retryable API failure — a one-off rate-limit (429), server error
  * (5xx), or network blip — as opposed to a timeout (which means "abandon", see
@@ -649,11 +690,13 @@ async function withTransientRetry(label, onActivity, fn) {
             return await fn();
         }
         catch (error) {
-            const waitMs = TRANSIENT_BACKOFF_MS[attempt];
+            // Rate limits get the slower, longer schedule — see RATE_LIMIT_BACKOFF_MS.
+            const schedule = isRateLimitError(error) ? RATE_LIMIT_BACKOFF_MS : TRANSIENT_BACKOFF_MS;
+            const waitMs = schedule[attempt];
             if (waitMs === undefined || !isTransientApiError(error)) {
                 throw error;
             }
-            onActivity?.(`${label}: transient API error (${errorMessage(error)}); retry ${attempt + 1}/${TRANSIENT_BACKOFF_MS.length} in ${Math.round(waitMs / 1000)}s`);
+            onActivity?.(`${label}: transient API error (${errorMessage(error)}); retry ${attempt + 1}/${schedule.length} in ${Math.round(waitMs / 1000)}s`);
             await sleep(waitMs);
         }
     }

package/build/core/render.js

@@ -108,7 +108,7 @@ export function renderMarkdown(review, tag, dismissed = [], link) {
     const kept = withFp.filter(({ fp }) => !dismissedByFp.has(fp));
     const dropped = withFp.filter(({ fp }) => dismissedByFp.has(fp));
     const lines = [commentMarker(tag), "## 🤖 AI code review", ""];
-    lines.push(`**Decision:** ${decisionLabel(review.decision)}`, "", review.summary, "");
+    lines.push(`**Decision:** ${review.couldNotComplete ? "No review — every pass failed" : decisionLabel(review.decision)}`, "", review.summary, "");
     if (review.incomplete.length > 0) {
         lines.push("> ⏱️ **Coverage note:** coverage is partial — some review passes did not", "> finish (timed out or failed), so issues may exist in areas not fully reviewed:", ...review.incomplete.map((note) => `> - ${note}`), "");
     }
@@ -230,7 +230,7 @@ export function renderAggregateMarkdown(results, tag, dismissed, link, opts) {
             "| --- | --- | --- |",
         ];
         for (const { result, kept } of perScope) {
-            lines.push(`| ${result.scope} | ${decisionLabel(result.review.decision)} | ${kept.length} |`);
+            lines.push(`| ${result.scope} | ${result.review.couldNotComplete ? "No review — every pass failed" : decisionLabel(result.review.decision)} | ${kept.length} |`);
         }
         lines.push("");
         const anyIncomplete = results.some((result) => result.review.incomplete.length > 0);

package/build/core/review.js

@@ -32,6 +32,20 @@ function makeRunId() {
  * → coordinate → apply policy. Returns a CoordinatorOutput; the CLI commands are
  * thin wrappers that supply a Source and render the result.
  */
+/**
+ * Max concurrent reviewer calls: an explicit config value wins; otherwise 3 when a
+ * subscription (oauth) credential is configured, else 6. One ChatGPT account
+ * handles six parallel streams poorly — requests get parked server-side (the
+ * stall signature seen on eas-cli#4084), and several PRs may be reviewing on the
+ * same credential at once — so subscription runs trade a little wall-clock for a
+ * lot of reliability. Exported for tests.
+ */
+export function effectiveConcurrency(config) {
+    if (config.chunk.concurrency) {
+        return config.chunk.concurrency;
+    }
+    return config.auth.some((entry) => entry.mode === "oauth") ? 3 : 6;
+}
 export async function runReview(source, options) {
     const { config } = options;
     const started = Date.now();
@@ -177,9 +191,10 @@ export async function runReview(source, options) {
         const chunks = chunkByLines(workspace.files, config.chunk.maxChangedLines, config.chunk.maxFiles);
         // Only chunk (and add a cross-cutting pass) when the diff exceeds one chunk.
         const chunked = chunks.length > 1;
+        const concurrency = effectiveConcurrency(config);
         progress(`Running ${selectedAgents.length} reviewer(s) [${selectedAgents.map((a) => a.id).join(", ")}] over ${chunks.length} chunk(s)` +
             `${chunked ? " + cross-cutting pass" : ""} ` +
-            `(${kept.length} files, concurrency ${config.chunk.concurrency})…`);
+            `(${kept.length} files, concurrency ${concurrency})…`);
         for (const agent of selectedAgents) {
             agentFindings[agent.id] = [];
             agentCosts[agent.id] = 0;
@@ -313,7 +328,7 @@ export async function runReview(source, options) {
         // TIMEOUT, instead of dropping the work we break it into units that converge:
         // subdivide the chunk, then a fast no-tools pass, and only report a coverage gap
         // when even that can't finish inside the budget — so dropped work is never silent.
-        await runGrowableQueue(tasks, config.chunk.concurrency, async (task, enqueue) => {
+        await runGrowableQueue(tasks, concurrency, async (task, enqueue) => {
             const minutes = Math.round(task.maxWaitMs / 60000);
             try {
                 const { value, cost, truncated, tokens, model } = await promptAndParse(handle, {
@@ -443,6 +458,9 @@ export async function runReview(source, options) {
                 summary: "⚠️ The AI review could not complete: every review pass failed or timed out, " +
                     'so these changes were effectively NOT reviewed. Treat this as "no review", not "looks good".',
                 incomplete: coverageNotes,
+                // Presentation override: without it the comment header reads "Decision:
+                // Approve with comments" over a review that reviewed nothing (euxy#8).
+                couldNotComplete: true,
             };
         }
         else {
@@ -515,6 +533,14 @@ export async function runReview(source, options) {
         if (removedAfterChecks > 0) {
             output = { ...output, summary: reconcileSummary(output.summary, output.findings.length) };
         }
+        // Surface provider throttling as a fact about the run: passes already waited or
+        // backed off, but the operator should still SEE that it happened (a run that
+        // was rate-limited is slower and may carry partial passes — that's the cause).
+        await handle.rateLimit.check();
+        if (handle.rateLimit.events > 0) {
+            progress(`  ⚠ provider rate-limited this run ${handle.rateLimit.events} time(s) ` +
+                `(429s in the OpenCode server log) — passes waited it out rather than failing`);
+        }
         // Every pass says which model actually answered it — in the job log, the step
         // summary table, and the run log — so a wrong or substituted model is always
         // visible, not just when the substitution warning fires.
@@ -535,6 +561,7 @@ export async function runReview(source, options) {
             agentFindings,
             coverageNotes,
             verifierDropped,
+            ...(handle.rateLimit.events > 0 ? { rateLimitEvents: handle.rateLimit.events } : {}),
             durationMs: Date.now() - started,
             decision: output.decision,
             findingCount: output.findings.length,

package/build/core/schema.js

@@ -46,6 +46,14 @@ export const CoordinatorOutputSchema = z.object({
      * cut-short review is never presented as complete.
      */
     incomplete: z.array(z.string()).default([]),
+    /**
+     * True when EVERY pass failed — nothing was actually reviewed. Set by the
+     * engine, never the model. Reporters must not render an approving decision
+     * label for such a run (the decision enum has no "no review" member, and
+     * widening it would ripple through dismiss state and exit codes — this flag
+     * overrides the presentation instead).
+     */
+    couldNotComplete: z.boolean().optional(),
 });
 /** Minimum normalized evidence length to key a fingerprint on the code (below
  * this we fall back to the title). */

package/build/core/throttle.js

@@ -0,0 +1,94 @@
+import { open } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Rate-limit evidence, read from the OpenCode server's own log.
+ *
+ * Why this exists: provider throttling reaches us in two shapes. An EXPLICIT
+ * failure (HTTP 429 / "rate limit" stream error) surfaces in OpenCode's log as a
+ * structured ERROR line — that is proof. A SILENT one (the request is accepted
+ * and parked server-side) produces no error anywhere and is indistinguishable
+ * from a wedged request from the outside. So: the log watcher turns the explicit
+ * case into a hard signal, and the stall path treats "stall + recent explicit
+ * evidence" as throttling — the one situation where the right move is to WAIT
+ * (re-sending the whole context into a limited account only makes it worse).
+ *
+ * During oauth runs prepareAuth points XDG_DATA_HOME at an isolated temp dir, so
+ * the log we read belongs to exactly this run's server — no cross-talk with a
+ * developer's own OpenCode sessions.
+ */
+/** The OpenCode server's log file under the active data dir. */
+export function opencodeLogFile(env = process.env) {
+    const dataHome = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+    return path.join(dataHome, "opencode", "log", "opencode.log");
+}
+/**
+ * Provider throttle signatures in OpenCode log lines. Matched only against ERROR
+ * lines (a chatty INFO line mentioning "retry" must not count as evidence).
+ */
+const RATE_LIMIT_PATTERN = /\b429\b|rate.?limit|too many requests|quota exceeded/i;
+const ERROR_LINE = /\blevel=ERROR\b/;
+/** Count rate-limit ERROR lines in a chunk of log text. Pure, for tests. */
+export function countRateLimitLines(chunk) {
+    let count = 0;
+    for (const line of chunk.split("\n")) {
+        if (ERROR_LINE.test(line) && RATE_LIMIT_PATTERN.test(line)) {
+            count++;
+        }
+    }
+    return count;
+}
+/** How recent explicit evidence must be for a stall to be read as throttling. */
+const EVIDENCE_WINDOW_MS = 5 * 60 * 1000;
+/**
+ * Incremental watcher over the OpenCode server log. `check()` reads only what was
+ * appended since the last call (cheap enough for poll loops); `recentlyLimited()`
+ * is the signal the stall path consults. Fails soft everywhere: a missing or
+ * unreadable log yields "no evidence", never an error.
+ */
+export class RateLimitWatch {
+    file;
+    /** Total rate-limit ERROR lines seen this run. */
+    events = 0;
+    /** Wall-clock time evidence was last SEEN (observation time, not log time). */
+    lastSeenAt = 0;
+    offset = 0;
+    constructor(file = opencodeLogFile()) {
+        this.file = file;
+    }
+    /** Scan newly-appended log lines for rate-limit evidence. */
+    async check() {
+        try {
+            const handle = await open(this.file, "r");
+            try {
+                const { size } = await handle.stat();
+                if (size < this.offset) {
+                    this.offset = 0; // rotated/truncated — rescan from the top
+                }
+                if (size === this.offset) {
+                    return this.events;
+                }
+                const length = size - this.offset;
+                const buffer = Buffer.alloc(length);
+                await handle.read(buffer, 0, length, this.offset);
+                this.offset = size;
+                const found = countRateLimitLines(buffer.toString("utf8"));
+                if (found > 0) {
+                    this.events += found;
+                    this.lastSeenAt = Date.now();
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            // No log yet (server just started) or unreadable — no evidence, no error.
+        }
+        return this.events;
+    }
+    /** True when explicit throttle evidence appeared within the recency window. */
+    recentlyLimited(now = Date.now()) {
+        return this.lastSeenAt > 0 && now - this.lastSeenAt < EVIDENCE_WINDOW_MS;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {
@@ -10,7 +10,8 @@
   "type": "module",
   "bin": {
     "ecr": "build/cli.js",
-    "expo-code-review": "build/cli.js"
+    "expo-code-review": "build/cli.js",
+    "code-review-cli": "build/cli.js"
   },
   "files": [
     "build",

package/templates/config.jsonc

@@ -23,6 +23,9 @@
   // Large diffs are split into focused chunks by changed-line count, plus a
   // cross-cutting pass for multi-file issues. Diffs under maxChangedLines are one
   // full-context pass. Defaults shown; raise/lower per your model + PR sizes.
+  // Concurrency defaults by auth mode: 6 with an API key, 3 on a subscription
+  // (oauth) credential — one account handles many parallel streams poorly, and
+  // several PRs may review on the same credential at once. Set it to override.
   // "chunk": { "maxChangedLines": 1000, "maxFiles": 20, "concurrency": 4 },
 
   // Which PRs `ecr ci` reviews. This is the source of truth for trigger policy;
@@ -56,11 +59,12 @@
   // of the agents that need the pro tier, and set ECR_EXPECTED_TOKEN_ENV in the
   // workflow to the comma-separated set of both env names.
   //   "auth": { "providers": {
-  //     "openai":     { "mode": "oauth",   "tokenEnv": "CODEX_OAUTH_REFRESH_TOKEN" },
+  //     "openai":     { "mode": "oauth",   "tokenEnv": "CODEX_OAUTH_ACCESS_TOKEN" },
   //     "openai-api": { "mode": "api-key", "tokenEnv": "OPENAI_API_KEY", "upstream": "openai" }
   //   } }
-  // (openai oauth: tokenEnv holds the REFRESH token from an `opencode auth login`
-  // ChatGPT sign-in — copy `.openai.refresh` from OpenCode's auth.json.)
+  // (openai oauth: tokenEnv holds the ACCESS token from an `opencode auth login`
+  // ChatGPT sign-in — `ecr setup-auth` extracts it. NEVER share the refresh
+  // token: it is single-use and dies on first rotation.)
   "auth": {
     "mode": "api-key",
     "provider": "openai",