argus-code-review 0.2.6__tar.gz → 0.2.8__tar.gz

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.8] - 2026-10-02
+
+### Changed
+
+- Raised the Claude-path turn budget from 30 to 50 and the default reviewer session
+  timeout from 900 to 1500 seconds globally across all runner platforms through
+  `ARGUS_SESSION_TIMEOUT` (TECH-7093), preserving headroom for longer sessions.
+- Added Claude's budget disclosure and supported `PostToolUse`/`PostToolUseFailure`
+  hook-based convergence warnings (derived from budget constants; 37 and 47 tool calls
+  by default), using truthful top-level tool-call counts, including failed calls.
+- Decoupled the Claude and OpenAI turn-budget constants; OpenAI remains at 30 turns.
+
+## [0.2.7] - 2026-09-26
+
+### Fixed
+
+- Reworded a misleading log message in `argus/graph.py`'s `_node_lite_review`
+  (TECH-6878, #29). The log previously stated "Lite round history skipped on HTTP
+  storage path", which was misinterpreted as indicating that review persistence
+  was skipped altogether and caused an operator/agent to file a false bug
+  report. The message now clarifies that only the comment markdown section for
+  prior lite history is omitted (because `select_recent_lite_rounds` is not
+  implemented in the HTTP storage shim), while the round's own finalize write is
+  not skipped and is attempted normally.
+- Added test coverage for lite-round persistence round-tripping through both the
+  SQLite and HTTP storage backends (previously untested for HTTP), verifying that
+  `reviewer_version="v3-lite"` is preserved on write and read (TECH-6878, #29).
+  Also marked `test_insert_agent_runs_batch[http]` as an explicit xfail for the
+  documented HTTP shim analytics gap rather than letting it pass vacuously.
+
 ## [0.2.6] - 2026-09-19
 
 ### Fixed
@@ -338,7 +368,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.2.6...HEAD
+[Unreleased]: https://github.com/redesignhealth/argus-review/compare/v0.2.8...HEAD
+[0.2.8]: https://github.com/redesignhealth/argus-review/compare/v0.2.7...v0.2.8
+[0.2.7]: https://github.com/redesignhealth/argus-review/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/redesignhealth/argus-review/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/redesignhealth/argus-review/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/redesignhealth/argus-review/compare/v0.2.3...v0.2.4

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-code-review
-Version: 0.2.6
+Version: 0.2.8
 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

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/argus/config.py

@@ -2,7 +2,7 @@
 
 A slim ``pydantic-settings`` implementation. All configuration comes from
 environment variables (or a local ``.env`` file loaded via
-``argus.dotenv_utils``) — no AWS, no SSM.
+``argus.dotenv_utils``) -- no AWS, no SSM.
 """
 
 from __future__ import annotations
@@ -15,7 +15,7 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 # ``argus.runners._SUBPROCESS_TIMEOUT_S`` (the fallback used when no Settings
 # instance is available, mostly tests) imports this same constant rather than
 # hardcoding its own copy, so the two can never drift out of sync.
-DEFAULT_ARGUS_SESSION_TIMEOUT_S = 900
+DEFAULT_ARGUS_SESSION_TIMEOUT_S = 1500
 
 
 class Settings(BaseSettings):
@@ -62,7 +62,7 @@ class Settings(BaseSettings):
             ``argus.precheck``.
         ARGUS_STOCK_SEMGREP_PACKS: Comma-separated semgrep registry pack IDs
             (e.g. ``"p/secrets"``) to run alongside (or instead of) a custom
-            ``ARGUS_RULES_DIR`` — unlike a local rules directory, each pack
+            ``ARGUS_RULES_DIR`` -- unlike a local rules directory, each pack
             is fetched over the network by semgrep itself on first use
             (cached locally after). Unset by default: this is an opt-in
             addition of vetted, community-maintained rules, not a silent
@@ -74,8 +74,8 @@ class Settings(BaseSettings):
             (``PrecheckResult.failed_scanners``/``missing_scanners``
             non-empty) instead of the default fail-open
             behavior (surface it in the review comment's degraded-coverage
-            section — see ``argus.helpers.build_degraded_coverage_labels``
-            — but let the review's own verdict stand on its own merits).
+            section -- see ``argus.helpers.build_degraded_coverage_labels``
+            -- but let the review's own verdict stand on its own merits).
             False by default: every other part of this module's design is
             deliberately fail-open (a broken scanner should never be the
             reason a review can't complete), and this flag exists for
@@ -117,14 +117,21 @@ class Settings(BaseSettings):
             Context7 call.
         ARGUS_SESSION_TIMEOUT: Wall-clock seconds a reviewer subprocess is
             allowed to run before it is killed and reported as a failure.
-            Defaults to 900 (15 minutes) — first raised from 300 to 420 after
+            Defaults to 1500 (25 minutes) -- first raised from 300 to 420 after
             production logs showed legitimate (non-runaway) specialist
             reviewers finishing as late as 294s, right at the old timeout's
             edge; raised again to 600 to match rh-data-platform's
             production-proven value ahead of this package taking over as the
             actual production reviewer (rh-data-platform's review_service is
-            being retired in its favor); raised once more to 900 for
-            additional headroom across all three reviewer platforms.
+            being retired in its favor); raised to 900 for additional headroom
+            across all three reviewer platforms; raised to 1500 in TECH-7093.
+            This timeout is deliberately global to all runner platforms through
+            ARGUS_SESSION_TIMEOUT, rather than scoped only to Claude, to preserve
+            a single operator control across runners. In production, an observed
+            cross-cutting session ran 533.8s under the 30-turn cap; linear
+            scaling 30 to 50 projects ~890s, meaning 900s leaves virtually zero
+            headroom. 1500s preserves roughly 1.69x margin, critical because a
+            timeout kill discards all reviewer output.
         GOOGLE_API_KEY: Gemini platform credential, consumed via the
             ``google_credential`` property by ``argus.gemini_runner``
             whenever a role's bench entry resolves to
@@ -206,7 +213,7 @@ class Settings(BaseSettings):
 
         Callers that need to hand this credential to something that itself
         reads an env var (the spawned ``claude`` CLI subprocess) must set
-        the SAME variable name the caller configured — forcing everything
+        the SAME variable name the caller configured -- forcing everything
         to ``ANTHROPIC_API_KEY`` would send a proxy/gateway bearer token as
         an ``x-api-key``, which not every gateway accepts. ``ANTHROPIC_API_KEY``
         wins when both are set, matching the Anthropic SDK's own precedence.

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/argus/gemini_runner.py

@@ -41,8 +41,9 @@ function call the model requests each turn (there can be more than
 one), feeding all of their results back as a single follow-up turn --
 until the model stops requesting function calls, calls
 ``finish_review``, or the turn budget (``_MAX_TURNS_GEMINI``, this
-module's own budget, independent of the Claude/OpenAI paths' shared
-``argus.runners._MAX_TURNS``) is exhausted. Findings arrive via
+module's own budget, independent of the Claude path's
+``argus.runners._MAX_TURNS_CLAUDE`` and the OpenAI path's
+``argus.openai_runner._MAX_TURNS_OPENAI``) is exhausted. Findings arrive via
 ``report_finding`` tool calls into ``review_tools``' per-session sink,
 not as a JSON blob embedded in the model's own text -- so, to keep this
 task's blast radius contained to this file plus ``argus.bench``'s

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/argus/graph.py

@@ -2228,7 +2228,11 @@ async def _node_lite_review(state: ReviewState) -> dict[str, Any]:
         except Exception:  # noqa: BLE001
             logger.error("Failed to build lite round history — skipping section", exc_info=True)
     elif req.pr_number and _lite_history_backend_kind == "http":
-        logger.info("Lite round history skipped on HTTP storage path")
+        logger.info(
+            "Lite round history markdown section omitted on HTTP storage path "
+            "(select_recent_lite_rounds not implemented in HTTP shim; "
+            "the round's own finalize write is not skipped and will be attempted normally)"
+        )
 
     response.review_comment = (
         f"## Code Review — Round {round_num} (Lite Mode)\n\n"

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/argus/openai_runner.py

@@ -40,7 +40,7 @@ the model requests each turn (there can be more than one), chaining the
 conversation state forward via ``previous_response_id`` and feeding back
 all tool outputs as ``function_call_output`` items -- until the model stops
 requesting function calls, calls ``finish_review``, or the turn budget
-(``argus.runners._MAX_TURNS``) is exhausted. Findings arrive via
+(``_MAX_TURNS_OPENAI``) is exhausted. Findings arrive via
 ``report_finding`` tool calls into ``review_tools``' per-session sink,
 not as a JSON blob embedded in the model's own text -- so, to keep this
 task's blast radius contained, the final ``SessionResult.result_text`` is
@@ -110,7 +110,6 @@ from argus.bench import BenchEntry
 from argus.llm.models import estimate_cost_usd
 from argus.llm.models import resolve as resolve_model_alias
 from argus.runners import (
-    _MAX_TURNS,
     _MID_BUDGET_NUDGE,
     _NUDGE_TURNS_BEFORE_BUDGET,
     _SUBPROCESS_TIMEOUT_S,
@@ -123,6 +122,8 @@ from argus.runners import (
 
 logger = logging.getLogger(__name__)
 
+_MAX_TURNS_OPENAI = 30
+
 _DEFAULT_READ_LIMIT = 2000  # mirrors argus.review_tools._DEFAULT_READ_LIMIT
 
 # Matches the fenced-json extraction argus.helpers.parse_review_result
@@ -417,7 +418,7 @@ async def _run_turns(
     whatever those completed turns actually produced and billed.
     """
     system_prompt = (
-        system_prompt + "\n\n" + _TURN_BUDGET_SYSTEM_PROMPT_LINE.format(max_turns=_MAX_TURNS)
+        system_prompt + "\n\n" + _TURN_BUDGET_SYSTEM_PROMPT_LINE.format(max_turns=_MAX_TURNS_OPENAI)
     )
     api_key = getattr(settings, "OPENAI_API_KEY", None)
     base_url = getattr(settings, "OPENAI_BASE_URL", None)
@@ -504,13 +505,13 @@ async def _run_turns(
         )
 
     exhausted = False
-    _mid_budget_nudge_turn = _compute_mid_budget_nudge_turn(_MAX_TURNS)
+    _mid_budget_nudge_turn = _compute_mid_budget_nudge_turn(_MAX_TURNS_OPENAI)
     try:
         async with asyncio.timeout(timeout_s):
             with review_tools.review_session(repo_root) as findings_sink:
                 previous_response_id: str | None = None
                 tool_outputs: list[dict[str, Any]] = []
-                for _turn in range(_MAX_TURNS):
+                for _turn in range(_MAX_TURNS_OPENAI):
                     create_kwargs: dict[str, Any] = {
                         "model": model,
                         "instructions": system_prompt,
@@ -625,7 +626,7 @@ async def _run_turns(
                     if finished:
                         break
 
-                    if _turn + 1 == _MAX_TURNS - _NUDGE_TURNS_BEFORE_BUDGET:
+                    if _turn + 1 == _MAX_TURNS_OPENAI - _NUDGE_TURNS_BEFORE_BUDGET:
                         tool_outputs.append({"role": "user", "content": _TURN_BUDGET_NUDGE})
 
                     # Not an `elif` -- these are two independent checkpoints
@@ -643,7 +644,7 @@ async def _run_turns(
                     logger.warning(
                         "OpenAI session [%s] exhausted its %d-turn budget without a finish_review call",
                         label or "unlabeled",
-                        _MAX_TURNS,
+                        _MAX_TURNS_OPENAI,
                     )
                     exhausted = True
 

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/argus/runners.py

@@ -30,6 +30,7 @@ from claude_agent_sdk import (
     AssistantMessage,
     ClaudeAgentOptions,
     ClaudeSDKClient,
+    HookMatcher,
     ResultMessage,
     TaskStartedMessage,
     TextBlock,
@@ -38,6 +39,13 @@ from claude_agent_sdk import (
     ToolUseBlock,
     UserMessage,
 )
+from claude_agent_sdk.types import (
+    HookContext,
+    HookEvent,
+    PostToolUseFailureHookSpecificOutput,
+    PostToolUseHookSpecificOutput,
+    SyncHookJSONOutput,
+)
 from langsmith import traceable
 from langsmith.run_helpers import LangSmithExtra, get_current_run_tree
 
@@ -141,9 +149,10 @@ if _CROSS_CUTTING_MODEL != ALIAS_MAP["claude-opus"]:
         _CROSS_CUTTING_MODEL,
     )
 
-# Shared by every Claude-path session (system/specialist/cross-cutting/tests-and-docs
-# reviewers, feedback verifier, blocking validator).
-_MAX_TURNS = 30
+# Turn budget for Claude-path sessions (system/specialist/cross-cutting/tests-and-docs
+# reviewers, feedback verifier, blocking validator) -- raised from 30 to 50
+# in TECH-7093.
+_MAX_TURNS_CLAUDE = 50
 
 # Nudges the Gemini/OpenAI turn loops (see their own _run_turns) to call
 # finish_review a few turns before the budget runs out.
@@ -155,8 +164,8 @@ _TURN_BUDGET_NUDGE = (
 )
 
 # One-sentence turn-budget disclosure appended to the Gemini/OpenAI reviewer
-# system prompts. Not used on the Claude path (_run_claude_session), which
-# has no mid-stream nudge for the sentence to work with.
+# system prompts. See _TURN_BUDGET_SYSTEM_PROMPT_LINE_CLAUDE below for the
+# Claude path equivalent.
 _TURN_BUDGET_SYSTEM_PROMPT_LINE = (
     "You have at most {max_turns} turns. Call `finish_review` before you run out -- "
     "a review that never calls it is discarded entirely."
@@ -187,7 +196,7 @@ def _compute_mid_budget_nudge_turn(max_turns: int) -> int | None:
     colliding the two nudges onto the same turn -- which would either
     double-post one message, or silently drop the mid-budget one. Not
     reachable at today's values (75 vs. 97 for Gemini's 100-turn budget, 22
-    vs. 27 for the shared 30-turn budget) -- only with a much smaller
+    vs. 27 for OpenAI's 30-turn budget) -- only with a much smaller
     ``max_turns``.
     """
     checkpoint_turn = int(max_turns * _MID_BUDGET_NUDGE_FRACTION)
@@ -197,6 +206,159 @@ def _compute_mid_budget_nudge_turn(max_turns: int) -> int | None:
     return checkpoint_turn
 
 
+# Claude-path equivalent of the disclosure line above. Claude-path reviewers do
+# not have a `finish_review` tool; they finish by emitting their role's final
+# JSON output block.
+_TURN_BUDGET_SYSTEM_PROMPT_LINE_CLAUDE = (
+    "You have at most {max_turns} turns. Emit your final JSON output block before you "
+    "run out -- a review that never emits it is discarded entirely."
+)
+
+
+# Tool-call budget warning thresholds and truthful messages for Claude-path
+# sessions.
+#
+# In claude-agent-sdk 0.1.81, supported tool-lifecycle hooks that can inject
+# feedback via hookSpecificOutput.additionalContext are PostToolUse and
+# PostToolUseFailure. PostToolBatch is the exact-per-turn future option in
+# Claude Code, but is untyped and unsupported in this SDK version.
+# We attach to PostToolUse and PostToolUseFailure to track combined tool
+# invocations and inject non-blocking convergence/stop nudges.
+#
+# Thresholds are derived from the turn budget constants: the final threshold
+# fires at the emergency checkpoint (_MAX_TURNS_CLAUDE - _NUDGE_TURNS_BEFORE_BUDGET,
+# or 47 under max_turns=50), and the mid threshold fires at the 75% checkpoint
+# (_compute_mid_budget_nudge_turn(_MAX_TURNS_CLAUDE), or 37 under max_turns=50).
+# Because every continuing agent turn has at least one tool call, these thresholds
+# are reachable no later than the corresponding tool-using turns under max_turns.
+# Multiple or parallel tool calls per turn can make the truthful tool-count advisory
+# fire earlier. The copy makes no turns-left claim, stating only the exact number of
+# tool calls made so far.
+def _compute_claude_tool_budget_thresholds(max_turns: int) -> tuple[int, int]:
+    """Compute and validate Claude tool-budget nudge thresholds (mid, final).
+
+    Returns:
+        tuple[int, int]: (mid_threshold, final_threshold) where mid_threshold
+        strictly precedes final_threshold.
+
+    Raises:
+        ValueError: If max_turns produces a mid-budget checkpoint that does not
+            strictly precede the final threshold (e.g. colliding or inverted thresholds
+            from a small budget).
+    """
+    final_threshold = max_turns - _NUDGE_TURNS_BEFORE_BUDGET
+    mid_threshold = _compute_mid_budget_nudge_turn(max_turns)
+    if mid_threshold is None:
+        raise ValueError(
+            f"Invalid max_turns={max_turns}: mid-budget checkpoint must precede "
+            f"the final budget nudge threshold ({final_threshold})"
+        )
+    return mid_threshold, final_threshold
+
+
+_TOOL_BUDGET_MID_THRESHOLD: int
+_TOOL_BUDGET_FINAL_THRESHOLD: int
+_TOOL_BUDGET_MID_THRESHOLD, _TOOL_BUDGET_FINAL_THRESHOLD = _compute_claude_tool_budget_thresholds(
+    _MAX_TURNS_CLAUDE
+)
+
+_TOOL_BUDGET_MID_NUDGE = (
+    "You have now made {n} tool calls. If you have gathered enough "
+    "context to identify findings, begin converging toward your final JSON output block "
+    "now rather than continuing to explore."
+)
+_TOOL_BUDGET_FINAL_NUDGE = (
+    "You have now made {n} tool calls. Stop reading and searching now, and emit "
+    "your final JSON output block with whatever you have found so far. If you have "
+    "found nothing, emit your final JSON output block with an empty findings list."
+)
+
+
+def _make_tool_budget_nudge_hooks(
+    label: str | None = None,
+    *,
+    mid_threshold: int = _TOOL_BUDGET_MID_THRESHOLD,
+    final_threshold: int = _TOOL_BUDGET_FINAL_THRESHOLD,
+) -> dict[HookEvent, list[HookMatcher]]:
+    """Create PostToolUse and PostToolUseFailure hooks that inject non-blocking
+    nudge warnings into Claude-path sessions when tool-call counts cross budget thresholds.
+
+    In claude-agent-sdk 0.1.81, supported tool-lifecycle hooks that can inject
+    feedback via hookSpecificOutput.additionalContext are PostToolUse and
+    PostToolUseFailure. PostToolBatch is the exact-per-turn future option in
+    Claude Code, but is untyped and unsupported in this SDK version.
+
+    One callback is shared by both events, closing over combined tool-call count
+    and one-shot flags. Subagent tool calls (bearing agent_id) are skipped.
+    """
+    tool_call_count = 0
+    mid_nudge_sent = False
+    final_nudge_sent = False
+
+    async def _hook_callback(
+        input_data: Any,
+        tool_use_id: str | None,
+        context: HookContext,
+    ) -> SyncHookJSONOutput:
+        nonlocal tool_call_count, mid_nudge_sent, final_nudge_sent
+        try:
+            if not isinstance(input_data, dict):
+                return {}
+            # Sub-agent attribution: skip Task-spawned subagents
+            if input_data.get("agent_id"):
+                return {}
+
+            tool_call_count += 1
+            nudge_message: str | None = None
+
+            if tool_call_count >= final_threshold and not final_nudge_sent:
+                final_nudge_sent = True
+                mid_nudge_sent = True
+                nudge_message = _TOOL_BUDGET_FINAL_NUDGE.format(n=tool_call_count)
+            elif tool_call_count >= mid_threshold and not mid_nudge_sent:
+                mid_nudge_sent = True
+                nudge_message = _TOOL_BUDGET_MID_NUDGE.format(n=tool_call_count)
+
+            if nudge_message is None:
+                return {}
+
+            event_name = input_data.get("hook_event_name")
+            logger.info(
+                "Injected Claude tool-budget nudge [%s] at tool call %d (event=%s)",
+                label or "unlabeled",
+                tool_call_count,
+                event_name,
+            )
+
+            # Mirror hook_event_name in hookSpecificOutput
+            if event_name == "PostToolUseFailure":
+                failure_output: PostToolUseFailureHookSpecificOutput = {
+                    "hookEventName": "PostToolUseFailure",
+                    "additionalContext": nudge_message,
+                }
+                return {"hookSpecificOutput": failure_output}
+            else:
+                success_output: PostToolUseHookSpecificOutput = {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": nudge_message,
+                }
+                return {"hookSpecificOutput": success_output}
+
+        except Exception:
+            logger.warning(
+                "Tool budget hook callback failed for [%s]",
+                label or "unlabeled",
+                exc_info=True,
+            )
+            return {}
+
+    matcher = HookMatcher(hooks=[_hook_callback])
+    return {
+        "PostToolUse": [matcher],
+        "PostToolUseFailure": [matcher],
+    }
+
+
 # Fallback repo root for ClaudeSDKClient cwd — used when no SHA-pinned
 # worktree has been provisioned (e.g. local dev runs, tests, subprocess
 # worker). In production, callers pass an explicit repo_root provisioned
@@ -1697,15 +1859,22 @@ async def _run_claude_session(
     betas: list[Literal["context-1m-2025-08-07"]] = (
         ["context-1m-2025-08-07"] if _attach_1m_context_beta else []
     )
+    system_prompt = (
+        system_prompt
+        + "\n\n"
+        + _TURN_BUDGET_SYSTEM_PROMPT_LINE_CLAUDE.format(max_turns=_MAX_TURNS_CLAUDE)
+    )
+    hooks = _make_tool_budget_nudge_hooks(label)
     options = ClaudeAgentOptions(
         cwd=effective_root,
         allowed_tools=["Read", "Glob", "Grep"] + context7_tools,
         mcp_servers=mcp_servers,
         strict_mcp_config=True,
         permission_mode="default",
+        hooks=hooks,
         model=model,
         system_prompt=system_prompt,
-        max_turns=_MAX_TURNS,
+        max_turns=_MAX_TURNS_CLAUDE,
         env=dict([settings.anthropic_credential]),
         stderr=_stderr_handler,
         betas=betas,
@@ -1743,6 +1912,11 @@ async def _run_claude_session(
         result_text = ""
         cost_usd = 0.0
         tool_calls: list[str] = []
+        # Note: message_index counts AssistantMessage objects received from the SDK
+        # stream, NOT CLI turns. Multiple AssistantMessage objects can occur within
+        # a single turn or sub-step. It must never be used as a turn counter.
+        # Key and log names ('msg_index', 'msg=%d') are preserved for log
+        # compatibility.
         message_index = 0
         failure_reason: Literal["turn_budget_exhausted"] | None = None
         async for message in client.receive_response():
@@ -1842,7 +2016,7 @@ async def _run_claude_session(
                     logger.warning(
                         "Agent [%s] exhausted its %d-turn budget (subtype=%s)",
                         label or "unlabeled",
-                        _MAX_TURNS,
+                        _MAX_TURNS_CLAUDE,
                         message.subtype,
                     )
                     failure_reason = "turn_budget_exhausted"

{argus_code_review-0.2.6 → argus_code_review-0.2.8}/tests/storage/test_backend_contract.py

@@ -3,22 +3,20 @@
 Every scenario in this file exercises the seven logical operations defined
 by ``argus/storage/sql.py`` (the Postgres canonical writer) purely through
 their Pydantic input/output shapes — no backend-specific assertions. The
-goal is a single suite that can run, unmodified, against any backend that
-implements the same operations: today that's just
-:class:`argus.storage.sqlite.SqliteHistoryBackend` (wired via the
-``backend`` fixture below); ``postgres`` and ``http`` params are declared
-already (each ``pytest.mark.skip``ped with the reason it isn't wired yet)
-so that adding those fixtures later is a matter of filling in the
-``elif`` branch in ``backend()`` — no test bodies change.
-
+goal is a single suite that runs against any backend implementing the same
+operations:
+
+- **sqlite**: fully supported locally (:class:`argus.storage.sqlite.SqliteHistoryBackend`).
+- **http**: wired via ``pytest-httpx`` standing in for the two-endpoint HTTP
+  storage contract (see ``docs/STORAGE.md``). Operations not implemented by
+  the minimal HTTP shim (e.g. status polling, recent-rounds listing,
+  select_recent_lite_rounds, insert_agent_runs) are documented and marked xfail.
+  Completed-round persistence and latest-round reads (including for lite-mode
+  reviews) are fully supported and verified.
 - **postgres**: needs a live database and ``argus.storage.session`` wired
-  up. Guard with ``ARGUS_DB_URL`` / ``SUPABASE_DB_URL`` env-var presence and
-  the ``integration`` marker once wired, mirroring the pattern in
+  up. Guarded with ``ARGUS_DB_URL`` / ``SUPABASE_DB_URL`` env-var presence and
+  the ``integration`` marker, mirroring the pattern in
   ``tests/storage/test_sql.py``.
-- **http**: needs a ``pytest-httpx`` fixture standing in for your configured
-  HTTP backend's endpoints (see ``docs/STORAGE.md`` for the contract). Once
-  wired, ``HttpStorageClient`` would sit behind the same seven-operation
-  surface as a thin adapter.
 
 Scenario coverage:
 
@@ -103,6 +101,9 @@ _HTTP_UNSUPPORTED_TESTS = {
     # select_recent_rounds -- not exposed over HTTP.
     "test_select_recent_rounds_orders_desc_and_respects_limit",
     "test_repeated_running_upsert_same_flow_run_id_does_not_duplicate",
+    # insert_agent_runs -- documented no-op on HTTP path (analytics inserts
+    # not covered by minimal HTTP shim, TECH-3487 follow-up).
+    "test_insert_agent_runs_batch",
     # select_recent_lite_rounds -- documented no-op (always returns []).
     "test_select_recent_lite_rounds_filters_reviewer_version",
     "test_select_recent_lite_rounds_default_limit_is_200",
@@ -112,6 +113,14 @@ _HTTP_UNSUPPORTED_TESTS = {
 def _mark_known_http_gaps(request: pytest.FixtureRequest) -> None:
     base_name = request.node.name.split("[")[0]
     if base_name in _HTTP_UNSUPPORTED_TESTS:
+        # insert_agent_runs is a documented no-op on the HTTP shim (analytics
+        # inserts not covered, TECH-3487 follow-up); the call does not assert
+        # rows or raise, so xfail directly rather than letting it pass vacuously.
+        if base_name == "test_insert_agent_runs_batch":
+            pytest.xfail(
+                "HTTP storage shim does not support agent_runs analytics inserts "
+                "(documented Phase-1 gap, TECH-3487)"
+            )
         request.node.add_marker(
             pytest.mark.xfail(
                 reason=(
@@ -202,10 +211,10 @@ async def backend(
         return
 
     if backend_kind == "http":
+        _mark_known_http_gaps(request)
         httpx_mock = request.getfixturevalue("httpx_mock")
         httpx_mock.add_callback(_FakeHttpStorageBackend().handle, is_reusable=True)
         install_http_storage(read_url=_HTTP_READ_URL, write_url=_HTTP_WRITE_URL)
-        _mark_known_http_gaps(request)
         try:
             yield HttpHistoryBackend()
         finally:
@@ -317,6 +326,79 @@ async def test_upsert_completed_row_defaults_reviewer_version_and_stage(
     assert written.verdict is None
 
 
+async def test_lite_round_completed_upsert_round_trips_through_latest(
+    backend: HistoryBackend,
+) -> None:
+    """Lite-mode rounds (reviewer_version='v3-lite') must persist via
+    upsert_completed_row and round-trip through select_latest_completed_round
+    on all backends (including the HTTP storage shim).
+    """
+    payload = CodeReviewRoundIn(
+        flow_run_id="fr-lite-rt-1",
+        repo="org/repo-lite",
+        pr_number=10,
+        verdict="approve",
+        risk_level="low",
+        blocking_count=0,
+        suggestion_count=0,
+        review_comment="lgtm lite review",
+        reviewer_version="v3-lite",
+        result_json={"review_round": 2, "preflight_reason": "test-only diff"},
+        sha="deadbeef123",
+        base_ref="main",
+    )
+
+    written = await backend.upsert_completed_row(row=payload)
+    assert written.reviewer_version == "v3-lite"
+
+    latest = await backend.select_latest_completed_round(repo="org/repo-lite", pr_number=10)
+    assert latest is not None
+    assert latest.id == written.id
+    assert latest.reviewer_version == "v3-lite"
+    assert latest.verdict == "approve"
+    assert latest.sha == "deadbeef123"
+    assert latest.result_json == {"review_round": 2, "preflight_reason": "test-only diff"}
+    assert latest.prior_count == 1
+
+
+async def test_lite_round_becomes_latest_completed_round(
+    backend: HistoryBackend,
+) -> None:
+    """When a lite review follows a full review on the same PR, the lite
+    round becomes the latest completed round and preserves its version.
+    """
+    first_full = await backend.upsert_completed_row(
+        row=CodeReviewRoundIn(
+            flow_run_id="fr-seq-1",
+            repo="org/repo-seq",
+            pr_number=20,
+            verdict="block",
+            reviewer_version="v3",
+            sha="sha-round-1",
+        )
+    )
+    second_lite = await backend.upsert_completed_row(
+        row=CodeReviewRoundIn(
+            flow_run_id="fr-seq-2",
+            repo="org/repo-seq",
+            pr_number=20,
+            verdict="approve",
+            reviewer_version="v3-lite",
+            sha="sha-round-2",
+            result_json={"review_round": 2, "preflight_reason": "catchup on green CI"},
+        )
+    )
+
+    latest = await backend.select_latest_completed_round(repo="org/repo-seq", pr_number=20)
+    assert latest is not None
+    assert latest.id == second_lite.id
+    assert latest.id != first_full.id
+    assert latest.reviewer_version == "v3-lite"
+    assert latest.verdict == "approve"
+    assert latest.sha == "sha-round-2"
+    assert latest.prior_count == 2
+
+
 # ---------------------------------------------------------------------------
 # 3. Two completed rounds -> latest wins; select_recent_rounds ordering + limit
 # ---------------------------------------------------------------------------
@@ -471,7 +553,7 @@ async def test_completed_upsert_same_flow_run_id_preserves_sha_via_coalesce(
 # ---------------------------------------------------------------------------
 
 
-async def test_insert_agent_runs_batch(backend: SqliteHistoryBackend) -> None:
+async def test_insert_agent_runs_batch(backend: HistoryBackend) -> None:
     review = await backend.upsert_completed_row(
         row=CodeReviewRoundIn(repo="org/repo6", pr_number=2, verdict="approve")
     )