@in-the-loop-labs/pair-review 4.0.0 → 4.1.0

package/README.md

@@ -20,6 +20,7 @@
   - [AI-Guided Review](#3-ai-guided-review-when-youre-accountable)
 - [Quick Start](#quick-start)
 - [Command Line Interface](#command-line-interface)
+  - [Local review scope](#local-review-scope)
   - [Headless analysis mode](#headless-analysis-mode)
 - [Configuration](#configuration)
   - [Environment Variables](#environment-variables)
@@ -89,7 +90,8 @@ Compared to giving feedback in chat, this feels like moving from a machete to a
 
 **Tips:**
 - Stage previous changes in git, then only review new modifications in the next round
-- Local mode only shows unstaged changes and untracked files (opinionated by design)
+- By default local mode reviews unstaged changes and untracked files; adjust the range with `--scope` (or the web UI scope selector) — e.g. `branch..untracked` to cover the whole branch (see [Local review scope](#local-review-scope))
+
 ### 2. Meta-Review: Judging AI Suggestions
 
 **When to use:** You're not going to read every line of code. Let AI be your reader.
@@ -203,7 +205,10 @@ pair-review --local [path]
 | `-d`, `--debug` | Enable verbose debug logging for troubleshooting |
 | `-h`, `--help` | Show help message with full CLI documentation |
 | `-l`, `--local [path]` | Review local uncommitted changes. Optional path defaults to current directory |
+| `--scope <start>..<end>` | **Local mode only.** Set the diff range a local review covers. Stops (in order): `branch`, `staged`, `unstaged`, `untracked`. Six valid ranges (contiguous, must include `unstaged`); default `unstaged..untracked`. `branch..*` diffs from the merge-base with the base branch. See [Local review scope](#local-review-scope). |
+| `--base <branch>` | **Local mode only.** With a `branch..*` scope, override base-branch auto-detection. Errors if used without a branch-start scope. |
 | `--model <name>` | Override the AI model for any provider. Model availability depends on provider configuration. |
+| `--provider <name>` | Override the AI provider. Applies to headless modes (`--ai-draft` / `--ai-review`) **and** to browser-driven auto-analysis (`--ai`), where it overrides the repo/app default the browser would otherwise use — including across single-port delegation to an already-running server. Defaults to the repo/app default provider (`claude`). Pair with `--model` when the model belongs to a non-default provider (e.g. `--provider codex --model gpt-5.5`). |
 | `--register` | Register `pair-review://` URL scheme handler (macOS only) |
 | `--unregister` | Unregister `pair-review://` URL scheme handler (macOS only) |
 | `--command <cmd>` | Custom CLI command for `--register` (default: `npx @in-the-loop-labs/pair-review`) |
@@ -216,8 +221,10 @@ pair-review 123                        # Review PR #123 in current repo
 pair-review https://github.com/owner/repo/pull/456
 pair-review --local                    # Review uncommitted local changes
 pair-review 123 --ai                   # Auto-run AI analysis
+pair-review 123 --ai --provider codex  # Auto-run analysis in the browser with a specific provider
 pair-review --list-councils            # List saved councils and their handles
 pair-review 123 --ai-draft --council security-review  # Headless draft with a council
+pair-review 123 --ai-draft --provider codex --model gpt-5.5  # Headless draft with a specific provider + model
 pair-review --local --ai --council security-review    # Local review with a council
 pair-review --local --headless         # Analyze local changes, print a summary, exit
 pair-review --local --headless --json  # Analyze local changes, emit JSON, exit
@@ -240,6 +247,44 @@ pair-review --register --command "node bin/pair-review.js"  # Custom command
 > web UI's default **Analyze** action, so `--council`/`--model` are optional when
 > a repo default is configured.
 
+### Local review scope
+
+`--scope <start>..<end>` sets which changes a **local** review covers (it has
+no effect on PR reviews). The scope walks four ordered stops — `branch` →
+`staged` → `unstaged` → `untracked` — and a range must be contiguous and always
+include `unstaged`, since the AI models read files from the working tree and the
+diff must cover that state. That leaves six valid ranges:
+
+| Scope | Covers |
+|-------|--------|
+| `branch..unstaged` | All tracked changes since the base branch (committed + staged + unstaged); no new files |
+| `branch..untracked` | Everything since the base branch, including new files |
+| `staged..unstaged` | Staged changes plus working-tree edits vs `HEAD`; no new files |
+| `staged..untracked` | Staged changes, working-tree edits, and new files |
+| `unstaged..unstaged` | Only unstaged working-tree edits (staged changes treated as already reviewed) |
+| `unstaged..untracked` | Unstaged working-tree edits plus new files (**default**) |
+
+A scope ending at `untracked` includes new (untracked) files automatically — no
+`git add -N` needed. `branch..*` diffs from the merge-base with the base branch.
+
+`--base <branch>` overrides base-branch auto-detection for a `branch..*` scope.
+Detection order when `--base` is omitted: Graphite stack state (only when
+`enable_graphite: true` is set in `~/.pair-review/config.json`) → GitHub PR base →
+`origin`'s default branch → `main`/`master`. `--base` errors if used without a
+branch-start scope.
+
+Both flags are **local-mode only**: they error when given a PR argument and do
+**not** imply `--local`. An explicit `--scope` is persisted on the review
+session, so opening the web UI for that review later shows the same scope.
+
+```bash
+# Review everything on this branch since it diverged from the trunk, plus new files
+pair-review --local --scope branch..untracked
+
+# Same, but against an explicit base branch (stacked branches / non-default trunk)
+pair-review --local --scope branch..untracked --base develop
+```
+
 ### Headless analysis mode
 
 `--headless` runs an AI analysis (single provider or council), stores the results
@@ -427,7 +472,7 @@ Nested objects (like `chat`, `providers`, `chat_providers`, `monorepos`) are dee
 
 ### Alternate Git Hosts
 
-pair-review can review pull requests on self-hosted Git platforms that expose a GitHub-compatible REST API, configured per-repository via `repos["owner/repo"].api_host` and related keys. See [docs/alt-host.md](docs/alt-host.md) for the full configuration guide.
+pair-review can review pull requests on self-hosted Git platforms that expose a GitHub-compatible REST API, configured per-repository via `repos["owner/repo"].api_host` and related keys. By default an `api_host` repo is treated as living exclusively on the alt host; set `exclusive: false` on the repo entry to mark it as **dual-host**, where some PRs live on `github.com` and others on the alt host and pair-review resolves the host per PR. See [docs/alt-host.md](docs/alt-host.md) for the full configuration guide.
 
 ### Environment Variables
 
@@ -444,10 +489,13 @@ pair-review supports several environment variables for customizing behavior:
 | `PAIR_REVIEW_CURSOR_AGENT_CMD` | Custom command to invoke Cursor Agent CLI | `agent` |
 | `PAIR_REVIEW_PI_CMD` | Custom command to invoke Pi CLI | `pi` |
 | `PAIR_REVIEW_MODEL` | Override the AI model to use (same as `--model` flag) | Provider default |
+| `PAIR_REVIEW_PROVIDER` | Override the AI provider to use (same as `--provider` flag) | `claude` |
 
 **Note:** `GITHUB_TOKEN` is the standard environment variable used by many GitHub tools (gh CLI, GitHub Actions, etc.). When set, it takes precedence over the `github_token` field in the config file.
 
-**Note:** The `--model` CLI flag is shorthand for setting `PAIR_REVIEW_MODEL`. If both are specified, the CLI flag takes precedence.
+**Note:** The `--model` CLI flag is shorthand for setting `PAIR_REVIEW_MODEL`, and `--provider` is shorthand for `PAIR_REVIEW_PROVIDER`. If both the flag and env var are specified, the CLI flag takes precedence. The `--provider` flag selects which provider runs the analysis; `--model` selects the model within that provider, so set both when the model belongs to a non-default provider (e.g. `--provider codex --model gpt-5.5`). The override outranks saved repository settings (`CLI/env > repo settings`); if the repo's default is a Review Council, an active `--provider`/`--model` override forces the single-provider path instead.
+
+**Delegation caveat:** With single-port mode (the default `single_port: true`), a new invocation delegates to an already-running server. On that path the `--provider`/`--model` override is carried to the running server only alongside browser auto-analysis (`--ai`). Delegating without `--ai` (just opening the review) does not seed the override into the other process's manual analysis dialog — use `--ai`, or a headless mode, to pin the provider on the delegated path.
 
 These variables are useful when:
 - Your CLI tools are installed in a non-standard location
@@ -472,6 +520,9 @@ PAIR_REVIEW_ANTIGRAVITY_CMD="/usr/local/bin/agy" pair-review --local
 # Force a specific model for this review
 PAIR_REVIEW_MODEL="opus" pair-review 123
 
+# Force a specific provider + model for a headless review
+PAIR_REVIEW_PROVIDER="codex" PAIR_REVIEW_MODEL="gpt-5.5" pair-review 123 --ai-draft
+
 # Combine multiple settings
 PAIR_REVIEW_CLAUDE_CMD="/opt/claude/bin/claude" PAIR_REVIEW_MODEL="haiku" pair-review 123
 ```
@@ -791,7 +842,10 @@ Templates typically include `{description}` to render the suggestion body.
 
 ### Local Mode
 
-Review **unstaged**, uncommitted changes before creating a PR:
+Review your uncommitted changes before creating a PR — by default the unstaged
+working-tree edits plus untracked files, with the range adjustable via `--scope`
+(or the web UI scope selector), e.g. `branch..untracked` to cover the whole
+branch (see [Local review scope](#local-review-scope)):
 
 ```bash
 pair-review --local
@@ -806,11 +860,28 @@ Perfect for:
 
 ## Claude Code Plugins
 
-pair-review provides two [Claude Code plugins](https://code.claude.com/docs/en/plugins) that bring AI-powered code review directly into Claude Code.
+pair-review provides three [Claude Code plugins](https://code.claude.com/docs/en/plugins) that bring AI-powered code review directly into Claude Code.
+
+### pair-loop — Agent-Orchestrated Review Loop
+
+An implement→review→fix loop with pair-review as the review oracle. The agent runs multi-model council reviews through the headless CLI, triages the findings (fixing, dismissing with reasons, or asking you), applies fixes, and repeats with narrowing instructions until a final review returns no blockers. Every round persists to pair-review, and when the server is running the agent writes its triage back — so you can open the web UI, inspect every round, and see exactly what was fixed or dismissed and why. No MCP required.
+
+**Install via Marketplace:**
+
+```
+/plugin marketplace add in-the-loop-labs/pair-review
+/plugin install pair-review@pair-loop
+```
+
+**Available Skills:**
+
+| Skill | Description |
+|-------|-------------|
+| `/pair-loop:loop` | Implement, review with pair-review councils, triage, fix, and repeat until clean |
 
 ### code-critic — Standalone Analysis
 
-AI-powered code review analysis that works without any server or MCP dependency. Install this plugin for three-level AI analysis and implement-review-fix loops directly in your coding agent.
+AI-powered code review analysis that works without any server or MCP dependency. Install this plugin for three-level AI analysis directly in your coding agent.
 
 **Install via Marketplace:**
 
@@ -824,7 +895,8 @@ AI-powered code review analysis that works without any server or MCP dependency.
 | Skill | Description |
 |-------|-------------|
 | `/code-critic:analyze` | Run three-level AI analysis using Task agents directly (standalone, no server needed) |
-| `/code-critic:loop` | Implement code, review with AI, fix issues, and repeat until clean |
+
+Looking for an implement-review-fix loop? That's the [pair-loop plugin](#pair-loop--agent-orchestrated-review-loop) above, which replaced the former `/code-critic:loop` skill.
 
 These skills work standalone. If the pair-review MCP server happens to be available (from the pair-review plugin), `code-critic:analyze` will use it for prompts and push results to the web UI — but it's entirely optional.
 
@@ -857,10 +929,12 @@ If you prefer not to use the marketplace, load plugins directly from an npm-inst
 
 ```bash
 # From a local clone
+claude --plugin-dir ./path/to/pair-review/plugin-pair-loop
 claude --plugin-dir ./path/to/pair-review/plugin-code-critic
 claude --plugin-dir ./path/to/pair-review/plugin
 
 # From a globally installed npm package
+claude --plugin-dir "$(npm root -g)/@in-the-loop-labs/pair-review/plugin-pair-loop"
 claude --plugin-dir "$(npm root -g)/@in-the-loop-labs/pair-review/plugin-code-critic"
 claude --plugin-dir "$(npm root -g)/@in-the-loop-labs/pair-review/plugin"
 ```
@@ -880,6 +954,7 @@ To pre-configure plugins for all contributors on a repository, add this to your
     }
   },
   "enabledPlugins": {
+    "pair-review@pair-loop": true,
     "pair-review@code-critic": true,
     "pair-review@pair-review": true
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {
@@ -14,6 +14,7 @@
     "public/",
     "plugin/",
     "plugin-code-critic/",
+    "plugin-pair-loop/",
     "config.managed.json",
     "README.md",
     "LICENSE"

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "code-critic",
-  "version": "4.0.0",
-  "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
+  "version": "4.1.0",
+  "description": "AI-powered code review analysis — Run three-level AI analysis directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",
     "email": "tjwp@inthelooplabs.com"
@@ -13,7 +13,6 @@
     "code-review",
     "ai",
     "analysis",
-    "code-critic",
-    "critic-loop"
+    "code-critic"
   ]
 }

package/plugin-pair-loop/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "pair-loop",
+  "version": "4.1.0",
+  "description": "Agent-orchestrated review loop — implement, review with pair-review multi-model councils via the headless CLI, triage, fix, and repeat until a final review returns no blockers. MCP-independent.",
+  "author": {
+    "name": "in-the-loop-labs",
+    "email": "tjwp@inthelooplabs.com"
+  },
+  "homepage": "https://github.com/in-the-loop-labs/pair-review",
+  "repository": "https://github.com/in-the-loop-labs/pair-review",
+  "license": "Apache-2.0",
+  "keywords": [
+    "code-review",
+    "ai",
+    "review-loop",
+    "council",
+    "feedback-loop"
+  ]
+}

package/plugin-pair-loop/skills/loop/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: loop
+description: >
+  Drive an implement→review→fix loop with pair-review as the review oracle:
+  run multi-model council reviews, triage the findings, apply fixes, and
+  repeat with narrowing instructions until a final review returns no
+  blockers. Use when the user says "pair loop", "review loop",
+  "loop until clean", "review this with pair-review and fix what it finds",
+  or wants iterative development reviewed by pair-review councils.
+arguments:
+  council:
+    description: "Council handle (name, name-slug, or id prefix) to review with. Defaults to the repo's default council when omitted."
+    required: false
+  maxRounds:
+    description: "Budget for review rounds. On reaching it without convergence, stop and report honestly."
+    required: false
+    default: 5
+  instructions:
+    description: "Extra review instructions applied to every round (e.g. 'focus on security')"
+    required: false
+---
+
+# pair-loop
+
+You are a thin orchestrator. pair-review does the heavy lifting — multi-level,
+multi-model council reviews with persistence and a web UI. Your job is
+judgment: what to send for review, how to triage what comes back, what to
+fix, when to ask the user, and when to stop.
+
+Reviews run through **one execution mode: the headless CLI**. It is
+synchronous (no polling), emits JSON, and needs no server. The HTTP API is
+used for exactly one optional thing: writing triage back so a running web UI
+shows reality (see Write triage back).
+
+Any text in the user's request beyond the named arguments is the
+**objective** — what to build or change. If there is no objective, the loop
+runs over the changes already in the working tree.
+
+## Hard rules
+
+These are not judgment calls:
+
+1. **Never report "clean" or "ready" unless a full-quality council round,
+   instructed to report only merge-blockers, came back with an empty finding
+   list.** A cheaper or broader round cannot grant the final verdict.
+2. **Never silently stop.** If the loop is not converging or hits
+   `maxRounds`, say so, list the outstanding findings, and (when a server is
+   up) link the review URL.
+3. **Sequence strictly: fix → write triage back → then run the next round.**
+4. **One review at a time.** Never run two reviews concurrently for the same
+   repo.
+5. **Do not commit or push.** Leave changes in the working tree. New
+   (untracked) files are included automatically whenever the review scope ends
+   at `untracked` — which the default scope (`unstaged..untracked`) does — so
+   no `git add -N` (intent-to-add) is needed.
+6. **Report failures faithfully.** A failed run (`"ok": false`, non-zero
+   exit) is reported as what it is — never papered over as "no findings".
+
+## Phase: Setup
+
+1. `git rev-parse --show-toplevel` → `REPO_ROOT`. All commands run from here.
+2. Create the round log at `REPO_ROOT/.pair-loop/round-log.md` (mkdir -p; add
+   `.pair-loop/` to `.gitignore` if missing). Record: objective, arguments,
+   start time. Append to this file after every phase — it is your resume
+   state if the session compacts.
+3. If a `council` argument was given, confirm the handle exists:
+   `pair-review --list-councils` prints the saved councils. If `pair-review`
+   is not on PATH, use `npx -y @in-the-loop-labs/pair-review` for every CLI
+   call. An unknown handle → show the available names and ask the user.
+4. If an objective was given and the working tree has no relevant changes
+   yet, implement the objective first (directly or via a Task agent — your
+   call based on size). Verify with `git status --short` that changes exist
+   before the first review round; if none, tell the user and stop.
+
+## Running a review round
+
+```bash
+pair-review --local --headless --json --council <handle> [--scope <range>] --instructions "<round instructions>"
+```
+
+- Run from `REPO_ROOT`. `--local` with no path uses the current directory.
+- Omit `--council` to use the repo's default council.
+- **Scope (`--scope`).** By default a local review covers only uncommitted
+  working-tree changes plus new files (`unstaged..untracked`). That is right
+  only while all the work under review stays uncommitted. If the work under
+  review already spans commits on a branch, a clean working tree would review as
+  **empty** — pass
+  `--scope branch..untracked` so every round covers the whole branch
+  (everything since the base branch) plus the working tree and new files. Add
+  `--base <branch>` when the base branch is not auto-detected (a non-default
+  trunk, or a stacked branch). `--scope`/`--base` are local-mode only.
+- **Be patient — council reviews routinely take 15–40 minutes.** Individual
+  council voices have their own internal timeouts; trust the CLI to finish.
+  Run the command in the background (or with a timeout of at least 45
+  minutes) and wait for it to exit. Do not abandon or kill it early; do not
+  start a second review while one is running (hard rule 4).
+- stdout is exactly one JSON document (logs go to stderr):
+  - success: `{"ok": true, "mode": "local", "run": {...}, "suggestions":
+    [...], "count": N}` — exit code 0. **Zero suggestions is still
+    success.** Record `run.id` (the runId) and `run.review_id` (the
+    reviewId, used for write-back and the review URL).
+  - failure: `{"ok": false, "error": {"message": ...}}`, exit code 1.
+
+### Round instructions
+
+Build `--instructions` per round from, in order: this standing line —
+"Do not report praise findings; report only issues." — then the user's
+`instructions` argument, the objective, and this round's directive (see
+Convergence judgment). On rounds after the first, add: "Earlier review
+rounds already reported issues that have since been fixed or dismissed;
+report only issues present in the current code."
+
+### Suggestion fields
+
+Each entry in `suggestions`: `id`, `file`, `line_start`, `line_end`, `type`
+(`bug|improvement|suggestion|design|performance|security|code-style` —
+praise is instructed away; ignore it if it appears anyway), `severity`
+(`critical|medium|minor`), `title`, `body`, `reasoning`, `ai_confidence`
+(0–1).
+
+## Triage
+
+For each finding, decide one of:
+
+- **Fix** — it is real and in scope. Goes on this round's fix list.
+- **Dismiss** — false positive, out of scope, or explicitly contrary to the
+  user's stated intent. Requires a stated reason in the round log.
+- **Ask the user** — mandatory stop, not a preference, when any of:
+  (a) you would dismiss a **critical**-severity finding;
+  (b) the fix would change behavior beyond the stated objective;
+  (c) the same finding has survived two fix rounds;
+  (d) findings conflict with the user's explicit instructions.
+  Batch the questions, ask once per round at most, record the answers in the
+  round log so later rounds do not re-ask.
+
+Dedup against your round log: a finding you already dismissed in an earlier
+round, reappearing unchanged, keeps its dismissal (re-dismiss it in
+write-back) — unless a fix touched that code since, in which case judge it
+fresh.
+
+## Fix
+
+Apply the fixes (directly or via a Task agent for large batches — your
+call). Run the project's relevant tests for the changed code. A fix that
+breaks tests is not a fix.
+
+## Write triage back (optional, needs the server)
+
+If the pair-review server is running, keep its UI truthful. Probe once per
+loop: `curl -s http://localhost:7247/health` → it is pair-review iff the
+response has `"service": "pair-review"`. (7247 is the default and is right
+most of the time; if it isn't pair-review, check `port` in
+`REPO_ROOT/.pair-review/config.json` then `~/.pair-review/config.json`, then
+give up on write-back for this loop.)
+
+When the server is up, after fixing/dismissing, for each handled finding:
+
+```bash
+curl -s -X POST http://localhost:<port>/api/reviews/<run.review_id>/suggestions/<id>/status \
+  -H 'Content-Type: application/json' -d '{"status": "dismissed"}'
+```
+
+- Only `"dismissed"` and `"active"` are accepted; `"adopted"` is reserved
+  for the human's adopt flow — never send it.
+- Newer servers accept a `reason` field on this endpoint (check
+  `http://localhost:<port>/api.md?reviewId=<reviewId>` if unsure); when
+  supported, include it: `"Fixed in loop round <n>: ..."` or
+  `"Dismissed: <why>"`. Otherwise the fixed-vs-rejected distinction lives in
+  your round log and final report.
+- The human may be triaging in the same UI: before fixing, you may re-check
+  `GET /api/reviews/<reviewId>/suggestions` and skip findings whose status
+  is no longer `active` — the human got there first. Do not resurrect
+  anything the human dismissed.
+- The review URL for your report: `http://localhost:<port>/local/<reviewId>`.
+  Note: the UI does not live-update during CLI runs; results appear on
+  refresh.
+
+No server → skip this entirely; triage lives in the round log and final
+report, and the persisted run history is visible whenever the user next
+starts the server.
+
+## Convergence judgment
+
+You decide each round's directive and whether to continue. Principles:
+
+- **Round 1**: broad. Directive like: "Review these changes thoroughly.
+  Objective: <objective>."
+- **Escalate** back to a broad directive whenever the previous round
+  produced any `critical` finding.
+- **Narrow** as findings shrink. The gate directive:
+  "Final review. Only report blockers — issues that must be fixed before
+  merging. Is this ready to merge?"
+- **The gate uses the same council.** The round that says "merge it" must be
+  just as rigorous as the rounds that found problems. Do not substitute a
+  cheaper configuration for gate rounds.
+- **Continue vs stop**: another round is worth it when the last one caused
+  substantial fixes. When rounds churn the same ground without progress,
+  stop and ask the user instead of grinding the budget.
+- The loop **ends successfully** when a gate round returns **no blockers** —
+  an empty finding list (per hard rule 1). Read the run's `summary` for the
+  reviewer's own answer to the ready-to-merge question and quote it in your
+  report.
+
+## PR mode
+
+The loop also works against a GitHub PR:
+
+```bash
+pair-review <pr-number-or-url> --headless --json [--council <handle>] [--instructions "..."]
+```
+
+This self-bootstraps the PR (fetches metadata, prepares a review worktree)
+and requires a GitHub token in `~/.pair-review/config.json`. The review's
+checkout lives in a pair-review worktree — your fixes belong in whatever
+checkout the user asked you to work in; do not edit the pool worktree.
+Write-back and the review URL work the same way via `run.review_id`.
+`--scope`/`--base` do not apply here — they are local-mode only; a PR review
+always covers the PR's full diff.
+
+## Reporting
+
+Every loop ends with a report containing:
+
+1. **Verdict** — converged (quote the final run's summary) or not converged
+   (why, and what remains).
+2. **Rounds table** — per round: directive, findings found, fixed, dismissed,
+   asked.
+3. **Triage detail** — every dismissed finding with its reason; every fix in
+   one line each.
+4. **The review URL** when a server is up, so the user can inspect
+   everything in the web UI.
+5. Working-tree status reminder: changes are uncommitted, tests run and
+   their result.

package/public/js/index.js

@@ -445,8 +445,14 @@
       ? ''
       : '<td class="col-author">' + authorDisplay + '</td>';
 
+    // `data-host` carries the alt-host api_host string for PRs that live on an
+    // alternate host; github.com rows have no host and render an empty
+    // attribute. The click handler threads it into the setup call so a dual
+    // repo's alt-host PR opens against the right system without re-probing.
+    var hostAttr = pr.host ? ' data-host="' + escapeHtml(pr.host) + '"' : '';
+
     return '' +
-      '<tr class="collection-pr-row" data-pr-url="' + escapeHtml(prUrl) + '" data-owner="' + escapeHtml(pr.owner) + '" data-repo="' + escapeHtml(pr.repo) + '" data-number="' + pr.number + '">' +
+      '<tr class="collection-pr-row" data-pr-url="' + escapeHtml(prUrl) + '" data-owner="' + escapeHtml(pr.owner) + '" data-repo="' + escapeHtml(pr.repo) + '" data-number="' + pr.number + '"' + hostAttr + '>' +
         '<td class="col-repo">' + escapeHtml(repoFull) + '</td>' +
         '<td class="col-pr"><span class="collection-pr-number">#' + pr.number + '</span></td>' +
         '<td class="col-title" title="' + escapeHtml(pr.title || '') + '">' + escapeHtml(pr.title || '') + '</td>' +
@@ -1293,7 +1299,14 @@
         return {
           owner: data.owner,
           repo: data.repo,
-          prNumber: data.prNumber
+          prNumber: data.prNumber,
+          // `host` tells setup which system the PR lives on: an api_host URL
+          // string = alt host, null = github.com, undefined = unknown.
+          host: data.host,
+          bindingRepository: data.bindingRepository,
+          // Whether the repo is dual (github + alt-host). Only dual repos probe,
+          // so only they need an explicit github pick when the URL is a github URL.
+          isDualHost: data.isDualHost
         };
       }
 
@@ -1343,7 +1356,22 @@
     // Navigate to the PR route which serves setup.html (with step-by-step progress)
     // for new PRs, or pr.html directly for PRs already in the database
     let href = '/pr/' + encodeURIComponent(parsed.owner) + '/' + encodeURIComponent(parsed.repo) + '/' + encodeURIComponent(parsed.prNumber);
-    if (analyze) href += '?analyze=true';
+    var params = new URLSearchParams();
+    if (analyze) params.set('analyze', 'true');
+    // Forward the parsed host so setup binds directly instead of probing:
+    //  - alt-host URL string → the api_host (setup binds that alt host)
+    //  - github URL (host === null) on a DUAL repo → the "github" sentinel, so
+    //    setup binds github.com instead of probing alt-first (which would fail
+    //    loudly if the alt host is down for a PR we KNOW is on github)
+    //  - anything else (plain/exclusive repo, unknown host) → omit; no probe
+    //    happens for those and omitting avoids the exclusive-null throw.
+    if (typeof parsed.host === 'string' && parsed.host) {
+      params.set('host', parsed.host);
+    } else if (parsed.host === null && parsed.isDualHost) {
+      params.set('host', 'github');
+    }
+    var qs = params.toString();
+    if (qs) href += '?' + qs;
     window.location.href = href;
   }
 
@@ -1385,6 +1413,11 @@
         window.__pairReview.chatProviders = chatProviders;
         window.__pairReview.defaultProvider = config.default_provider || 'claude';
         window.__pairReview.defaultModel = config.default_model || 'opus';
+        // CLI/env override (PAIR_REVIEW_PROVIDER / PAIR_REVIEW_MODEL) surfaced
+        // by /api/config. The bulk-analysis seed prepends these ahead of repo
+        // settings so a `--provider` override outranks a repo's saved default.
+        window.__pairReview.providerOverride = config.provider_override || null;
+        window.__pairReview.modelOverride = config.model_override || null;
         window.__pairReview.hasGithubToken = Boolean(config.has_github_token);
         window.__pairReview.enableGraphite = config.enable_graphite === true;
         window.__pairReview.chatSpinner = config.chat_spinner || 'dots';
@@ -1891,7 +1924,7 @@
    * Read selected collection rows as PR descriptors.
    * @param {Set} selectedIds - PR URLs (data-pr-url values)
    * @param {string} tbodyId - tbody element ID
-   * @returns {Array<{owner: string, repo: string, number: string, prUrl: string}>}
+   * @returns {Array<{owner: string, repo: string, number: string, prUrl: string, host: string|undefined}>}
    */
   function getSelectedCollectionRows(selectedIds, tbodyId) {
     var tbody = document.getElementById(tbodyId);
@@ -1908,7 +1941,11 @@
           owner: tr.dataset.owner,
           repo: tr.dataset.repo,
           number: tr.dataset.number,
-          prUrl: prUrl
+          prUrl: prUrl,
+          // Alt-host rows carry a host; github.com rows leave it undefined. The
+          // single-row click path threads this the same way (see the collection
+          // row click handler) so bulk-open binds to the right system too.
+          host: tr.dataset.host
         });
       }
     }
@@ -1917,7 +1954,14 @@
 
   function buildReviewUrlsFromRows(rows, query) {
     return rows.map(function (row) {
-      return '/pr/' + encodeURIComponent(row.owner) + '/' + encodeURIComponent(row.repo) + '/' + row.number + (query || '');
+      // Preserve any existing params (analyze / analysisConfigId) and append the
+      // alt host so setup opens the PR against the system it lives on instead of
+      // re-probing. github.com rows (no host) keep the URL unchanged.
+      var qs = query || '';
+      if (row.host) {
+        qs += (qs ? '&' : '?') + 'host=' + encodeURIComponent(row.host);
+      }
+      return '/pr/' + encodeURIComponent(row.owner) + '/' + encodeURIComponent(row.repo) + '/' + row.number + qs;
     });
   }
 
@@ -2000,10 +2044,18 @@
     };
 
     var providersInfo = await getBulkProvidersInfo();
-    var resolvedPair = window.resolveProviderModelPair([
-      { provider: repoSettings?.default_provider, model: repoSettings?.default_model },
-      { provider: window.__pairReview?.defaultProvider, model: window.__pairReview?.defaultModel }
-    ], providersInfo);
+    // Shape __pairReview into the appConfig fields buildProviderModelScopes reads
+    // so a CLI/env `--provider` override is prepended ahead of repo settings.
+    var bulkAppConfig = {
+      default_provider: window.__pairReview?.defaultProvider,
+      default_model: window.__pairReview?.defaultModel,
+      provider_override: window.__pairReview?.providerOverride || null,
+      model_override: window.__pairReview?.modelOverride || null
+    };
+    var resolvedPair = window.resolveProviderModelPair(
+      window.buildProviderModelScopes(repoSettings, bulkAppConfig),
+      providersInfo
+    );
 
     var config = await bulkAnalysisConfigModal.show({
       currentModel: resolvedPair.model,
@@ -2163,6 +2215,21 @@
         return;
       }
 
+      // Alt-host PR: we already know owner/repo/number and the host it lives
+      // on, so navigate straight to the PR route with the host as a query
+      // param (setup.html forwards it into the setup POST body). This bypasses
+      // the URL-parse round trip, which can't reliably recover the host from a
+      // pasted alt-host html_url. github.com rows (no host) keep the existing
+      // parse-and-submit flow below, byte-identical.
+      var rowHost = collectionRow.dataset.host;
+      if (rowHost) {
+        var o = encodeURIComponent(collectionRow.dataset.owner);
+        var r = encodeURIComponent(collectionRow.dataset.repo);
+        var n = encodeURIComponent(collectionRow.dataset.number);
+        window.location.href = '/pr/' + o + '/' + r + '/' + n + '?host=' + encodeURIComponent(rowHost);
+        return;
+      }
+
       var prUrl = collectionRow.dataset.prUrl;
       if (prUrl) {
         // Switch to PR tab to show loading state (do NOT persist to
@@ -2542,4 +2609,14 @@
   window.__pairReview = window.__pairReview || {};
   window.__pairReview.refreshAnalysisSpinners = fetchAndApplyActiveAnalyses;
 
+  // Test-only exports. In the browser `module` is undefined, so this is a
+  // no-op; under Vitest (CommonJS) it exposes the internal bulk-open helpers
+  // for direct unit testing rather than duplicating their logic in a test.
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+      buildReviewUrlsFromRows: buildReviewUrlsFromRows,
+      getSelectedCollectionRows: getSelectedCollectionRows
+    };
+  }
+
 })();