@in-the-loop-labs/pair-review 3.7.2 → 3.9.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)
+  - [Headless analysis mode](#headless-analysis-mode)
 - [Configuration](#configuration)
   - [Environment Variables](#environment-variables)
   - [GitHub Token](#github-token)
@@ -192,6 +193,12 @@ pair-review --local [path]
 | `<PR-URL>` | Full GitHub PR URL (e.g., `https://github.com/owner/repo/pull/123`) |
 | `--ai` | Automatically run AI analysis when the review loads |
 | `--ai-draft` | Run AI analysis and save suggestions as a draft review on GitHub |
+| `--headless` | Run AI analysis, store it in the local database, report the results, then exit. No server, no browser, no GitHub post. Implies analysis (does not require `--ai`). Works with a `<PR-number-or-URL>` or with `--local`. See [Headless analysis mode](#headless-analysis-mode). |
+| `--json` | With `--headless`, emit the completed run plus its consolidated suggestions as a single JSON document on a clean stdout. For any outcome of the headless run (success, zero findings, or an error raised while running it), stdout carries a JSON document with an `ok` field; failures emit an `{ "ok": false, "error": … }` envelope on stdout with a non-zero exit. (Pre-flight config/startup failures are the exception: they exit non-zero with a stderr message and no JSON envelope — branch on the exit code first.) stderr is quiet by default (only warnings/errors) — add `--debug` for verbose progress logs. Only valid together with `--headless`. |
+| `--instructions <text>` | Per-run custom instructions for this analysis. Applies to any mode that runs analysis — `--headless`, `--ai-draft`, `--ai-review` (consumed directly), and `--ai`/`--council` (carried into the browser-triggered analysis). Rejected with a clear error if no analysis mode is selected, so it is never silently dropped. Default: none. |
+| `--instructions-file <path>` | Read per-run custom instructions from a file (5000-character cap). Mutually exclusive with `--instructions`. |
+| `--council <handle>` | Run analysis with a saved multi-voice council. Implies analysis. The handle resolves by council name, name-slug, id (prefix), or a partial name fragment (resolving when it matches a single council, otherwise listing the candidates). When set, `--model` is ignored (council voices use their own per-voice models). Works in headless PR (`--ai-draft`/`--ai-review`/`--headless`), interactive PR (`--ai`), and local (`--local --ai`) modes. |
+| `--list-councils` | List saved councils with their handles, names, types, and last-used repo, then exit. Use a printed handle with `--council`. |
 | `--configure` | Show setup instructions and configuration options |
 | `-d`, `--debug` | Enable verbose debug logging for troubleshooting |
 | `-h`, `--help` | Show help message with full CLI documentation |
@@ -209,10 +216,166 @@ 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 --list-councils            # List saved councils and their handles
+pair-review 123 --ai-draft --council security-review  # Headless draft with a council
+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
+pair-review 123 --headless             # Analyze a PR, print a summary, exit
 pair-review --register                 # Register pair-review:// URL scheme (macOS)
 pair-review --register --command "node bin/pair-review.js"  # Custom command
 ```
 
+> **Councils** are saved multi-voice review configurations created and managed
+> in the web UI (under Analysis settings). `--council <handle>` selects one from
+> the CLI; the handle can be the council's name, its name-slug, an id prefix, or
+> a partial name fragment (which resolves when it uniquely identifies a council,
+> otherwise lists the candidates). Run `pair-review --list-councils` to discover
+> available handles.
+
+> **Repo default review config:** when neither `--council` nor `--model` is
+> given, pair-review uses the repository's configured default — its default
+> council if one is set, otherwise its default provider/model, otherwise the
+> global config default. This applies to `--headless`, the submit modes, and the
+> web UI's default **Analyze** action, so `--council`/`--model` are optional when
+> a repo default is configured.
+
+### Headless analysis mode
+
+`--headless` runs an AI analysis (single provider or council), stores the results
+in the local SQLite database exactly as the web UI does, reports them, and exits.
+It never starts the server, opens a browser, or posts to GitHub — it is the
+analysis core without the interactive or submit steps.
+
+```bash
+# Analyze uncommitted local changes, print a human-readable summary
+pair-review --local --headless
+
+# Analyze a PR (no review is created on GitHub)
+pair-review 123 --headless
+
+# Use a council and per-run instructions
+pair-review --local --headless --council security-review \
+  --instructions "Focus on auth and input validation."
+```
+
+**Exit codes:** a successful analysis exits `0` regardless of how many findings it
+surfaces (zero findings is still success, with an empty `suggestions` array).
+Non-zero exit is reserved for operational errors — invalid flags, an unreadable
+`--instructions-file`, or an analysis failure.
+
+**Machine-readable output (`--json`):** add `--json` to emit the completed run
+plus its consolidated final suggestions as a single JSON document on stdout, so
+stdout is a clean, parseable document suitable for scripting and AI coding
+agents:
+
+```bash
+pair-review --local --headless --json | jq '.suggestions | length'
+```
+
+Because this mode is consumed mostly by coding agents — whose shell tools capture
+stderr alongside stdout — **stderr is quiet by default**: only genuine warnings
+and errors are emitted, not progress narration. Add `--debug` to restore the full
+verbose log stream on stderr when diagnosing a run.
+
+The JSON document has this shape (fields reflect the stored run and the
+consolidated suggestion layer the app shows by default):
+
+```jsonc
+{
+  "ok": true,                 // false on failure (see below)
+  "mode": "local",            // "pr" or "local"
+  "run": {
+    "id": "…",                 // analysis run id
+    "review_id": 1,
+    "provider": "claude",      // for a council run: "council"
+    "model": "opus",           // for a council run: the council id
+    "tier": "balanced",
+    "config_type": "standard", // or "council" / "advanced"
+    "status": "completed",
+    "summary": "…",
+    "total_suggestions": 3,
+    "files_analyzed": 5,
+    "started_at": "…",
+    "completed_at": "…",
+    "head_sha": "…",
+    "parent_run_id": null,
+    "custom_instructions": null,
+    "global_instructions": null,
+    "repo_instructions": null,
+    "request_instructions": "Focus on auth…",  // from --instructions[-file]
+    "levels_config": { /* parsed */ },
+    "level_outcomes": { /* parsed */ }
+  },
+  "suggestions": [
+    {
+      "id": 42,
+      "ai_run_id": "…",
+      "ai_level": null,        // consolidated layer (per-level rows excluded)
+      "ai_confidence": 0.9,
+      "file": "src/app.js",
+      "line_start": 120,
+      "line_end": 124,
+      "type": "bug",
+      "title": "…",
+      "body": "…",
+      "severity": "high",
+      "status": "active",      // active or adopted
+      "is_file_level": 0,
+      "reasoning": { /* parsed */ },
+      "created_at": "…"
+    }
+  ],
+  "count": 1                   // suggestions.length
+}
+```
+
+**On failure** (invalid flags, an unreadable `--instructions-file`, or an
+analysis error raised while running the headless flow) `--json` emits a JSON
+document on stdout — a compact failure envelope — and the exit code is non-zero,
+so a consumer parses one stream and branches on `ok`:
+
+```jsonc
+{
+  "ok": false,
+  "mode": "local",            // "pr" or "local"
+  "error": { "message": "…" }
+}
+```
+
+The envelope covers errors raised once the headless run is under way. A fatal
+*pre-flight* failure — an unreadable or malformed `~/.pair-review/config.json`, an
+unwritable config directory, or an invalid port — exits non-zero with a message
+on **stderr** and does **not** emit a JSON envelope on stdout. Branch on the exit
+code first (as the example below does), then parse stdout.
+
+**Agent workflow.** A coding agent can run a headless analysis against its own
+uncommitted work, parse the JSON, and act on the suggestions:
+
+```bash
+result=$(pair-review --local --headless --json \
+  --council security-review \
+  --instructions "Review the changes I just made for security issues.")
+
+# Bail out on failure: non-zero exit, and `ok` is false in the JSON envelope.
+if [ $? -ne 0 ] || [ "$(echo "$result" | jq -r '.ok')" != "true" ]; then
+  echo "analysis failed: $(echo "$result" | jq -r '.error.message')" >&2
+  exit 1
+fi
+
+# Act on high-severity findings
+echo "$result" | jq -r '.suggestions[]
+  | select(.severity == "high")
+  | "\(.file):\(.line_start) [\(.type)] \(.title)"'
+```
+
+Once the run starts, `--json` produces a JSON document on stdout for any outcome
+— `{ "ok": true, … }` on success (any number of findings, including zero) and
+`{ "ok": false, … }` with a non-zero exit on an error raised while running it —
+so the agent reads exactly one stream and branches on `ok`. Because a pre-flight
+config/startup failure is the one case that exits without a JSON envelope,
+checking the exit code first (as above) covers every outcome.
+
 ## Configuration
 
 On first run, pair-review will prompt you to configure the application.
@@ -360,11 +523,11 @@ You can override provider settings and define custom models in your config file.
       "command": "opencode",
       "extra_args": ["--verbose"],
       "env": { "OPENCODE_TELEMETRY": "off" },
+      "default_model": "anthropic/claude-sonnet-4",
       "models": [
         {
           "id": "anthropic/claude-sonnet-4",
           "tier": "balanced",
-          "default": true,
           "name": "Claude Sonnet 4",
           "description": "Fast and capable for most reviews",
           "tagline": "Best balance of speed and quality"
@@ -395,7 +558,11 @@ You can override provider settings and define custom models in your config file.
 | `extra_args` | Additional arguments to pass to the CLI |
 | `env` | Environment variables to set when running the CLI |
 | `installInstructions` | Custom installation instructions shown in UI |
+| `availability_timeout_seconds` | Seconds to allow for the startup availability probe before the provider is reported unavailable (default `10`). Raise it for providers whose check runs a slow build/compile step. Also supported per chat provider under `chat_providers.<id>`. |
+| `availability_command` | Command run to decide availability. Executable providers default to always-available when omitted; chat providers fall back to `<command> --version` (or, for the built-in Pi, the cached AI-provider status). Pair with `availability_timeout_seconds` when the probe runs a slow build. |
 | `models` | Array of model definitions (see below) |
+| `default_model` | Model `id` to use as the provider's default (in the picker and when no model is specified). Preferred over the per-model `default: true` flag. If it names an unknown or disabled model, the provider falls back to automatic selection. |
+| `disabled_models` | Array of model selectors to hide, matched by model `id` or alias. Disabled models disappear from the model picker for that provider. Works on built-in models too, so you can remove a built-in option without redefining the rest. A list that would hide *every* model is ignored. |
 
 #### Model Configuration Fields
 
@@ -408,10 +575,29 @@ You can override provider settings and define custom models in your config file.
 | `tagline` | No | Short description shown in model picker |
 | `badge` | No | Badge text (e.g., "NEW", "BETA") |
 | `badgeClass` | No | CSS class for badge styling |
-| `default` | No | Set to `true` to make this the default model for the provider |
+| `default` | No | **Deprecated** — use the provider-level `default_model` field instead. Set to `true` to make this the default model for the provider. Still honored for backward compatibility, but `default_model` takes precedence when both are present. |
 | `extra_args` | No | Model-specific CLI arguments |
 | `env` | No | Model-specific environment variables |
 
+#### Choosing and Hiding Models
+
+Use the provider-level `default_model` and `disabled_models` fields to tailor which models a provider exposes — these work on **built-in** models too, so you can adjust a provider without redefining its entire model list.
+
+```json
+{
+  "providers": {
+    "claude": {
+      "default_model": "sonnet-4.6",
+      "disabled_models": ["haiku", "fable"]
+    }
+  }
+}
+```
+
+- `disabled_models` removes those models from the picker. It matches by model id or alias, so either a canonical id (`opus-4.8-xhigh`) or a convenience alias (`opus`) works. To find the built-in IDs for a provider, see the comments in `config.example.json` (e.g. Claude ships `opus-4.8-xhigh`, `sonnet-4.6`, `haiku`, …).
+- `default_model` selects which of the *remaining* models is the default. If it points at a model that is unknown or also disabled, the provider falls back to automatic selection (the model marked `default: true`, then the first `balanced`-tier model, then the first model).
+- Prefer `default_model` over the per-model `default: true` flag, which is deprecated. Setting `default_model` suppresses the deprecation warning.
+
 #### Model Tiers
 
 Models are grouped by tier to help users choose appropriately:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "3.7.2",
+  "version": "3.9.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "3.7.2",
+  "version": "3.9.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,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "3.7.2",
+  "version": "3.9.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.",
   "author": {
     "name": "in-the-loop-labs",

package/public/js/local.js

@@ -72,20 +72,40 @@ class LocalManager {
     // Auto-trigger analysis if ?analyze=true is present
     const autoAnalyze = new URLSearchParams(window.location.search).get('analyze');
     if (autoAnalyze === 'true' && !window.prManager.isAnalyzing) {
+      const manager = window.prManager;
       try {
-        // Fetch repo settings so we honour the repository's default provider/council
-        const manager = window.prManager;
-        const [repoSettings, reviewSettings, appConfig] = await Promise.all([
-          manager.fetchRepoSettings().catch(() => null),
-          manager.fetchLastReviewSettings().catch(() => ({ custom_instructions: '', last_council_id: null })),
-          manager._getAppConfig()
-        ]);
-        const config = await manager._buildDefaultAnalysisConfig(repoSettings, reviewSettings, appConfig);
+        // Prefer a stashed bulk-analysis config (threaded via analysisConfigId).
+        // The CLI uses it to carry --instructions plus the resolved
+        // provider/model or council snapshot into the browser auto-analyze;
+        // mirrors PRManager._maybeAutoAnalyze.
+        const storedConfig = await manager._fetchAutoAnalysisConfigFromUrl();
+        let config;
+        if (storedConfig.requested) {
+          if (!storedConfig.config) {
+            // The stored config expired (TTL/eviction/restart). The diff has
+            // already rendered, so leave the review usable for manual analysis
+            // rather than failing; warn and bail.
+            const message = 'Could not load the selected analysis settings. Start analysis manually to choose new settings.';
+            if (window.toast) window.toast.showWarning(message);
+            return;
+          }
+          config = storedConfig.config;
+        } else {
+          // Fetch repo settings so we honour the repository's default provider/council
+          const [repoSettings, reviewSettings, appConfig] = await Promise.all([
+            manager.fetchRepoSettings().catch(() => null),
+            manager.fetchLastReviewSettings().catch(() => ({ custom_instructions: '', last_council_id: null })),
+            manager._getAppConfig()
+          ]);
+          config = await manager._buildDefaultAnalysisConfig(repoSettings, reviewSettings, appConfig);
+        }
 
         await this.startLocalAnalysis(null, config);
       } finally {
         const cleanUrl = new URL(window.location);
         cleanUrl.searchParams.delete('analyze');
+        cleanUrl.searchParams.delete('analysisConfigId');
+        cleanUrl.searchParams.delete('council');
         history.replaceState(null, '', cleanUrl);
       }
     }

package/public/js/pr.js

@@ -638,6 +638,44 @@ class PRManager {
     const defaultTab = repoSettings?.default_tab || 'single';
     const councilId = repoSettings?.default_council_id || reviewSettings?.last_council_id || null;
 
+    // A `?council=<id>` URL param (set by the CLI when opening the browser) takes
+    // highest priority for council selection. When present we force the council
+    // branch regardless of default_tab/settings, and derive configType from the
+    // council's own type ('council' or 'advanced') rather than the repo default.
+    const urlSearch = (typeof window !== 'undefined' && window.location && window.location.search) || '';
+    const urlCouncilId = new URLSearchParams(urlSearch).get('council');
+    if (urlCouncilId) {
+      let councilConfig = null;
+      let councilName = null;
+      let councilType = null;
+      try {
+        const resp = await fetch(`/api/councils/${urlCouncilId}`);
+        if (resp.ok) {
+          const data = await resp.json();
+          councilConfig = data.council?.config || null;
+          councilName = data.council?.name || null;
+          councilType = data.council?.type || null;
+        } else {
+          console.warn(`Failed to fetch council "${urlCouncilId}" from URL param (status ${resp.status}); falling back to default analysis config`);
+        }
+      } catch (e) {
+        console.warn('Failed to fetch council config for URL council param:', e);
+      }
+
+      // Only honor the URL council if we successfully fetched its config.
+      // Otherwise fall through to the existing default-selection logic.
+      if (councilConfig) {
+        return {
+          isCouncil: true,
+          councilId: urlCouncilId,
+          councilConfig,
+          councilName,
+          configType: councilType || 'advanced',
+          customInstructions: null
+        };
+      }
+    }
+
     if ((defaultTab === 'council' || defaultTab === 'advanced') && councilId) {
       // Fetch the full council config so the progress modal can render correctly
       let councilConfig = null;
@@ -763,6 +801,7 @@ class PRManager {
           const cleanUrl = new URL(window.location);
           cleanUrl.searchParams.delete('analyze');
           cleanUrl.searchParams.delete('analysisConfigId');
+          cleanUrl.searchParams.delete('council');
           history.replaceState(null, '', cleanUrl);
         }
       }
@@ -3706,7 +3745,13 @@ class PRManager {
       // /file-content fetches) entirely when this body has none. The selector
       // mirrors the one validatePendingEofGaps scans for.
       if (entry.fileBody.querySelector('tr.context-expand-row[data-pending-eof-validation="true"]')) {
-        this.validatePendingEofGaps(entry.fileBody);
+        // Keep the in-flight promise on the entry. Until it resolves, the
+        // trailing EOF gap still carries EOF_SENTINEL coords, which makes
+        // findMatchingGap()'s overlap test unmatchable for a real target line.
+        // Line-anchoring callers (expandForSuggestion) await this so a
+        // suggestion/comment on a trailing unchanged line doesn't silently fail
+        // to expand. Fire-and-forget for everyone else.
+        entry.eofValidationPromise = this.validatePendingEofGaps(entry.fileBody);
       }
     }
 
@@ -4626,6 +4671,26 @@ class PRManager {
     // lazy body has rendered. Without this the gap query below returns nothing.
     await this.ensureFileBodyRendered(file);
 
+    // The trailing end-of-file gap is created with EOF_SENTINEL (-1) coords and
+    // resolved to real line numbers asynchronously by validatePendingEofGaps(),
+    // which _renderFileBodyNow fires fire-and-forget as the body renders. Until
+    // it settles the gap's NEW/OLD end is negative, so findMatchingGap()'s
+    // overlap test can never match a real target line — a suggestion (or
+    // comment, via ensureLinesVisible) on a trailing unchanged line silently
+    // fails to expand and never anchors. Pre-lazy-render this validation ran at
+    // renderDiff time, long before any suggestion was placed; lazy rendering
+    // collapsed that head start to nothing, which is the regression. Await the
+    // same in-flight promise (not a second /file-content fetch) so the EOF gap
+    // carries real coordinates before we match below.
+    const lazyEntry = this._lazyFileBodies?.get(fileElement.dataset?.fileName || file);
+    if (lazyEntry?.eofValidationPromise) {
+      try {
+        await lazyEntry.eofValidationPromise;
+      } catch {
+        // Validation removes the gap on fetch failure; matching simply misses.
+      }
+    }
+
     // Check if file is collapsed (generated files)
     if (fileElement.classList.contains('collapsed')) {
       debugLog?.('expandForSuggestion', 'File is collapsed, expanding first');
@@ -7069,22 +7134,42 @@ class PRManager {
   }
 
   /**
-   * Show an error when the worktree is not found during analysis.
-   * Displays a helpful message with a reload link. If the user arrived
-   * via auto-analyze (?analyze=true), the reload link preserves that
-   * parameter so analysis re-triggers after setup.
+   * Build the worktree-not-found recovery URL. When the user arrived via
+   * auto-analyze (?analyze=true), the reload link preserves the auto-analyze
+   * state so analysis re-triggers after worktree setup. Both the
+   * `analysisConfigId` and `council` params are carried through, since
+   * `_buildDefaultAnalysisConfig()` treats `?council=<id>` as the
+   * highest-priority analysis source — dropping it would silently fall back to
+   * the repo/default analysis configuration on retry.
    * @param {string} owner - Repository owner
    * @param {string} repo - Repository name
    * @param {number} number - PR number
+   * @returns {string} The recovery URL (unescaped)
    */
-  showWorktreeNotFoundError(owner, repo, number) {
+  _buildWorktreeRecoveryUrl(owner, repo, number) {
     let setupUrl = `/pr/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(number)}`;
     if (this._autoAnalyzeRequested) {
+      const currentParams = new URLSearchParams(window.location.search);
       const params = new URLSearchParams({ analyze: 'true' });
-      const analysisConfigId = new URLSearchParams(window.location.search).get('analysisConfigId');
+      const analysisConfigId = currentParams.get('analysisConfigId');
+      const councilId = currentParams.get('council');
       if (analysisConfigId) params.set('analysisConfigId', analysisConfigId);
+      if (councilId) params.set('council', councilId);
       setupUrl += `?${params.toString()}`;
     }
+    return setupUrl;
+  }
+
+  /**
+   * Show an error when the worktree is not found during analysis.
+   * Displays a helpful message with a reload link that preserves any
+   * auto-analyze state (see _buildWorktreeRecoveryUrl).
+   * @param {string} owner - Repository owner
+   * @param {string} repo - Repository name
+   * @param {number} number - PR number
+   */
+  showWorktreeNotFoundError(owner, repo, number) {
+    const setupUrl = this._buildWorktreeRecoveryUrl(owner, repo, number);
     const container = document.getElementById('pr-container');
     if (container) {
       container.innerHTML = `

package/public/js/utils/provider-model.js

@@ -19,13 +19,20 @@
 /**
  * @param {Object} providerInfo - One entry from /api/providers
  * @param {string} modelId
- * @returns {boolean} Whether modelId is one of the provider's models
+ * @returns {boolean} Whether modelId is one of the provider's models, matched by
+ *   canonical id OR any of its aliases. A persisted/configured value may name an
+ *   alias (e.g. `opus`) rather than the canonical id; matching aliases keeps the
+ *   user's choice instead of silently falling back to the provider default. The
+ *   model cards carry their `aliases` in the /api/providers payload. Mirrors the
+ *   backend `modelMatches()` helper in src/ai/provider.js.
  */
 function _modelBelongsToProvider(providerInfo, modelId) {
   return !!(
     providerInfo &&
     Array.isArray(providerInfo.models) &&
-    providerInfo.models.some(m => m && m.id === modelId)
+    // Optional chaining: a model with no `aliases` short-circuits to undefined
+    // (falsy) rather than throwing, so no Array.isArray guard is needed.
+    providerInfo.models.some(m => m && (m.id === modelId || m.aliases?.includes(modelId)))
   );
 }
 

package/public/setup.html

@@ -770,6 +770,10 @@
                         var qs = new URLSearchParams(window.location.search);
                         if (qs.get('analyze') === 'true') targetUrl.searchParams.set('analyze', qs.get('analyze'));
                         if (qs.get('analysisConfigId')) targetUrl.searchParams.set('analysisConfigId', qs.get('analysisConfigId'));
+                        // Forward the CLI-supplied council selection (PR & local cold-start
+                        // and delegated paths route through here); the review page keys
+                        // council auto-analysis on this param.
+                        if (qs.get('council')) targetUrl.searchParams.set('council', qs.get('council'));
                         window.location.href = targetUrl.toString();
                         return;
                     }
@@ -831,6 +835,10 @@
                                     var qs = new URLSearchParams(window.location.search);
                                     if (qs.get('analyze') === 'true') targetUrl.searchParams.set('analyze', qs.get('analyze'));
                                     if (qs.get('analysisConfigId')) targetUrl.searchParams.set('analysisConfigId', qs.get('analysisConfigId'));
+                                    // Forward the CLI-supplied council selection (PR & local cold-start
+                                    // and delegated paths route through here); the review page keys
+                                    // council auto-analysis on this param.
+                                    if (qs.get('council')) targetUrl.searchParams.set('council', qs.get('council'));
                                     window.location.href = targetUrl.toString();
                                 }
                             }, 400);

package/src/ai/claude-provider.js

@@ -33,8 +33,8 @@ const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
 const CLAUDE_MODELS = [
   // ── Thorough tier ───────────────────────────────────────────────────────
   {
-    id: 'fable',
-    aliases: ['fable-5-xhigh'],
+    id: 'fable-5-xhigh',
+    aliases: ['fable'],
     cli_model: 'claude-fable-5',
     env: { CLAUDE_CODE_EFFORT_LEVEL: 'xhigh' },
     name: 'Fable 5 XHigh',
@@ -61,49 +61,49 @@ const CLAUDE_MODELS = [
     extra_args: ['--thinking', 'adaptive']
   },
   {
-    id: 'opus',
-    aliases: ['opus-4.7-xhigh'],
-    cli_model: 'claude-opus-4-7',
+    id: 'opus-4.8-xhigh',
+    aliases: ['opus'],
+    cli_model: 'claude-opus-4-8',
     env: { CLAUDE_CODE_EFFORT_LEVEL: 'xhigh' },
-    name: 'Opus 4.7 XHigh',
+    name: 'Opus 4.8 XHigh',
     tier: 'thorough',
     tagline: 'Maximum Depth',
-    description: 'Opus 4.7 with extra-high effort — deepest analysis',
+    description: 'Opus 4.8 (newest) with extra-high effort — deepest analysis',
     badge: 'Most Thorough',
     badgeClass: 'badge-power',
     default: true
   },
   {
-    id: 'opus-4.7-high',
-    cli_model: 'claude-opus-4-7',
+    id: 'opus-4.8-high',
+    cli_model: 'claude-opus-4-8',
     env: { CLAUDE_CODE_EFFORT_LEVEL: 'high' },
-    name: 'Opus 4.7 High',
+    name: 'Opus 4.8 High',
     tier: 'thorough',
-    tagline: 'High Effort',
-    description: 'Opus 4.7 with high effort — thorough, quicker than XHigh',
-    badge: 'Thorough',
+    tagline: 'Newest',
+    description: 'Opus 4.8 (newest) with high effort',
+    badge: 'Latest',
     badgeClass: 'badge-power'
   },
   {
-    id: 'opus-4.8-xhigh',
-    cli_model: 'claude-opus-4-8',
+    id: 'opus-4.7-xhigh',
+    cli_model: 'claude-opus-4-7',
     env: { CLAUDE_CODE_EFFORT_LEVEL: 'xhigh' },
-    name: 'Opus 4.8 XHigh',
+    name: 'Opus 4.7 XHigh',
     tier: 'thorough',
-    tagline: 'Newest',
-    description: 'Opus 4.8 (newest) with extra-high effort',
-    badge: 'Latest',
+    tagline: 'Previous Gen',
+    description: 'Opus 4.7 with extra-high effort',
+    badge: 'Previous Gen',
     badgeClass: 'badge-power'
   },
   {
-    id: 'opus-4.8-high',
-    cli_model: 'claude-opus-4-8',
+    id: 'opus-4.7-high',
+    cli_model: 'claude-opus-4-7',
     env: { CLAUDE_CODE_EFFORT_LEVEL: 'high' },
-    name: 'Opus 4.8 High',
+    name: 'Opus 4.7 High',
     tier: 'thorough',
-    tagline: 'Newest',
-    description: 'Opus 4.8 (newest) with high effort',
-    badge: 'Latest',
+    tagline: 'High Effort',
+    description: 'Opus 4.7 with high effort — thorough, quicker than XHigh',
+    badge: 'Thorough',
     badgeClass: 'badge-power'
   },
   {
@@ -162,7 +162,7 @@ class ClaudeProvider extends AIProvider {
    * @param {Object} configOverrides.env - Additional environment variables
    * @param {Object[]} configOverrides.models - Custom model definitions
    */
-  constructor(model = 'opus', configOverrides = {}) {
+  constructor(model = ClaudeProvider.getDefaultModel(), configOverrides = {}) {
     super(model);
 
     // Command precedence: ENV > config > default
@@ -858,9 +858,10 @@ class ClaudeProvider extends AIProvider {
    * Test if Claude CLI is available
    * Uses fast `--version` check instead of running a prompt.
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.claudeCmd)
@@ -889,10 +890,10 @@ class ClaudeProvider extends AIProvider {
       const availabilityTimeout = setTimeout(() => {
         if (settled) return;
         settled = true;
-        logger.warn('Claude CLI availability check timed out after 10s');
+        logger.warn(`Claude CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
         try { claude.kill(); } catch { /* ignore */ }
         resolve(false);
-      }, 10000);
+      }, timeoutMs);
 
       claude.stdout.on('data', (data) => {
         stdout += data.toString();
@@ -939,7 +940,7 @@ class ClaudeProvider extends AIProvider {
   }
 
   static getDefaultModel() {
-    return 'opus';
+    return 'opus-4.8-xhigh';
   }
 
   static getInstallInstructions() {