major update

.env.example

@@ -18,7 +18,13 @@ ELIZACLOUD_API_KEY=your-elizacloud-key-here
 # Default model (optional, defaults to gpt-4o):
 # PRR_LLM_MODEL=gpt-4o
 
-# ElizaCloud: extra 500/502/504 retries inside each complete() (0–15). CI defaults to 5 HTTP attempts when unset; locally 3.
+# Stronger models for verification / final audit (optional; invalid ids ignored with warning — see shared/config.ts).
+# Order: PRR_FINAL_AUDIT_MODEL → PRR_VERIFIER_MODEL → PRR_LLM_MODEL (README / AGENTS.md).
+# PRR_VERIFIER_MODEL=anthropic/claude-sonnet-4-5-20250929
+# PRR_FINAL_AUDIT_MODEL=anthropic/claude-opus-4-5-20251101
+
+# ElizaCloud: extra 500/502/504 retries inside each complete() (integer 0–15). CI defaults to 5 HTTP attempts when unset; locally 3.
+# Non-numeric, non–whole-decimal (e.g. 3abc), or out-of-range values log a warning once per value and fall back to those defaults.
 # PRR_ELIZACLOUD_SERVER_ERROR_RETRIES=6
 
 # After 2 consecutive gateway 5xx on the same model, try these ids in order (comma-separated). off = disable.
@@ -32,7 +38,68 @@ ELIZACLOUD_API_KEY=your-elizacloud-key-here
 # OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
 
 # Optionally force a specific provider (auto-detects if not set):
-# PRR_LLM_PROVIDER=elizacloud  # or 'anthropic' or 'openai'
+# PRR_LLM_PROVIDER=elizacloud  # or 'anthropic' | 'openai' | 'nvidiacloud' | 'openrouter' | 'ollama' | 'lmstudio'
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# NVIDIA Cloud (NIM / integrate) — OpenAI-compatible
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# PRR_LLM_PROVIDER=nvidiacloud
+# NVIDIA_API_KEY=nvapi-xxxxxxxx   # or NVIDIA_CLOUD_API_KEY
+# Optional: NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+# PRR_LLM_MODEL=meta/llama-3.1-405b-instruct   # default when unset; override per account
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# OpenRouter — OpenAI-compatible
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# PRR_LLM_PROVIDER=openrouter
+# OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx
+# Optional: OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# Optional attribution (OpenRouter docs): OPENROUTER_HTTP_REFERER=, OPENROUTER_APP_TITLE=
+# PRR_LLM_MODEL=google/gemini-2.0-flash-001   # default when unset
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Ollama / LM Studio (first-class — OpenAI-compatible /v1)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# PRR_LLM_PROVIDER=ollama
+# Optional: OLLAMA_BASE_URL=http://127.0.0.1:11434/v1   # default if unset
+# Optional: OLLAMA_API_KEY=ollama   # placeholder for SDK; Ollama often ignores auth
+# PRR_LLM_MODEL=llama3.2   # default when unset for ollama; override to a pulled tag
+#
+# PRR_LLM_PROVIDER=lmstudio
+# Optional: LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1   # default if unset
+# Optional: LMSTUDIO_API_KEY=lm-studio
+# PRR_LLM_MODEL=your-loaded-model-id   # REQUIRED for lmstudio (from LM Studio server UI)
+#
+# WHY first-class ollama/lmstudio: PRR + llm-api share defaults (base URL, max_tokens style, reachability)
+# and PRR_LLM_PROVIDER wins for the fixer without hand-syncing OPENAI_BASE_URL.
+#
+# Startup model lists (validateAndFilterModels): OpenRouter/NVIDIA /v1/models also use OPENROUTER_API_KEY
+# and NVIDIA_* from env when config fields are unset — WHY: keep rotation aligned with llm-api when
+# only process.env has the key. Empty /v1/models for local backends does not strip pinned/fallback ids.
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Local OpenAI-compatible servers (same /v1 via openai provider)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Alternative: use PRR_LLM_PROVIDER=openai and point the OpenAI client at /v1.
+#
+# OPENAI_BASE_URL must be the OpenAI-compatible ROOT ending in /v1 (SDK + llm-api use it for
+# models.list and /chat/completions). Examples:
+#   Ollama (default port):     http://127.0.0.1:11434/v1
+#   Ollama (custom host/port): http://192.168.1.50:8080/v1
+#   LM Studio (default):       http://localhost:1234/v1   — see https://lmstudio.ai/docs/developer/openai-compat
+#
+# Do NOT set OPENAI_BASE_URL to Ollama's native /api/... base (e.g. http://host:11434/api) — that is
+# not the OpenAI compatibility surface.
+#
+# OPENAI_API_KEY can be any non-empty string if the server ignores auth (typical Ollama / local LM Studio).
+#
+# PRR_LLM_MODEL / PRR_VERIFIER_MODEL / PRR_FINAL_AUDIT_MODEL must match ids from GET {OPENAI_BASE_URL}/models
+# on that host (e.g. gpt-oss:20b, llama3.2:latest — colon tags are allowed).
+#
+# PRR_LLM_PROVIDER=openai
+# OPENAI_BASE_URL=http://127.0.0.1:11434/v1
+# OPENAI_API_KEY=ollama
+# PRR_LLM_MODEL=gpt-oss:20b
 
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # Other Options
@@ -48,18 +115,27 @@ ELIZACLOUD_API_KEY=your-elizacloud-key-here
 # LLM concurrency (default 1). Raised values speed batches when the gateway allows it.
 # PRR_MAX_CONCURRENT_LLM=3
 
+# Min ms between ElizaCloud request starts per concurrent slot (default from shared/constants/models.ts).
+# PRR_LLM_MIN_DELAY_MS=6000
+
 # Optional: max ms per concurrent pool task (batch analysis / parallel fix groups). Unset or 0 = no cap.
 # PRR_LLM_TASK_TIMEOUT_MS=600000
 
+# llm-api fixer: client wait per HTTP attempt when NOT in full-file rewrite mode. Unset = auto (90s, then 120s/150s/180s by prompt size). Full-file rewrite always uses 180s unless you change code constants.
+# PRR_LLM_API_REQUEST_TIMEOUT_MS=240000
+
 # Skip a fixer model for the rest of the run after this many verification failures with zero verified fixes (default 4). Set to 0 to disable.
 # PRR_SESSION_MODEL_SKIP_FAILURES=4
-# Every N fix iterations, clear session-skipped models so rotation retries them (0 = off). Pill-output #847.
+# After N fix iterations since each model was session-skipped, drop that skip so rotation can retry (0 = off). Pill-output #847.
 # PRR_SESSION_MODEL_SKIP_RESET_AFTER_FIX_ITERATIONS=8
 
 # Warn once after this many consecutive iterations with no new verified fixes (default 10). Set to 0 to disable.
 # PRR_DIMINISHING_RETURNS_ITERATIONS=10
 
-# ElizaCloud: built-in skip list is in shared/constants.ts (ELIZACLOUD_SKIP_MODEL_IDS).
+# Total failed fix attempts per issue before chronic-failure dismissal (integer ≥ 1; default 5). Non-integer values log a warning and fall back to 5.
+# PRR_CHRONIC_FAILURE_THRESHOLD=8
+
+# ElizaCloud: built-in skip list is authored in shared/constants/models.ts (ELIZACLOUD_SKIP_MODEL_IDS; barrel: shared/constants).
 # Add more models to skip for this machine/run (comma-separated API ids, merged with built-in list):
 # PRR_ELIZACLOUD_EXTRA_SKIP_MODELS=openai/some-model-id
 
@@ -72,25 +148,66 @@ ELIZACLOUD_API_KEY=your-elizacloud-key-here
 # Catalog model advice (see AGENTS.md): disable 0a6 dismissal and/or quoted-literal auto-heal.
 # PRR_DISABLE_MODEL_CATALOG_SOLVABILITY=1
 # PRR_DISABLE_MODEL_CATALOG_AUTOHEAL=1
+# Override committed JSON snapshot (default: generated/model-provider-catalog.json). Malformed file → empty catalog + warn.
+# PRR_MODEL_CATALOG_PATH=/path/to/model-provider-catalog.json
 
-# Thread replies: set to the GitHub login that posts replies so re-runs skip duplicate posts.
+# Thread replies: optional override for cross-run idempotency (default: token login from GET /user).
 # PRR_BOT_LOGIN=my-bot
 # PRR_REPLY_TO_THREADS=true
+# When replies are on, PRR resolves review threads by default. Opt out:
+# PRR_RESOLVE_THREADS=0
+# Thread working reactions (REST 👀 on inline review comments while PRR works them). Default on.
+# WHY opt-out exists: token-tight CI or PATs without reactions scope should not spam errors — use 0/false/off.
+# PRR_THREAD_WORKING_REACTIONS=0
+# Min ms between reaction POSTs in one run (default 1000; caps burst traffic on huge PRs).
+# PRR_THREAD_WORKING_REACTION_MIN_MS=1200
 # Also reply on threads dismissed as chronic-failure (default: no — batch token-saving dismissals).
 # PRR_THREAD_REPLY_INCLUDE_CHRONIC_FAILURE=1
 
+# Exit 2 on success when any issue stayed verified despite final audit UNFIXED (audit overrides; rare).
+# PRR_STRICT_FINAL_AUDIT=1
 # Exit 2 on success when final audit passed any issue via UNCERTAIN or truncation guard (fail closed).
 # PRR_STRICT_FINAL_AUDIT_UNCERTAIN=1
 
 # Exit setup before clone when CodeRabbit (or bot) review SHA ≠ PR HEAD — saves work if inline comments are stale.
 # PRR_EXIT_ON_STALE_BOT_REVIEW=1
 
-# Exit setup before clone when GitHub says PR is not mergeable / dirty (unless you pass --merge-base).
+# Exit when GitHub says PR is not mergeable / dirty while --no-merge-base (skip base integration): before clone and each push iter (fresh pulls.get).
 # PRR_EXIT_ON_UNMERGEABLE=1
 
-# On PR HEAD change: clear every dismissal (default clears only "already-fixed" dismissals).
+# When REST pulls.get returns mergeable=null (GitHub still computing), re-fetch up to N times with delay (default 3 × 2000 ms). Set attempts to 0 to disable.
+# PRR_MERGEABLE_POLL_ATTEMPTS=3
+# PRR_MERGEABLE_POLL_MS=2000
+
+# On PR HEAD change: clear every dismissal category (default clears already-fixed, chronic-failure, stale; keeps e.g. not-an-issue).
 # PRR_CLEAR_ALL_DISMISSED_ON_HEAD=1
 
+# Throw on state load if the same comment id appears in both verified and dismissed (default: auto-repair overlap).
+# PRR_STRICT_STATE_OVERLAP=1
+
+# After load-time state repair (overlap scrub, HEAD sync, lesson compact, …), write .pr-resolver-state.json immediately.
+# Default (unset): on — set 0/false/off to skip (e.g. read-only inspection of a workdir state file).
+# PRR_PERSIST_STATE_AFTER_LOAD_REPAIR=0
+
+# Fixer allowlist: strict first-segment filter (static REPO_TOP_LEVEL + PR changed-file roots).
+# Default (unset): open — any repo-relative path is OK except absolute, node_modules, dist/, .cursor, .prr.
+# WHY default open: unknown roots like agent/ were silently stripped from allowedPaths → no injection, wasted iterations (Cycle 72).
+# WHY set strict: comment bodies that paste dependency-style paths; pair with PR diff so touched roots still whitelist.
+# PRR_STRICT_ALLOWED_PATHS=1
+
+# Max new bot review threads to enqueue per mid–fix-loop batch (0 = unlimited). Default 45.
+# PRR_MID_LOOP_NEW_COMMENT_CAP=45
+
+# Blast radius (changed files + import graph + proximity) — deprioritize / optional dismiss / narrower injection:
+# WHY: Order and llm-api injection focus on PR-related files; fixer allowlist stays full (see README "Blast radius").
+# Graph uses async FS in specifier-resolver; timeout/max-files abort → all issues in-scope (no silent skip).
+# PRR_DISABLE_BLAST_RADIUS=1
+# PRR_BLAST_RADIUS_DEPTH=2
+# PRR_BLAST_RADIUS_DISMISS=1
+# PRR_BLAST_RADIUS_MAX_FILES=5000
+# PRR_BLAST_RADIUS_TIMEOUT_MS=30000
+# PRR_BLAST_RADIUS_MAX_DIR_NEIGHBORS=30
+
 # Dry-merge probes after fetch (git merge-tree; warns before pull if conflicts):
 # PRR_DISABLE_LATENT_MERGE_PROBE=1          # skip HEAD vs origin/<prBranch>
 # PRR_DISABLE_LATENT_MERGE_PROBE_BASE=1     # skip HEAD vs origin/<prBase> (GitHub mergeable/dirty)
@@ -99,9 +216,25 @@ ELIZACLOUD_API_KEY=your-elizacloud-key-here
 # PRR_MATERIALIZE_LATENT_MERGE=1            # merge origin/<prBranch> --no-commit
 # PRR_MATERIALIZE_LATENT_MERGE_BASE=1       # merge origin/<prBase> --no-commit
 
+# Clone / fetch (ms). Large or slow remotes: raise timeouts (README Troubleshooting / AGENTS.md).
+# PRR_CLONE_TIMEOUT_MS=900000
+# PRR_FETCH_TIMEOUT_MS=120000
+
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # Pill (log audit — optional, e.g. prr --pill)
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # When tools/prr exists under the pill target directory, drop improvements whose file paths
 # look like the PR clone (src/, packages/, …). Set to 0 to record everything the LLM returns.
 # PILL_TOOL_REPO_SCOPE_FILTER=0
+# Rerun pill on explicit log files (absolute or cwd-relative). CLI --output-log / --prompts-log wins.
+# PILL_OUTPUT_LOG_PATH=/path/to/output.log
+# PILL_PROMPTS_LOG_PATH=/path/to/prompts.log
+#
+# Optional: force provider (else auto-detect from keys: ElizaCloud > Anthropic > OpenAI > OpenRouter > NVIDIA).
+# PILL_LLM_PROVIDER=openrouter
+#
+# Optional: override models. WHY defaults matter: CLI --audit-model still defaults to a Claude id; when the only
+# key is OpenRouter/NVIDIA/OpenAI and PILL_AUDIT_MODEL is unset, loadConfig substitutes provider defaults so the
+# audit is not sent to the wrong /v1 host (see tools/pill/README.md, shared/llm/openai-compat-chat-params.ts).
+# PILL_AUDIT_MODEL=anthropic/claude-sonnet-4-5-20250929
+# PILL_LLM_MODEL=google/gemini-2.0-flash-001