@in-the-loop-labs/pair-review 3.8.0 → 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,7 +193,11 @@ 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 |
-| `--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`), interactive PR (`--ai`), and local (`--local --ai`) modes. |
+| `--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 |
@@ -214,6 +219,9 @@ 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
 ```
@@ -225,6 +233,149 @@ pair-review --register --command "node bin/pair-review.js"  # Custom command
 > 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.
@@ -372,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"
@@ -410,6 +561,8 @@ You can override provider settings and define custom models in your config file.
 | `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
 
@@ -422,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.8.0",
+  "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.8.0",
+  "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.8.0",
+  "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,39 @@ 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/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/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
@@ -940,7 +940,7 @@ class ClaudeProvider extends AIProvider {
   }
 
   static getDefaultModel() {
-    return 'opus';
+    return 'opus-4.8-xhigh';
   }
 
   static getInstallInstructions() {

package/src/ai/index.js

@@ -24,6 +24,10 @@ const {
   getProviderConfigOverrides,
   inferModelDefaults,
   resolveDefaultModel,
+  modelMatches,
+  mergeModels,
+  applyModelOverrides,
+  normalizeDisabledModels,
   prettifyModelId,
   createAliasedProviderClass,
   getTierForModel
@@ -81,6 +85,10 @@ module.exports = {
   getProviderConfigOverrides,
   inferModelDefaults,
   resolveDefaultModel,
+  modelMatches,
+  mergeModels,
+  applyModelOverrides,
+  normalizeDisabledModels,
   prettifyModelId,
   getTierForModel,