argus-code-review 0.3.1__tar.gz → 0.3.3__tar.gz

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-10-22
+
+### Changed
+
+- Gemini reviewer sessions now retry ONCE on a transient failure (HTTP 429/500/502/503/504, `RESOURCE_EXHAUSTED`/`UNAVAILABLE`/`DEADLINE_EXCEEDED`/`INTERNAL`, or an httpx timeout/connect/read/remote-protocol error) that happens before the model returned any response. The cooldown depends on the error: 45-60 s jitter for 429/`RESOURCE_EXHAUSTED` (per-minute quota windows), 5-10 s for 5xx and network errors; a server `Retry-After`/`retryDelay` >= 5 s is honored; never more than 60 s. A daily-quota 429 (`PerDay` quota or a retry delay over 120 s) and auth, permission, bad-request and not-found errors are never retried. Overridable via `ARGUS_GEMINI_RETRY_RATE_LIMIT_{MIN,MAX}_S`, `ARGUS_GEMINI_RETRY_COOLDOWN_{MIN,MAX}_S` and `ARGUS_GEMINI_RETRY_MAX_WAIT_S`.
+- A failed Gemini session now logs a WARNING with the exception type, HTTP code/status and a scrubbed, 300-character-truncated message, and `SessionResult.failure_detail` carries a short label such as `429 RESOURCE_EXHAUSTED`. `failure_reason` stays `worker_crashed`; degraded-coverage note text is unchanged. The existing ERROR log for a failed `generate_content` call is also scrubbed of key-shaped strings.
+
+## [0.3.2] - 2026-10-21
+
+### Added
+
+- CLI `--expect-head-sha <sha>`: the review fails before any LLM spend unless the resolved head commit equals this 40-character lowercase SHA, so a service that reviews a specific commit never silently reviews a newer one if the PR head moves (TECH-7789). Also available as `run_review(..., expect_head_sha=...)`.
+- `ARGUS_NO_DOTENV` (truthy): stop all `.env` loading. It disables both `load_dotenv_early` and the `Settings` `env_file`, so a `.env` in the working directory cannot configure the process. For service workers that review untrusted checkouts, alongside the prompt-override and bench-override switches. Enforced on `Settings` itself, so every `Settings()` construction honors it.
+
 ## [0.3.1] - 2026-10-19
 
 ### Fixed
@@ -434,7 +448,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   packaged set.
 - `argus --version`, `argus prompts list`, and `argus prompts export`.
 
-[Unreleased]: https://github.com/redesignhealth/argus-review/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/redesignhealth/argus-review/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/redesignhealth/argus-review/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/redesignhealth/argus-review/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/redesignhealth/argus-review/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/redesignhealth/argus-review/compare/v0.2.11...v0.3.0
 [0.2.11]: https://github.com/redesignhealth/argus-review/compare/v0.2.10...v0.2.11

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-code-review
-Version: 0.3.1
+Version: 0.3.3
 Summary: Self-orchestrated PR review agent using LangGraph + Claude Agent SDK
 Project-URL: Repository, https://github.com/redesignhealth/argus-review
 Project-URL: Issues, https://github.com/redesignhealth/argus-review/issues
@@ -280,6 +280,8 @@ Argus reads configuration from environment variables, or from a `.env` file
 in the working directory (add it to `.gitignore` — never commit it).
 [`.env.example`](.env.example) lists every variable Argus reads, required
 and optional, with comments — copy it to `.env` and fill in what you need.
+Set `ARGUS_NO_DOTENV=1` in the real environment to ignore `.env` files
+entirely (for service workers that run in a directory they do not control).
 
 Three keys are required for a first run:
 

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/README.md

@@ -229,6 +229,8 @@ Argus reads configuration from environment variables, or from a `.env` file
 in the working directory (add it to `.gitignore` — never commit it).
 [`.env.example`](.env.example) lists every variable Argus reads, required
 and optional, with comments — copy it to `.env` and fill in what you need.
+Set `ARGUS_NO_DOTENV=1` in the real environment to ignore `.env` files
+entirely (for service workers that run in a directory they do not control).
 
 Three keys are required for a first run:
 

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/cli.py

@@ -70,6 +70,8 @@ import time
 from pathlib import Path
 from typing import TYPE_CHECKING, Final
 
+from argus.dotenv_utils import TRUTHY_STRINGS
+
 if TYPE_CHECKING:
     from argus.config import Settings
     from argus.models import ReviewRequest, ReviewResponse
@@ -79,6 +81,7 @@ logging.basicConfig(
     format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
     datefmt="%H:%M:%S",
 )
+
 logger = logging.getLogger("argus_review_local")
 
 # Hard wall-clock backstop: if the entire review has not completed within this
@@ -229,6 +232,7 @@ async def run(
     request: "ReviewRequest",
     review_override_sha: str | None = None,
     review_override_reason: str | None = None,
+    expect_head_sha: str | None = None,
 ) -> "ReviewResponse":
     """Run the review pipeline (storage backend resolved automatically:
     Postgres if ``ARGUS_DB_URL`` is set, HTTP shim if the storage URLs are
@@ -240,6 +244,7 @@ async def run(
         flow_run_id=None,
         review_override_sha=review_override_sha,
         review_override_reason=review_override_reason,
+        expect_head_sha=expect_head_sha,
     )
 
 
@@ -363,6 +368,16 @@ def _add_review_args(parser: argparse.ArgumentParser) -> None:
         default=None,
         help="Reason for --review-override-sha (1-500 characters); recorded in the scope receipt.",
     )
+    parser.add_argument(
+        "--expect-head-sha",
+        dest="expect_head_sha",
+        default=None,
+        help=(
+            "Fail before any review spend unless the resolved head commit equals this "
+            "40-character lowercase SHA. For services that review a specific commit and "
+            "must not silently review a newer one if the PR head moved."
+        ),
+    )
     parser.add_argument(
         "--no-prompt-overrides",
         action="store_true",
@@ -483,10 +498,11 @@ def _validate_review_args(parser: argparse.ArgumentParser, args: argparse.Namesp
     """Cross-flag validation that argparse's own declarative options can't express."""
     if args.post and args.sha and not args.pr:
         parser.error("--post requires --pr (a PR to comment on); --sha alone has nowhere to post")
-    from argus.scope import validate_override
+    from argus.scope import validate_expect_head_sha, validate_override
 
     try:
         validate_override(args.review_override_sha, args.review_override_reason)
+        validate_expect_head_sha(args.expect_head_sha)
     except ValueError as exc:
         parser.error(str(exc))
 
@@ -676,6 +692,7 @@ def _run_review(parser: argparse.ArgumentParser, args: argparse.Namespace) -> No
                 request,
                 review_override_sha=args.review_override_sha,
                 review_override_reason=args.review_override_reason,
+                expect_head_sha=args.expect_head_sha,
             )
         )
     except HistoryBackendConnectivityError as exc:
@@ -720,7 +737,7 @@ def _packaged_prompt_names() -> list[str]:
 # argus.config.Settings). Kept in sync here so `argus prompts list`/`export`
 # (deliberately Settings-free, see below) treats the env var identically to
 # `argus review`, which resolves it through Settings.
-_PYDANTIC_TRUTHY_STRINGS = frozenset({"1", "true", "t", "yes", "y", "on"})
+_PYDANTIC_TRUTHY_STRINGS = TRUTHY_STRINGS
 
 
 def _is_truthy_env_value(value: str) -> bool:

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/config.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from functools import lru_cache
 
 from pydantic import Field
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
 
 # Single source of truth for the reviewer-subprocess wall-clock budget.
 # ``argus.runners._SUBPROCESS_TIMEOUT_S`` (the fallback used when no Settings
@@ -209,6 +209,26 @@ class Settings(BaseSettings):
         env_file_encoding="utf-8",
     )
 
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Drop the ``.env`` source when ``ARGUS_NO_DOTENV`` is truthy.
+
+        Enforced here, on the class, so every ``Settings()`` construction honors the
+        kill switch, not just the cached accessor.
+        """
+        from argus.dotenv_utils import dotenv_disabled
+
+        if dotenv_disabled():
+            return (init_settings, env_settings, file_secret_settings)
+        return (init_settings, env_settings, dotenv_settings, file_secret_settings)
+
     @property
     def db_url(self) -> str | None:
         """Resolved Postgres URL: ``ARGUS_DB_URL`` wins over ``SUPABASE_DB_URL``."""

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/dotenv_utils.py

@@ -13,6 +13,22 @@ import os
 from pathlib import Path
 
 
+# The strings pydantic treats as True for a bool setting; shared with the CLI so the
+# two truthy checks cannot drift.
+TRUTHY_STRINGS = frozenset({"1", "true", "t", "yes", "y", "on"})
+
+
+def dotenv_disabled() -> bool:
+    """True when ``ARGUS_NO_DOTENV`` is truthy.
+
+    Official/service runs review untrusted checkouts from a working directory
+    that may contain a ``.env``; this switch stops every ``.env`` load (both
+    :func:`load_dotenv_early` and the pydantic ``Settings`` env_file) so the
+    process environment is the only configuration source.
+    """
+    return os.environ.get("ARGUS_NO_DOTENV", "").strip().lower() in TRUTHY_STRINGS
+
+
 def _preferred_env_filename() -> str:
     """Pick the default env filename based on ENVIRONMENT."""
     env = (os.environ.get("ENVIRONMENT") or "").lower()
@@ -61,11 +77,15 @@ def load_dotenv_early(
     """Load dotenv file early (before importing settings/clients).
 
     This is a no-op when:
+    - ``ARGUS_NO_DOTENV`` is truthy, or
     - running in AWS Lambda (secrets are expected to come from SSM/env), or
     - running in pytest and `skip_in_test=True`, or
     - python-dotenv isn't installed, or
     - no env file can be found.
     """
+    if dotenv_disabled():
+        return None
+
     # Never load local dotenv inside Lambda.
     if os.environ.get("AWS_LAMBDA_FUNCTION_NAME"):
         return None

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/gemini_runner.py

@@ -144,7 +144,10 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import os
+import random
 import re
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any
 
@@ -208,6 +211,171 @@ _FORCE_TOOL_CONFIG = types.ToolConfig(
 # uncaught.
 _HTTP_TIMEOUT_FRACTION = 0.8
 
+# ---------------------------------------------------------------------------
+# One-shot retry of transient Gemini failures
+# ---------------------------------------------------------------------------
+# A session is retried AT MOST ONCE, and only when it failed with a transient
+# error (HTTP 429/500/502/503/504, RESOURCE_EXHAUSTED/UNAVAILABLE/
+# DEADLINE_EXCEEDED/INTERNAL, or an httpx timeout/connect/read/remote-protocol
+# error) before the model returned ANY response (i.e. on turn 0), so the retry
+# restarts the session cleanly from the beginning. Later failures are not
+# retried. The cooldown depends on the error kind (see `_retry_decision`):
+# 45-60 s jitter for 429/RESOURCE_EXHAUSTED (per-minute quota windows), 5-10 s
+# for 5xx/network errors; a server Retry-After/retryDelay >= 5 s is honored;
+# never more than 60 s. Daily-quota 429s are not retried. Overridable via
+# ARGUS_GEMINI_RETRY_RATE_LIMIT_{MIN,MAX}_S, ARGUS_GEMINI_RETRY_COOLDOWN_{MIN,MAX}_S
+# and ARGUS_GEMINI_RETRY_MAX_WAIT_S (read per call, so tests can set them to 0).
+# The 60 s worst case is far inside ARGUS_SESSION_TIMEOUT (default 1500 s), and
+# the retry is skipped if <25% of that timeout remains.
+_RETRY_RATE_LIMIT_MIN_S = 45.0  # 429 / RESOURCE_EXHAUSTED: per-minute windows
+_RETRY_RATE_LIMIT_MAX_S = 60.0
+_RETRY_SHORT_MIN_S = 5.0  # 5xx / UNAVAILABLE / DEADLINE_EXCEEDED / network
+_RETRY_SHORT_MAX_S = 10.0
+_RETRY_MAX_WAIT_S = 60.0  # hard cap on any single wait, incl. a server Retry-After
+_RETRY_AFTER_MIN_S = 5.0  # a server delay below this is ignored (jitter used)
+# A server-suggested delay above this means the quota window is not a
+# per-minute one (minutes/hours): fail fast rather than retry.
+_RETRY_GIVEUP_DELAY_S = 120.0
+# Do not retry when less than this fraction of the session timeout remains
+# (e.g. the first attempt already burned its HTTP timeout).
+_RETRY_MIN_REMAINING_FRACTION = 0.25
+_TRANSIENT_HTTP_CODES = frozenset({429, 500, 502, 503, 504})
+_TRANSIENT_STATUSES = frozenset(
+    {"RESOURCE_EXHAUSTED", "UNAVAILABLE", "DEADLINE_EXCEEDED", "INTERNAL"}
+)
+_TRANSIENT_HTTPX = (
+    httpx.TimeoutException,
+    httpx.ConnectError,
+    httpx.ReadError,
+    httpx.RemoteProtocolError,
+)
+_DETAIL_MAX_CHARS = 300
+_SECRET_RE = re.compile(
+    r"(AIza[0-9A-Za-z_\-]{20,}|(?i:(?:api[_-]?key|key|token)=)[^&\s\"']+|"
+    r"(?i:bearer\s+)[A-Za-z0-9._\-]+|sk-[A-Za-z0-9_\-]{16,})"
+)
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return default
+
+
+@dataclass
+class _Progress:
+    """Mutable per-session state shared between attempts and the failure handler."""
+
+    responses: int = 0  # successful generate_content responses received
+    retried: bool = False
+    retry_wait_s: float = 0.0
+
+
+def _scrub(text: str) -> str:
+    """Redact anything key-shaped and truncate for logging."""
+    text = _SECRET_RE.sub("***", text).replace("\n", " ")
+    return text[:_DETAIL_MAX_CHARS]
+
+
+def _error_code_status(exc: BaseException) -> tuple[int | None, str | None]:
+    """Best-effort (HTTP code, status string) for an SDK/transport exception."""
+    if isinstance(exc, genai_errors.APIError):
+        code = getattr(exc, "code", None)
+        status = getattr(exc, "status", None)
+        return (
+            code if isinstance(code, int) else None,
+            status if isinstance(status, str) else None,
+        )
+    if isinstance(exc, httpx.HTTPStatusError):
+        return exc.response.status_code, None
+    return None, None
+
+
+def _is_transient_error(exc: BaseException) -> bool:
+    code, status = _error_code_status(exc)
+    if code in _TRANSIENT_HTTP_CODES or (status or "").upper() in _TRANSIENT_STATUSES:
+        return True
+    if isinstance(exc, (genai_errors.APIError, httpx.HTTPStatusError)):
+        return False  # a definite API answer that is not transient (400/401/403/404...)
+    return isinstance(exc, _TRANSIENT_HTTPX)
+
+
+def _retry_after_seconds(exc: BaseException) -> float | None:
+    """Server-suggested delay from a Retry-After header or RetryInfo.retryDelay."""
+    response = getattr(exc, "response", None)
+    headers = getattr(response, "headers", None)
+    try:
+        raw = headers.get("retry-after") if headers is not None else None
+        if raw is not None:
+            return max(0.0, float(raw))
+    except (TypeError, ValueError, AttributeError):
+        pass
+    details = getattr(exc, "details", None)
+    err = details.get("error", details) if isinstance(details, dict) else None
+    items = err.get("details") if isinstance(err, dict) else None
+    for item in items if isinstance(items, list) else []:
+        delay = item.get("retryDelay") if isinstance(item, dict) else None
+        if isinstance(delay, str) and delay.endswith("s"):
+            try:
+                return max(0.0, float(delay[:-1]))
+            except ValueError:
+                pass
+    return None
+
+
+def _is_daily_quota(exc: BaseException, server_delay: float | None) -> bool:
+    """True when a 429 reports a per-day quota or a many-minutes retry delay."""
+    if server_delay is not None and server_delay > _RETRY_GIVEUP_DELAY_S:
+        return True
+    return bool(re.search(r"per\s*day|perday", str(exc), re.IGNORECASE))
+
+
+def _retry_decision(exc: BaseException) -> tuple[str, float] | None:
+    """``(kind, wait_seconds)`` if ``exc`` should be retried once, else ``None``.
+
+    Kinds: ``rate_limit`` (429/RESOURCE_EXHAUSTED, 45-60 s jitter),
+    ``server`` (5xx/UNAVAILABLE/DEADLINE_EXCEEDED/INTERNAL) and ``network``
+    (5-10 s jitter). A server Retry-After/retryDelay >= 5 s replaces the
+    jittered value; the wait never exceeds 60 s. A daily-quota 429 is never
+    retried.
+    """
+    if not _is_transient_error(exc):
+        return None
+    code, status = _error_code_status(exc)
+    server_delay = _retry_after_seconds(exc)
+    if code == 429 or (status or "").upper() == "RESOURCE_EXHAUSTED":
+        if _is_daily_quota(exc, server_delay):
+            return None
+        kind = "rate_limit"
+        lo = _env_float("ARGUS_GEMINI_RETRY_RATE_LIMIT_MIN_S", _RETRY_RATE_LIMIT_MIN_S)
+        hi = _env_float("ARGUS_GEMINI_RETRY_RATE_LIMIT_MAX_S", _RETRY_RATE_LIMIT_MAX_S)
+    else:
+        kind = "server" if code is not None or status else "network"
+        lo = _env_float("ARGUS_GEMINI_RETRY_COOLDOWN_MIN_S", _RETRY_SHORT_MIN_S)
+        hi = _env_float("ARGUS_GEMINI_RETRY_COOLDOWN_MAX_S", _RETRY_SHORT_MAX_S)
+    cap = _env_float("ARGUS_GEMINI_RETRY_MAX_WAIT_S", _RETRY_MAX_WAIT_S)
+    wait = random.uniform(lo, max(lo, hi))  # noqa: S311 - jitter, not security
+    if server_delay is not None and server_delay >= _RETRY_AFTER_MIN_S:
+        wait = server_delay
+    return kind, min(wait, cap)
+
+
+def _failure_detail(exc: BaseException) -> str:
+    """Short, key-free label such as ``429 RESOURCE_EXHAUSTED`` or ``ConnectError``."""
+    code, status = _error_code_status(exc)
+    detail = " ".join(p for p in (str(code) if code is not None else "", status or "") if p)
+    detail = detail or type(exc).__name__
+    if (code == 429 or (status or "").upper() == "RESOURCE_EXHAUSTED") and _is_daily_quota(
+        exc, _retry_after_seconds(exc)
+    ):
+        detail += " (daily quota)"
+    return detail
+
+
 # Matches the fenced-json extraction argus.helpers.parse_review_result
 # already applies for the Claude path.
 _FENCED_JSON_RE = re.compile(r"```(?:json)?\s*(\{.*?\})\s*```", re.DOTALL)
@@ -599,6 +767,7 @@ async def _run_turns(
     repo_root: str,
     timeout_s: float,
     started_at: datetime,
+    progress: _Progress | None = None,
 ) -> SessionResult:
     """The actual tool-calling loop. Returns ``failure_reason="turn_budget_exhausted"``
     when the loop ran out of turns without a ``finish_review`` call, else
@@ -736,8 +905,7 @@ async def _run_turns(
                             entry.role if entry else "unknown",
                             model,
                             _turn,
-                            exc,
-                            exc_info=True,
+                            _scrub(str(exc)),
                         )
                         raise
                     logger.warning(
@@ -760,6 +928,8 @@ async def _run_turns(
                         model=model, contents=contents, config=config
                     )
 
+                if progress is not None:
+                    progress.responses += 1
                 usage = response.usage_metadata
                 if usage is not None:
                     usage_prompt_total += usage.prompt_token_count or 0
@@ -922,6 +1092,35 @@ async def _run_turns(
         )
 
 
+async def _run_turns_with_retry(
+    *, progress: _Progress, timeout_s: float, **kwargs: Any
+) -> SessionResult:
+    """``_run_turns`` with at most one retry of a transient turn-0 failure."""
+    label = kwargs.get("label") or "unlabeled"
+    t0 = asyncio.get_running_loop().time()
+    try:
+        return await _run_turns(timeout_s=timeout_s, progress=progress, **kwargs)
+    except (genai_errors.APIError, httpx.HTTPError) as exc:
+        remaining = timeout_s - (asyncio.get_running_loop().time() - t0)
+        decision = _retry_decision(exc) if progress.responses == 0 else None
+        if decision is None or remaining < timeout_s * _RETRY_MIN_REMAINING_FRACTION:
+            raise
+        kind, wait = decision
+        if wait >= remaining:
+            raise
+        progress.retried = True
+        progress.retry_wait_s = wait
+        logger.info(
+            "gemini session [%s] retrying after %s (kind=%s) in %.1fs",
+            label,
+            _failure_detail(exc),
+            kind,
+            wait,
+        )
+        await asyncio.sleep(wait)
+    return await _run_turns(timeout_s=timeout_s, progress=progress, **kwargs)
+
+
 def _redact_gemini_inputs(inputs: dict[str, Any], **_: Any) -> dict[str, Any]:
     """LangSmith ``process_inputs`` hook: redact credentials from Settings."""
     if not isinstance(inputs, dict):
@@ -988,9 +1187,11 @@ async def run_session_gemini(
     )
 
     started_at = datetime.now(timezone.utc)
+    progress = _Progress()
     try:
         return await asyncio.wait_for(
-            _run_turns(
+            _run_turns_with_retry(
+                progress=progress,
                 entry=entry,
                 model=model,
                 system_prompt=system_prompt,
@@ -1057,12 +1258,15 @@ async def run_session_gemini(
         # identically here, even though this runner has no literal
         # subprocess "worker" the way the Claude Agent SDK path does.
         finished_at = datetime.now(timezone.utc)
+        detail = _failure_detail(exc)
         logger.warning(
-            "Gemini session [%s] failed with a non-timeout error after %.1fs (%s: %s)",
+            "Gemini session [%s] failed after %.1fs (%s, %s%s): %s",
             label or "unlabeled",
             (finished_at - started_at).total_seconds(),
             type(exc).__name__,
-            exc,
+            detail,
+            ", after one retry" if progress.retried else "",
+            _scrub(str(exc)),
         )
         return SessionResult(
             result_text="",
@@ -1075,4 +1279,5 @@ async def run_session_gemini(
             context7_call_count=0,
             model=model,
             failure_reason="worker_crashed",
+            failure_detail=detail,
         )

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/graph.py

@@ -85,6 +85,7 @@ from argus.models import (
 from argus.scope import (
     SCOPE_PROMPT,
     SHA40,
+    validate_expect_head_sha,
     ScopeAssessment,
     ScopeUnverified,
     build_scope_input,
@@ -3605,6 +3606,7 @@ async def run_review(
     *,
     review_override_sha: str | None = None,
     review_override_reason: str | None = None,
+    expect_head_sha: str | None = None,
 ) -> ReviewResponse:
     """Execute the v3 review pipeline via LangGraph StateGraph.
 
@@ -3620,6 +3622,7 @@ async def run_review(
     import uuid
 
     override = validate_override(review_override_sha, review_override_reason)
+    validate_expect_head_sha(expect_head_sha)
 
     # Fail fast on a bad ARGUS_DB_URL / ARGUS_HISTORY_DB_PATH, before any of
     # the pipeline's LLM cost runs. Both history-backend implementations
@@ -3690,6 +3693,13 @@ async def run_review(
     else:
         head_sha_for_worktree = None
 
+    if expect_head_sha is not None and expect_head_sha != head_sha_for_worktree:
+        raise ValueError(
+            f"expect_head_sha {expect_head_sha[:12]} does not match the resolved head "
+            f"{(head_sha_for_worktree or 'none')[:12]}; the PR head moved, refusing to review "
+            "a different commit"
+        )
+
     if override and override[0] != head_sha_for_worktree:
         raise ValueError(
             f"--review-override-sha {override[0][:12]} does not match the resolved head "

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/runners.py

@@ -572,6 +572,9 @@ class SessionResult:
     model: str | None = None
     failure_reason: Literal["timeout", "worker_crashed", "turn_budget_exhausted"] | None = None
     timed_out: bool = False
+    # Short, key-free reason detail (e.g. "429 RESOURCE_EXHAUSTED") for logs and
+    # diagnostics; not persisted and does not affect failure_reason semantics.
+    failure_detail: str | None = None
 
     def __post_init__(self) -> None:
         self.timed_out, self.failure_reason = _sync_timed_out_and_failure_reason(

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/argus/scope.py

@@ -50,6 +50,13 @@ class ScopeAssessment(BaseModel):
     rationale: str
 
 
+def validate_expect_head_sha(sha: str | None) -> str | None:
+    """Return ``sha`` unchanged if it is ``None`` or a 40-char lowercase hex SHA, else raise."""
+    if sha is not None and not SHA40.fullmatch(sha):
+        raise ValueError("expect_head_sha must be a 40-character lowercase hex SHA")
+    return sha
+
+
 def validate_override(sha: str | None, reason: str | None) -> tuple[str, str] | None:
     """Return ``(sha, reason)`` for a valid human override pair, ``None`` if neither is set."""
     if sha is None and reason is None:

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/tests/test_cli_args.py

@@ -343,3 +343,26 @@ class TestPromptsSubcommand:
     def test_prompts_export_force_defaults_off(self) -> None:
         args = _parse(["prompts", "export", "/tmp/out"])
         assert args.force is False
+
+
+class TestExpectHeadShaFlag:
+    def test_defaults_to_none(self) -> None:
+        assert _parse(["review", "owner/repo", "--pr", "1"]).expect_head_sha is None
+
+    def test_flag_parses(self) -> None:
+        sha = "a" * 40
+        args = _parse(["review", "owner/repo", "--pr", "1", "--expect-head-sha", sha])
+        assert args.expect_head_sha == sha
+
+    def test_malformed_sha_is_a_parser_error(self) -> None:
+        parser = _build_parser()
+        for bad in ("a" * 39, "A" * 40, "g" * 40, ""):
+            args = _parse(["review", "owner/repo", "--pr", "1", "--expect-head-sha", bad])
+            with pytest.raises(SystemExit) as exc:
+                _validate_review_args(parser, args)
+            assert exc.value.code == 2
+
+    def test_valid_sha_passes_validation(self) -> None:
+        parser = _build_parser()
+        args = _parse(["review", "owner/repo", "--pr", "1", "--expect-head-sha", "a" * 40])
+        _validate_review_args(parser, args)

{argus_code_review-0.3.1 → argus_code_review-0.3.3}/tests/test_cli_preflight.py

@@ -229,6 +229,7 @@ class TestRunReviewConnectivityErrorExit:
             output=None,
             review_override_sha=None,
             review_override_reason=None,
+            expect_head_sha=None,
         )
         parser = MagicMock()