Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

151 KB
Raw Blame
#!/usr/bin/env python3
"""Wait until a GitHub pull request or repository receives new PR activity."""

from __future__ import annotations

import argparse
import hashlib
import json
import math
import os
import re
import sys
import tempfile
import time
import urllib.parse
from contextlib import contextmanager
from datetime import datetime, timezone
from functools import partial
from pathlib import Path
from typing import Any, Iterator, NamedTuple

try:  # POSIX only, which is every platform `vibe` runs the waiter on.
    import fcntl
except ImportError:  # pragma: no cover - Windows has no flock
    fcntl = None  # type: ignore[assignment]

SCRIPT_DIR = Path(__file__).resolve().parent
if str(SCRIPT_DIR) not in sys.path:
    sys.path.insert(0, str(SCRIPT_DIR))

from _github_wait_common import (  # noqa: E402
    filter_new,
    get_authenticated_login,
    get_token,
    github_get,
    github_graphql,
    github_request,
    InitialRequestRetriesExhausted,
    LAST_DELIVERY_ENV,
    later_since,
    list_paginated,
    list_paginated_with_count,
    max_id,
    min_interval_for_unauthenticated,
    REQUEST_TIMEOUT_SECONDS,
    RETRY_EXIT_CODE,
    retry_initial_request,
    requests_per_poll,
    ResponseCache,
    squash,
    WATCH_ID_ENV,
)
from _github_actions_wait import (  # noqa: E402
    DEFAULT_SUCCESS_CONCLUSIONS,
    fetch_workflow_runs,
    normalize_selected_runs,
    render_actions_result,
    select_matching_runs,
)

CODEX_REVIEW_PASS_REACTION_USERS = {
    "chatgpt-codex-connector",
    "chatgpt-codex-connector[bot]",
}
CODEX_REVIEW_PASS_REACTION_CONTENT = "+1"
CODEX_STANDARD_SUMMARY_FOOTER = (
    "<details> <summary>ℹ️ About Codex in GitHub</summary>",
    "<br/>",
    "[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general).",
    "Codex reviews are triggered when you",
    "- Open a pull request for review",
    "- Mark a draft as ready",
    "- Comment \"@codex review\" or \"@codex security review\".",
    "Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.",
    "</details>",
)
# The clean-pass receipt Codex posts as a PR conversation comment. Its verdict line
# ends with a rotating sign-off (":+1:", "Chef's kiss.", "Keep them coming!"), and
# its details footer differs from the summary comment's.
CODEX_RECEIPT_MARKER = "<!-- codex-review-receipt:v1 -->"
CODEX_RECEIPT_FOOTER = (
    "<details> <summary>ℹ️ About Codex in GitHub</summary>",
    "<br/>",
    "[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you",
    "- Open a pull request for review",
    "- Mark a draft as ready",
    "- Comment \"@codex review\".",
    "If Codex has suggestions, it will comment; otherwise it will react with 👍.",
    "Codex can also answer questions or update the PR. Try commenting \"@codex address that feedback\".",
    "</details>",
)
CODEX_SIGN_OFF_MAX_CHARS = 80

# Comments that only drive the review loop rather than report its result. On a
# busy PR these outnumber the real findings, and each one costs a full Agent turn.
# Anchored at BOTH ends: a trigger comment is only the command. "@codex review" is
# noise; "@author fix the timeout handling" is a person asking for work and must
# survive, because suppressing it still advances the cursor and the request would be
# lost for good rather than merely delayed.
DEFAULT_NOISE_COMMENT_PATTERNS = (
    r"^@[\w\[\]-]+\s+(review|fix|rebase|merge)\s*$",
    r"^/[\w-]+\s*$",
)
# Lifecycle transitions worth interrupting for. Draft toggles are usually the
# Agent's own doing, so they are noise in --actionable-only mode.
ACTIONABLE_PR_STATUSES = frozenset({"merged", "closed"})
STATE_FILE_VERSION = 1
# Cursors that cover a REPORTED event, held here instead of committed, next to the
# supervisor's last-delivery stamp as it read at report time. A waiter cannot see its
# own delivery -- the supervisor reads its output only after the process exits -- so
# committing them at report time loses the event whenever the service stops in
# between. A later cycle that reads a different stamp knows the report was delivered
# and promotes them; an unchanged stamp replays the report.
STAGED_KEY = "pending"
STATE_CURSOR_KEYS = (
    "review_cursor",
    "review_comment_cursor",
    "issue_comment_cursor",
    "reaction_cursor",
)
REVIEW_FINGERPRINTS_KEY = "review_fingerprints"
REVIEW_COMMENT_FINGERPRINTS_KEY = "review_comment_fingerprints"
ISSUE_COMMENT_FINGERPRINTS_KEY = "issue_comment_fingerprints"
REVIEW_THREAD_STATES_KEY = "review_thread_states"
PR_SNAPSHOT_KEY = "snapshot"
ACTIONS_SNAPSHOT_KEY = "actions"
ACTIONS_OBSERVED_KEY = "actions_observed"
SUCCESS_BATCH_KEY = "success_batch"
# The last Codex review stall this watch reported (``_codex_review_stall``), and when
# this watch first saw the current head, which no stall of that head may predate.
REVIEW_STALL_KEY = "review_stall_reported"
REVIEW_STALL_HEAD_KEY = "review_stall_head"
CODEX_SUMMARY_MARKER = "<!-- codex-pull-request-review-summary -->"
# A review request is a comment that is the trigger command and nothing else, the same
# anchored shape ``DEFAULT_NOISE_COMMENT_PATTERNS`` treats as a trigger; a sentence that
# merely mentions it is not one.
CODEX_REVIEW_REQUEST = re.compile(r"\s*@codex\s+review\s*", re.IGNORECASE)
# Codex reviews almost always conclude within minutes: over 68 reviews on
# avibe-bot/avibe the median was 3.5 min, p90 15 min and p95 39 min, while a stuck one
# can sit at "running" for hours. Past this, the review is treated as stalled.
DEFAULT_REVIEW_STALL_MINUTES = 30.0
_CODEX_REVIEW_IN_PROGRESS = frozenset({"queued", "pending", "running", "in_progress"})


class PRReport(NamedTuple):
    """One delivery and the observations its pending transaction will commit."""

    output: str | None
    cursors: tuple[int, int, int, int, str]
    pr_state: dict[str, Any]
    actions: dict[str, Any] | None = None
    success_batch: dict[str, Any] | None = None
    failed_actions: bool = False


PR_FINGERPRINT_KEYS = (
    REVIEW_FINGERPRINTS_KEY,
    REVIEW_COMMENT_FINGERPRINTS_KEY,
    ISSUE_COMMENT_FINGERPRINTS_KEY,
)
# A bot review lands as a burst of inline comments plus an envelope. Re-polling a
# few times while the burst is still arriving turns it into one Agent turn instead
# of one turn per fragment that happened to cross a poll boundary.
SETTLE_MAX_ROUNDS = 3
REVIEW_THREADS_QUERY = """
query($owner: String!, $repo: String!, $number: Int!, $endCursor: String) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $number) {
      reviewThreads(first: 100, after: $endCursor) {
        nodes { id isResolved }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
}
"""


class StateFileError(RuntimeError):
    """The requested ``--state-file`` cannot do the job it was asked to do.

    Raised rather than warned about because a forever watch that keeps polling
    without usable cursors loses activity instead of reporting it, and does so
    silently: every fresh cycle re-baselines from the current PR.
    """


class StatePersistenceError(StateFileError):
    """The cursors an explicit ``--state-file`` promised could not be saved."""


class StateFileUnusableError(StateFileError):
    """An existing ``--state-file`` cannot be read, so its cursors are unknown.

    Not recoverable by starting over: re-baselining from the current PR skips
    everything that arrived after the last cursor this file did hold, and then
    overwrites the evidence. The corrupt file has to be removed deliberately.
    """


class StateFileOwnershipError(StateFileError):
    """The state file at this path belongs to a different PR, or a different watch.

    Two watches pointed at one file is a configuration error, not a state to
    recover from: each would read the other's cursors as absent, re-baseline, and
    then overwrite them, so both watches keep missing activity between cycles.
    """


def _format_review(review: dict[str, Any]) -> str:
    review_id = review.get("id")
    author = ((review.get("user") or {}).get("login")) or "unknown"
    state = str(review.get("state") or "commented").lower()
    body = squash(review.get("body") or state)
    url = review.get("html_url") or ""
    return f"- review #{review_id} by {author} ({state})\n  {body}\n  {url}"


def _format_review_comment(comment: dict[str, Any]) -> str:
    comment_id = comment.get("id")
    author = ((comment.get("user") or {}).get("login")) or "unknown"
    path = comment.get("path") or "unknown-path"
    body = squash(comment.get("body"))
    url = comment.get("html_url") or ""
    return f"- review_comment #{comment_id} by {author} on {path}\n  {body}\n  {url}"


def _format_issue_comment(comment: dict[str, Any]) -> str:
    comment_id = comment.get("id")
    author = ((comment.get("user") or {}).get("login")) or "unknown"
    body = squash(comment.get("body"))
    url = comment.get("html_url") or ""
    return f"- issue_comment #{comment_id} by {author}\n  {body}\n  {url}"


def _is_self_authored_comment(comment: dict[str, Any], viewer_login: str | None) -> bool:
    if not viewer_login:
        return False
    author = ((comment.get("user") or {}).get("login")) or ""
    return str(author).casefold() == viewer_login.casefold()


def _compile_ignore_patterns(values: list[str] | None, *, actionable_only: bool) -> list[re.Pattern[str]]:
    patterns = list(DEFAULT_NOISE_COMMENT_PATTERNS) if actionable_only else []
    patterns.extend(values or [])
    return [re.compile(pattern, re.IGNORECASE) for pattern in patterns]


def _normalize_authors(values: list[str] | None) -> set[str]:
    return {value.strip().casefold() for value in (values or []) if value.strip()}


def _is_ignored_author(item: dict[str, Any], ignored_authors: set[str]) -> bool:
    if not ignored_authors:
        return False
    author = ((item.get("user") or {}).get("login")) or ""
    return str(author).casefold() in ignored_authors


def _matches_ignored_pattern(item: dict[str, Any], patterns: list[re.Pattern[str]]) -> bool:
    if not patterns:
        return False
    text = squash(item.get("body"), limit=1000)
    if not text:
        return False
    return any(pattern.search(text) for pattern in patterns)


def _is_actionable_review(review: dict[str, Any]) -> bool:
    """A review carries a verdict, or a body worth reading.

    A bodyless ``COMMENTED`` review is the envelope GitHub wraps around inline
    comments; those comments are reported on their own, so the envelope adds a
    turn and no information.
    """

    state = str(review.get("state") or "").lower()
    if state in {"changes_requested", "approved", "dismissed"}:
        return True
    return bool(squash(review.get("body")))


def _keep_item(
    item: dict[str, Any],
    *,
    ignored_authors: set[str],
    ignore_patterns: list[re.Pattern[str]],
) -> bool:
    return not _is_ignored_author(item, ignored_authors) and not _matches_ignored_pattern(item, ignore_patterns)


def _visible_activity_items(
    items: list[dict[str, Any]],
    *,
    viewer_login: str | None,
    ignore_self_comments: bool,
    ignored_authors: set[str],
    ignore_patterns: list[re.Pattern[str]],
) -> list[dict[str, Any]]:
    kept = (
        items
        if not ignore_self_comments
        else [item for item in items if not _is_self_authored_comment(item, viewer_login)]
    )
    return [
        item
        for item in kept
        if _keep_item(item, ignored_authors=ignored_authors, ignore_patterns=ignore_patterns)
    ]


def _is_codex_pass_reaction(reaction: dict[str, Any]) -> bool:
    author = ((reaction.get("user") or {}).get("login")) or ""
    content = str(reaction.get("content") or "")
    return author in CODEX_REVIEW_PASS_REACTION_USERS and content == CODEX_REVIEW_PASS_REACTION_CONTENT


def _is_codex_item(item: dict[str, Any]) -> bool:
    author = item.get("author") or ((item.get("user") or {}).get("login"))
    return author in CODEX_REVIEW_PASS_REACTION_USERS


def _has_codex_problem_text(body: str) -> bool:
    return bool(re.search(
        r"\b(errors?|failed|failures?|something went wrong|changes requested|found issues|needs? changes|P[0-3])\b",
        body, re.IGNORECASE,
    ))


def _codex_summary_cells(line: str) -> list[str] | None:
    stripped = line.strip()
    if not stripped.startswith("|") or not stripped.endswith("|"):
        return None
    cells = stripped.split("|")
    return cells if len(cells) == 6 else None


def _is_codex_summary_table_line(line: str) -> bool:
    return _codex_summary_cells(line) is not None


def _is_codex_summary_separator(line: str) -> bool:
    cells = _codex_summary_cells(line)
    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", cell.strip()) for cell in cells[1:-1])


def _is_codex_summary_review_row(line: str) -> bool:
    cells = _codex_summary_cells(line)
    if cells is None:
        return False
    label = re.sub(r"^[^\w]+", "", cells[1].strip()).replace("*", "").strip()
    return (
        label in {"Code Review", "Security Review"}
        and bool(cells[2].strip())
        and re.fullmatch(r"`[0-9a-f]{7,40}`", cells[3].strip(), re.IGNORECASE) is not None
        and bool(cells[4].strip())
    )


def _is_codex_summary_state_line(line: str) -> bool:
    match = re.fullmatch(r"<!-- codex-review-state:v1 (.+) -->", line.strip())
    if not match:
        return False
    try:
        state = json.loads(match.group(1))
    except json.JSONDecodeError:
        return False
    return isinstance(state, dict)


def _is_codex_summary_shape(body: str) -> bool:
    """Require the recognized progress table to be the whole known summary shape."""

    lines = body.splitlines()
    table_start = next(
        (
            index for index, line in enumerate(lines)
            if _is_codex_summary_table_line(line)
            and (cells := line.strip().split("|"))[1].strip() == "Review"
            and cells[2].strip() == "Status"
        ),
        None,
    )
    if table_start is None:
        return False

    allowed_prefix = {
        "<!-- codex-pull-request-review-summary -->",
        "## Codex Review Summary",
        "This comment shows the latest Codex review activity on this pull request.",
    }
    if any(
        line.strip()
        and line.strip() not in allowed_prefix
        and not _is_codex_summary_state_line(line)
        for line in lines[:table_start]
    ):
        return False

    table_end = table_start
    while table_end + 1 < len(lines) and _is_codex_summary_table_line(lines[table_end + 1]):
        table_end += 1
    table_lines = lines[table_start:table_end + 1]
    if (
        len(table_lines) < 3
        or not _is_codex_summary_separator(table_lines[1])
        or not all(_is_codex_summary_review_row(line) for line in table_lines[2:])
    ):
        return False
    suffix = [line.strip() for line in lines[table_end + 1:] if line.strip()]
    if not suffix:
        return True
    standard_footer = "\n".join(CODEX_STANDARD_SUMMARY_FOOTER)
    return "\n".join(suffix) in {
        standard_footer,
        standard_footer.replace(
            "\nCodex reviews are triggered when you", " Reviews are triggered when you", 1,
        ),
    }


def _is_codex_sign_off(text: str) -> bool:
    """A short plain-text sign-off, never markup or anything that reads as a problem."""

    return (
        len(text) <= CODEX_SIGN_OFF_MAX_CHARS
        and not _has_codex_problem_text(text)
        and re.search(r"[`\[\]<>#|]|https?:", text) is None
    )


def _codex_clean_pass_body_sha(body: str) -> str | None:
    lines = [line.strip() for line in body.splitlines() if line.strip()]
    if lines and lines[0] == CODEX_RECEIPT_MARKER:
        lines = lines[1:]
    verdict = re.fullmatch(
        r"Codex Review:\s*Didn['’]t find any major issues\.?(?:\s+(.+))?",
        lines[0] if lines else "", re.IGNORECASE,
    )
    if not verdict or (verdict.group(1) is not None and not _is_codex_sign_off(verdict.group(1))):
        return None
    if len(lines) == 1:
        return ""
    if len(lines) != 2 and tuple(lines[2:]) != CODEX_RECEIPT_FOOTER:
        return None
    match = re.fullmatch(
        r"\*{0,2}Reviewed commit\*{0,2}:\*{0,2}\s*`([0-9a-f]{7,40})`",
        lines[1], re.IGNORECASE,
    )
    return match.group(1) if match else None


def _is_codex_summary_pass(item: dict[str, Any], head_sha: str) -> bool:
    """Codex's review summary in its known shape, whose state line names ``head_sha`` in full as reviewed with no
    findings, and every other review it lists finished without one: the pass ``pr-delivery-loop`` reads.

    The summary is edited in place, so this is a verdict about the commit it names, wherever its row was first seen.
    """

    if not _is_codex_progress(item):
        return False
    state = _codex_summary_state(str(item.get("body") or ""))
    code_review = state.get("code_review") if state is not None else None
    if not isinstance(code_review, dict) or str(code_review.get("commit_sha") or "").casefold() != head_sha.casefold():
        return False
    others = [review for review in state.values() if isinstance(review, dict) and review.get("status") is not None]
    return all(
        str(review.get("status")).casefold() == "completed" and review.get("has_any_findings") is False
        for review in (code_review, *others)
    )


def _is_codex_clean_pass(item: dict[str, Any], head_sha: str) -> bool:
    """Recognize a success shape, not a substitute for the Agent's review gate."""

    if not head_sha or not _is_codex_item(item):
        return False
    if str(item.get("state") or "").lower() in {"changes_requested", "dismissed"}:
        return False
    if _is_codex_summary_pass(item, head_sha):
        return True
    body_sha = _codex_clean_pass_body_sha(str(item.get("body") or ""))
    if body_sha is None:
        return False
    item_sha = item.get("commit_id")
    item_sha = item_sha if isinstance(item_sha, str) else ""
    if item_sha and body_sha and not (
        item_sha.casefold().startswith(body_sha.casefold())
        or body_sha.casefold().startswith(item_sha.casefold())
    ):
        return False
    reviewed = item_sha or body_sha
    return len(reviewed) >= 7 and head_sha.casefold().startswith(reviewed.casefold())


def _awaits_review_judgment(state: dict[str, Any], batch: dict[str, Any]) -> bool:
    """The latest Codex verdict is neither a recognized pass nor a recognized problem."""

    outcome = batch.get("outcome")
    if batch.get("review") is not None or not outcome or outcome["kind"] not in {"reviews", "issue_comments"}:
        return False
    item = next((item for item in state[outcome["kind"]] if item.get("id") == outcome["id"]), None)
    return (
        item is not None
        and str(item.get("state") or "").lower() not in {"changes_requested", "dismissed"}
        and not _has_codex_problem_text(str(item.get("body") or ""))
    )


def _is_codex_progress(item: dict[str, Any]) -> bool:
    body = str(item.get("body") or "")
    if (
        not _is_codex_item(item)
        or "<!-- codex-pull-request-review-summary -->" not in body
        or _has_codex_problem_text(body)
        or not _is_codex_summary_shape(body)
    ):
        return False
    statuses = [
        cells[2].strip() for line in body.splitlines()
        if len(cells := line.strip().split("|")) >= 5 and cells[0] == ""
        and cells[2].strip() != "Status" and cells[2].strip(": -")
    ]
    return bool(statuses) and all(
        re.fullmatch(
            r"[\W_]*(queued|pending|running|in progress|completed)[\W_]*"
            r"(?:since\s+)?(?:<relative-time\b[^>]*>[^<]*</relative-time>\s*)?",
            status, re.IGNORECASE,
        )
        for status in statuses
    )


def _utc_now() -> datetime:
    return datetime.now(timezone.utc)


def _github_time(value: Any) -> datetime | None:
    try:
        parsed = datetime.fromisoformat(str(value or "").replace("Z", "+00:00"))
    except ValueError:
        return None
    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=timezone.utc)


def _codex_summary_state(body: str) -> dict[str, Any] | None:
    """A Codex summary's machine-readable state line, as an object."""

    for line in body.splitlines():
        match = re.fullmatch(r"<!-- codex-review-state:v1 (.+) -->", line.strip())
        if not match:
            continue
        try:
            state = json.loads(match.group(1))
        except json.JSONDecodeError:
            return None
        return state if isinstance(state, dict) else None
    return None


def _codex_summary_code_review(body: str) -> dict[str, Any] | None:
    """The ``code_review`` object of a Codex summary's machine-readable state line."""

    state = _codex_summary_state(body)
    code_review = state.get("code_review") if state is not None else None
    return code_review if isinstance(code_review, dict) else None


def _codex_review_stall(
    state: dict[str, Any],
    *,
    repo: str,
    stall_seconds: float,
    now: datetime,
    head_seen_at: datetime,
) -> tuple[str, str] | None:
    """A Codex review of the current head stuck at "running": (key, report), else ``None``.

    The one shape observed live: Codex's summary names the current head as being
    reviewed, and no Codex answer naming that head (a review of its commit, or a
    verdict comment for it) came since. It counts from the latest of the summary's
    last update, a later standalone ``@codex review`` request (a re-request restarts
    it, and one left unanswered is caught a window later), and when this watch saw
    the head become reviewable (``head_seen_at``: pushed, reopened, or marked ready).
    A head Codex never started on is the pickup check ``pr-delivery-loop`` already
    owns after each push. ``key`` changes every further ``stall_seconds`` the stall
    lasts, so a still-stuck review is reported again rather than once and forgotten.
    """

    pr = state.get("pull_request")
    head = _current_pr_head_sha(pr)
    # Only an open, ready PR is expected to be reviewed through; a draft or a closed
    # PR restarts the clock when it becomes one (``head_seen_at``).
    if stall_seconds <= 0 or not head or _current_pr_status(pr) != "open":
        return None
    summary_at: datetime | None = None
    code_review: dict[str, Any] = {}
    request_at: datetime | None = None
    answered_at: datetime | None = None
    for comment in state.get("issue_comments") or []:
        body = str(comment.get("body") or "")
        stamp = _github_time(comment.get("updated_at") or comment.get("created_at"))
        if stamp is None:
            continue
        if _is_codex_item(comment):
            parsed = _codex_summary_code_review(body) if CODEX_SUMMARY_MARKER in body else None
            if parsed is not None:
                if summary_at is None or stamp > summary_at:
                    summary_at, code_review = stamp, parsed
            elif _is_codex_clean_pass(comment, head) and (answered_at is None or stamp > answered_at):
                answered_at = stamp
        elif CODEX_REVIEW_REQUEST.fullmatch(body):
            created = _github_time(comment.get("created_at")) or stamp
            request_at = created if request_at is None or created > request_at else request_at
    for review in state.get("reviews") or []:
        stamp = _github_time(review.get("submitted_at"))
        if (
            stamp is not None
            and _is_codex_item(review)
            and str(review.get("commit_id") or "").casefold() == head.casefold()
            and (answered_at is None or stamp > answered_at)
        ):
            answered_at = stamp
    if (
        summary_at is None
        or str(code_review.get("commit_sha") or "").casefold() != head.casefold()
        or str(code_review.get("status") or "").casefold() not in _CODEX_REVIEW_IN_PROGRESS
        or (answered_at is not None and answered_at >= summary_at)
    ):
        return None
    since = max(summary_at, request_at or summary_at, head_seen_at)
    shape = "has shown the review of this head as running"
    elapsed = (now - since).total_seconds()
    if elapsed < stall_seconds:
        return None
    rounds = int(elapsed // stall_seconds)
    number = (pr or {}).get("number")
    report = (
        f"Codex review stalled for {repo}#{number}@{head[:12]}\n"
        f"- Codex {shape} for {int(elapsed // 60)} min (since {since.strftime('%Y-%m-%dT%H:%M:%SZ')}).\n"
        "  Re-request it with `@codex review` and verify that Codex reacts to that comment.\n"
        f"  {(pr or {}).get('html_url') or ''}".rstrip()
    )
    return f"{head.casefold()}:{since.isoformat()}:{rounds}", report


def _quiet_success_snapshot(value: dict[str, Any], *, defer_reactions: bool) -> dict[str, Any]:
    """Remove only recognized success/progress payloads from the wake comparison."""

    result = dict(value)
    head = str((value.get("pull_request") or {}).get("head_sha") or "")
    for kind in ("reviews", "issue_comments"):
        result[kind] = {
            key: item for key, item in value.get(kind, {}).items()
            if not (_is_codex_clean_pass(item, head) or _is_codex_progress(item))
        }
    if defer_reactions:
        result["reactions"] = {}
    return result


def _format_reaction(reaction: dict[str, Any]) -> str:
    reaction_id = reaction.get("id")
    author = ((reaction.get("user") or {}).get("login")) or "unknown"
    content = str(reaction.get("content") or "")
    created_at = str(reaction.get("created_at") or "")
    return (
        f"- pr_reaction #{reaction_id} by {author} ({content})\n"
        f"  Codex review completed without comments and reacted on the PR body at {created_at}."
    )


def _current_pr_status(pr: dict[str, Any] | None) -> str:
    if not isinstance(pr, dict):
        return "unknown"
    if pr.get("merged_at"):
        return "merged"
    state = str(pr.get("state") or "").lower()
    if state == "closed":
        return "closed"
    if pr.get("draft") is True:
        return "draft"
    if state == "open":
        return state
    return state or "unknown"


def _describe_pr_status_change(previous_status: str, current_status: str) -> str:
    if previous_status == "draft" and current_status == "open":
        return "Pull request is ready for review."
    if previous_status == "open" and current_status == "draft":
        return "Pull request was converted to draft."
    if current_status == "merged":
        return "Pull request was merged."
    if current_status == "closed":
        return "Pull request was closed without merge."
    if current_status == "open":
        return "Pull request was reopened."
    return f"Pull request status changed from {previous_status} to {current_status}."


def _format_pr_status_event(pr: dict[str, Any], previous_status: str, current_status: str) -> str:
    pr_number = pr.get("number")
    url = pr.get("html_url") or ""
    return (
        f"- pr_status #{pr_number} {previous_status} -> {current_status}\n"
        f"  {_describe_pr_status_change(previous_status, current_status)}\n"
        f"  {url}"
    )


def _current_pr_head_sha(pr: dict[str, Any] | None) -> str:
    if not isinstance(pr, dict):
        return ""
    head = pr.get("head")
    if not isinstance(head, dict):
        return ""
    value = head.get("sha")
    return value if isinstance(value, str) else ""


def _format_pr_head_event(pr: dict[str, Any], previous_sha: str, current_sha: str) -> str:
    pr_number = pr.get("number")
    url = pr.get("html_url") or ""
    return (
        f"- pr_head #{pr_number} {previous_sha[:12]} -> {current_sha[:12]}\n"
        "  Pull request head changed; start a fresh exact-head review cycle.\n"
        f"  {url}"
    )


def _format_review_thread_event(
    pr: dict[str, Any],
    thread_id: str,
    previous_resolved: bool | None,
    current_resolved: bool | None,
) -> str:
    url = pr.get("html_url") or ""

    def _label(value: bool | None) -> str:
        if value is None:
            return "absent"
        return "resolved" if value else "unresolved"

    return (
        f"- review_thread {thread_id} {_label(previous_resolved)} -> {_label(current_resolved)}\n"
        "  Review thread state changed; re-evaluate unresolved threads across the entire PR.\n"
        f"  {url}"
    )


def _format_pull_request(pr: dict[str, Any]) -> str:
    pr_number = pr.get("number")
    author = ((pr.get("user") or {}).get("login")) or "unknown"
    state = str(pr.get("state") or "open").lower()
    title = squash(pr.get("title") or "")
    url = pr.get("html_url") or ""
    return f"- pull_request #{pr_number} by {author} ({state})\n  {title}\n  {url}"


def _item_fingerprint(item: dict[str, Any]) -> str:
    mutable = {
        key: item.get(key)
        for key in (
            "id",
            "body",
            "state",
            "submitted_at",
            "commit_id",
            "path",
            "line",
            "original_line",
            "side",
            "start_line",
            "start_side",
            "user",
            "updated_at",
        )
    }
    encoded = json.dumps(mutable, sort_keys=True, separators=(",", ":"), default=str)
    return hashlib.sha256(encoded.encode()).hexdigest()


def _changed_items(
    items: list[dict[str, Any]],
    since_id: int,
    fingerprints: dict[str, str],
) -> list[dict[str, Any]]:
    """Return new or edited items while advancing fingerprints for this fetch."""

    changed: dict[int, dict[str, Any]] = {}
    for item in items:
        item_id = item.get("id")
        if not isinstance(item_id, int):
            continue
        key = str(item_id)
        fingerprint = _item_fingerprint(item)
        # A legacy cursor has no content baseline. Seed it silently; otherwise every
        # pre-existing item would look edited on the first run after the migration.
        previous = fingerprints.get(key)
        if item_id > since_id or (previous is not None and previous != fingerprint):
            changed[item_id] = item
        fingerprints[key] = fingerprint
    return sorted(
        changed.values(),
        key=lambda item: (str(item.get("updated_at") or item.get("created_at") or ""), int(item["id"])),
    )


def _fingerprint_map(items: list[dict[str, Any]]) -> dict[str, str]:
    return {
        str(item["id"]): _item_fingerprint(item)
        for item in items
        if isinstance(item.get("id"), int) and not isinstance(item.get("id"), bool)
    }


def _review_thread_state_map(threads: list[dict[str, Any]]) -> dict[str, bool]:
    return {
        str(thread["id"]): bool(thread["isResolved"])
        for thread in threads
        if isinstance(thread.get("id"), str) and isinstance(thread.get("isResolved"), bool)
    }


def _normalized_item_map(
    items: list[dict[str, Any]],
    *,
    fields: tuple[str, ...],
) -> dict[str, dict[str, Any]]:
    normalized: dict[str, dict[str, Any]] = {}
    for item in items:
        item_id = item.get("id")
        if not isinstance(item_id, (int, str)) or isinstance(item_id, bool):
            continue
        author = ((item.get("user") or {}).get("login")) or ""
        normalized[str(item_id)] = {
            "author": str(author),
            **{field: item.get(field) for field in fields},
        }
    return normalized


def _normalized_pr_snapshot(
    state: dict[str, Any],
    *,
    viewer_login: str | None = None,
    ignore_self_comments: bool = True,
    actionable_only: bool = False,
    ignored_authors: set[str] | None = None,
    ignore_patterns: list[re.Pattern[str]] | None = None,
    committed_snapshot: dict[str, Any] | None = None,
    review_threads_available: bool = True,
) -> dict[str, Any]:
    """Return complete gate-relevant state without volatile timestamps."""

    ignored_authors = ignored_authors or set()
    ignore_patterns = ignore_patterns or []

    def _visible(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
        return _visible_activity_items(
            items,
            viewer_login=viewer_login,
            ignore_self_comments=ignore_self_comments,
            ignored_authors=ignored_authors,
            ignore_patterns=ignore_patterns,
        )

    reviews = _visible(state["reviews"])
    if actionable_only:
        reviews = [review for review in reviews if _is_actionable_review(review)]
    review_comments = _visible(state["review_comments"])
    issue_comments = _visible(state["issue_comments"])
    reactions = [reaction for reaction in state["reactions"] if _is_codex_pass_reaction(reaction)]
    normalized_reactions = _normalized_item_map(reactions, fields=("content",))
    for reaction in normalized_reactions.values():
        reaction["author"] = "chatgpt-codex-connector"

    if review_threads_available:
        raw_threads = state.get("review_threads")
        review_threads = _review_thread_state_map(raw_threads if isinstance(raw_threads, list) else [])
    else:
        saved_threads = (committed_snapshot or {}).get("review_threads")
        review_threads = saved_threads if isinstance(saved_threads, dict) else {}

    pr_status = _current_pr_status(state.get("pull_request"))
    if actionable_only and pr_status not in ACTIONABLE_PR_STATUSES:
        pr_status = "open"
    return {
        "pull_request": {
            "status": pr_status,
            "head_sha": _current_pr_head_sha(state.get("pull_request")),
        },
        "reviews": _normalized_item_map(reviews, fields=("state", "body", "commit_id")),
        "review_comments": _normalized_item_map(review_comments, fields=("body", "path")),
        "issue_comments": _normalized_item_map(issue_comments, fields=("body",)),
        "reactions": normalized_reactions,
        "review_threads": review_threads,
    }


def _review_observation(kind: str, item: dict[str, Any]) -> dict[str, Any]:
    fields = {
        "reviews": ("state", "body", "commit_id"),
        "issue_comments": ("body",),
        "review_comments": ("body", "path"),
        "reactions": ("content",),
    }[kind]
    normalized = _normalized_item_map([item], fields=fields)
    if _is_codex_item(item):
        for value in normalized.values():
            value["author"] = "chatgpt-codex-connector"
    encoded = json.dumps(normalized, sort_keys=True, separators=(",", ":"))
    return {
        "kind": kind, "id": item["id"],
        "fingerprint": hashlib.sha256(encoded.encode()).hexdigest(),
        "order": [str(item.get("updated_at") or item.get("submitted_at") or item.get("created_at") or ""),
                  int(item["id"])],
    }


def _select_review_outcome(
    outcomes: list[tuple[dict[str, Any], bool]],
) -> tuple[dict[str, Any], bool]:
    # IDs break equivalent ties, never conflicting updates within one clock tick.
    return max(
        outcomes,
        key=lambda pair: (pair[0]["order"][0], not pair[1], pair[0]["id"]),
    )


def _should_adopt_review_outcome(
    outcome: dict[str, Any],
    clean: bool,
    last_outcome: dict[str, Any] | None,
    batch: dict[str, Any],
) -> bool:
    if last_outcome is None:
        return True
    timestamp, last_timestamp = outcome["order"][0], last_outcome["order"][0]
    if timestamp != last_timestamp:
        return timestamp > last_timestamp
    if outcome["kind"] == last_outcome["kind"] and outcome["id"] == last_outcome["id"]:
        return outcome["fingerprint"] != last_outcome["fingerprint"]
    return not clean or batch.get("review") is not None


def _coalesced_review_state(
    state: dict[str, Any],
    previous: dict[str, Any] | None,
    baseline: dict[str, Any] | None,
    *,
    reaction_cursor: int = 0,
    initialize: bool = False,
) -> tuple[dict[str, Any], bool]:
    """Advance monotonic observations, independently of notification progress.

    Retain the latest bot outcome even when its response row disappears. Retain
    reaction IDs across head epochs so an old reaction cannot become a new pass.
    """

    head = _current_pr_head_sha(state.get("pull_request"))
    previous = previous or {}
    same_head = str(previous.get("head_sha") or "").casefold() == head.casefold()
    reaction_floor = max(
        reaction_cursor, previous.get("reaction_seen", 0),
        max((int(key) for key in (baseline or {}).get("reactions", {})), default=0),
    )
    batch = dict(previous) if same_head else {
        "head_sha": head, "review": None, "outcome": None, "notified": None,
    }
    batch["reaction_seen"] = max(reaction_floor, max_id(state["reactions"]))
    seen = dict(batch.get("review_seen") or {})
    batch["review_seen"] = seen
    evidence = batch.get("review")
    revoked = False
    if evidence:
        item = next((item for item in state[evidence["kind"]] if item.get("id") == evidence["id"]), None)
        if item is None or _review_observation(evidence["kind"], item)["fingerprint"] != evidence["fingerprint"]:
            batch.update(review=None, notified=None)
            revoked = True

    outcomes: list[tuple[dict[str, Any], bool]] = []
    for kind, fields in (
        ("reviews", ("state", "body", "commit_id")),
        ("issue_comments", ("body",)),
        ("review_comments", ("body", "path")),
    ):
        old_items = (baseline or {}).get(kind, {})
        for item in state[kind]:
            # A summary is progress, except the state that names this head as passed.
            if not _is_codex_item(item) or (_is_codex_progress(item) and not _is_codex_clean_pass(item, head)):
                continue
            if kind == "reviews" and not _is_actionable_review(item):
                continue
            normalized = _normalized_item_map([item], fields=fields)
            observation = _review_observation(kind, item)
            key = f"{kind}/{item['id']}"
            previous_fingerprint = seen.get(key)
            changed = (
                previous_fingerprint != observation["fingerprint"] if previous_fingerprint is not None
                else old_items.get(str(item.get("id"))) != normalized.get(str(item.get("id")))
            )
            seen[key] = observation["fingerprint"]
            # A replay scans old rows without renewing already-seen verdicts.
            if changed or (initialize and previous_fingerprint is None):
                clean = kind != "review_comments" and _is_codex_clean_pass(item, head)
                outcomes.append((observation, clean))

    if not initialize and same_head:
        outcomes.extend(
            (_review_observation("reactions", item), True) for item in state["reactions"]
            if _is_codex_pass_reaction(item) and int(item["id"]) > reaction_floor
        )
    if outcomes:
        outcome, clean = _select_review_outcome(outcomes)
        last_outcome = batch.get("outcome")
        if _should_adopt_review_outcome(outcome, clean, last_outcome, batch):
            batch["outcome"] = outcome
            batch["review"] = outcome if clean else None
            if not clean:
                batch["notified"] = None
    return batch, revoked and batch.get("review") is None


def _review_thread_state_changes(
    current: dict[str, bool],
    baseline: dict[str, bool],
) -> list[tuple[str, bool | None, bool | None]]:
    return [
        (thread_id, baseline.get(thread_id), current.get(thread_id))
        for thread_id in sorted(current.keys() | baseline.keys())
        if baseline.get(thread_id) != current.get(thread_id)
    ]


def _fetch_review_threads(
    repo: str,
    pr_number: int,
    token: str | None,
) -> tuple[list[dict[str, Any]], int]:
    if token is None:
        return [], 0
    try:
        owner, repo_name = repo.split("/", 1)
    except ValueError as err:
        raise RuntimeError(f"Invalid repository name: {repo}") from err

    threads: list[dict[str, Any]] = []
    end_cursor: str | None = None
    request_count = 0
    while True:
        data = github_graphql(
            REVIEW_THREADS_QUERY,
            {
                "owner": owner,
                "repo": repo_name,
                "number": pr_number,
                "endCursor": end_cursor,
            },
            token,
        )
        request_count += 1
        repository = data.get("repository")
        pull_request = repository.get("pullRequest") if isinstance(repository, dict) else None
        connection = pull_request.get("reviewThreads") if isinstance(pull_request, dict) else None
        if not isinstance(connection, dict):
            raise RuntimeError("GitHub GraphQL response has no reviewThreads connection")
        nodes = connection.get("nodes")
        if not isinstance(nodes, list):
            raise RuntimeError("GitHub GraphQL reviewThreads response has no nodes list")
        threads.extend(node for node in nodes if isinstance(node, dict))
        page_info = connection.get("pageInfo")
        if not isinstance(page_info, dict) or page_info.get("hasNextPage") is not True:
            break
        next_cursor = page_info.get("endCursor")
        if not isinstance(next_cursor, str) or not next_cursor:
            raise RuntimeError("GitHub GraphQL reviewThreads page has no endCursor")
        end_cursor = next_cursor
    return threads, request_count


def _fetch_state(
    repo: str,
    pr_number: int,
    token: str | None,
    *,
    cache: ResponseCache | None = None,
    review_comment_since: str | None = None,
    issue_comment_since: str | None = None,
    ci_sha: str | None = None,
    ci_branch: str | None = None,
    ci_workflows: list[str] | None = None,
    ci_max_pages: int = 3,
) -> tuple[dict[str, list[dict[str, Any]]], int]:
    encoded_repo = urllib.parse.quote(repo, safe="/")
    base_url = f"https://api.github.com/repos/{encoded_repo}"
    pull_request = github_get(f"{base_url}/pulls/{pr_number}", token, cache=cache)
    # The reviews endpoint ignores sort/direction (verified against api.github.com:
    # direction=desc returns the same ascending ids), so there is no way to page it
    # newest-first and no `since` support either. An unchanged review list stays
    # cheap by revalidating to 304 rather than by fetching less.
    reviews, review_requests = list_paginated_with_count(
        f"{base_url}/pulls/{pr_number}/reviews",
        token,
        cache=cache,
    )
    # PR state is a mutable snapshot: complete collections are required to detect
    # edits and removals. The legacy since arguments remain accepted so existing
    # callers do not break, but they intentionally do not narrow these requests.
    review_comments, review_comment_requests = list_paginated_with_count(
        f"{base_url}/pulls/{pr_number}/comments",
        token,
        cache=cache,
    )
    issue_comments, issue_comment_requests = list_paginated_with_count(
        f"{base_url}/issues/{pr_number}/comments",
        token,
        cache=cache,
    )
    # Only the Codex pass reaction is ever reported, and this endpoint filters by
    # content server-side, so every other reaction on the PR body stays home.
    reactions, reaction_requests = list_paginated_with_count(
        f"{base_url}/issues/{pr_number}/reactions"
        f"?content={urllib.parse.quote(CODEX_REVIEW_PASS_REACTION_CONTENT)}",
        token,
        cache=cache,
    )
    review_threads, review_thread_requests = _fetch_review_threads(repo, pr_number, token)
    actions: list[dict[str, Any]] = []
    action_requests = 0
    selected_ci_sha = ci_sha or (_current_pr_head_sha(pull_request) if ci_workflows else None)
    if ci_workflows and not selected_ci_sha:
        raise RuntimeError(
            "GitHub PR response has no head SHA for current-head CI monitoring"
        )
    if selected_ci_sha and ci_workflows:
        actions, action_requests = fetch_workflow_runs(
            repo,
            token,
            branch=ci_branch,
            head_sha=selected_ci_sha,
            max_pages=ci_max_pages,
            cache=cache,
        )
        # Actions are fetched after several independent PR requests. Re-read the
        # mutable PR object after that window so a push cannot pair an old head with
        # a terminal result from the exact SHA supplied by the caller.
        pull_request = github_get(f"{base_url}/pulls/{pr_number}", token, cache=cache)
        requests_after_actions = 1
    else:
        requests_after_actions = 0
    if (
        selected_ci_sha
        and ci_workflows
        and _current_pr_head_sha(pull_request).casefold() != selected_ci_sha.casefold()
    ):
        # The PR moved while this snapshot was assembled. The caller will report the
        # head transition; never render Actions fetched for the previous head.
        actions = []
    return (
        {
            "pull_request": pull_request,
            "reviews": reviews,
            "review_comments": review_comments,
            "issue_comments": issue_comments,
            "reactions": reactions,
            "review_threads": review_threads,
            "actions": actions,
        },
        (
            1
            + review_requests
            + review_comment_requests
            + issue_comment_requests
            + reaction_requests
            + review_thread_requests
            + action_requests
            + requests_after_actions
        ),
    )


def _fetch_new_pr_state(
    repo: str,
    token: str | None,
    *,
    stop_after_id: int | None = None,
    max_pages: int | None = None,
    cache: ResponseCache | None = None,
) -> tuple[dict[str, list[dict[str, Any]]], int]:
    encoded_repo = urllib.parse.quote(repo, safe="/")
    pull_requests, request_count = list_paginated_with_count(
        f"https://api.github.com/repos/{encoded_repo}/pulls?state=all&sort=created&direction=desc",
        token,
        stop_after_id=stop_after_id,
        max_pages=max_pages,
        cache=cache,
    )
    return {"pull_requests": pull_requests}, request_count


def _render_activity(
    *,
    repo: str,
    pr_number: int,
    state: dict[str, list[dict[str, Any]]],
    review_cursor: int,
    review_comment_cursor: int,
    issue_comment_cursor: int,
    reaction_cursor: int,
    pr_status: str,
    event_limit: int,
    previous_head_sha: str | None = None,
    snapshot: dict[str, Any] | None = None,
    review_fingerprints: dict[str, str] | None = None,
    review_comment_fingerprints: dict[str, str] | None = None,
    issue_comment_fingerprints: dict[str, str] | None = None,
    review_thread_states: dict[str, bool] | None = None,
    review_threads_available: bool = True,
    viewer_login: str | None = None,
    ignore_self_comments: bool = True,
    actionable_only: bool = False,
    ignored_authors: set[str] | None = None,
    ignore_patterns: list[re.Pattern[str]] | None = None,
    coalesce_success: bool = False,
) -> tuple[str | None, int, int, int, int, str]:
    ignored_authors = ignored_authors or set()
    ignore_patterns = ignore_patterns or []
    review_fingerprints = {} if review_fingerprints is None else review_fingerprints
    review_comment_fingerprints = (
        {} if review_comment_fingerprints is None else review_comment_fingerprints
    )
    issue_comment_fingerprints = (
        {} if issue_comment_fingerprints is None else issue_comment_fingerprints
    )
    current_snapshot = _normalized_pr_snapshot(
        state,
        viewer_login=viewer_login,
        ignore_self_comments=ignore_self_comments,
        actionable_only=actionable_only,
        ignored_authors=ignored_authors,
        ignore_patterns=ignore_patterns,
        committed_snapshot=snapshot,
        review_threads_available=review_threads_available,
    )
    current_pr_status = _current_pr_status(state.get("pull_request"))
    current_head_sha = _current_pr_head_sha(state.get("pull_request"))
    new_reviews = _changed_items(state["reviews"], review_cursor, review_fingerprints)
    new_review_comments = _changed_items(
        state["review_comments"], review_comment_cursor, review_comment_fingerprints
    )
    new_issue_comments = _changed_items(
        state["issue_comments"], issue_comment_cursor, issue_comment_fingerprints
    )

    def _visible(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
        return _visible_activity_items(
            items,
            viewer_login=viewer_login,
            ignore_self_comments=ignore_self_comments,
            ignored_authors=ignored_authors,
            ignore_patterns=ignore_patterns,
        )

    visible_reviews = _visible(new_reviews)
    if actionable_only:
        visible_reviews = [review for review in visible_reviews if _is_actionable_review(review)]
    visible_review_comments = _visible(new_review_comments)
    visible_issue_comments = _visible(new_issue_comments)
    new_reactions = [
        reaction
        for reaction in filter_new(state["reactions"], reaction_cursor)
        if _is_codex_pass_reaction(reaction)
    ]
    has_pr_status_event = current_pr_status != pr_status
    has_head_event = bool(previous_head_sha and current_head_sha and previous_head_sha != current_head_sha)
    raw_threads = state.get("review_threads")
    current_thread_states = (
        _review_thread_state_map(raw_threads if isinstance(raw_threads, list) else [])
        if review_threads_available
        else dict(review_thread_states or {})
    )
    thread_changes = _review_thread_state_changes(current_thread_states, review_thread_states or {})
    next_review_cursor = max(review_cursor, max_id(state["reviews"]))
    next_review_comment_cursor = max(review_comment_cursor, max_id(state["review_comments"]))
    next_issue_comment_cursor = max(issue_comment_cursor, max_id(state["issue_comments"]))
    next_reaction_cursor = max(reaction_cursor, max_id(state["reactions"]))
    next_pr_status = current_pr_status

    if coalesce_success:
        def quiet(item: dict[str, Any]) -> bool:
            return _is_codex_clean_pass(item, current_head_sha) or _is_codex_progress(item)

        visible_reviews = [item for item in visible_reviews if not quiet(item)]
        visible_issue_comments = [item for item in visible_issue_comments if not quiet(item)]
        defer_reactions = not has_head_event and snapshot is not None
        if defer_reactions:
            new_reactions = []
        current_snapshot = _quiet_success_snapshot(current_snapshot, defer_reactions=defer_reactions)
        if snapshot is not None:
            snapshot = _quiet_success_snapshot(snapshot, defer_reactions=defer_reactions)
    snapshot_changed = snapshot is not None and current_snapshot != snapshot
    if snapshot is not None and not snapshot_changed:
        return (
            None,
            next_review_cursor,
            next_review_comment_cursor,
            next_issue_comment_cursor,
            next_reaction_cursor,
            next_pr_status,
        )
    if snapshot is None and not (
        new_reviews
        or new_review_comments
        or new_issue_comments
        or new_reactions
        or has_pr_status_event
        or has_head_event
        or thread_changes
    ):
        return None, review_cursor, review_comment_cursor, issue_comment_cursor, reaction_cursor, pr_status

    render_pr_status_event = has_pr_status_event and (
        not actionable_only or current_pr_status in ACTIONABLE_PR_STATUSES
    )

    required_events: list[str] = []
    if has_head_event and isinstance(state.get("pull_request"), dict):
        required_events.append(_format_pr_head_event(state["pull_request"], previous_head_sha, current_head_sha))
    if render_pr_status_event and isinstance(state.get("pull_request"), dict):
        required_events.append(_format_pr_status_event(state["pull_request"], pr_status, current_pr_status))
    if isinstance(state.get("pull_request"), dict):
        required_events.extend(
            _format_review_thread_event(state["pull_request"], *change)
            for change in thread_changes
        )
    optional_events = [_format_review(review) for review in visible_reviews]
    optional_events.extend(_format_review_comment(comment) for comment in visible_review_comments)
    optional_events.extend(_format_issue_comment(comment) for comment in visible_issue_comments)

    if not required_events and not optional_events and snapshot_changed:
        required_events.append(
            "- pr_snapshot changed\n"
            "  Gate-relevant PR state changed; re-evaluate the exact head, review verdict, "
            "and all unresolved threads."
        )
    if not required_events and not optional_events and not new_reactions:
        return (
            None,
            next_review_cursor,
            next_review_comment_cursor,
            next_issue_comment_cursor,
            next_reaction_cursor,
            next_pr_status,
        )

    lines = [f"GitHub PR activity detected for {repo}#{pr_number}"]

    visible_limit = max(event_limit, len(required_events), 1)
    visible_optional = optional_events[: max(0, visible_limit - len(required_events))]
    selected_events = [*required_events, *visible_optional]
    for entry in selected_events:
        lines.append(entry)

    total_events = len(required_events) + len(optional_events)
    if total_events > len(selected_events):
        lines.append(f"- {total_events - len(selected_events)} additional event(s) omitted")
    # A Codex +1 is durable pass evidence, not ordinary overflow. Always append it
    # after the bounded optional batch so a busy review cannot hide the gate signal.
    lines.extend(_format_reaction(reaction) for reaction in new_reactions)

    return (
        "\n".join(lines),
        next_review_cursor,
        next_review_comment_cursor,
        next_issue_comment_cursor,
        next_reaction_cursor,
        next_pr_status,
    )


def _render_new_pull_requests(
    *,
    repo: str,
    state: dict[str, list[dict[str, Any]]],
    pr_cursor: int,
    event_limit: int,
) -> tuple[str | None, int]:
    new_pull_requests = filter_new(state["pull_requests"], pr_cursor)
    if not new_pull_requests:
        return None, pr_cursor

    next_pr_cursor = max(pr_cursor, max_id(new_pull_requests))
    lines = [f"GitHub new pull request activity detected for {repo}"]
    rendered_events = [_format_pull_request(pr) for pr in new_pull_requests]

    visible_limit = max(event_limit, 1)
    for entry in rendered_events[:visible_limit]:
        lines.append(entry)

    total_events = len(rendered_events)
    if total_events > visible_limit:
        lines.append(f"- {total_events - visible_limit} additional event(s) omitted")

    return "\n".join(lines), next_pr_cursor


def _write_cursor_output(
    path: str | None,
    *,
    review_cursor: int,
    review_comment_cursor: int,
    issue_comment_cursor: int,
    reaction_cursor: int,
    pr_status: str,
) -> None:
    if not path:
        return

    payload = {
        "review_cursor": review_cursor,
        "review_comment_cursor": review_comment_cursor,
        "issue_comment_cursor": issue_comment_cursor,
        "reaction_cursor": reaction_cursor,
        "pr_status": pr_status,
    }
    with open(path, "w", encoding="utf-8") as handle:
        json.dump(payload, handle)


def _write_new_pr_cursor_output(path: str | None, *, pr_cursor: int) -> None:
    if not path:
        return

    with open(path, "w", encoding="utf-8") as handle:
        json.dump({"pr_cursor": pr_cursor}, handle)


def _startup_failure_exit_code(error: Any) -> int:
    """How a failure *before* the first poll should end this run.

    Nothing has been observed yet, so no activity is lost by ending the run early.
    A transient failure that merely outlasted the bounded startup retries -- a
    truncated body on a large PR, a blip in the network -- must therefore exit
    ``RETRY_EXIT_CODE`` so a managed retry-capable watch can re-arm itself instead
    of dying and leaving the PR unwatched until somebody notices. Genuinely
    terminal failures (a bad token, a PR that does not exist) still exit 1:
    retrying those would poll forever without ever succeeding.
    """

    return RETRY_EXIT_CODE if isinstance(error, InitialRequestRetriesExhausted) else 1


def _watch_identity(
    args: argparse.Namespace,
    *,
    legacy_ci_sha: str | None = None,
    include_ci_max_pages: bool = True,
) -> str:
    """A stable digest of the options that decide what this watch reports.

    Ownership by repo and PR alone cannot tell two watches on the same PR apart --
    one ``--actionable-only``, one meant to report everything -- and a shared state
    file then lets whichever polls first advance the cursors past an event the other
    would have reported. That event is gone for good rather than merely late, so the
    filters belong in the identity.

    Only the report-shaping options are in here. ``--interval``, ``--timeout`` and
    ``--settle`` change pacing, not which activity counts, and two watches differing
    only in those can share cursors without losing anything.
    """

    material_fields = {
        "mode": "new-prs" if args.new_prs else "pr",
        "actionable_only": bool(args.actionable_only),
        "include_self_comments": bool(args.include_self_comments),
        "ignore_authors": sorted(_normalize_authors(args.ignore_author)),
        "ignore_comment_patterns": sorted(set(args.ignore_comment_pattern or [])),
    }
    # Keep the v0.14 PR-only identity stable. Adding CI fields to that hash would
    # make every existing PR-only state file look owned by a different watch after
    # upgrading, even though its report contract has not changed.
    if _ci_enabled(args):
        material_fields.update(
            {
                "ci_branch": args.branch,
                "ci_workflows": list(args.workflow or []),
                "ci_success_conclusions": sorted(
                    _parse_success_conclusions(args.success_conclusion)
                ),
            }
        )
        if include_ci_max_pages:
            material_fields["ci_max_pages"] = args.max_pages
        if legacy_ci_sha is not None:
            material_fields["ci_sha"] = legacy_ci_sha
    if args.coalesce_success:
        material_fields["coalesce_success"] = True
    # Only a non-default stall window is material, so watches seeded before the stall
    # report existed keep their identity.
    if getattr(args, "review_stall_minutes", DEFAULT_REVIEW_STALL_MINUTES) != DEFAULT_REVIEW_STALL_MINUTES:
        material_fields["review_stall_minutes"] = args.review_stall_minutes
    material = json.dumps(material_fields, sort_keys=True)
    return hashlib.sha256(f"wait_pr/{STATE_FILE_VERSION}/{material}".encode()).hexdigest()[:16]


def _legacy_watch_identity_aliases(
    args: argparse.Namespace,
    path: str | None,
) -> set[str]:
    """Return released combined identities that can be migrated at this path.

    Before combined waiting was stabilized, the CI target SHA was part of the watch
    identity. A head change therefore made an otherwise identical watch look foreign.
    Only hashes derived from this path's own recorded PR/Actions head are accepted;
    this is a narrow migration, not a general identity bypass.
    """

    if not path or not _ci_enabled(args):
        return set()
    try:
        payload = json.loads(Path(path).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return set()
    if not isinstance(payload, dict):
        return set()
    if payload.get("version") != STATE_FILE_VERSION:
        return set()
    if payload.get("repo") != args.repo or payload.get("pr") != args.pr:
        return set()

    candidate_shas: set[str] = set()
    for value in (args.sha, payload.get("head_sha")):
        if isinstance(value, str) and value:
            candidate_shas.add(value)
    actions = payload.get(ACTIONS_SNAPSHOT_KEY)
    if isinstance(actions, dict):
        for runs in actions.values():
            if not isinstance(runs, list):
                continue
            for run in runs:
                if isinstance(run, dict):
                    value = run.get("head_sha")
                    if isinstance(value, str) and value:
                        candidate_shas.add(value)
    aliases = {
        _watch_identity(args, legacy_ci_sha=sha, include_ci_max_pages=False)
        for sha in candidate_shas
    }
    # The released combined identity omitted both the target SHA and page limit.
    # Accept that exact old shape once so adding coverage cannot strand cursors.
    aliases.add(_watch_identity(args, include_ci_max_pages=False))
    return aliases


def _managed_watch_id() -> str | None:
    """The id of the ``vibe watch`` this waiter is a cycle of, when there is one.

    Two separately managed watches on the same PR with the same filters are
    indistinguishable by configuration alone, and sharing a state file means
    whichever polls first advances the cursors past events the other never
    reported. The supervisor hands the id down, so the owner can be exact. A manual
    run has none, which is not a conflict -- only proof of one is.
    """

    value = os.environ.get(WATCH_ID_ENV, "").strip()
    return value or None


def _owner_conflict(
    owner: tuple[Any, Any, Any, Any] | None,
    *,
    repo: str,
    pr_number: int | None,
    watch_identity: str | None,
    watch_id: str | None,
    watch_identity_aliases: set[str] | None = None,
) -> str | None:
    """Why ``owner`` is somebody else's claim on the path, or ``None`` when it is ours.

    A state file written before identities existed carries no owner, and an absent
    owner is compatible with every run -- that is the file a managed watch adopts.

    A file that DOES name an owner is the opposite: the burden is on this run to
    prove it is that owner, and a manual run cannot. Letting it through would be
    silent data loss rather than a mere sharing of the path -- the manual run polls,
    reports to a terminal nobody is reading, and ``_write_state_file`` stamps
    ``owner: null`` over the managed claim while advancing the cursors past that
    activity. The managed watch then adopts its own file back as ownerless and
    resumes from cursors covering events its Agent follow-up never received.
    """

    if owner is None:
        return None
    saved_repo, saved_pr, saved_watch, saved_owner = owner
    if saved_repo != repo or saved_pr != pr_number:
        return f"belongs to {saved_repo}#{saved_pr}, not {repo}#{pr_number}"
    if (
        saved_watch is not None
        and watch_identity is not None
        and saved_watch != watch_identity
        and saved_watch not in (watch_identity_aliases or set())
    ):
        return (
            f"belongs to another watch on {saved_repo}#{saved_pr} with different "
            "reporting filters"
        )
    if saved_owner is not None and saved_owner != watch_id:
        if watch_id is None:
            return (
                f"belongs to watch {saved_owner}; this run is not managed by that "
                "watch. Use a different --state-file."
            )
        return f"belongs to watch {saved_owner}, not watch {watch_id}"
    return None


def _load_state_file(
    path: str | None,
    *,
    repo: str,
    pr_number: int | None,
    watch_identity: str | None = None,
    watch_id: str | None = None,
    watch_identity_aliases: set[str] | None = None,
) -> dict[str, Any]:
    """Read cursors left behind by an earlier run of this same waiter.

    A `--forever` watch runs the waiter once per cycle, so without this the next
    cycle re-baselines from whatever the PR looks like at startup and silently
    swallows everything that arrived between the previous cycle's exit and that
    snapshot.
    """

    if not path:
        return {}

    try:
        raw = Path(path).read_text(encoding="utf-8")
    except FileNotFoundError:
        return {}
    except OSError as err:
        raise StateFileUnusableError(f"State file {path} cannot be read: {err}") from err

    # An empty file is the claim below caught between its exclusive create and its
    # first write, so no cursor was ever recorded in it and there is none to lose.
    # Anything else that will not parse HAD cursors, and how far they reached is now
    # unknown -- which is why this is terminal rather than a fresh baseline.
    if not raw.strip():
        return {}
    try:
        payload = json.loads(raw)
    except ValueError as err:
        raise StateFileUnusableError(f"State file {path} is corrupt: {err}") from err
    if not isinstance(payload, dict) or payload.get("version") != STATE_FILE_VERSION:
        raise StateFileUnusableError(f"State file {path} is not in a recognised format")
    # Resuming from somebody else's cursors would skip the history they cover, and
    # carrying on would overwrite them on the first cursor advance -- so this is
    # terminal rather than a fresh baseline. A file left behind by another watch has
    # to be removed, or that watch given its own path, deliberately.
    conflict = _owner_conflict(
        (payload.get("repo"), payload.get("pr"), payload.get("watch"), payload.get("owner")),
        repo=repo,
        pr_number=pr_number,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
    )
    if conflict is not None:
        raise StateFileOwnershipError(f"State file {path} {conflict}")
    _validate_saved_actions(payload)
    _validate_saved_success_batch(payload)
    pending = payload.get(STAGED_KEY)
    if isinstance(pending, dict) and isinstance(pending.get("cursors"), dict):
        # Legacy pending transactions may contain only some cursor fields.
        # Validate their effective state before acknowledgement can write it.
        _validate_saved_actions({**payload, **pending["cursors"]})
        _validate_saved_success_batch({**payload, **pending["cursors"]})
    return payload


def _state_file_scratch(target: Path) -> tuple[int, str]:
    """An exclusively created scratch file beside ``target``.

    ``mkstemp`` rather than a derived name such as ``<state-file>.tmp``: this runs
    in a directory of persisted user state, and a deterministic path both
    truncates whatever already occupies it and lets two waiters sharing a
    directory scribble over each other's half-written file.
    """

    return tempfile.mkstemp(dir=target.parent, prefix=f".{target.name}.", suffix=".tmp")


def _state_file_owner(target: Path) -> tuple[Any, Any, Any, Any] | None:
    """Which watch the file at ``target`` currently claims, or ``None`` if it says nothing.

    Missing and unusable files both answer ``None``, matching ``_load_state_file``:
    there is no owner to respect, so the caller may take the path.
    """

    try:
        with target.open(encoding="utf-8") as handle:
            payload = json.load(handle)
    except (OSError, ValueError):
        return None
    if not isinstance(payload, dict) or payload.get("version") != STATE_FILE_VERSION:
        return None
    return payload.get("repo"), payload.get("pr"), payload.get("watch"), payload.get("owner")


def _claim_state_file(
    target: Path,
    *,
    repo: str,
    pr_number: int | None,
    watch_identity: str | None = None,
    watch_id: str | None = None,
) -> bool:
    """Take a currently missing state file for this PR, atomically.

    ``O_EXCL`` is the whole point: two waiters starting together both see no file,
    and exactly one of them creates it. The loser reads the winner's claim and stops
    on the ownership check instead of quietly sharing the path and overwriting the
    winner's cursors on its next advance -- a silent gap in the review loop.

    Returns False when somebody else got there first; the caller then treats the path
    as pre-existing and lets ``_load_state_file`` judge the owner.
    """

    try:
        handle = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    except FileExistsError:
        return False
    except OSError as err:
        raise StatePersistenceError(f"Cannot write state file {target}: {err}") from err

    try:
        with os.fdopen(handle, "w", encoding="utf-8") as stream:
            json.dump(
                {
                    "version": STATE_FILE_VERSION,
                    "repo": repo,
                    "pr": pr_number,
                    "watch": watch_identity,
                    "owner": watch_id,
                },
                stream,
            )
    except OSError as err:
        raise StatePersistenceError(f"Cannot write state file {target}: {err}") from err
    return True


@contextmanager
def _state_file_lock(target: Path) -> Iterator[None]:
    """Serialize the ownership decision on ``target`` across processes.

    Deciding who owns a state file is read-then-write, and two managed watches that
    interleave those halves both conclude the path is theirs. A sidecar lock file
    makes the decision one step. It is a separate file precisely because the state
    file itself is replaced rather than rewritten: a lock held on an inode that has
    since been renamed away guards nothing.

    Best effort by design. A filesystem without working locks, or a directory that
    refuses the lock file, must not stop the watch -- the write probe and the
    ownership re-check on every replace still stand.
    """

    if fcntl is None:
        yield
        return

    handle = None
    try:
        handle = os.open(target.with_name(f"{target.name}.lock"), os.O_RDWR | os.O_CREAT, 0o600)
        fcntl.flock(handle, fcntl.LOCK_EX)
    except OSError:
        if handle is not None:
            os.close(handle)
        yield
        return

    try:
        yield
    finally:
        try:
            fcntl.flock(handle, fcntl.LOCK_UN)
        finally:
            os.close(handle)


def _adopt_state_file(
    target: Path,
    *,
    repo: str,
    pr_number: int | None,
    watch_id: str,
    watch_identity: str | None,
) -> bool:
    """Stamp this managed watch onto an ownerless state file, keeping its cursors.

    A file written before owners existed, or by a manual run, names no owner -- and an
    absent owner is compatible with every managed watch. Two of them would therefore
    both adopt the same path, poll, and overwrite each other's cursors, skipping
    activity for good. Claiming the name here, under the lock and before any polling,
    turns that into a conflict the loser sees while it can still be told about it.

    An EMPTY file is the same hazard wearing different clothes: it is a claim caught
    between its exclusive create and its first write, so ``_load_state_file`` reads it
    as a fresh baseline with no cursors to lose. Left as it is, it names no owner
    either, and two managed watches pointed at that path both clear this preflight and
    poll -- so finish the claim the interrupted run started rather than falling through
    to a byte-for-byte rewrite that preserves the emptiness and the ambiguity with it.

    Returns False when the file says nothing usable, leaving it to the caller's probe.
    """

    try:
        raw = target.read_text(encoding="utf-8")
    except OSError:
        return False

    if not raw.strip():
        payload: dict[str, Any] = {
            "version": STATE_FILE_VERSION,
            "repo": repo,
            "pr": pr_number,
        }
    else:
        try:
            payload = json.loads(raw)
        except ValueError:
            return False
        if not isinstance(payload, dict) or payload.get("version") != STATE_FILE_VERSION:
            return False

    payload["owner"] = watch_id
    if payload.get("watch") is None and watch_identity is not None:
        payload["watch"] = watch_identity

    scratch = None
    try:
        handle, scratch = _state_file_scratch(target)
        with os.fdopen(handle, "w", encoding="utf-8") as stream:
            json.dump(payload, stream)
        os.replace(scratch, target)
        scratch = None
    except OSError as err:
        raise StatePersistenceError(f"Cannot write state file {target}: {err}") from err
    finally:
        if scratch is not None:
            try:
                os.unlink(scratch)
            except OSError:
                pass
    return True


def _verify_state_file_writable(
    path: str | None,
    *,
    repo: str,
    pr_number: int | None,
    watch_identity: str | None = None,
    watch_id: str | None = None,
    watch_identity_aliases: set[str] | None = None,
) -> None:
    """Claim the requested state file, and fail before the first poll if it is unusable.

    A forever watch only discovers a read-only parent directory when the cycle it
    spent minutes on tries to save its cursors, and by then the activity that
    cycle observed is already unrecoverable.

    A missing state file is created here holding nothing but this PR's ownership, so
    the path is owned before any polling starts rather than after the first cursor
    advance. It carries no cursors, so this cycle still baselines from the current PR
    exactly as it did before.

    An existing file that names no owner is adopted here too, cursors intact, because
    an absent owner is compatible with every managed watch and would otherwise let two
    of them share the path. Both steps happen under a lock on the path, so the
    read-then-write that decides ownership cannot interleave with another waiter's.

    A file that belongs to somebody else is left untouched and unprobed, and this
    returns without writing anything -- see the conflict branch below.

    For a file that already exists the probe is the whole write, ``os.replace``
    included, because that is the step persistence actually depends on and the step a
    sibling-creation check cannot speak for: a target that is a directory, or one in a
    sticky-bit directory owned by somebody else, accepts new siblings all day and
    still refuses the rename. It is rewritten with the bytes it already holds, so a
    watch resuming from good cursors keeps them either way.
    """

    if not path:
        return

    target = Path(path)
    try:
        target.parent.mkdir(parents=True, exist_ok=True)
    except OSError as err:
        raise StatePersistenceError(f"Cannot write state file {path}: {err}") from err

    with _state_file_lock(target):
        try:
            exists = target.exists()
        except OSError as err:
            raise StatePersistenceError(f"Cannot write state file {path}: {err}") from err

        if not exists and _claim_state_file(
            target,
            repo=repo,
            pr_number=pr_number,
            watch_identity=watch_identity,
            watch_id=watch_id,
        ):
            # Creating the real file in the real directory is the write probe, and the
            # rename in later cycles lands on a file this process owns.
            return

        # Somebody else's file is not ours to touch AT ALL -- not to adopt, and not to
        # probe. The probe below is an ``os.replace`` of bytes read a moment earlier,
        # and the owner's own cursor writes do NOT take this lock, so probing a foreign
        # path can land stale bytes over a cursor it has just advanced or a ``pending``
        # handoff it is mid-way through, making the owning watch replay or lose
        # activity. Returning here costs nothing: ``_load_state_file`` refuses the same
        # file moments later, with the same conflict, before a single poll.
        conflict = _owner_conflict(
            _state_file_owner(target),
            repo=repo,
            pr_number=pr_number,
            watch_identity=watch_identity,
            watch_id=watch_id,
            watch_identity_aliases=watch_identity_aliases,
        )
        if conflict is not None:
            return

        # An ownerless file is adopted, not merely accepted: taking the name is what
        # makes a second managed watch on the same path fail instead of sharing it.
        if watch_id is not None and _adopt_state_file(
            target,
            repo=repo,
            pr_number=pr_number,
            watch_id=watch_id,
            watch_identity=watch_identity,
        ):
            # Rewriting the real file is the write probe, as the claim is above.
            return

        try:
            existing = target.read_bytes()
        except OSError as err:
            raise StatePersistenceError(f"Cannot write state file {path}: {err}") from err

        scratch = None
        try:
            handle, scratch = _state_file_scratch(target)
            with os.fdopen(handle, "wb") as stream:
                stream.write(existing)
            os.replace(scratch, target)
            scratch = None
        except OSError as err:
            raise StatePersistenceError(f"Cannot write state file {path}: {err}") from err
        finally:
            if scratch is not None:
                try:
                    os.unlink(scratch)
                except OSError:
                    pass


def _write_state_file(
    path: str | None,
    *,
    repo: str,
    pr_number: int | None,
    watch_identity: str | None = None,
    watch_id: str | None = None,
    watch_identity_aliases: set[str] | None = None,
    **fields: Any,
) -> None:
    if not path:
        return

    payload = {
        "version": STATE_FILE_VERSION,
        "repo": repo,
        "pr": pr_number,
        "watch": watch_identity,
        "owner": watch_id,
        **fields,
    }
    target = Path(path)
    scratch = None
    # Re-checked on every replace, not just at startup: the claim can lose a race with
    # a waiter that created the file in the same instant, or a person can point another
    # watch at the same path mid-run. Clobbering that watch's cursors would make it
    # re-baseline and skip real activity, so hand the path back and stop instead.
    conflict = _owner_conflict(
        _state_file_owner(target),
        repo=repo,
        pr_number=pr_number,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
    )
    if conflict is not None:
        raise StateFileOwnershipError(f"State file {path} now {conflict}")
    try:
        target.parent.mkdir(parents=True, exist_ok=True)
        # Written aside and moved into place: a cycle killed mid-write must not
        # leave a truncated file that the next cycle has to discard.
        handle, scratch = _state_file_scratch(target)
        with os.fdopen(handle, "w", encoding="utf-8") as stream:
            json.dump(payload, stream)
        os.replace(scratch, target)
        scratch = None
    except OSError as err:
        # Terminal, not a warning. The caller asked for cursors that survive the
        # process; continuing without them lets the next cycle re-baseline from the
        # current PR and silently drop everything that arrived in between, which is
        # the exact loss ``--state-file`` exists to prevent.
        raise StatePersistenceError(f"Could not write state file {path}: {err}") from err
    finally:
        # A failed write must not leave its scratch file behind in the state dir.
        if scratch is not None:
            try:
                os.unlink(scratch)
            except OSError:
                pass


def _check_state_file_path(path: str | None) -> None:
    """Reject an unusable path without claiming it before remote validation."""

    if not path:
        return
    target = Path(path)
    try:
        target.parent.mkdir(parents=True, exist_ok=True)
        if target.exists() and not target.is_file():
            raise StatePersistenceError(f"Cannot write state file {path}: target is not a regular file")
        if target.parent.stat().st_mode & 0o222 == 0:
            raise StatePersistenceError(f"Cannot write state file {path}: parent directory is read-only")
    except StatePersistenceError:
        raise
    except OSError as err:
        raise StatePersistenceError(f"Cannot write state file {path}: {err}") from err


def _token_fingerprint(token: str | None) -> str | None:
    """Which credentials a cached ``viewer_login`` was resolved under.

    A one-way digest, never the token itself: the state file lives on disk next to
    the cursors and has no business holding a credential. It exists so a resumed
    cycle can tell "same account, reuse the saved login" from "the token now
    belongs to someone else", which otherwise filtered the wrong author's
    comments out of the review loop.
    """

    if not token:
        return None
    return hashlib.sha256(f"wait_pr/{STATE_FILE_VERSION}/{token}".encode()).hexdigest()[:16]


def _saved_int(saved: dict[str, Any], key: str) -> int | None:
    value = saved.get(key)
    return int(value) if isinstance(value, int) and not isinstance(value, bool) else None


def _saved_str(saved: dict[str, Any], key: str) -> str | None:
    value = saved.get(key)
    return value if isinstance(value, str) and value else None


def _saved_fingerprints(saved: dict[str, Any], key: str) -> dict[str, str]:
    value = saved.get(key)
    if not isinstance(value, dict):
        return {}
    return {
        str(item_id): fingerprint
        for item_id, fingerprint in value.items()
        if isinstance(fingerprint, str) and fingerprint
    }


def _saved_review_thread_states(saved: dict[str, Any]) -> dict[str, bool]:
    value = saved.get(REVIEW_THREAD_STATES_KEY)
    if not isinstance(value, dict):
        return {}
    return {str(item_id): state for item_id, state in value.items() if isinstance(state, bool)}


def _saved_snapshot(saved: dict[str, Any]) -> dict[str, Any]:
    value = saved.get(PR_SNAPSHOT_KEY)
    return value if isinstance(value, dict) else {}


def _saved_actions_snapshot(saved: dict[str, Any], key: str = ACTIONS_SNAPSHOT_KEY) -> dict[str, Any]:
    return saved.get(key, {})


def _validate_saved_actions(saved: dict[str, Any]) -> None:
    """Reject corrupt history, never filter it into an apparently empty gate."""

    for key in (ACTIONS_SNAPSHOT_KEY, ACTIONS_OBSERVED_KEY):
        if key not in saved:
            continue
        value = saved[key]
        if not isinstance(value, dict):
            raise StateFileUnusableError(f"Saved {key} is malformed: expected a workflow mapping")
        for workflow, runs in value.items():
            if not isinstance(workflow, str) or not isinstance(runs, list):
                raise StateFileUnusableError(f"Saved {key} is malformed: expected workflow run lists")
            for run in runs:
                if not isinstance(run, dict):
                    raise StateFileUnusableError(f"Saved {key} is malformed: expected run objects")
                run_id = run.get("id")
                attempt = run.get("run_attempt")
                if (
                    not isinstance(run_id, (int, str))
                    or isinstance(run_id, bool)
                    or (isinstance(run_id, str) and not run_id)
                    or any(
                        run.get(field) is not None and not isinstance(run[field], str)
                        for field in ("status", "conclusion", "head_sha", "head_branch")
                    )
                    or (
                        attempt is not None
                        and (not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1)
                    )
                ):
                    raise StateFileUnusableError(f"Saved {key} is malformed: invalid run comparison fields")
    if ACTIONS_SNAPSHOT_KEY in saved and ACTIONS_OBSERVED_KEY in saved:
        if set(saved[ACTIONS_SNAPSHOT_KEY]) != set(saved[ACTIONS_OBSERVED_KEY]):
            raise StateFileUnusableError("Saved actions_observed is malformed: workflow inventory differs from actions")


def _validate_saved_success_batch(saved: dict[str, Any]) -> None:
    if SUCCESS_BATCH_KEY not in saved:
        return
    value = saved[SUCCESS_BATCH_KEY]
    if not isinstance(value, dict) or not isinstance(value.get("head_sha"), str):
        raise StateFileUnusableError("Saved success_batch is malformed: expected head-bound state")
    notified = value.get("notified")
    if notified is not None and not isinstance(notified, str):
        raise StateFileUnusableError("Saved success_batch is malformed: invalid notification signature")
    reaction_seen = value.get("reaction_seen", 0)
    if not isinstance(reaction_seen, int) or isinstance(reaction_seen, bool) or reaction_seen < 0:
        raise StateFileUnusableError("Saved success_batch is malformed: invalid reaction watermark")
    threads = value.get("thread_states", {})
    if not isinstance(threads, dict) or any(not isinstance(key, str) or not isinstance(flag, bool) for key, flag in threads.items()):
        raise StateFileUnusableError("Saved success_batch is malformed: invalid observed thread states")
    seen = value.get("review_seen", {})
    if not isinstance(seen, dict) or any(not isinstance(key, str) or not isinstance(fp, str) for key, fp in seen.items()):
        raise StateFileUnusableError("Saved success_batch is malformed: invalid semantic observation history")
    for key in ("review", "outcome"):
        review = value.get(key)
        if review is None:
            continue
        if (
            not isinstance(review, dict)
            or review.get("kind") not in {"reviews", "issue_comments", "review_comments", "reactions"}
            or not isinstance(review.get("id"), (int, str))
            or isinstance(review.get("id"), bool)
            or not isinstance(review.get("fingerprint"), str)
            or not isinstance(review.get("order"), list)
            or len(review["order"]) != 2
            or not isinstance(review["order"][0], str)
            or not isinstance(review["order"][1], int)
        ):
            raise StateFileUnusableError("Saved success_batch is malformed: invalid review evidence")


def _combined_success_signature(selected: dict[str, Any], batch: dict[str, Any]) -> str:
    review = batch["review"]
    material = {
        "head": str(batch["head_sha"]).casefold(),
        "review": {key: review[key] for key in ("kind", "id", "fingerprint")},
        "actions": normalize_selected_runs(selected),
    }
    encoded = json.dumps(material, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(encoded.encode()).hexdigest()


def _actions_snapshot_regressed(current: dict[str, Any], previous: dict[str, Any]) -> bool:
    """An incomplete inventory or older attempt cannot establish a new verdict."""

    for workflow, previous_runs in previous.items():
        current_runs = {run.get("id"): run for run in current.get(workflow, [])}
        for previous_run in previous_runs:
            current_run = current_runs.get(previous_run.get("id"))
            if current_run is None:
                return True
            previous_attempt = previous_run.get("run_attempt")
            current_attempt = current_run.get("run_attempt")
            if isinstance(previous_attempt, int) and (
                not isinstance(current_attempt, int) or current_attempt < previous_attempt
            ):
                return True
    return False


def _observe_actions(
    previous: dict[str, Any], current: dict[str, Any], head_sha: str, *, preserve_terminal: bool = False,
) -> dict[str, Any]:
    """Remember known run IDs/attempts without treating observation as delivery."""

    observed = {}
    for workflow, runs in current.items():
        known = {
            run.get("id"): run
            for run in previous.get(workflow, [])
            if str(run.get("head_sha") or "").casefold() == head_sha.casefold()
        }
        for run in runs:
            old_attempt = known.get(run.get("id"), {}).get("run_attempt")
            new_attempt = run.get("run_attempt")
            if isinstance(old_attempt, int) and (
                not isinstance(new_attempt, int) or new_attempt < old_attempt
            ):
                continue
            if (
                preserve_terminal and old_attempt == new_attempt
                and known.get(run.get("id"), {}).get("status") == "completed"
                and run.get("status") != "completed"
            ):
                continue
            known[run.get("id")] = run
        observed[workflow] = list(known.values())
    return normalize_selected_runs(observed)


def _without_older_attempts(
    selected: dict[str, list[dict[str, Any]]], observed: dict[str, Any],
) -> dict[str, list[dict[str, Any]]]:
    """Missing inventory does not hide a new failure; an older attempt does."""

    result = {}
    for workflow, runs in selected.items():
        known = {run["id"]: run for run in observed.get(workflow, [])}
        result[workflow] = [
            run for run in runs
            if not isinstance(attempt := known.get(run.get("id"), {}).get("run_attempt"), int)
            or (isinstance(run.get("run_attempt"), int) and run["run_attempt"] >= attempt)
        ]
    return result


def _ci_enabled(args: argparse.Namespace) -> bool:
    return bool(args.sha or args.branch or args.workflow or args.success_conclusion)


def _validate_ci_args(args: argparse.Namespace) -> str | None:
    provided = _ci_enabled(args)
    if args.coalesce_success and not args.workflow:
        return "--coalesce-success requires --pr and at least one --workflow"
    if not provided:
        return None
    if args.pr is None:
        return "CI monitoring requires --pr; --new-prs cannot be combined with --sha or --workflow"
    if not args.workflow:
        return "CI monitoring requires at least one --workflow"
    if args.max_pages < 1:
        return "--max-pages must be at least 1"
    if len(set(args.workflow)) != len(args.workflow):
        return "--workflow values must be unique"
    return None


def _parse_success_conclusions(values: list[str] | None) -> set[str]:
    if not values:
        return set(DEFAULT_SUCCESS_CONCLUSIONS)
    result: set[str] = set()
    for value in values:
        result.update(item.strip() for item in value.split(",") if item.strip())
    return result


def _missing_pr_baselines(saved: dict[str, Any]) -> list[str]:
    missing: list[str] = []
    if _saved_str(saved, "head_sha") is None:
        missing.append("head_sha")
    for key in PR_FINGERPRINT_KEYS:
        value = saved.get(key)
        if not isinstance(value, dict) or any(not isinstance(item, str) for item in value.values()):
            missing.append(key)
    thread_states = saved.get(REVIEW_THREAD_STATES_KEY)
    if not isinstance(thread_states, dict) or any(not isinstance(item, bool) for item in thread_states.values()):
        missing.append(REVIEW_THREAD_STATES_KEY)
    if not isinstance(saved.get(PR_SNAPSHOT_KEY), dict):
        missing.append(PR_SNAPSHOT_KEY)
    return missing


def _missing_actions_baselines(saved: dict[str, Any], workflows: list[str]) -> list[str]:
    value = saved.get(ACTIONS_SNAPSHOT_KEY)
    if not isinstance(value, dict) or set(value) != set(workflows):
        return [ACTIONS_SNAPSHOT_KEY]
    if any(not isinstance(runs, list) for runs in value.values()):
        return [ACTIONS_SNAPSHOT_KEY]
    return []


def _last_delivery() -> str | None:
    """When the supervisor last queued a report from this watch, as it sees it.

    ``None`` for a manual run, which has no supervisor -- and needs none, because
    there printing the report IS delivering it and nothing is ever staged.
    """

    return os.environ.get(LAST_DELIVERY_ENV, "").strip() or None


def _staged_replay_output(saved: dict[str, Any], delivery: str | None) -> str | None:
    staged = saved.get(STAGED_KEY)
    if not isinstance(staged, dict):
        return None
    if not isinstance(staged.get("cursors"), dict):
        raise StateFileUnusableError("Pending waiter transaction has no usable cursor state")
    output = staged.get("output")
    if staged.get("delivered_after") == delivery and isinstance(output, str) and output:
        return output
    return None


def _resolve_staged_state(
    path: str | None,
    saved: dict[str, Any],
    *,
    delivery: str | None,
    repo: str,
    pr_number: int | None,
    watch_identity: str | None,
    watch_id: str | None,
    watch_identity_aliases: set[str] | None = None,
    return_replay: bool = False,
) -> dict[str, Any] | tuple[dict[str, Any], str | None]:
    """Promote acknowledged state or replay its persisted event payload.

    Promoted when the supervisor's last-delivery stamp has moved since the report was
    staged: the report was queued, so polling may start after it. Dropped when the
    stamp is unchanged, which replays the report -- one repeated Agent turn, against
    an event lost for good. Comparing stamps rather than consuming a one-shot ack is
    what makes this survive a restart, and makes a ``once`` watch resumed long after
    its one report promote instead of replaying. Either way the decision is written
    down before polling, so it is taken once.
    """

    staged = saved.get(STAGED_KEY)
    if not isinstance(staged, dict):
        return (saved, None) if return_replay else saved
    cursors = staged.get("cursors")
    if not isinstance(cursors, dict):
        raise StateFileUnusableError("Pending waiter transaction has no usable cursor state")
    replay_output = _staged_replay_output(saved, delivery)
    delivered = staged.get("delivered_after") != delivery

    if replay_output is not None:
        print("An earlier report was never delivered; replaying its persisted output.", file=sys.stderr)
        return (saved, replay_output) if return_replay else saved

    resolved = {key: value for key, value in saved.items() if key != STAGED_KEY}
    if delivered:
        resolved.update(cursors)
    _validate_saved_actions(resolved)
    _validate_saved_success_batch(resolved)
    print(
        (
            "An earlier report was delivered; advancing past it."
            if delivered
            else "Legacy pending state has no report payload; reconstructing from committed cursors."
        ),
        file=sys.stderr,
    )
    fields = {
        key: value
        for key, value in resolved.items()
        if key not in {"version", "repo", "pr", "watch", "owner"}
    }
    _write_state_file(
        path,
        repo=repo,
        pr_number=pr_number,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
        **fields,
    )
    return (resolved, None) if return_replay else resolved


def _deliver(output: str) -> None:
    """Hand the report to the supervisor, and make sure it has left this process.

    The cursors covering a reported event are committed only after this returns, so
    the report must be out of our own buffers first.
    """

    print(output)
    sys.stdout.flush()


def _build_parser() -> argparse.ArgumentParser:
    """The waiter's CLI surface, separate from main() so it can be inspected directly."""

    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--repo", required=True, help="GitHub repo in owner/name form")
    mode = parser.add_mutually_exclusive_group(required=True)
    mode.add_argument("--pr", type=int, help="Pull request number")
    mode.add_argument("--new-prs", action="store_true", help="Watch for new pull requests in the repository")
    parser.add_argument("--interval", type=float, default=45.0, help="Polling interval in seconds")
    parser.add_argument(
        "--timeout",
        type=float,
        default=21600.0,
        help="Overall timeout in seconds; default 21600 (6 hours), 0 means forever",
    )
    parser.add_argument("--since-review-id", type=int, default=None, help="Existing review cursor")
    parser.add_argument("--since-review-comment-id", type=int, default=None, help="Existing review comment cursor")
    parser.add_argument("--since-issue-comment-id", type=int, default=None, help="Existing PR conversation comment cursor")
    parser.add_argument("--since-reaction-id", type=int, default=None, help="Existing PR-body reaction cursor")
    parser.add_argument("--since-pr-status", help=argparse.SUPPRESS)
    parser.add_argument("--since-pr-id", type=int, default=None, help="Existing repository pull request cursor")
    parser.add_argument("--cursor-output", help=argparse.SUPPRESS)
    parser.add_argument(
        "--state-file",
        help=(
            "Path to a JSON file holding this watch's cursors between runs. Strongly recommended for "
            "--forever watches: each cycle resumes where the previous one stopped instead of "
            "re-baselining, so activity arriving between cycles is not lost, and the next fetch only "
            "asks GitHub for what is new."
        ),
    )
    parser.add_argument(
        "--settle",
        type=float,
        default=0.0,
        help=(
            "Seconds to wait after the first new activity before reporting, re-polling until the set "
            f"stops growing (at most {SETTLE_MAX_ROUNDS} extra polls). A batched review that straddles "
            "a poll boundary then costs one Agent turn instead of one per fragment. 0 disables it."
        ),
    )
    parser.add_argument("--event-limit", type=int, default=8, help="Maximum number of new events to include in stdout")
    parser.add_argument(
        "--include-self-comments",
        action="store_true",
        help="Include reviews and comments authored by the current authenticated GitHub user",
    )
    parser.add_argument(
        "--actionable-only",
        action="store_true",
        help=(
            "Only wake the Agent for review activity that needs a response: reviews carrying a "
            "verdict or a body, inline review comments, the Codex pass reaction, and merged/closed "
            "transitions. Drops bodyless COMMENTED review envelopes, bot trigger comments such as "
            "'@codex review', and draft toggles."
        ),
    )
    parser.add_argument(
        "--ignore-author",
        action="append",
        help=(
            "GitHub login whose review/comment payloads never trigger a follow-up; repeatable. "
            "Independent review-thread status transitions remain visible"
        ),
    )
    parser.add_argument(
        "--ignore-comment-pattern",
        action="append",
        help=(
            "Case-insensitive regex; matching review/comment payloads never trigger a follow-up. "
            "Independent review-thread status transitions remain visible. Repeatable"
        ),
    )
    parser.add_argument(
        "--catch-up",
        action="store_true",
        help="Treat current existing activity as pending when no explicit cursor is provided",
    )
    parser.add_argument(
        "--seed-state",
        action="store_true",
        help="Write a complete current baseline to --state-file and exit without waiting",
    )
    parser.add_argument(
        "--sha",
        help=(
            "Optional exact PR head SHA whose Actions runs should be monitored together with PR "
            "activity. Omit it to follow the PR's current head across watch cycles"
        ),
    )
    parser.add_argument(
        "--branch",
        help="Optional Actions head branch constraint used with --sha and --workflow",
    )
    parser.add_argument(
        "--workflow",
        action="append",
        help=(
            "Actions workflow name to monitor at --sha, or at the PR's current head when --sha is "
            "omitted; repeatable and enables combined CI mode"
        ),
    )
    parser.add_argument(
        "--coalesce-success",
        action="store_true",
        help=(
            "In combined PR/CI mode, defer recognized Codex and CI successes until both are "
            "present at the same head; findings, errors, and unfamiliar activity still report"
        ),
    )
    parser.add_argument(
        "--review-stall-minutes",
        type=float,
        default=DEFAULT_REVIEW_STALL_MINUTES,
        help=(
            "PR mode: report when Codex's summary has shown the current head's review running "
            "this many minutes on an open PR (a re-request restarts the clock), and again each "
            "further interval while it stays stuck; 0 disables. A head Codex never started on "
            "is not detected. Default 30."
        ),
    )
    parser.add_argument(
        "--max-pages",
        type=int,
        default=3,
        help="Maximum Actions run-list pages to inspect per poll in combined CI mode",
    )
    parser.add_argument(
        "--success-conclusion",
        action="append",
        help=(
            "Actions conclusion treated as successful in combined CI mode; repeatable or comma-separated. "
            "Defaults to success,skipped,neutral."
        ),
    )
    parser.add_argument(
        "--allow-unauthenticated",
        action="store_true",
        help="Allow polling without GitHub auth; the interval will be clamped to a safer minimum",
    )
    return parser


def main() -> int:
    args = _build_parser().parse_args()

    ci_error = _validate_ci_args(args)
    if ci_error is not None:
        print(ci_error, file=sys.stderr)
        return 2
    if not math.isfinite(args.review_stall_minutes) or args.review_stall_minutes < 0:
        print("--review-stall-minutes must be 0 (off) or a finite positive number", file=sys.stderr)
        return 2
    ci_enabled = _ci_enabled(args)
    success_conclusions = _parse_success_conclusions(args.success_conclusion)

    cache = ResponseCache()
    # Everything that can reject the arguments runs BEFORE any state is claimed. A
    # bad --ignore-comment-pattern used to leave a claimed state file behind on its
    # way to exit 2, and fixing the regex changes the watch identity, so the very
    # next run was refused as another watch's until the file was deleted by hand.
    ignored_authors = _normalize_authors(args.ignore_author)
    try:
        ignore_patterns = _compile_ignore_patterns(
            args.ignore_comment_pattern,
            actionable_only=args.actionable_only,
        )
    except re.error as err:
        print(f"Invalid --ignore-comment-pattern: {err}", file=sys.stderr)
        return 2
    if args.seed_state and (not args.state_file or args.catch_up):
        print("--seed-state requires --state-file and cannot be combined with --catch-up", file=sys.stderr)
        return 2

    watch_identity = _watch_identity(args)
    watch_identity_aliases = _legacy_watch_identity_aliases(args, args.state_file)
    watch_id = _managed_watch_id()
    delivery_stamp = _last_delivery()
    two_phase = watch_id is not None
    if args.seed_state and two_phase:
        print("--seed-state is a pre-watch command and cannot run as a managed watch", file=sys.stderr)
        return 2
    if two_phase and not args.state_file:
        print(
            "Managed PR watchers require an owner-specific --state-file; refusing to poll without durable state.",
            file=sys.stderr,
        )
        return 2
    _check_state_file_path(args.state_file)
    saved = _load_state_file(
        args.state_file,
        repo=args.repo,
        pr_number=args.pr,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
    )
    replay_output = _staged_replay_output(saved, delivery_stamp)
    if replay_output is not None:
        print(
            "An earlier report was never delivered; replaying it before GitHub preflight.",
            file=sys.stderr,
        )
        _deliver(replay_output)
        return 0
    token = get_token()
    if token is None and not args.allow_unauthenticated:
        print(
            (
                "GitHub authentication is required for reliable polling. "
                "Set GITHUB_TOKEN/GH_TOKEN, run 'gh auth login', or pass "
                "--allow-unauthenticated for a throttled best-effort run."
            ),
            file=sys.stderr,
        )
        return 2

    token_fingerprint = _token_fingerprint(token)
    viewer_login = None
    if args.pr is not None and not args.include_self_comments:
        # The stored login spares a /user request on every cycle of a forever watch,
        # but only while the token still belongs to the account it was resolved for.
        # A rotated or swapped credential would otherwise keep filtering out the old
        # account's comments and let the new account's own comments wake the Agent.
        if token_fingerprint is not None and _saved_str(saved, "token_fingerprint") == token_fingerprint:
            viewer_login = _saved_str(saved, "viewer_login")
        if viewer_login is None:
            viewer_result = retry_initial_request(
                lambda: get_authenticated_login(token, raise_on_error=True),
                description="GitHub viewer lookup",
                unauthenticated=token is None,
            )
            if viewer_result.error is not None:
                print(f"GitHub viewer lookup failed: {viewer_result.error}", file=sys.stderr)
                return _startup_failure_exit_code(viewer_result.error)
            viewer_login = viewer_result.value
        if token is not None and not viewer_login:
            print(
                "Could not resolve the authenticated GitHub login; refusing to poll while self-comment filtering is enabled.",
                file=sys.stderr,
            )
            return 1

    base_interval = max(args.interval, 1.0)
    effective_interval = base_interval
    settle_seconds = max(args.settle, 0.0)

    start = time.monotonic()

    saved_pr_cursor = None if args.catch_up else _saved_int(saved, "pr_cursor")
    since_pr_id = args.since_pr_id if args.since_pr_id is not None else saved_pr_cursor
    initial_resume = all(_saved_int(saved, key) is not None for key in STATE_CURSOR_KEYS)
    initial_review_comment_since = (
        _saved_str(saved, "review_comment_since")
        if initial_resume and args.since_review_comment_id is None
        else None
    )
    initial_issue_comment_since = (
        _saved_str(saved, "issue_comment_since")
        if initial_resume and args.since_issue_comment_id is None
        else None
    )

    def _fetch_initial_state() -> tuple[dict[str, Any], int]:
        if args.pr is not None:
            return _fetch_state(
                args.repo,
                args.pr,
                token,
                cache=cache,
                review_comment_since=initial_review_comment_since,
                issue_comment_since=initial_issue_comment_since,
                ci_sha=args.sha if ci_enabled else None,
                ci_branch=args.branch if ci_enabled else None,
                ci_workflows=args.workflow if ci_enabled else None,
                ci_max_pages=args.max_pages,
            )
        initial_pr_stop_after_id = None
        initial_pr_max_pages = None
        if since_pr_id is not None and not args.catch_up:
            initial_pr_stop_after_id = since_pr_id
        elif not args.catch_up:
            initial_pr_max_pages = 1
        return _fetch_new_pr_state(
            args.repo,
            token,
            stop_after_id=initial_pr_stop_after_id,
            max_pages=initial_pr_max_pages,
            cache=cache,
        )

    initial_request = retry_initial_request(
        _fetch_initial_state,
        description="initial GitHub PR state request",
        unauthenticated=token is None,
    )
    if initial_request.error is not None:
        print(f"Failed to fetch initial PR state: {initial_request.error}", file=sys.stderr)
        return _startup_failure_exit_code(initial_request.error)
    if initial_request.value is None:
        print("Initial GitHub PR state request completed without a result", file=sys.stderr)
        return 1
    selected_actions: dict[str, list[dict[str, Any]]] = {}
    state, requests_per_poll_count = initial_request.value
    if args.pr is not None and ci_enabled and args.sha:
        observed_head_sha = _current_pr_head_sha(state.get("pull_request"))
        if observed_head_sha.casefold() != args.sha.casefold():
            print(
                "Refusing to start a combined watch: PR head "
                f"{observed_head_sha} does not match --sha {args.sha}. "
                "Refresh the SHA and retry.",
                file=sys.stderr,
            )
            return 2
    if ci_enabled:
        selected_ci_sha = args.sha or _current_pr_head_sha(state.get("pull_request"))
        selected_actions = select_matching_runs(
            state.get("actions", []),
            workflows=args.workflow or [],
            branch=args.branch,
            head_sha=selected_ci_sha,
        )

    # The remote target is now proven valid. Only now may this run create or adopt
    # its state path; a typo or inaccessible PR must leave no ownership claim.
    _verify_state_file_writable(
        args.state_file,
        repo=args.repo,
        pr_number=args.pr,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
    )
    saved = _load_state_file(
        args.state_file,
        repo=args.repo,
        pr_number=args.pr,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
    )
    saved, replay_output = _resolve_staged_state(
        args.state_file,
        saved,
        delivery=delivery_stamp,
        repo=args.repo,
        pr_number=args.pr,
        watch_identity=watch_identity,
        watch_id=watch_id,
        watch_identity_aliases=watch_identity_aliases,
        return_replay=True,
    )
    if replay_output is not None:
        _deliver(replay_output)
        return 0

    resume_cursors = {key: _saved_int(saved, key) for key in STATE_CURSOR_KEYS}
    resumed = not args.catch_up and all(value is not None for value in resume_cursors.values())
    explicit_replay = args.pr is not None and any(
        value is not None
        for value in (
            args.since_review_id,
            args.since_review_comment_id,
            args.since_issue_comment_id,
            args.since_reaction_id,
            args.since_pr_status,
        )
    )
    missing_baselines = _missing_pr_baselines(saved) if resumed and args.pr is not None else []
    if ci_enabled and resumed and args.pr is not None:
        missing_baselines.extend(_missing_actions_baselines(saved, args.workflow or []))
    if missing_baselines and not explicit_replay:
        print(
            "Saved PR state lacks required baseline(s): %s; use --catch-up, or remove "
            "and reseed this legacy state file before resuming."
            % ", ".join(missing_baselines),
            file=sys.stderr,
        )
        return 2
    if two_phase and not args.catch_up:
        seeded = _saved_int(saved, "pr_cursor") is not None if args.new_prs else resumed
        if not seeded:
            print(
                "Managed first watch requires a state file seeded before the watched action.",
                file=sys.stderr,
            )
            return 2

    saved_pr_cursor = None if args.catch_up else _saved_int(saved, "pr_cursor")
    since_pr_id = args.since_pr_id if args.since_pr_id is not None else saved_pr_cursor
    tracked_head_sha = _saved_str(saved, "head_sha")
    # A state file from before the stall report has none, which reads as nothing
    # reported yet: a review already stuck then is reported on the first cycle.
    reported_stall = (_saved_str(saved, REVIEW_STALL_KEY) or "") if resumed else ""
    saved_stall_head = saved.get(REVIEW_STALL_HEAD_KEY) if resumed else None
    stall_head: dict[str, str] = (
        {
            "sha": str(saved_stall_head["sha"]),
            "at": str(saved_stall_head["at"]),
            "status": str(saved_stall_head.get("status") or ""),
        }
        if isinstance(saved_stall_head, dict)
        and isinstance(saved_stall_head.get("sha"), str)
        and _github_time(saved_stall_head.get("at")) is not None
        else {}
    )
    review_fingerprints = _saved_fingerprints(saved, REVIEW_FINGERPRINTS_KEY)
    review_comment_fingerprints = _saved_fingerprints(saved, REVIEW_COMMENT_FINGERPRINTS_KEY)
    issue_comment_fingerprints = _saved_fingerprints(saved, ISSUE_COMMENT_FINGERPRINTS_KEY)
    review_thread_states = _saved_review_thread_states(saved)
    latest_review_thread_states = dict((saved.get(SUCCESS_BATCH_KEY) or {}).get("thread_states", review_thread_states))
    # Normal monitoring always compares one complete normalized snapshot. Numeric
    # cursors, fingerprints, and thread maps only explain that change in the report;
    # they never decide independently whether to wake. Explicit replay/catch-up is
    # the deliberate exception: there the requested cursor streams are the contract.
    snapshot = None if args.catch_up or explicit_replay else (_saved_snapshot(saved) if resumed else None)
    if not ci_enabled:
        actions_snapshot = None
    elif args.catch_up:
        actions_snapshot = None
    elif explicit_replay:
        # Explicit cursor replay is a PR activity request, not a request to
        # replay an already observed terminal Actions result.
        actions_snapshot = normalize_selected_runs(selected_actions)
    elif resumed:
        actions_snapshot = normalize_selected_runs(_saved_actions_snapshot(saved))
    else:
        # Explicit PR cursor replay does not replay an unrelated already-terminal
        # Actions result. A fresh normal watch still needs the current CI snapshot
        # as its baseline to avoid waking on the seed itself.
        actions_snapshot = normalize_selected_runs(selected_actions)
    review_comment_since = (
        _saved_str(saved, "review_comment_since")
        if resumed and args.since_review_comment_id is None
        else None
    )
    issue_comment_since = (
        _saved_str(saved, "issue_comment_since")
        if resumed and args.since_issue_comment_id is None
        else None
    )

    def _pr_observation_snapshot(pr_state: dict[str, Any]) -> dict[str, Any]:
        return _normalized_pr_snapshot(
            pr_state, viewer_login=viewer_login,
            ignore_self_comments=not args.include_self_comments,
            actionable_only=args.actionable_only, ignored_authors=ignored_authors,
            ignore_patterns=ignore_patterns,
            committed_snapshot={"review_threads": dict(
                latest_review_thread_states if args.coalesce_success else review_thread_states
            )},
            review_threads_available=token is not None,
        )

    observed_head_sha = _current_pr_head_sha(state.get("pull_request"))

    if args.pr is not None and not resumed and not args.catch_up and not explicit_replay:
        tracked_head_sha = observed_head_sha
        review_fingerprints = _fingerprint_map(state["reviews"])
        review_comment_fingerprints = _fingerprint_map(state["review_comments"])
        issue_comment_fingerprints = _fingerprint_map(state["issue_comments"])
        if token is not None:
            raw_threads = state.get("review_threads")
            review_thread_states = _review_thread_state_map(
                raw_threads if isinstance(raw_threads, list) else []
            )
        snapshot = _pr_observation_snapshot(state)
        actions_snapshot = normalize_selected_runs(selected_actions) if ci_enabled else None

    # Explicit PR replay baselines CI at the current head, independently of the
    # historical PR cursor. Explicit seed likewise adopts the current snapshot.
    if ci_enabled and args.seed_state:
        actions_snapshot = normalize_selected_runs(selected_actions)
    actions_head_sha = observed_head_sha if explicit_replay or args.seed_state else tracked_head_sha
    actions_observed = (
        _observe_actions(
            # Only a normal resume inherits old inventory. Replaying or
            # establishing a fresh baseline must not retain omitted old runs.
            {} if not resumed or args.seed_state or explicit_replay else (
                _saved_actions_snapshot(saved, ACTIONS_OBSERVED_KEY)
                if ACTIONS_OBSERVED_KEY in saved else _saved_actions_snapshot(saved)
            ),
            normalize_selected_runs(selected_actions),
            args.sha or observed_head_sha,
            preserve_terminal=args.coalesce_success,
        )
        if ci_enabled else {}
    )

    def _visible_success_state() -> dict[str, Any]:
        visible = dict(state)
        for kind in ("reviews", "review_comments", "issue_comments"):
            visible[kind] = _visible_activity_items(
                state[kind], viewer_login=viewer_login,
                ignore_self_comments=not args.include_self_comments,
                ignored_authors=ignored_authors, ignore_patterns=ignore_patterns,
            )
        return visible

    success_batch = (
        saved.get(SUCCESS_BATCH_KEY) or {
            "head_sha": tracked_head_sha or observed_head_sha, "review": None,
            "outcome": None, "notified": None, "reaction_seen": _saved_int(saved, "reaction_cursor") or 0,
        }
    ) if args.coalesce_success else None
    if args.coalesce_success and token is not None:
        latest_review_thread_states = _review_thread_state_map(state.get("review_threads") or [])
    if args.coalesce_success and (args.seed_state or not resumed or explicit_replay):
        # Deliberate replay must not rebuild monotonic review history from the
        # current response: omitted rows can otherwise resurrect an older pass
        # over a newer invalidating outcome. A seed is an explicit new baseline.
        prior_success_batch = success_batch if (args.catch_up or explicit_replay) else None
        success_batch, _ = _coalesced_review_state(
            _visible_success_state(), prior_success_batch, snapshot, initialize=True,
            reaction_cursor=_saved_int(saved, "reaction_cursor") or 0,
        )
        _baseline_output, baseline_failed = render_actions_result(
            repo=args.repo, branch=args.branch, head_sha=args.sha or observed_head_sha,
            selected=selected_actions, success_conclusions=success_conclusions,
        )
        if (
            not args.catch_up and success_batch["review"] and _baseline_output and not baseline_failed
            and all(_pr_observation_snapshot(state)["review_threads"].values())
        ):
            success_batch["notified"] = _combined_success_signature(selected_actions, success_batch)
    if args.coalesce_success:
        success_batch = {**success_batch, "thread_states": dict(latest_review_thread_states)}
    success_observed = success_batch
    success_observation_snapshot = snapshot
    success_observation_state = None
    success_revoked = False

    if token is None:
        bootstrap_requests = requests_per_poll_count
        unauthenticated_min = min_interval_for_unauthenticated(
            requests_per_poll_count,
            bootstrap_requests=bootstrap_requests,
        )
        startup_interval = max(base_interval, unauthenticated_min)
        if effective_interval < startup_interval:
            print(
                (
                    "No GitHub token detected; clamping polling interval from %.1fs to %.1fs "
                    "for %s request(s) per poll plus %s bootstrap request(s) to avoid "
                    "unauthenticated rate-limit lockout."
                )
                % (effective_interval, startup_interval, requests_per_poll_count, bootstrap_requests),
                file=sys.stderr,
            )
            effective_interval = startup_interval
    else:
        bootstrap_requests = 0

    if args.pr is not None:

        def _active_ci_head_sha() -> str:
            return args.sha or _current_pr_head_sha(state.get("pull_request"))

        def _same_actions_head() -> bool:
            return actions_head_sha is not None and actions_head_sha.casefold() == _active_ci_head_sha().casefold()

        def _initial_cursor(flag_value: int | None, saved_key: str, items_key: str) -> int:
            if flag_value is not None:
                return flag_value
            if resumed:
                return resume_cursors[saved_key] or 0
            return 0 if args.catch_up else max_id(state[items_key])

        review_cursor = _initial_cursor(args.since_review_id, "review_cursor", "reviews")
        review_comment_cursor = _initial_cursor(
            args.since_review_comment_id, "review_comment_cursor", "review_comments"
        )
        issue_comment_cursor = _initial_cursor(
            args.since_issue_comment_id, "issue_comment_cursor", "issue_comments"
        )
        reaction_cursor = _initial_cursor(args.since_reaction_id, "reaction_cursor", "reactions")
        pr_status = (
            args.since_pr_status
            or (_saved_str(saved, "pr_status") if resumed else None)
            or _current_pr_status(state.get("pull_request"))
        )

        print(
            (
                "Watching GitHub PR %s#%s from cursors: review=%s review_comment=%s issue_comment=%s reaction=%s pr_status=%s catch_up=%s resumed=%s"
                % (
                    args.repo,
                    args.pr,
                    review_cursor,
                    review_comment_cursor,
                    issue_comment_cursor,
                    reaction_cursor,
                    pr_status,
                    args.catch_up,
                    resumed,
                )
            ),
            file=sys.stderr,
        )

        def _observe_success_state() -> None:
            nonlocal success_observed, success_observation_snapshot, success_observation_state, success_revoked
            nonlocal latest_review_thread_states
            if not args.coalesce_success or state is success_observation_state:
                return
            visible = _visible_success_state()
            if token is not None:
                latest_review_thread_states = _review_thread_state_map(visible.get("review_threads") or [])
            success_observed, revoked = _coalesced_review_state(
                visible, success_observed, success_observation_snapshot, reaction_cursor=reaction_cursor,
            )
            success_observed["thread_states"] = dict(latest_review_thread_states)
            success_revoked = success_revoked or revoked
            success_observation_snapshot = _pr_observation_snapshot(visible)
            success_observation_state = state

        def _active_actions() -> dict[str, list[dict[str, Any]]]:
            if not args.coalesce_success:
                return selected_actions
            active = _without_older_attempts(selected_actions, actions_observed)
            for workflow, observed_runs in actions_observed.items():
                by_id = {run["id"]: run for run in active.get(workflow, [])}
                for run in observed_runs:
                    if run.get("status") == "completed" and run.get("conclusion") not in success_conclusions:
                        payload = by_id.get(run["id"], {})
                        by_id[run["id"]] = {
                            **payload, **run, "name": workflow,
                            "html_url": payload.get("html_url") or f"https://github.com/{args.repo}/actions/runs/{run['id']}",
                        }
                active[workflow] = list(by_id.values())
            return active

        def _render(cursors: tuple[int, int, int, int, str]) -> PRReport:
            activity = _render_activity(
                repo=args.repo,
                pr_number=args.pr,
                state=state,
                review_cursor=cursors[0],
                review_comment_cursor=cursors[1],
                issue_comment_cursor=cursors[2],
                reaction_cursor=cursors[3],
                pr_status=cursors[4],
                event_limit=args.event_limit,
                previous_head_sha=tracked_head_sha,
                snapshot=snapshot,
                review_fingerprints=dict(review_fingerprints),
                review_comment_fingerprints=dict(review_comment_fingerprints),
                issue_comment_fingerprints=dict(issue_comment_fingerprints),
                review_thread_states=review_thread_states,
                review_threads_available=token is not None,
                viewer_login=viewer_login,
                ignore_self_comments=not args.include_self_comments,
                actionable_only=args.actionable_only,
                ignored_authors=ignored_authors,
                ignore_patterns=ignore_patterns,
                coalesce_success=args.coalesce_success and not (args.catch_up or explicit_replay),
            )
            return PRReport(activity[0], activity[1:], state)

        def _render_combined(
            cursors: tuple[int, int, int, int, str],
            *,
            fallback_pr: PRReport | None = None,
        ) -> PRReport:
            pr_result = _render(cursors)
            if pr_result.output is None and fallback_pr is not None and fallback_pr.output is not None:
                pr_result = fallback_pr
            if not ci_enabled:
                return pr_result

            _observe_success_state()
            if args.coalesce_success:
                batch = dict(success_observed)
                # Observation history is independently head-tagged. Preserve a
                # fresh latest-head verdict even when the PR report retains an
                # older head event; the CI guard below still forbids mixing them.
                pr_result = pr_result._replace(success_batch=batch)

            # A transient PR head can itself be retained as evidence. Never
            # attach another head's CI verdict to that observation's baseline.
            if _current_pr_head_sha(pr_result.pr_state.get("pull_request")).casefold() != (
                _current_pr_head_sha(state.get("pull_request")).casefold()
            ):
                return pr_result

            if args.coalesce_success:
                if success_revoked and batch.get("review") is None and pr_result.output is None:
                    pr_result = pr_result._replace(output=(
                        f"Codex review evidence changed or was removed for {args.repo}#{args.pr}; "
                        "re-evaluate the current head."
                    ))
                ci_output, failed = render_actions_result(
                    repo=args.repo, branch=args.branch, head_sha=_active_ci_head_sha(),
                    selected=_active_actions(), success_conclusions=success_conclusions,
                    fail_fast=True,
                )
                unresolved = not all(success_observation_snapshot["review_threads"].values())
                if failed or unresolved:
                    batch["notified"] = None
                elif (
                    ci_output and batch.get("review")
                    and str(batch["head_sha"]).casefold() == _active_ci_head_sha().casefold()
                    and not _actions_snapshot_regressed(normalize_selected_runs(selected_actions), actions_observed)
                ):
                    signature = _combined_success_signature(selected_actions, batch)
                    if batch.get("notified") != signature:
                        evidence = batch["review"]
                        item = next(item for item in state[evidence["kind"]] if item.get("id") == evidence["id"])
                        formatter = {
                            "reviews": _format_review, "issue_comments": _format_issue_comment,
                            "reactions": _format_reaction,
                        }[evidence["kind"]]
                        output = (
                            f"CI + Codex review success candidate for {args.repo}#{args.pr}"
                            f"@{_active_ci_head_sha()[:12]}; verify all delivery gates before close-out.\n"
                            f"{formatter(item)}\n{ci_output}"
                        )
                        if pr_result.output:
                            output = f"{pr_result.output}\n{output}"
                        batch["notified"] = signature
                        return pr_result._replace(
                            output=output, actions=normalize_selected_runs(selected_actions),
                        )
                # A green CI result alone must not advance its delivery baseline.
                # The review evidence above is still adopted on quiet/problem polls.
                # A reported verdict the waiter could not classify is the Agent's to
                # judge, so the green result that judgment may be waiting on is reported.
                if not failed and not (
                    ci_output and not unresolved
                    and str(batch["head_sha"]).casefold() == _active_ci_head_sha().casefold()
                    and _awaits_review_judgment(state, batch)
                ):
                    return pr_result

            actions_output = _render_new_actions()
            if actions_output is None:
                return pr_result
            reported_actions = normalize_selected_runs(_active_actions())
            output = actions_output if pr_result.output is None else f"{pr_result.output}\n{actions_output}"
            return pr_result._replace(
                output=output, actions=reported_actions, failed_actions=args.coalesce_success and failed,
            )

        def _render_new_actions() -> str | None:
            active_actions = _active_actions()
            current_actions = normalize_selected_runs(active_actions)
            # A push starts a new CI epoch even if it returns to an earlier SHA.
            previous = actions_snapshot if _same_actions_head() else None
            if previous is not None and current_actions == previous:
                return None
            output, failed = render_actions_result(
                repo=args.repo,
                branch=args.branch,
                head_sha=_active_ci_head_sha(),
                selected=active_actions,
                success_conclusions=success_conclusions,
                fail_fast=args.coalesce_success,
            )
            if _actions_snapshot_regressed(current_actions, actions_observed) and not (args.coalesce_success and failed):
                return None
            if args.coalesce_success and failed and previous is not None:
                # Other workflows finishing must not reannounce the same failure.
                known = {
                    (workflow, run["id"]): run for workflow, runs in previous.items() for run in runs
                }
                failures = [
                    (workflow, run) for workflow, runs in current_actions.items() for run in runs
                    if run.get("status") == "completed" and run.get("conclusion") not in success_conclusions
                ]
                if all(known.get((workflow, run["id"])) == run for workflow, run in failures):
                    return None
            return output

        def _advance_actions_baseline(report: PRReport) -> None:
            nonlocal actions_snapshot, actions_head_sha
            if not ci_enabled:
                return
            # Only a reported terminal result advances the notification baseline.
            # Quiet polls and PR-only reports must not erase an acknowledged CI
            # result. The existing pending transaction covers this state too.
            report_head = args.sha or _current_pr_head_sha(report.pr_state.get("pull_request"))
            if report.actions is not None:
                actions_snapshot = (
                    _observe_actions(actions_snapshot or {}, report.actions, report_head, preserve_terminal=True)
                    if args.coalesce_success else report.actions
                )
            elif actions_head_sha is None or actions_head_sha.casefold() != report_head.casefold():
                actions_snapshot = {workflow: [] for workflow in args.workflow}
            actions_head_sha = report_head

        def _refresh_actions() -> None:
            nonlocal selected_actions, actions_observed
            if ci_enabled:
                selected_actions = select_matching_runs(
                    state.get("actions", []),
                    workflows=args.workflow or [],
                    branch=args.branch,
                    head_sha=_active_ci_head_sha(),
                )
                actions_observed = _observe_actions(
                    actions_observed, normalize_selected_runs(selected_actions), _active_ci_head_sha(),
                    preserve_terminal=args.coalesce_success,
                )
            _observe_success_state()

        def _actions_waiting_for_terminal_result() -> bool:
            if not ci_enabled:
                return False
            current_actions = normalize_selected_runs(selected_actions)
            previous = actions_snapshot if _same_actions_head() else None
            actions_output, failed = render_actions_result(
                repo=args.repo,
                branch=args.branch,
                head_sha=_active_ci_head_sha(),
                selected=_active_actions(),
                success_conclusions=success_conclusions,
                fail_fast=args.coalesce_success,
            )
            if args.coalesce_success and failed:
                return False
            if _actions_snapshot_regressed(current_actions, actions_observed):
                return True
            if previous is not None and current_actions == previous:
                return False
            return actions_output is None

        def _with_review_stall(output: str | None) -> str | None:
            """Add a Codex review stall not yet reported to this cycle's output.

            Called after the cycle's ``pre_event_fields`` were taken, so a staged report
            keeps the previous stall key committed until its delivery is confirmed.
            """
            nonlocal reported_stall, stall_head
            now = _utc_now()
            head = _current_pr_head_sha(state.get("pull_request"))
            pr_status = _current_pr_status(state.get("pull_request"))
            # The clock of a head starts when the head appears, and again when the PR
            # becomes reviewable (draft or closed to open): a review is expected only from then.
            if head and (
                stall_head.get("sha", "").casefold() != head.casefold()
                or (pr_status == "open" and stall_head.get("status") != "open")
            ):
                stall_head = {"sha": head, "at": now.isoformat(), "status": pr_status}
            elif head:
                stall_head = {**stall_head, "status": pr_status}
            if args.seed_state or args.catch_up or explicit_replay or not head:
                return output
            stall = _codex_review_stall(
                state,
                repo=args.repo,
                stall_seconds=args.review_stall_minutes * 60,
                now=now,
                head_seen_at=_github_time(stall_head["at"]) or now,
            )
            if stall is None or stall[0] == reported_stall:
                return output
            reported_stall = stall[0]
            return stall[1] if output is None else f"{output}\n\n{stall[1]}"

        def _adopt_report(report: PRReport) -> None:
            nonlocal review_cursor, review_comment_cursor, issue_comment_cursor, reaction_cursor, pr_status
            nonlocal observed_head_sha, snapshot, success_batch
            nonlocal review_fingerprints, review_comment_fingerprints, issue_comment_fingerprints, review_thread_states
            nonlocal review_comment_since, issue_comment_since
            review_cursor, review_comment_cursor, issue_comment_cursor, reaction_cursor, pr_status = report.cursors
            pr_state = report.pr_state
            observed_head_sha = _current_pr_head_sha(pr_state.get("pull_request"))
            review_comment_since = later_since(review_comment_since, pr_state["review_comments"])
            issue_comment_since = later_since(issue_comment_since, pr_state["issue_comments"])
            review_fingerprints = _fingerprint_map(pr_state["reviews"])
            review_comment_fingerprints = _fingerprint_map(pr_state["review_comments"])
            issue_comment_fingerprints = _fingerprint_map(pr_state["issue_comments"])
            if token is not None:
                raw_threads = pr_state.get("review_threads")
                review_thread_states = _review_thread_state_map(
                    raw_threads if isinstance(raw_threads, list) else []
                )
            snapshot = _pr_observation_snapshot(pr_state)
            _advance_actions_baseline(report)
            if report.success_batch is not None:
                success_batch = report.success_batch

        def _pr_state_fields() -> dict[str, Any]:
            fields = {
                "review_cursor": review_cursor,
                "review_comment_cursor": review_comment_cursor,
                "issue_comment_cursor": issue_comment_cursor,
                "reaction_cursor": reaction_cursor,
                "pr_status": pr_status,
                "review_comment_since": review_comment_since,
                "issue_comment_since": issue_comment_since,
                "viewer_login": viewer_login,
                "token_fingerprint": token_fingerprint,
                "head_sha": observed_head_sha,
                REVIEW_FINGERPRINTS_KEY: dict(review_fingerprints),
                REVIEW_COMMENT_FINGERPRINTS_KEY: dict(review_comment_fingerprints),
                ISSUE_COMMENT_FINGERPRINTS_KEY: dict(issue_comment_fingerprints),
                REVIEW_THREAD_STATES_KEY: dict(review_thread_states),
                PR_SNAPSHOT_KEY: snapshot or {},
                REVIEW_STALL_KEY: reported_stall,
                REVIEW_STALL_HEAD_KEY: dict(stall_head),
            }
            if ci_enabled:
                fields[ACTIONS_SNAPSHOT_KEY] = actions_snapshot or {workflow: [] for workflow in args.workflow}
                fields[ACTIONS_OBSERVED_KEY] = actions_observed
            if args.coalesce_success:
                fields[SUCCESS_BATCH_KEY] = success_batch
            return fields

        def _persist_pr_state(
            *,
            previous: dict[str, Any] | None = None,
            output: str | None = None,
        ) -> None:
            fields = _pr_state_fields()
            if previous is not None:
                # Committed state stays where the reported event is still unseen; the
                # cursors past it wait under STAGED_KEY, stamped with the delivery this
                # waiter started from so a later cycle can tell whether it has moved.
                fields = {
                    **previous,
                    STAGED_KEY: {
                        "delivered_after": delivery_stamp,
                        "output": output,
                        "cursors": fields,
                    },
                }
            _write_state_file(
                args.state_file,
                repo=args.repo,
                pr_number=args.pr,
                watch_identity=watch_identity,
                watch_id=watch_id,
                watch_identity_aliases=watch_identity_aliases,
                **fields,
            )

        def _report_pr(output: str, previous: dict[str, Any]) -> None:
            """Hand one report to the supervisor, staging or committing to match.

            Under ``vibe watch`` the cursors covering the event are staged first, so a
            crash before the supervisor queues the follow-up replays the report instead
            of skipping it. A manual run has no next cycle to promote anything, and
            printing there is the delivery, so it commits straight after.
            """

            if two_phase:
                _persist_pr_state(previous=previous, output=output)
                _deliver(output)
                return
            _deliver(output)
            _persist_pr_state()

        def _settle(
            first: PRReport,
            pending: tuple[int, int, int, int, str],
        ) -> PRReport:
            """Re-poll while a batch is still landing so it costs one Agent turn."""

            nonlocal state
            if settle_seconds <= 0 or first.failed_actions:
                return first

            best = first
            best_pr = _render(pending)

            def _fallback() -> PRReport:
                # Revalidate against the latest successful poll, not a transient
                # earlier candidate that may now equal the delivered baseline.
                # PR evidence remains at-least-once even if a later collection
                # omits it; only the provisional CI verdict can be withdrawn.
                return _render_combined(pending, fallback_pr=best_pr)

            for _round in range(SETTLE_MAX_ROUNDS):
                # The batch is already worth a turn, so waiting for the rest of it must
                # not push the waiter past its own deadline: `vibe watch` kills the
                # process on timeout and the report would be lost with it. The sleep is
                # only half the cost — the re-poll behind it is several sequential
                # requests, each free to block for REQUEST_TIMEOUT_SECONDS — so both
                # have to fit in what is left, not just the sleep.
                if args.timeout > 0:
                    remaining = args.timeout - (time.monotonic() - start)
                    repoll_budget = max(1, requests_per_poll_count) * REQUEST_TIMEOUT_SECONDS
                    if remaining <= settle_seconds + repoll_budget:
                        print(
                            "Settle window plus its re-poll would outlast --timeout; "
                            "reporting the batch seen so far.",
                            file=sys.stderr,
                        )
                        return _fallback()
                time.sleep(settle_seconds)
                settle_request = github_request(
                    lambda: _fetch_state(
                        args.repo,
                        args.pr,
                        token,
                        cache=cache,
                        ci_sha=args.sha if ci_enabled else None,
                        ci_branch=args.branch if ci_enabled else None,
                        ci_workflows=args.workflow if ci_enabled else None,
                        ci_max_pages=args.max_pages,
                    ),
                    unauthenticated=token is None,
                )
                if settle_request.error is not None:
                    # Settling only coalesces a batch. Once an event is known, no
                    # enrichment failure may suppress it; the follow-up re-fetches
                    # live state and can handle a terminal API problem explicitly.
                    print(
                        f"Settle re-poll failed: {settle_request.error}; reporting the batch seen so far.",
                        file=sys.stderr,
                    )
                    return _fallback()
                if settle_request.value is None:
                    print(
                        "Settle re-poll returned no state; reporting the batch seen so far.",
                        file=sys.stderr,
                    )
                    return _fallback()
                state, _count = settle_request.value
                _refresh_actions()
                pr_candidate = _render(pending)
                if pr_candidate.output is not None:
                    best_pr = pr_candidate
                if _actions_waiting_for_terminal_result():
                    continue
                # Rendered from the same cursors as the first hit, so the result is a
                # superset rather than a second, partial report.
                candidate = _fallback()
                if candidate.failed_actions:
                    return candidate
                if candidate.output is None:
                    return candidate
                if candidate.cursors == best.cursors:
                    return candidate
                best = candidate
            return _fallback()

        pending_cursors = (
            review_cursor,
            review_comment_cursor,
            issue_comment_cursor,
            reaction_cursor,
            pr_status,
        )
        # Until a report is adopted, the committed PR head must stay paired
        # with the saved snapshot, even if the first fetch already saw a push.
        observed_head_sha = tracked_head_sha or observed_head_sha
        pre_event_fields = _pr_state_fields()
        initial_result = (
            PRReport(None, pending_cursors, state)
            if args.seed_state
            else _render_combined(pending_cursors)
        )
        if initial_result.output is not None and not args.catch_up:
            initial_result = _settle(initial_result, pending_cursors)
        initial_output = initial_result.output
        _adopt_report(initial_result)
        initial_output = _with_review_stall(initial_output)
        if initial_output is None:
            # Persisted even with nothing to report: the baseline this cycle
            # established is exactly what the next cycle must resume from.
            _persist_pr_state()
            tracked_head_sha = observed_head_sha
            if args.seed_state:
                print(f"Seeded GitHub PR baseline in {args.state_file}", file=sys.stderr)
                return 0
        else:
            _write_cursor_output(
                args.cursor_output,
                review_cursor=review_cursor,
                review_comment_cursor=review_comment_cursor,
                issue_comment_cursor=issue_comment_cursor,
                reaction_cursor=reaction_cursor,
                pr_status=pr_status,
            )
            _report_pr(initial_output, pre_event_fields)
            return 0
    else:
        pr_cursor = since_pr_id if since_pr_id is not None else (0 if args.catch_up else max_id(state["pull_requests"]))
        print(
            f"Watching GitHub new PRs in {args.repo} from cursor: pr={pr_cursor} catch_up={args.catch_up}",
            file=sys.stderr,
        )
        pre_event_pr_cursor = pr_cursor
        initial_output, pr_cursor = _render_new_pull_requests(
            repo=args.repo,
            state=state,
            pr_cursor=pr_cursor,
            event_limit=args.event_limit,
        )
        def _persist_new_pr_state(
            *,
            previous: int | None = None,
            output: str | None = None,
        ) -> None:
            fields: dict[str, Any] = {"pr_cursor": pr_cursor}
            if previous is not None:
                fields = {
                    "pr_cursor": previous,
                    STAGED_KEY: {
                        "delivered_after": delivery_stamp,
                        "output": output,
                        "cursors": {"pr_cursor": pr_cursor},
                    },
                }
            _write_state_file(
                args.state_file,
                repo=args.repo,
                pr_number=None,
                watch_identity=watch_identity,
                watch_id=watch_id,
                **fields,
            )

        def _report_new_pr(output: str, previous: int) -> None:
            """Same staging contract as ``_report_pr``, over the single new-PR cursor."""

            if two_phase:
                _persist_new_pr_state(previous=previous, output=output)
                _deliver(output)
                return
            _deliver(output)
            _persist_new_pr_state()

        if initial_output is None:
            _persist_new_pr_state()
            if args.seed_state:
                print(f"Seeded GitHub repository PR baseline in {args.state_file}", file=sys.stderr)
                return 0
        else:
            _write_new_pr_cursor_output(args.cursor_output, pr_cursor=pr_cursor)
            _report_new_pr(initial_output, pre_event_pr_cursor)
            return 0

    while True:
        sleep_seconds = effective_interval
        if args.timeout > 0:
            remaining_timeout = args.timeout - (time.monotonic() - start)
            if remaining_timeout <= 0:
                print("Timed out while waiting for GitHub PR activity", file=sys.stderr)
                print(cache.summary(), file=sys.stderr)
                return 124
            sleep_seconds = min(sleep_seconds, remaining_timeout)

        time.sleep(sleep_seconds)

        if args.pr is not None:
            poll_request = github_request(
                lambda: _fetch_state(
                    args.repo,
                    args.pr,
                    token,
                    cache=cache,
                    ci_sha=args.sha if ci_enabled else None,
                    ci_branch=args.branch if ci_enabled else None,
                    ci_workflows=args.workflow if ci_enabled else None,
                    ci_max_pages=args.max_pages,
                ),
                unauthenticated=token is None,
            )
        else:
            poll_request = github_request(
                lambda: _fetch_new_pr_state(
                    args.repo,
                    token,
                    stop_after_id=pr_cursor if pr_cursor > 0 else None,
                    cache=cache,
                ),
                unauthenticated=token is None,
            )
        if poll_request.error is not None:
            print(f"GitHub polling failed: {poll_request.error}", file=sys.stderr)
            if poll_request.error.retryable:
                print(
                    "Retryable GitHub request failure; continuing in this watch",
                    file=sys.stderr,
                )
                continue
            return 1
        if poll_request.value is None:
            print("GitHub polling completed without a result", file=sys.stderr)
            return 1
        state, requests_per_poll_count = poll_request.value

        if token is None:
            unauthenticated_min = min_interval_for_unauthenticated(requests_per_poll_count)
            target_interval = max(base_interval, unauthenticated_min)
            if target_interval != effective_interval:
                if target_interval > effective_interval:
                    print(
                        (
                            "GitHub unauthenticated polling now needs %.1fs minimum for %s request(s) "
                            "per poll; increasing interval."
                        )
                        % (target_interval, requests_per_poll_count),
                        file=sys.stderr,
                    )
                else:
                    print(
                        (
                            "GitHub unauthenticated polling now needs only %.1fs minimum for %s request(s) "
                            "per poll; reducing interval."
                        )
                        % (target_interval, requests_per_poll_count),
                        file=sys.stderr,
                    )
                effective_interval = target_interval

        if args.pr is not None:
            _refresh_actions()
            pending_cursors = (
                review_cursor,
                review_comment_cursor,
                issue_comment_cursor,
                reaction_cursor,
                pr_status,
            )
            pre_event_fields = _pr_state_fields()
            result = _render_combined(pending_cursors)
            if result.output is not None:
                result = _settle(result, pending_cursors)
            output = result.output
            _adopt_report(result)
            output = _with_review_stall(output)
            if output is None:
                # Cursors also move when everything new was filtered out, and that
                # progress has to survive the cycle or the next one re-examines it.
                # Nothing is being reported, so there is no delivery to wait for.
                _persist_pr_state()
                tracked_head_sha = observed_head_sha
                continue

            _write_cursor_output(
                args.cursor_output,
                review_cursor=review_cursor,
                review_comment_cursor=review_comment_cursor,
                issue_comment_cursor=issue_comment_cursor,
                reaction_cursor=reaction_cursor,
                pr_status=pr_status,
            )
            report = partial(_report_pr, previous=pre_event_fields)
        else:
            pre_event_pr_cursor = pr_cursor
            output, pr_cursor = _render_new_pull_requests(
                repo=args.repo,
                state=state,
                pr_cursor=pr_cursor,
                event_limit=args.event_limit,
            )
            if output is None:
                _persist_new_pr_state()
                continue
            _write_new_pr_cursor_output(args.cursor_output, pr_cursor=pr_cursor)
            report = partial(_report_new_pr, previous=pre_event_pr_cursor)

        print(cache.summary(), file=sys.stderr)
        report(output)
        return 0


def run_cli() -> int:
    """``main`` plus the terminal handling of an unusable ``--state-file``.

    Exit 1 and not the retryable 75: a directory that cannot be written to, a path
    already owned by another PR, and a file whose cursors cannot be read do not start
    working on the next cycle, and a forever watch retrying into one would poll
    indefinitely while losing the activity it saw.
    """

    try:
        return main()
    except StateFileError as err:
        print(
            f"{err}. Give this watch its own --state-file path (or fix or remove "
            "this one), then recreate the watch.",
            file=sys.stderr,
        )
        return 1


if __name__ == "__main__":
    raise SystemExit(run_cli())