@openhands/extensions 0.4.1 → 0.5.0

package/skills/github-pr-reviewer/scripts/main.py

@@ -1,26 +1,9 @@
 """
-GitHub PR Reviewer  -  OpenHands Automation Script
+GitHub PR Reviewer - OpenHands Automation Script
 
-Polls a GitHub repository on a cron schedule. For each open pull request
-that has not yet been reviewed it:
-  1. Fetches the PR metadata and diff.
-  2. Creates an OpenHands conversation with a targeted review prompt.
-  3. When the conversation completes, posts the AI review as a GitHub comment.
-
-On subsequent runs:
-  - Already-reviewed PRs are skipped (tracked in the state file).
-  - Active conversations are checked for completion and results posted.
-
-Configuration constants are embedded at automation-creation time by the skill.
-See SKILL.md for the full setup workflow.
-
-Required secret (set in OpenHands Settings → Secrets):
-  GITHUB_PERSONAL_ACCESS_TOKEN  - Personal Access Token
-                  Classic PAT:       'repo' scope (private) or 'public_repo' (public)
-                  Fine-grained PAT:  Pull requests: Read and Write
-
-Optional secret:
-  OPENHANDS_URL - base URL for conversation links (default: http://localhost:8000)
+Cron-polls a GitHub repository for open pull requests carrying the configured
+trigger label. A review is queued only when the latest matching GitHub `labeled`
+event has not already been processed by this automation.
 """
 
 import json
@@ -29,38 +12,24 @@ import sys
 import time
 import urllib.error
 import urllib.request
-from datetime import datetime, timezone
 from pathlib import Path
 from urllib.parse import urlencode
 
-# ── Embedded configuration (filled in by the skill at creation time) ──────────
-REPO = "owner/repo"           # e.g. "myorg/backend"
-REVIEW_TONE = "thorough"      # "thorough" | "concise" | "friendly"
-REVIEW_STYLE_INSTRUCTIONS = ""  # extra free-form persona / style notes
+REPO = "owner/repo"
+TRIGGER_LABEL = "openhands-review"
+REVIEW_TONE = "thorough"
+REVIEW_STYLE_INSTRUCTIONS = ""
 DEFAULT_OPENHANDS_URL = "http://localhost:8000"
 
-# Max diff lines to include in the review prompt (avoids token overrun).
-MAX_DIFF_LINES = 500
-
-# PRs whose diff exceeds this many lines are skipped with an explanatory comment.
-MAX_DIFF_LINES_SKIP = 5000
-
-# Prevent posting summaries in the same run that created the conversation.
 DONE_DEBOUNCE = 15
+TERMINAL_STATUSES = {"idle", "finished", "error", "stuck"}
 
 
-# ── Stdlib helpers ─────────────────────────────────────────────────────────────
-
 def _get_env_key() -> str:
-    return (
-        os.environ.get("SESSION_API_KEY")
-        or os.environ.get("OH_SESSION_API_KEYS_0")
-        or ""
-    )
+    return os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0") or ""
 
 
 def get_secret(name: str) -> str:
-    """Fetch a named secret from the agent server."""
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = _get_env_key()
     req = urllib.request.Request(
@@ -76,7 +45,6 @@ def fire_callback(
     error: str | None = None,
     conversation_id: str | None = None,
 ) -> None:
-    """Signal run completion to the automation service."""
     url = os.environ.get("AUTOMATION_CALLBACK_URL", "")
     if not url:
         return
@@ -99,14 +67,7 @@ def fire_callback(
         print(f"Callback error (non-fatal): {exc}")
 
 
-# ── State management ───────────────────────────────────────────────────────────
-
 def _state_file_path() -> str:
-    """Derive a persistent storage path from WORKSPACE_BASE.
-
-    WORKSPACE_BASE = {root}/automation-runs/{run_id}
-    State lives two levels up at {root}/automation-state/.
-    """
     workspace_base = os.environ.get("WORKSPACE_BASE", "")
     event_payload = json.loads(os.environ.get("AUTOMATION_EVENT_PAYLOAD", "{}"))
     automation_id = event_payload.get("automation_id", "default")
@@ -118,7 +79,7 @@ def _state_file_path() -> str:
 
     state_dir = root / "automation-state"
     state_dir.mkdir(parents=True, exist_ok=True)
-    return str(state_dir / f"github_pr_reviewer_{automation_id}.json")
+    return str(state_dir / f"github_pr_reviewer_label_event_{automation_id}.json")
 
 
 def load_state(path: str) -> dict:
@@ -129,18 +90,20 @@ def load_state(path: str) -> dict:
         except (json.JSONDecodeError, OSError) as exc:
             print(f"Warning: state file {path} unreadable ({exc}); starting fresh")
     return {
-        "version": 1,
+        "version": 2,
         "repo": REPO,
-        "conversations": {},  # pr_number (str) → ConversationRecord
+        "trigger_label": TRIGGER_LABEL,
+        "reviews": {},
+        "prs": {},
     }
 
 
 def save_state(path: str, state: dict) -> None:
-    with open(path, "w") as f:
-        json.dump(state, f, indent=2)
-
+    tmp_path = f"{path}.tmp"
+    with open(tmp_path, "w") as f:
+        json.dump(state, f, indent=2, sort_keys=True)
+    os.replace(tmp_path, path)
 
-# ── GitHub API helpers ─────────────────────────────────────────────────────────
 
 def _github_request(
     token: str,
@@ -150,9 +113,7 @@ def _github_request(
     body: dict | None = None,
     accept: str = "application/vnd.github+json",
 ) -> tuple:
-    """Low-level GitHub API call. Returns (parsed_body, response_headers)."""
-    base = "https://api.github.com"
-    url = f"{base}{path}"
+    url = f"https://api.github.com{path}"
     if params:
         url = f"{url}?{urlencode(params)}"
     headers = {
@@ -164,15 +125,11 @@ def _github_request(
     data = json.dumps(body).encode() if body is not None else None
     req = urllib.request.Request(url, data=data, headers=headers, method=method)
     with urllib.request.urlopen(req) as r:
-        resp_headers = dict(r.headers)
         raw = r.read()
-        if accept == "application/vnd.github.diff":
-            return raw.decode("utf-8", errors="replace"), resp_headers
-        return (json.loads(raw) if raw.strip() else {}), resp_headers
+        return (json.loads(raw) if raw.strip() else {}), dict(r.headers)
 
 
 def _github_paginate(token: str, path: str, params: dict | None = None) -> list:
-    """Fetch all pages from a GitHub list endpoint."""
     results = []
     page = 1
     base_params = dict(params or {})
@@ -202,57 +159,59 @@ def _resolve_github_token() -> str:
     )
 
 
-def _verify_token_and_repo(token: str, repo: str) -> str:
-    """Verify token validity and repo access. Returns the authenticated GitHub username."""
+def _verify_token_and_repo(token: str, repo: str) -> None:
     try:
         user_data, _ = _github_request(token, "GET", "/user")
     except urllib.error.HTTPError as exc:
         if exc.code == 401:
-            raise RuntimeError(
-                "GITHUB_PERSONAL_ACCESS_TOKEN is invalid or expired. "
-                "Update it in OpenHands Settings → Secrets."
-            )
-        raise RuntimeError(f"GitHub /user check failed: {exc.code}")
+            raise RuntimeError("GITHUB_PERSONAL_ACCESS_TOKEN is invalid or expired.") from exc
+        raise RuntimeError(f"GitHub /user check failed: {exc.code}") from exc
 
-    username: str = user_data.get("login", "?")
-    print(f"Authenticated as GitHub user: {username}")
+    print(f"Authenticated as GitHub user: {user_data.get('login', '?')}")
 
     try:
         _github_request(token, "GET", f"/repos/{repo}")
     except urllib.error.HTTPError as exc:
         if exc.code == 404:
-            raise RuntimeError(
-                f"Repository '{repo}' not found or not accessible with the current token."
-            )
-        raise RuntimeError(f"GitHub /repos/{repo} check failed: {exc.code}")
-
-    print(f"Repository '{repo}' accessible.")
-    return username
+            raise RuntimeError(f"Repository '{repo}' is not accessible with the current token.") from exc
+        raise RuntimeError(f"GitHub /repos/{repo} check failed: {exc.code}") from exc
 
 
 def _list_open_prs(token: str, repo: str) -> list[dict]:
-    """Fetch all open pull requests, oldest first."""
     return _github_paginate(
         token,
         f"/repos/{repo}/pulls",
-        {"state": "open", "sort": "created", "direction": "asc"},
+        {"state": "open", "sort": "updated", "direction": "desc"},
     )
 
 
-def _get_pr_diff(token: str, repo: str, pr_number: int) -> str:
-    """Fetch the unified diff for a pull request."""
-    diff, _ = _github_request(
-        token, "GET", f"/repos/{repo}/pulls/{pr_number}",
-        accept="application/vnd.github.diff",
-    )
-    return diff
+def _get_pr(token: str, repo: str, pr_number: int) -> dict:
+    pr, _ = _github_request(token, "GET", f"/repos/{repo}/pulls/{pr_number}")
+    return pr
+
+
+def _get_issue_events(token: str, repo: str, pr_number: int) -> list[dict]:
+    return _github_paginate(token, f"/repos/{repo}/issues/{pr_number}/events")
+
+
+def _latest_trigger_label_event(token: str, repo: str, pr_number: int) -> dict | None:
+    events = _get_issue_events(token, repo, pr_number)
+    matching = [
+        event for event in events
+        if event.get("event") == "labeled"
+        and (event.get("label") or {}).get("name", "").lower() == TRIGGER_LABEL.lower()
+        and event.get("id") is not None
+    ]
+    if not matching:
+        return None
+    return max(matching, key=lambda event: (event.get("created_at") or "", int(event.get("id") or 0)))
 
 
 def _post_github_comment(token: str, repo: str, pr_number: int, body: str) -> None:
-    """Post a comment on a pull request."""
     try:
         _github_request(
-            token, "POST",
+            token,
+            "POST",
             f"/repos/{repo}/issues/{pr_number}/comments",
             body={"body": body},
         )
@@ -260,11 +219,7 @@ def _post_github_comment(token: str, repo: str, pr_number: int, body: str) -> No
         print(f"  Warning: failed to post comment on PR #{pr_number}: {exc}")
 
 
-# ── OpenHands conversation helpers ────────────────────────────────────────────
-
-def _oh_request(
-    agent_url: str, api_key: str, method: str, path: str, body: dict | None = None
-) -> dict:
+def _oh_request(agent_url: str, api_key: str, method: str, path: str, body: dict | None = None) -> dict:
     url = f"{agent_url}{path}"
     headers = {"X-Session-API-Key": api_key, "Content-Type": "application/json"}
     data = json.dumps(body).encode() if body is not None else None
@@ -279,17 +234,17 @@ def _oh_request(
 
 
 def _fetch_settings(agent_url: str, api_key: str) -> dict:
-    url = f"{agent_url}/api/settings"
-    headers = {"X-Session-API-Key": api_key, "X-Expose-Secrets": "plaintext"}
-    req = urllib.request.Request(url, headers=headers)
+    req = urllib.request.Request(
+        f"{agent_url}/api/settings",
+        headers={"X-Session-API-Key": api_key, "X-Expose-Secrets": "plaintext"},
+    )
     with urllib.request.urlopen(req) as r:
         return json.loads(r.read())
 
 
 def _get_agent_dict(agent_url: str, api_key: str) -> dict:
     data = _fetch_settings(agent_url, api_key)
-    agent_settings = data.get("agent_settings", {})
-    llm = agent_settings.get("llm", {})
+    llm = data.get("agent_settings", {}).get("llm", {})
     return {
         "kind": "Agent",
         "llm": llm,
@@ -318,9 +273,8 @@ def _list_secret_names(agent_url: str, api_key: str) -> list[dict]:
 
 
 def _build_secrets_payload(agent_url: str, api_key: str) -> dict:
-    secrets_list = _list_secret_names(agent_url, api_key)
-    secrets: dict = {}
-    for secret in secrets_list:
+    secrets = {}
+    for secret in _list_secret_names(agent_url, api_key):
         name = secret.get("name", "")
         if not name:
             continue
@@ -338,12 +292,10 @@ def _build_secrets_payload(agent_url: str, api_key: str) -> dict:
 
 
 def create_conversation(agent_url: str, api_key: str, initial_message: str) -> str:
-    """Create an OpenHands conversation and return its ID."""
     workspace_dir = os.environ.get("WORKSPACE_BASE", "/workspace")
-    agent = _get_agent_dict(agent_url, api_key)
     payload: dict = {
         "workspace": {"working_dir": workspace_dir},
-        "agent": agent,
+        "agent": _get_agent_dict(agent_url, api_key),
         "initial_message": {"content": [{"text": initial_message}]},
     }
     secrets = _build_secrets_payload(agent_url, api_key)
@@ -362,33 +314,52 @@ def conversation_status(agent_url: str, api_key: str, conv_id: str) -> str:
 
 
 def conversation_final_response(agent_url: str, api_key: str, conv_id: str) -> str:
-    result = _oh_request(
-        agent_url, api_key, "GET",
-        f"/api/conversations/{conv_id}/agent_final_response",
-    )
+    result = _oh_request(agent_url, api_key, "GET", f"/api/conversations/{conv_id}/agent_final_response")
     return result.get("response", "")
 
 
-# ── Prompt building ────────────────────────────────────────────────────────────
-
-_TONE_INSTRUCTIONS: dict[str, str] = {
+_TONE_INSTRUCTIONS = {
     "thorough": (
         "Provide a comprehensive review. Cover correctness, security vulnerabilities, "
-        "missing or inadequate tests, code style, maintainability, and potential edge "
-        "cases. Reference specific files and line numbers where relevant."
+        "missing or inadequate tests, code style, maintainability, and potential edge cases. "
+        "Reference specific files and line numbers where relevant."
     ),
     "concise": (
-        "Provide a brief, high-signal review. Focus only on the most important issues — "
-        "bugs, security problems, or significant design flaws. Omit minor style feedback."
+        "Provide a brief, high-signal review. Focus only on important bugs, security problems, "
+        "or significant design flaws. Omit minor style feedback."
     ),
     "friendly": (
         "Provide a constructive, encouraging review. Acknowledge what is done well before "
-        "raising concerns. Be positive and supportive while still noting real issues."
+        "raising concerns while still noting real issues."
     ),
 }
 
 
-def _build_review_prompt(pr: dict, diff: str, diff_truncated: bool) -> str:
+def _labels(pr: dict) -> list[str]:
+    return [label.get("name", "") for label in pr.get("labels", [])]
+
+
+def _has_trigger_label(pr: dict) -> bool:
+    return any(label.lower() == TRIGGER_LABEL.lower() for label in _labels(pr))
+
+
+def _head_sha(pr: dict) -> str:
+    return ((pr.get("head") or {}).get("sha") or "").strip()
+
+
+def _review_key(pr_number: int, label_event_id: int | str) -> str:
+    return f"{pr_number}:label:{label_event_id}"
+
+
+def _with_ai_disclosure(body: str) -> str:
+    disclosure = "_This comment was posted by an AI agent (OpenHands)._"
+    body = (body or "").strip()
+    if disclosure.lower() in body.lower():
+        return body
+    return f"{body}\n\n{disclosure}" if body else disclosure
+
+
+def _build_review_prompt(pr: dict, head_sha: str, label_event: dict) -> str:
     number = pr.get("number", "?")
     title = pr.get("title", "(no title)")
     body = (pr.get("body") or "").strip() or "(no description)"
@@ -396,90 +367,67 @@ def _build_review_prompt(pr: dict, diff: str, diff_truncated: bool) -> str:
     author = (pr.get("user") or {}).get("login", "?")
     base_branch = (pr.get("base") or {}).get("ref", "?")
     head_branch = (pr.get("head") or {}).get("ref", "?")
-    labels = [lb["name"] for lb in (pr.get("labels") or [])]
-    label_str = ", ".join(labels) if labels else "(none)"
+    label_str = ", ".join(_labels(pr)) or "(none)"
+    label_event_id = label_event.get("id", "?")
+    label_event_created_at = label_event.get("created_at", "?")
     changed_files = pr.get("changed_files", "?")
     additions = pr.get("additions", "?")
     deletions = pr.get("deletions", "?")
-
+    clone_url = f"https://github.com/{REPO}.git"
     tone = _TONE_INSTRUCTIONS.get(REVIEW_TONE, _TONE_INSTRUCTIONS["thorough"])
-    extra = (
-        f"\n\nAdditional style instructions:\n{REVIEW_STYLE_INSTRUCTIONS}"
-        if REVIEW_STYLE_INSTRUCTIONS.strip()
-        else ""
-    )
-    truncation_note = (
-        f"\n\n⚠️  The diff below has been truncated to the first {MAX_DIFF_LINES} lines. "
-        "Review what is available and note that the full diff is larger."
-    ) if diff_truncated else ""
+    extra = f"\n\nAdditional style instructions:\n{REVIEW_STYLE_INSTRUCTIONS}" if REVIEW_STYLE_INSTRUCTIONS.strip() else ""
 
     return (
-        f"You are an AI code reviewer. Review the following GitHub pull request "
-        f"and write a review comment.\n\n"
+        "You are an AI code reviewer. Review the GitHub pull request below and write "
+        "a single review comment. Do not modify files, push commits, approve via the GitHub "
+        "API, or request changes via the review API; only produce the final comment text.\n\n"
         f"Repository : {REPO}\n"
+        f"Clone URL  : {clone_url}\n"
         f"PR #{number}: \"{title}\"\n"
         f"Author     : @{author}\n"
         f"Base → Head: {base_branch} ← {head_branch}\n"
+        f"Head SHA   : {head_sha}\n"
+        f"Trigger    : latest `{TRIGGER_LABEL}` labeled event {label_event_id} at {label_event_created_at}\n"
         f"Labels     : {label_str}\n"
         f"Changes    : +{additions} -{deletions} across {changed_files} file(s)\n"
         f"URL        : {html_url}\n"
-        f"\nPR Description:\n---\n{body}\n---\n"
-        f"{truncation_note}"
-        f"\nDiff:\n```diff\n{diff}\n```\n"
+        f"\nPR Description:\n---\n{body}\n---\n\n"
+        "Required workflow:\n"
+        "1. Clone the repository into a fresh working directory inside the workspace.\n"
+        f"   Example: `git clone {clone_url} pr-review-{number}`.\n"
+        "2. Check out the exact pull request branch by PR number, then verify HEAD matches the SHA above.\n"
+        f"   Example: `git fetch origin pull/{number}/head:openhands-pr-{number}` followed by `git checkout openhands-pr-{number}`.\n"
+        "3. Inspect the existing PR context before reviewing, including PR description, issue comments, review comments, changed files, and the diff.\n"
+        "   Prefer `gh pr view`, `gh pr diff`, `gh pr checkout`, or GitHub REST API calls with `GITHUB_PERSONAL_ACCESS_TOKEN`; do not print secret values.\n"
+        "4. Use the checked-out repository to inspect relevant files and surrounding code, not just the patch.\n"
+        "5. Before producing the final review text, delete only the cloned repository directory created in step 1.\n"
+        f"   Example: `rm -rf pr-review-{number}`. Do not delete any other files or directories.\n"
+        "6. Write a high-signal review comment with specific findings. If there are no material issues, say so.\n"
         f"\nReview instructions:\n{tone}{extra}\n\n"
-        f"Output ONLY the review text — no preamble, no meta-commentary. "
-        f"This text will be posted verbatim as a comment on the pull request.\n"
-        f"End your review with a clear verdict on its own line: "
-        f"either `✅ APPROVED` or `🔄 CHANGES REQUESTED`."
+        "Output ONLY the review text — no preamble, no meta-commentary. "
+        "This text will be posted verbatim as a comment on the pull request. "
+        "End your review with a clear verdict on its own line: either `✅ APPROVED` "
+        "or `🔄 CHANGES REQUESTED`."
     )
 
-
-# ── Core logic ─────────────────────────────────────────────────────────────────
-
-def _process_new_pr(
+def _process_review_request(
     github_token: str,
     agent_url: str,
     api_key: str,
     openhands_url: str,
     pr: dict,
-    conversations: dict,
+    label_event: dict,
+    reviews: dict,
 ) -> str | None:
-    """Start a review conversation for a PR not yet seen. Returns the conversation ID."""
     number = pr["number"]
+    head_sha = _head_sha(pr)
+    label_event_id = label_event["id"]
+    key = _review_key(number, label_event_id)
     title = pr.get("title", "(no title)")
     html_url = pr.get("html_url", "")
-    print(f"  New PR #{number}: \"{title}\"")
-
-    try:
-        diff = _get_pr_diff(github_token, REPO, number)
-    except Exception as exc:
-        print(f"  Warning: could not fetch diff for PR #{number}: {exc}")
-        return None
-
-    diff_lines = diff.splitlines()
-
-    if len(diff_lines) > MAX_DIFF_LINES_SKIP:
-        print(f"  Skipping PR #{number}: diff too large ({len(diff_lines)} lines)")
-        conversations[str(number)] = {
-            "pr_number": number,
-            "html_url": html_url,
-            "status": "skipped",
-            "reason": f"diff too large ({len(diff_lines)} lines)",
-            "last_activity": time.time(),
-        }
-        _post_github_comment(
-            github_token, REPO, number,
-            f"⚠️ **OpenHands PR Reviewer**: This PR's diff is too large to review "
-            f"automatically ({len(diff_lines):,} lines). Consider splitting it into "
-            f"smaller PRs.\n\n_This message was posted by an AI agent (OpenHands)._",
-        )
-        return None
-
-    diff_truncated = len(diff_lines) > MAX_DIFF_LINES
-    if diff_truncated:
-        diff = "\n".join(diff_lines[:MAX_DIFF_LINES])
 
-    prompt = _build_review_prompt(pr, diff, diff_truncated)
+    print(f"  Queuing review for PR #{number} from `{TRIGGER_LABEL}` event {label_event_id} at {head_sha[:12]}: {title}")
+    prompt = _build_review_prompt(pr, head_sha, label_event)
 
     try:
         conv_id = create_conversation(agent_url, api_key, prompt)
@@ -487,8 +435,11 @@ def _process_new_pr(
         print(f"  Error creating conversation for PR #{number}: {exc}")
         return None
 
-    conversations[str(number)] = {
+    reviews[key] = {
         "pr_number": number,
+        "head_sha": head_sha,
+        "trigger_label_event_id": label_event_id,
+        "trigger_label_event_created_at": label_event.get("created_at"),
         "html_url": html_url,
         "status": "active",
         "conversation_id": conv_id,
@@ -498,26 +449,45 @@ def _process_new_pr(
 
     conv_url = f"{openhands_url}/conversations/{conv_id}"
     _post_github_comment(
-        github_token, REPO, number,
-        f"🤖 **OpenHands is reviewing this PR.**\n\n"
-        f"View the conversation: {conv_url}\n\n"
-        f"_This comment was posted by an AI agent (OpenHands)._",
+        github_token,
+        REPO,
+        number,
+        _with_ai_disclosure(
+            "🤖 **OpenHands is reviewing this PR.**\n\n"
+            f"Trigger label: `{TRIGGER_LABEL}`\n"
+            f"Label event: `{label_event_id}` at `{label_event.get('created_at', '?')}`\n"
+            f"Head commit: `{head_sha}`\n"
+            f"View the conversation: {conv_url}"
+        ),
     )
     return conv_id
 
-
 def _check_conversation_completion(
     rec: dict,
+    latest_open_prs: dict[int, dict],
     github_token: str,
     agent_url: str,
     api_key: str,
 ) -> None:
-    """Post the review result and close the conversation record once it finishes."""
     if (time.time() - rec.get("last_activity", 0.0)) < DONE_DEBOUNCE:
         return
 
     conv_id = rec["conversation_id"]
     pr_number = rec["pr_number"]
+    reviewed_sha = rec.get("head_sha", "")
+    current_pr = latest_open_prs.get(pr_number)
+
+    if not current_pr:
+        rec["status"] = "closed"
+        print(f"  PR #{pr_number} closed/merged — skipping result post")
+        return
+
+    current_sha = _head_sha(current_pr)
+    if current_sha and reviewed_sha and current_sha != reviewed_sha:
+        rec["status"] = "stale"
+        rec["stale_reason"] = f"head changed from {reviewed_sha} to {current_sha}"
+        print(f"  PR #{pr_number} advanced to {current_sha[:12]} — suppressing stale review {conv_id}")
+        return
 
     try:
         status = conversation_status(agent_url, api_key, conv_id)
@@ -526,8 +496,7 @@ def _check_conversation_completion(
         return
 
     print(f"  PR #{pr_number} conversation {conv_id} → status={status}")
-
-    if status not in ("idle", "finished", "error", "stuck"):
+    if status not in TERMINAL_STATUSES:
         return
 
     try:
@@ -535,33 +504,26 @@ def _check_conversation_completion(
     except Exception:
         final = ""
 
-    if status in ("error", "stuck"):
-        comment_body = (
-            f"⚠️ **OpenHands PR Reviewer encountered a problem** (status: `{status}`).\n\n"
-            + (f"{final}\n\n" if final else "")
-            + "_This message was posted by an AI agent (OpenHands)._"
+    if status in {"error", "stuck"}:
+        comment_body = _with_ai_disclosure(
+            f"⚠️ **OpenHands PR Reviewer encountered a problem** at commit `{reviewed_sha[:12]}` "
+            f"(status: `{status}`).\n\n{final}".strip()
         )
     else:
-        comment_body = (
-            final if final
-            else (
-                "✅ **OpenHands completed the review.** (No review text was produced.)\n\n"
-                "_This message was posted by an AI agent (OpenHands)._"
-            )
+        comment_body = _with_ai_disclosure(
+            final
+            or f"✅ **OpenHands completed the review for commit `{reviewed_sha[:12]}`.** No review text was produced."
         )
 
     _post_github_comment(github_token, REPO, pr_number, comment_body)
     rec["status"] = "closed"
-    print(f"  Posted review for PR #{pr_number}")
-
+    rec["completed_at"] = time.time()
+    print(f"  Posted review for PR #{pr_number} at {reviewed_sha[:12]}")
 
-# ── Main ───────────────────────────────────────────────────────────────────────
 
 def main() -> str | None:
-    """Run one polling cycle. Returns the last conversation ID created, if any."""
     state_path = _state_file_path()
     state = load_state(state_path)
-
     agent_url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     api_key = _get_env_key()
 
@@ -573,42 +535,62 @@ def main() -> str | None:
     except Exception:
         openhands_url = DEFAULT_OPENHANDS_URL
 
-    conversations: dict = state.get("conversations", {})
-
-    try:
-        open_prs = _list_open_prs(github_token, REPO)
-    except Exception as exc:
-        raise RuntimeError(f"Failed to list open PRs for {REPO}: {exc}") from exc
+    reviews: dict = state.setdefault("reviews", {})
+    prs_state: dict = state.setdefault("prs", {})
 
+    open_prs = _list_open_prs(github_token, REPO)
+    latest_open_prs = {pr["number"]: pr for pr in open_prs}
     print(f"Found {len(open_prs)} open PR(s) in {REPO}")
 
-    open_pr_numbers = {str(pr["number"]) for pr in open_prs}
-
-    last_conversation_id: str | None = None
+    last_conversation_id = None
 
-    # Queue reviews for PRs not yet in state.
     for pr in open_prs:
-        key = str(pr["number"])
-        if key in conversations:
+        number = pr["number"]
+        head_sha = _head_sha(pr)
+        label_present = _has_trigger_label(pr)
+        prs_state[str(number)] = {
+            "head_sha": head_sha,
+            "label_present": label_present,
+            "labels": _labels(pr),
+            "last_seen": time.time(),
+        }
+
+        if not label_present:
             continue
-        conv_id = _process_new_pr(
-            github_token, agent_url, api_key, openhands_url, pr, conversations,
-        )
+        if not head_sha:
+            print(f"  PR #{number} has no head SHA; skipping")
+            continue
+
+        fresh_pr = _get_pr(github_token, REPO, number)
+        fresh_head_sha = _head_sha(fresh_pr)
+        if fresh_head_sha != head_sha:
+            print(f"  PR #{number} head changed during poll ({head_sha[:12]} → {fresh_head_sha[:12]}); using latest PR metadata")
+        if not _has_trigger_label(fresh_pr):
+            print(f"  PR #{number} lost `{TRIGGER_LABEL}` during poll; skipping")
+            continue
+
+        label_event = _latest_trigger_label_event(github_token, REPO, number)
+        if not label_event:
+            print(f"  PR #{number} has `{TRIGGER_LABEL}` but no matching labeled event; skipping")
+            continue
+
+        key = _review_key(number, label_event["id"])
+        if key in reviews:
+            print(f"  PR #{number} label event {label_event['id']} already tracked ({reviews[key].get('status')})")
+            continue
+
+        conv_id = _process_review_request(github_token, agent_url, api_key, openhands_url, fresh_pr, label_event, reviews)
         if conv_id:
             last_conversation_id = conv_id
 
-    # Check active conversations for completion.
-    for key, rec in list(conversations.items()):
+    for rec in list(reviews.values()):
         if rec.get("status") != "active":
             continue
-        if key not in open_pr_numbers:
-            # PR was closed/merged before review completed — mark closed silently.
-            rec["status"] = "closed"
-            print(f"  PR #{rec.get('pr_number')} closed/merged — skipping result post")
-            continue
-        _check_conversation_completion(rec, github_token, agent_url, api_key)
+        _check_conversation_completion(rec, latest_open_prs, github_token, agent_url, api_key)
 
-    state["conversations"] = conversations
+    state["repo"] = REPO
+    state["trigger_label"] = TRIGGER_LABEL
+    state["updated_at"] = time.time()
     save_state(state_path, state)
     print(f"State saved → {state_path}")
     return last_conversation_id
@@ -620,6 +602,7 @@ if __name__ == "__main__":
         fire_callback("COMPLETED", conversation_id=conversation_id)
     except Exception as exc:
         import traceback
+
         traceback.print_exc()
         fire_callback("FAILED", str(exc))
         sys.exit(1)