feat: resume reviews from cached codex state (#21)

Author: gersmann

.github/workflows/codex-review.yml

@@ -30,7 +30,7 @@ jobs:
         with:
           mode: review
           openai_api_key: ${{ secrets.OPENAI_API_KEY }}
-          model: gpt-5.1-codex-max
+          model: gpt-5.4
           reasoning_effort: medium
           debug_level: 1
 

README.md

@@ -117,13 +117,22 @@ jobs:
 - **PR-level summary** as an issue comment on each run (refreshed on re-runs; prior summaries are deleted).
 - **Multi-line suggestions** only when contiguous and short; otherwise a single-line comment.
 
+## Review Continuation
+
+On repeated `pull_request` review runs, the action now tries to continue the prior Codex review instead of restarting from scratch.
+
+1. The PR summary stores the previously reviewed head SHA in hidden metadata.
+2. Review mode caches an isolated Codex home keyed by repository, PR number, model, and reviewed SHA.
+3. On the next push, the action restores that cache, resumes the latest stored review thread, and scopes the prompt to the delta since the previously reviewed SHA.
+4. If the prior SHA is no longer an ancestor, the cache is missing, or no thread can be restored, the action falls back to a fresh full review.
+
 ## Deduplication on Repeated Runs
 
 When a prior Codex review exists on the PR, reruns only reuse **unresolved Codex-authored review threads** as context.
 
 1. **Inline semantic dedup** — prior unresolved Codex comments are passed to the model's structured-output turn so it can avoid reposting the same issue as a new finding.
 2. **Re-adjudicated carry-forward** — the model separately marks which of those prior unresolved Codex comments are still relevant now. Only those count toward the PR summary.
-3. **Separated counts** — the summary reports new findings from the current run separately from prior Codex findings that still appear relevant.
+3. **Separated counts** — the summary reports new findings and still-relevant prior findings separately.
 
 ## Security & Permissions
 

action.yml

@@ -74,6 +74,29 @@ runs:
         if ! contains_word "$valid_search_modes" "${{ inputs.web_search_mode }}"; then
           echo "::error::Invalid web_search_mode: ${{ inputs.web_search_mode }} (allowed: disabled|cached|live)"; exit 2;
         fi
+    - name: Prepare review resume state
+      if: ${{ inputs.mode == 'review' }}
+      id: review_resume_state
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        GITHUB_API_URL: ${{ github.api_url }}
+        GITHUB_EVENT_PATH: ${{ github.event_path }}
+        GITHUB_REPOSITORY: ${{ github.repository }}
+        RUNNER_TEMP: ${{ runner.temp }}
+        CODEX_MODEL_INPUT: ${{ inputs.model }}
+        GITHUB_ACTION_PATH: ${{ github.action_path }}
+      run: |
+        set -euo pipefail
+        PYTHONPATH="${GITHUB_ACTION_PATH}:${PYTHONPATH:-}" \
+          python3 -m cli.review.prepare_resume_state
+    - name: Restore review Codex cache
+      if: ${{ inputs.mode == 'review' && steps.review_resume_state.outputs.restore_key != '' }}
+      id: review_codex_cache
+      uses: actions/cache/restore@v4
+      with:
+        path: ${{ steps.review_resume_state.outputs.codex_home }}
+        key: ${{ steps.review_resume_state.outputs.restore_key }}
     - name: Install Python dependencies
       shell: bash
       run: |
@@ -82,6 +105,7 @@ runs:
         python3 -m pip install ${{ inputs.extra_pip_args }} -r "${{ github.action_path }}/requirements.txt"
 
     - name: Run Codex autonomous review (CLI)
+      id: run_codex_cli
       shell: bash
       env:
         # Tokens
@@ -98,8 +122,17 @@ runs:
         DEBUG_CODEREVIEW: ${{ inputs.debug_level }}
         DRY_RUN: ${{ inputs.dry_run }}
         STREAM_AGENT_MESSAGES: ${{ inputs.stream_agent_messages }}
+        CODEX_HOME: ${{ steps.review_resume_state.outputs.codex_home }}
+        CODEX_REVIEW_PREVIOUS_HEAD_SHA: ${{ steps.review_resume_state.outputs.previous_reviewed_sha }}
+        CODEX_REVIEW_CACHE_HIT: ${{ steps.review_codex_cache.outputs.cache-hit }}
       run: |
         set -euo pipefail
         # Execute the CLI directly; it detects GitHub Actions via env
         PYTHONPATH="${{ github.action_path }}:${PYTHONPATH:-}" \
           python3 -m cli.main
+    - name: Save review Codex cache
+      if: ${{ inputs.mode == 'review' && steps.run_codex_cli.outcome == 'success' && steps.review_resume_state.outputs.current_cache_key != '' && !(steps.review_codex_cache.outputs.cache-hit == 'true' && steps.review_resume_state.outputs.restore_key == steps.review_resume_state.outputs.current_cache_key) }}
+      uses: actions/cache/save@v4
+      with:
+        path: ${{ steps.review_resume_state.outputs.codex_home }}
+        key: ${{ steps.review_resume_state.outputs.current_cache_key }}

cli/README.md

@@ -138,6 +138,15 @@ pytest tests/ -v
   - **Codex-thread attribution**: only unresolved review threads whose root author matches a prior Codex summary author are reused as rerun context.
   - **Inline semantic dedup**: the structured-output turn uses those prior Codex comments to decide which issues are new vs already covered.
   - **Re-adjudicated summary carry-forward**: the model returns prior comment IDs that still seem relevant, and the summary reports those separately from new findings.
+  - **Auto-resolution of fixed Codex threads**: the model can also mark prior unresolved Codex comments as fixed, and review mode resolves those GitHub review threads automatically.
+
+## Review Resume Between Pushes
+
+- Review mode can resume the previous Codex thread when a PR receives new commits.
+- The summary issue comment stores the last reviewed head SHA in hidden metadata.
+- GitHub Actions review runs restore an isolated review-only `CODEX_HOME` cache keyed by repository, PR number, model, and reviewed SHA.
+- When the prior reviewed SHA is still an ancestor of the current head and the cached session index contains a thread, the workflow resumes that thread and narrows the prompt to `previous_reviewed_sha..HEAD`.
+- Small incremental diffs are embedded directly in the prompt; larger deltas are referenced by commit range and inspected with git during the review turn.
 
 ### Customizing the Review Prompt
 

cli/clients/codex_client.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import os
 import sys
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any, Literal, cast
 
-from codex import Codex, CodexOptions, ThreadStartOptions, TurnOptions
+from codex import Codex, CodexOptions, ThreadResumeOptions, ThreadStartOptions, TurnOptions
 from codex.errors import CodexParseError, ThreadRunError
 from codex.protocol import types as protocol
 from codex.thread import CodexTurnStream, Thread
@@ -92,13 +93,15 @@ def execute_text(
         reasoning_effort: str | None = None,
         suppress_stream: bool = False,
         sandbox_mode: str = "read-only",
+        resume_thread_id: str | None = None,
     ) -> str:
         """Run a single text turn and return the final agent text."""
         return self._run_session(
             model_name=model_name,
             reasoning_effort=reasoning_effort,
             suppress_stream=suppress_stream,
             sandbox_mode=sandbox_mode,
+            resume_thread_id=resume_thread_id,
             session_runner=lambda thread, effort, stream_enabled: self._run_text_session(
                 thread=thread,
                 prompt=prompt,
@@ -117,13 +120,15 @@ def execute_structured(
         reasoning_effort: str | None = None,
         suppress_stream: bool = False,
         sandbox_mode: str = "read-only",
+        resume_thread_id: str | None = None,
     ) -> str:
         """Run an agentic turn followed by a schema-enforced output turn."""
         return self._run_session(
             model_name=model_name,
             reasoning_effort=reasoning_effort,
             suppress_stream=suppress_stream,
             sandbox_mode=sandbox_mode,
+            resume_thread_id=resume_thread_id,
             session_runner=lambda thread, effort, stream_enabled: self._run_structured_session(
                 thread=thread,
                 prompt=prompt,
@@ -141,15 +146,17 @@ def _run_session(
         reasoning_effort: str | None,
         suppress_stream: bool,
         sandbox_mode: str,
+        resume_thread_id: str | None,
         session_runner: Callable[[Thread, str, bool], str],
     ) -> str:
         effort = self._resolve_effort(reasoning_effort)
         stream_enabled = self._should_stream(suppress_stream)
 
         try:
-            thread = self._create_thread(
+            thread = self._start_or_resume_thread(
                 model_name=model_name,
                 sandbox_mode=sandbox_mode,
+                resume_thread_id=resume_thread_id,
             )
             return session_runner(thread, effort, stream_enabled)
         except ThreadRunError as run_err:
@@ -419,18 +426,62 @@ def _codex_web_search_mode(self) -> Literal["disabled", "cached", "live"]:
         self._debug(1, f"Invalid web search mode '{mode}', falling back to 'live'")
         return "live"
 
-    def _create_thread(self, *, model_name: str | None, sandbox_mode: str) -> Thread:
-        resolved_sandbox_mode = self._normalize_sandbox_mode(sandbox_mode, "read-only")
+    def _codex_process_env(self) -> dict[str, str] | None:
+        codex_home = os.environ.get("CODEX_HOME")
+        if not isinstance(codex_home, str):
+            return None
+        normalized = codex_home.strip()
+        if not normalized:
+            return None
+        return {"CODEX_HOME": normalized}
+
+    def _resolved_model_name(self, model_name: str | None) -> str:
+        resolved_model_name = model_name if model_name is not None else self.config.model_name
+        return resolved_model_name.strip()
+
+    def _make_codex_client(self) -> Codex:
         return Codex(
             options=CodexOptions(
                 config=cast(Any, {"show_raw_agent_reasoning": self.config.debug_level >= 2}),
                 api_key=self._resolve_api_key(),
+                env=self._codex_process_env(),
             )
-        ).start_thread(
+        )
+
+    def _thread_config(self) -> dict[str, Literal["disabled", "cached", "live"]]:
+        return {"web_search": self._codex_web_search_mode()}
+
+    def _start_or_resume_thread(
+        self,
+        *,
+        model_name: str | None,
+        sandbox_mode: str,
+        resume_thread_id: str | None,
+    ) -> Thread:
+        resolved_sandbox_mode = self._normalize_sandbox_mode(sandbox_mode, "read-only")
+        resolved_model_name = self._resolved_model_name(model_name)
+        codex_client = self._make_codex_client()
+        if resume_thread_id:
+            try:
+                self._debug(1, f"Attempting to resume Codex thread {resume_thread_id}")
+                return codex_client.resume_thread(
+                    resume_thread_id,
+                    ThreadResumeOptions(
+                        model=resolved_model_name,
+                        sandbox=cast(Any, resolved_sandbox_mode),
+                        config=cast(Any, self._thread_config()),
+                    ),
+                )
+            except Exception as exc:
+                self._debug(
+                    1,
+                    f"Failed to resume Codex thread {resume_thread_id}: {exc}; starting fresh",
+                )
+        return codex_client.start_thread(
             ThreadStartOptions(
-                model=(model_name or self.config.model_name).strip(),
+                model=resolved_model_name,
                 sandbox=cast(Any, resolved_sandbox_mode),
-                config=cast(Any, {"web_search": self._codex_web_search_mode()}),
+                config=cast(Any, self._thread_config()),
             )
         )
 

cli/clients/git_ops.py

@@ -191,6 +191,36 @@ def git_is_ancestor(older_sha: str, newer_sha: str) -> bool:
     )
 
 
+def git_diff_text(revision_range: str, *, unified: int = 3) -> str:
+    """Return the git diff for ``revision_range``.
+
+    Raises:
+        subprocess.CalledProcessError: Git diff failed.
+    """
+    result = _run_git(
+        ["diff", f"--unified={unified}", "--no-color", revision_range],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        _raise_git_result_error(result)
+    return result.stdout
+
+
+def git_commit_shas(revision_range: str) -> list[str]:
+    """Return commit SHAs in ``revision_range`` from oldest to newest.
+
+    Raises:
+        subprocess.CalledProcessError: Git log probe failed.
+    """
+    result = _run_git(
+        ["rev-list", "--reverse", revision_range],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        _raise_git_result_error(result)
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
 def git_rebase_in_progress() -> bool:
     """Return whether repository is in an active rebase state.
 

cli/core/exceptions.py

@@ -31,3 +31,7 @@ class PromptError(CodexReviewError):
 
 class ReviewContractError(CodexReviewError):
     """Structured review payload or metadata contract violations."""
+
+
+class ReviewResumeError(CodexReviewError):
+    """Review resume invariant or infrastructure failures."""

cli/core/models.py

@@ -165,14 +165,16 @@ def as_dict(self) -> dict[str, Any]:
 
 
 @dataclass(frozen=True)
-class ExistingReviewComment:
-    """Structured inline review comment used for local dedupe."""
+class PriorCodexReviewComment:
+    """Unresolved Codex-authored review thread comment reused on reruns."""
 
     id: str
+    thread_id: str
     path: str
     line: int
     body: str
     current_code: str
+    is_currently_applicable: bool
 
 
 @dataclass(frozen=True)

cli/main.py

@@ -299,11 +299,14 @@ def _run_mode_workflow(config: ReviewConfig) -> int:
 
     summary = result.summary
     if summary.carried_forward_count > 0:
+        extra_parts: list[str] = []
+        if summary.carried_forward_count > 0:
+            extra_parts.append(f"{summary.carried_forward_count} prior findings still relevant")
         print(
             "\nReview completed: "
             f"{summary.overall_correctness}, "
             f"{summary.current_findings_count} new findings, "
-            f"{summary.carried_forward_count} prior findings still relevant "
+            f"{', '.join(extra_parts)} "
             f"({summary.active_findings_count} active total)"
         )
     else: