codegraph-brain 0.6.0__py3-none-any.whl

cgis/guardian/providers/mistral.py

@@ -0,0 +1,83 @@
+"""Mistral AI LLM provider for Guardian."""
+
+from pydantic import BaseModel
+
+from cgis.guardian.providers.base import DEFAULT_REQUEST_TIMEOUT, BaseProvider, ProviderUsage
+
+
+class MistralProvider(BaseProvider):
+    """Mistral AI provider. Requires: uv sync --group guardian"""
+
+    def __init__(
+        self,
+        api_key: str,
+        model_name: str = "mistral-medium-latest",
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ) -> None:
+        """Store credentials and the request timeout; mistralai is imported lazily.
+
+        The SDK takes MILLISECONDS and hard-codes 60 000 when given nothing
+        (mistralai/client/chat.py) — that default is what killed the review on
+        #274, so it is always overridden here.
+        """
+        super().__init__()
+        self._api_key = api_key
+        self._model_name = model_name
+        self._timeout_ms = int(timeout * 1000)
+
+    async def _generate(self, system_prompt: str, user_prompt: str, *, json_mode: bool) -> str:
+        """Shared transport: one chat.complete_async call, optional json_object mode."""
+        _install_hint = "mistralai is required. Install with: uv sync --group guardian"
+        try:
+            from mistralai.client import Mistral  # noqa: PLC0415
+        except ImportError as exc:
+            raise ImportError(_install_hint) from exc
+        extra: dict[str, object] = {}
+        if json_mode:
+            extra["response_format"] = {"type": "json_object"}
+        async with Mistral(api_key=self._api_key, timeout_ms=self._timeout_ms) as client:
+            response = await client.chat.complete_async(
+                model=self._model_name,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                **extra,
+            )
+        if not response.choices:
+            _msg = f"Mistral returned no choices for model {self._model_name}"
+            raise ValueError(_msg)
+        content = response.choices[0].message.content
+        if content is None:
+            _msg = f"Mistral returned null message content for model {self._model_name}"
+            raise ValueError(_msg)
+        usage = getattr(response, "usage", None)
+        if usage is not None:
+            self._record_usage(
+                ProviderUsage(
+                    prompt_tokens=getattr(usage, "prompt_tokens", 0),
+                    completion_tokens=getattr(usage, "completion_tokens", 0),
+                )
+            )
+        return str(content)
+
+    async def generate_content(self, system_prompt: str, user_prompt: str) -> str:
+        """Send prompts to Mistral and return the text response."""
+        return await self._retry(
+            lambda: self._generate(system_prompt, user_prompt, json_mode=False)
+        )
+
+    async def generate_structured(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        schema: type[BaseModel],
+    ) -> str:
+        """Send prompts in json_object mode.
+
+        Mistral's json_object mode takes no schema parameter — the schema is
+        described in the user prompt (spec §2.4); the argument exists to
+        satisfy the BaseProvider contract.
+        """
+        del schema
+        return await self._retry(lambda: self._generate(system_prompt, user_prompt, json_mode=True))

cgis/guardian/providers/ollama.py

@@ -0,0 +1,99 @@
+"""Ollama LLM provider for Guardian — local/colab inference, no API key.
+
+Targets an Ollama server (default http://localhost:11434, or a tunneled port via
+GUARDIAN_OLLAMA_HOST). The model must already be pulled on that server
+(`ollama pull <model>`). Useful for free local benching and for a cross-model
+skeptic built from two distinct local models.
+"""
+
+from pydantic import BaseModel
+
+from cgis.guardian.providers.base import BaseProvider, ProviderUsage
+
+# Colab/local GPUs are slow and cold-load weights on the first call — a tight
+# timeout would spuriously fail the first request of every run.
+DEFAULT_OLLAMA_TIMEOUT = 600.0
+
+# Ollama defaults num_ctx to ~2048 and SILENTLY TRUNCATES longer prompts — which
+# would feed the finder a fraction of the diff and quietly tank recall. Guardian
+# prompts (diff + graph + files) run tens of thousands of tokens, so set an
+# explicit window. 32768 matches qwen2.5-coder's max; raise it (e.g. for
+# llama3.1's 128k) or lower it for VRAM via GUARDIAN_OLLAMA_NUM_CTX.
+DEFAULT_OLLAMA_NUM_CTX = 32768
+
+
+class OllamaProvider(BaseProvider):
+    """Ollama provider. Requires: uv sync --group guardian (ollama client)."""
+
+    def __init__(
+        self,
+        model_name: str,
+        host: str | None = None,
+        timeout: float = DEFAULT_OLLAMA_TIMEOUT,
+        num_ctx: int = DEFAULT_OLLAMA_NUM_CTX,
+    ) -> None:
+        """Store model, host (None → localhost:11434), timeout, and context window."""
+        super().__init__()
+        self._model_name = model_name
+        self._host = host
+        self._timeout = timeout
+        self._num_ctx = num_ctx
+
+    async def _generate(
+        self, system_prompt: str, user_prompt: str, *, fmt: str | dict[str, object]
+    ) -> str:
+        """Shared transport: one non-streaming chat call.
+
+        fmt is "" (free text), "json" (valid JSON, any shape), or a JSON Schema
+        dict (constrained decoding — forces a schema-conformant object). Small
+        local models emit null in required fields under plain "json"; the schema
+        form prevents that.
+        """
+        _install_hint = "ollama is required. Install with: uv sync --group guardian"
+        try:
+            from ollama import AsyncClient  # noqa: PLC0415
+        except ImportError as exc:
+            raise ImportError(_install_hint) from exc
+        # Context manager so the underlying httpx pool is closed each call.
+        async with AsyncClient(host=self._host, timeout=self._timeout) as client:
+            response = await client.chat(
+                model=self._model_name,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                stream=False,
+                format=fmt,
+                options={"num_ctx": self._num_ctx},
+            )
+        content = response.message.content
+        if content is None:
+            _msg = f"Ollama returned null message content for model {self._model_name}"
+            raise ValueError(_msg)
+        self._record_usage(
+            ProviderUsage(
+                prompt_tokens=response.prompt_eval_count or 0,
+                completion_tokens=response.eval_count or 0,
+            )
+        )
+        return str(content)
+
+    async def generate_content(self, system_prompt: str, user_prompt: str) -> str:
+        """Send prompts to Ollama and return the text response."""
+        return await self._retry(lambda: self._generate(system_prompt, user_prompt, fmt=""))
+
+    async def generate_structured(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        schema: type[BaseModel],
+    ) -> str:
+        """Send prompts with Ollama's schema-constrained format (structured output).
+
+        Passing the model's JSON Schema makes Ollama constrain decoding to a
+        conformant object — small local models otherwise emit null in required
+        fields under plain "json" mode, which fails strict validation downstream.
+        """
+        return await self._retry(
+            lambda: self._generate(system_prompt, user_prompt, fmt=schema.model_json_schema())
+        )

cgis/guardian/recording.py

@@ -0,0 +1,82 @@
+"""Persisted finder passes: the recording format shared by bench and production.
+
+Extracted from bench.py (#279) once run_guardian became a second consumer —
+production code must not import the benchmark module. Same reason diff_index.py
+was split out of chunker.py when the skeptic pass needed the per-file split.
+"""
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from cgis.guardian.findings import ReviewResult
+
+
+class FinderRecording(BaseModel, frozen=True):
+    """A frozen finder pass: its findings plus the diff they were found in (#246 §4.1).
+
+    The diff travels with the findings so a replay needs no worktree, ingest or
+    git at all — without it, isolating the skeptic would still pay the whole
+    setup cost the replay exists to avoid.
+    """
+
+    result: ReviewResult
+    diff: str
+
+
+def _validated_recording_path(path: Path, *, must_exist: bool) -> Path:
+    """Resolve and check a CLI-supplied recording path before touching the filesystem.
+
+    Both entry points take their path from a benchmark CLI flag, so the value is
+    untrusted input. Validation mirrors the precedent set for the MCP drift
+    surface (#167): resolve, require the expected suffix, and require an
+    existing file when reading — deliberately WITHOUT confining the path under
+    the CWD, which would break the legitimate cross-repo/tmpdir workflows this
+    tool is used in.
+    """
+    resolved = path.expanduser().resolve()
+    if resolved.suffix != ".json":
+        _msg = f"Recording path must be a .json file: {path}"
+        raise ValueError(_msg)
+    if must_exist and not resolved.is_file():
+        _msg = f"Recording path is not a file: {path}"
+        raise ValueError(_msg)
+    return resolved
+
+
+def save_finder_recording(path: Path, result: ReviewResult, diff: str) -> None:
+    """Write a finder pass to disk for later replay.
+
+    A production recording is taken AFTER the skeptic ran, which is safe because
+    load_finder_recording strips verdicts on read. One caveat travels with it:
+    apply_judgements rewrites confidence to round(confidence * 0.9) for
+    'uncertain' verdicts and the load path does not restore it, so a recorded
+    confidence on that subset is not the finder's own number (#279).
+    """
+    target = _validated_recording_path(path, must_exist=False)
+    recording = FinderRecording(result=result, diff=diff)
+    target.write_text(recording.model_dump_json(), encoding="utf-8")
+
+
+def load_finder_recording(path: Path) -> FinderRecording:
+    """Load a recorded finder pass, stripping any skeptic verdicts it carries.
+
+    A recording captured from a run that HAD a skeptic would otherwise smuggle
+    those verdicts into the next variant's scoring — every replay must start
+    from unjudged findings, or the arms are not comparable.
+    """
+    source = _validated_recording_path(path, must_exist=True)
+    recording = FinderRecording.model_validate_json(source.read_text(encoding="utf-8"))
+    findings = [
+        f.model_copy(update={"verdict": None, "skeptic_note": None, "impact_score": None})
+        for f in recording.result.findings
+    ]
+    clean = recording.result.model_copy(
+        update={
+            "findings": findings,
+            "skeptic_status": "off",
+            "skeptic_judged": 0,
+            "skeptic_total": 0,
+        }
+    )
+    return recording.model_copy(update={"result": clean})

cgis/guardian/render.py

@@ -0,0 +1,107 @@
+"""Pure rendering of ReviewResult into the PR-comment markdown (spec §2.5)."""
+
+from cgis.guardian.findings import Finding, ReviewResult
+from cgis.guardian.skeptic import visible_findings
+
+_SEVERITY_MARKER = {"critical": "🔴", "major": "🟠", "minor": "🟡"}
+_SEVERITY_ORDER = {"critical": 0, "major": 1, "minor": 2}
+_CATEGORY_LABEL = {
+    "logic": "Logic Bug",
+    "contract": "Library Contract",
+    "tests": "Test Coverage",
+    "types": "Type Safety",
+    "ontology": "Ontology",
+}
+
+
+def _rank_key(finding: Finding) -> tuple[int, int]:
+    """Sort key: impact descending, then severity (#246 §3.5).
+
+    An unjudged finding scores -1 rather than 0 so it sorts after every scored
+    one — no score is "no ranking signal", not "scored zero".
+    """
+    impact = finding.impact_score if finding.impact_score is not None else -1
+    return (-impact, _SEVERITY_ORDER[finding.severity])
+
+
+def render_finding(finding: Finding) -> str:
+    """Render one finding in the **[Category] — title** block format."""
+    location = (
+        f"`{finding.file}:{finding.line}`" if finding.line is not None else f"`{finding.file}`"
+    )
+    impact = f" · Impact: {finding.impact_score}/10" if finding.impact_score is not None else ""
+    lines = [
+        f"**[{_CATEGORY_LABEL[finding.category]}] — {finding.title}**",
+        f"{_SEVERITY_MARKER[finding.severity]} {finding.severity} at {location}"
+        f" · Confidence: {finding.confidence}%{impact}",
+        f"Lines: `` {finding.evidence} ``",
+        f"Problem: {finding.problem}",
+        f"Fix: {finding.fix}",
+    ]
+    if finding.verdict is not None:
+        note = f" — {finding.skeptic_note}" if finding.skeptic_note else ""
+        lines.append(f"Skeptic: {finding.verdict}{note}")
+    return "\n".join(lines)
+
+
+def render_inline_comment(finding: Finding, *, skeptic_model: str | None) -> str:
+    """One finding as a standalone inline comment body (spec §6.3)."""
+    lines = [
+        f"{_SEVERITY_MARKER[finding.severity]} "
+        f"**[{_CATEGORY_LABEL[finding.category]}] — {finding.title}**",
+        f"{finding.problem}",
+        f"Fix: {finding.fix}",
+    ]
+    if finding.verdict == "confirmed" and skeptic_model:
+        lines.append(f"_Verified by {skeptic_model}_")
+    return "\n\n".join(lines)
+
+
+def render_review_body(result: ReviewResult, *, outside: list[Finding], threshold: int = 0) -> str:
+    """The review's top-level body: summary plus any out-of-diff findings (spec §6.3)."""
+    if not visible_findings(result.findings, threshold):
+        return render_report(result, threshold)
+    parts: list[str] = []
+    if outside:
+        ordered = sorted(outside, key=_rank_key)
+        blocks = "\n\n".join(render_finding(f) for f in ordered)
+        parts.append(f"### Findings outside the diff\n\n{blocks}")
+    parts.append(f"**Summary:** {result.summary}")
+    return "\n\n".join(parts)
+
+
+def render_report(result: ReviewResult, threshold: int = 0) -> str:
+    """Render the full review; hidden findings are never hidden silently.
+
+    ``threshold`` suppresses findings the skeptic scored below it (#246 §3.5).
+    Both kinds of suppression — refuted and below-threshold — are counted in the
+    notes, and both stay in ``result.findings`` for metrics.
+    """
+    if result.parse_failed:
+        return (
+            "⚠️ Guardian could not produce structured output; raw response below.\n\n"
+            + result.summary
+        )
+    unrefuted = visible_findings(result.findings)
+    visible = visible_findings(result.findings, threshold)
+    refuted_count = len(result.findings) - len(unrefuted)
+    below_threshold = len(unrefuted) - len(visible)
+    notes: list[str] = []
+    if refuted_count:
+        plural = "finding was" if refuted_count == 1 else "findings were"
+        notes.append(f"_{refuted_count} {plural} refuted by the skeptic pass._")
+    if below_threshold:
+        plural = "finding was" if below_threshold == 1 else "findings were"
+        notes.append(f"_{below_threshold} {plural} below the impact threshold ({threshold})._")
+    if result.skeptic_status == "failed":
+        notes.append("_Skeptic pass failed; findings are single-pass._")
+    if result.skeptic_status == "partial":
+        notes.append(
+            f"_Skeptic judged {result.skeptic_judged} of {result.skeptic_total} findings; "
+            "the rest are single-pass._"
+        )
+    suffix = ("\n\n" + "\n".join(notes)) if notes else ""
+    if not visible:
+        return f"LGTM — no defects found in this diff.\n\n{result.summary}{suffix}"
+    blocks = [render_finding(f) for f in sorted(visible, key=_rank_key)]
+    return "\n\n".join(blocks) + f"\n\n---\n**Summary:** {result.summary}{suffix}"

cgis/guardian/runner.py

@@ -0,0 +1,295 @@
+"""Testable orchestration for the guardian review script."""
+
+import asyncio
+import time
+from collections.abc import Mapping
+from pathlib import Path
+
+import structlog
+
+from cgis.guardian.chunked import run_review_routed
+from cgis.guardian.collector import ContextCollector
+from cgis.guardian.diff_index import diff_line_content
+from cgis.guardian.findings import ReviewResult
+from cgis.guardian.github_poster import post_inline_review
+from cgis.guardian.metrics import SkepticRecord, record_review
+from cgis.guardian.providers.base import BaseProvider, ProviderUsage
+from cgis.guardian.providers.gemini import GeminiProvider
+from cgis.guardian.providers.mistral import MistralProvider
+from cgis.guardian.providers.ollama import DEFAULT_OLLAMA_NUM_CTX, OllamaProvider
+from cgis.guardian.recording import save_finder_recording
+from cgis.guardian.render import render_report
+
+log = structlog.getLogger(__name__)
+
+DEFAULT_GEMINI_MODEL = "gemini-2.5-flash"
+DEFAULT_MISTRAL_MODEL = "mistral-medium-latest"
+
+
+def _ollama_host(env: Mapping[str, str]) -> str | None:
+    """GUARDIAN_OLLAMA_HOST, or None so the ollama client uses localhost:11434.
+
+    Collapses empty/whitespace-only values to None at the boundary so a blank
+    env var never reaches the client as an invalid host.
+    """
+    return (env.get("GUARDIAN_OLLAMA_HOST") or "").strip() or None
+
+
+def impact_threshold(env: Mapping[str, str]) -> int:
+    """GUARDIAN_IMPACT_THRESHOLD clamped to 0-10; 0 (nothing hidden) on absence or garbage.
+
+    Ships inert on purpose (#246 §3.5): the threshold is chosen from the
+    benchmark's score distribution, not guessed. A garbage value must not
+    silently hide findings, so it degrades to "hide nothing".
+    """
+    raw = (env.get("GUARDIAN_IMPACT_THRESHOLD") or "").strip()
+    if not raw:
+        return 0
+    try:
+        return max(0, min(10, int(raw)))
+    except ValueError:
+        log.warning("Invalid GUARDIAN_IMPACT_THRESHOLD; hiding nothing.", value=raw)
+        return 0
+
+
+def _ollama_num_ctx(env: Mapping[str, str]) -> int:
+    """GUARDIAN_OLLAMA_NUM_CTX as an int, or the provider default (avoids silent truncation)."""
+    raw = (env.get("GUARDIAN_OLLAMA_NUM_CTX") or "").strip()
+    if not raw:
+        return DEFAULT_OLLAMA_NUM_CTX
+    try:
+        return int(raw)
+    except ValueError:
+        log.warning("Invalid GUARDIAN_OLLAMA_NUM_CTX; using default.", value=raw)
+        return DEFAULT_OLLAMA_NUM_CTX
+
+
+def _build_mistral(env: Mapping[str, str], model_override: str | None) -> tuple[BaseProvider, str]:
+    """Construct a MistralProvider; MISTRAL_API_KEY is required."""
+    key = env.get("MISTRAL_API_KEY")
+    if not key:
+        _msg = "MISTRAL_API_KEY must be set when GUARDIAN_PROVIDER=mistral"
+        raise RuntimeError(_msg)
+    model = model_override or DEFAULT_MISTRAL_MODEL
+    return MistralProvider(api_key=key, model_name=model), model
+
+
+def _build_gemini(env: Mapping[str, str], model_override: str | None) -> tuple[BaseProvider, str]:
+    """Construct a GeminiProvider; GEMINI_API_KEY is required."""
+    key = env.get("GEMINI_API_KEY")
+    if not key:
+        _msg = "GEMINI_API_KEY must be set when GUARDIAN_PROVIDER=gemini"
+        raise RuntimeError(_msg)
+    model = model_override or DEFAULT_GEMINI_MODEL
+    return GeminiProvider(api_key=key, model_name=model), model
+
+
+def _build_ollama(env: Mapping[str, str], model_override: str | None) -> tuple[BaseProvider, str]:
+    """Construct an OllamaProvider; GUARDIAN_MODEL names the model (no API key)."""
+    if not model_override:
+        _msg = "GUARDIAN_MODEL must name an Ollama model when GUARDIAN_PROVIDER=ollama"
+        raise RuntimeError(_msg)
+    provider = OllamaProvider(
+        model_name=model_override, host=_ollama_host(env), num_ctx=_ollama_num_ctx(env)
+    )
+    return provider, model_override
+
+
+def build_provider(env: Mapping[str, str]) -> tuple[BaseProvider, str]:
+    """Return (provider, model_name) from GUARDIAN_PROVIDER / available API keys.
+
+    With no explicit GUARDIAN_PROVIDER, auto-select: mistral if its key is set,
+    else gemini if its key is set, else an error.
+    """
+    model_override = env.get("GUARDIAN_MODEL")
+    provider_name = env.get("GUARDIAN_PROVIDER", "").lower() or _autodetect_provider(env)
+
+    builders = {"mistral": _build_mistral, "gemini": _build_gemini, "ollama": _build_ollama}
+    builder = builders.get(provider_name)
+    if builder is None:
+        _msg = f"Unknown GUARDIAN_PROVIDER={provider_name!r}. Use 'mistral', 'gemini', or 'ollama'."
+        raise RuntimeError(_msg)
+    return builder(env, model_override)
+
+
+def _autodetect_provider(env: Mapping[str, str]) -> str:
+    """Pick a provider from available API keys when GUARDIAN_PROVIDER is unset."""
+    if env.get("MISTRAL_API_KEY"):
+        return "mistral"
+    if env.get("GEMINI_API_KEY"):
+        return "gemini"
+    _msg = "Set MISTRAL_API_KEY or GEMINI_API_KEY to run Guardian."
+    raise RuntimeError(_msg)
+
+
+def build_skeptic_provider(
+    env: Mapping[str, str], *, primary: str
+) -> tuple[BaseProvider, str] | None:
+    """Return (skeptic_provider, model) or None for single-pass (spec §5.5).
+
+    Default skeptic = the provider opposite to the primary; GUARDIAN_SKEPTIC
+    overrides ('gemini'|'mistral'|'ollama'|'off'); GUARDIAN_SKEPTIC_MODEL overrides
+    the model, enabling same-provider/different-model pairs (incl. two distinct
+    local Ollama models — a cross-model skeptic with no API cost). A missing API
+    key / model degrades to None — a review never fails because of the skeptic.
+    """
+    choice = env.get("GUARDIAN_SKEPTIC", "").lower()
+    if choice == "off":
+        return None
+    if choice not in ("", "gemini", "mistral", "ollama"):
+        log.warning("Unknown GUARDIAN_SKEPTIC; skeptic disabled.", value=choice)
+        return None
+    name = choice or ("mistral" if primary == "gemini" else "gemini")
+    model_override = env.get("GUARDIAN_SKEPTIC_MODEL")
+    if name == "ollama":
+        model = model_override or env.get("GUARDIAN_MODEL")
+        if not model:
+            log.warning(
+                "Skeptic disabled: set GUARDIAN_SKEPTIC_MODEL (or GUARDIAN_MODEL) "
+                "for an ollama skeptic."
+            )
+            return None
+        provider = OllamaProvider(
+            model_name=model, host=_ollama_host(env), num_ctx=_ollama_num_ctx(env)
+        )
+        return provider, model
+    if name == "mistral":
+        key = env.get("MISTRAL_API_KEY")
+        if not key:
+            log.warning("Skeptic disabled: MISTRAL_API_KEY not set.")
+            return None
+        model = model_override or DEFAULT_MISTRAL_MODEL
+        return MistralProvider(api_key=key, model_name=model), model
+    key = env.get("GEMINI_API_KEY")
+    if not key:
+        log.warning("Skeptic disabled: GEMINI_API_KEY not set.")
+        return None
+    model = model_override or DEFAULT_GEMINI_MODEL
+    return GeminiProvider(api_key=key, model_name=model), model
+
+
+def build_footer(
+    *,
+    model: str,
+    usage: ProviderUsage,
+    stats: dict[str, int],
+    result: ReviewResult | None = None,
+) -> str:
+    """Build the markdown footer with model, token usage, graph coverage and skeptic reach."""
+    parts = [f"🤖 **{model}**"]
+    if usage.total_tokens > 0:
+        parts.append(
+            f"{usage.prompt_tokens:,} prompt + {usage.completion_tokens:,} completion"
+            f" = **{usage.total_tokens:,} tokens**"
+        )
+    if stats.get("total", 0) > 0:
+        pct = round(stats.get("with_graph", 0) / stats["total"] * 100)
+        parts.append(f"graph {stats.get('with_graph', 0)}/{stats['total']} files ({pct}%)")
+    if result is not None and result.skeptic_total:
+        parts.append(f"skeptic {result.skeptic_judged}/{result.skeptic_total}")
+    return "\n\n---\n> " + " · ".join(parts)
+
+
+async def run_guardian(
+    *,
+    provider: BaseProvider,
+    model: str,
+    collector: ContextCollector,
+    pr: int | None,
+    metrics_path: Path,
+    skeptic: tuple[BaseProvider, str] | None = None,
+    inline_repo: str | None = None,
+    threshold: int = 0,
+    record_finder: Path | None = None,
+) -> tuple[str, bool]:
+    """Run the review; try the inline path when configured.
+
+    Returns (rendered report + footer, posted_inline). posted_inline=False
+    covers both "not configured" and "API rejected" — the caller posts the
+    big comment in either case (spec §6.5).
+
+    ``record_finder`` writes the finder pass (findings + diff) to that path so
+    the review can be re-scored offline against a benchmark entry (#279).
+    """
+    started = time.monotonic()
+    routed = await run_review_routed(
+        provider=provider,
+        collector=collector,
+        skeptic_provider=skeptic[0] if skeptic else None,
+    )
+    # monotonic, not time(): a wall-clock adjustment mid-review would otherwise
+    # produce a negative or nonsense duration.
+    duration_s = round(time.monotonic() - started, 2)
+    result = routed.result
+    if record_finder is not None:
+        # Recorded AFTER the skeptic on purpose: load_finder_recording strips
+        # verdicts on read, and refuted findings stay in result.findings — so a
+        # replay still starts clean, with no second API call to pay for (#279).
+        try:
+            save_finder_recording(record_finder, result, collector.get_git_diff())
+            log.info("Finder pass recorded.", path=str(record_finder))
+        except OSError:
+            # OSError only, and the narrowness is the point: an environment
+            # failure (disk, permissions) must not cost a review that is already
+            # done, but a bad --record-finder path raises ValueError from the
+            # validator and MUST stay loud. Swallowing that would leave a
+            # misconfigured pipeline silently producing no recordings — the very
+            # failure this feature exists to prevent (#279).
+            log.warning(
+                "Finder recording failed; continuing without it.",
+                path=str(record_finder),
+                exc_info=True,
+            )
+    report = render_report(result, threshold)
+    # Built BEFORE the inline attempt: a successful inline post skips the
+    # fallback comment, so the footer must ride inside the review body too
+    # (live finding on PR #157 — inline reviews arrived footerless).
+    footer = build_footer(
+        model=model,
+        usage=provider.cumulative_usage,
+        stats=collector.graph_stats,
+        result=result,
+    )
+
+    posted = False
+    if inline_repo is not None and pr is not None:
+        try:
+            diff_text = collector.get_git_diff()
+            content = diff_line_content(diff_text)
+            await asyncio.to_thread(  # subprocess `gh api` call — keep the loop responsive
+                post_inline_review,
+                repo=inline_repo,
+                pr=pr,
+                result=result,
+                diff_index={path: set(lines) for path, lines in content.items()},
+                skeptic_model=skeptic[1] if skeptic else None,
+                footer=footer,
+                diff_content=content,
+                threshold=threshold,
+            )
+            posted = True
+        except Exception:
+            log.warning("Inline review failed; falling back to comment.", exc_info=True)
+
+    record_review(
+        model=model,
+        pr=pr,
+        prompt_tokens=provider.cumulative_usage.prompt_tokens,
+        completion_tokens=provider.cumulative_usage.completion_tokens,
+        findings_total=len(result.findings),
+        # lgtm counts pre-skeptic findings on purpose: all-refuted is "finder
+        # flagged something, skeptic killed it" — not a clean LGTM.
+        lgtm=not result.findings and not result.parse_failed,
+        parse_failed=result.parse_failed,
+        skeptic=SkepticRecord(
+            model=skeptic[1] if skeptic else None,
+            status=result.skeptic_status,
+            judged=result.skeptic_judged,
+            total=result.skeptic_total,
+            impact_threshold=threshold,
+        ),
+        chunk_count=routed.chunk_count,
+        duration_s=duration_s,
+        metrics_path=metrics_path,
+    )
+    return report + footer, posted