Skip Stale-labeled PRs in review scan

- Carry PR labels onto OpenPR from the get_pulls payload (no extra API call)
- Add STALE_LABEL/EXCLUDED_LABELS constants; case-sensitive exact "Stale"
- Fold Stale-label pruning into _recency_filter via stale_labeled_numbers
- Keep in-flight/retry-eligible and --pr recheck targets exempt from the skip
- Refresh README/CHEATSHEET/CLAUDE.md and add github_client + review tests

The pytorch stale bot bumps updated_at when it applies the "Stale" label,
which drags abandoned, never-reviewed PRs back inside the recency window and
gets them dispatched. Pruning on the label closes that hole: a Stale-labeled
PR is skipped without fingerprinting when it is terminal or never reviewed,
while a non-terminal ledger state still survives so decide can re-dispatch on
timeout/retry. A single --pr target bypasses listing, so the label can never
suppress a manual @greenlight recheck.

Signed-off-by: Jean Schmidt <contato@jschmidt.me>

Author: jeanschmidt

greenlight/CHEATSHEET.md

@@ -11,8 +11,9 @@ loops as a daemon with `--loop`. It also has a one-shot `verdict` subcommand:
   for each, compute its fingerprint (`eval_hash`), read its latest state from
   `misc.greenlight_pr_state`, and dispatch the reviewer workflow
   (`greenlight-pr-review.yml` on `pytorch/test-infra`) for new or changed PRs. A PR whose
-  `updated_at` is older than `PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS` (default 24) is skipped
-  without fingerprinting unless a review is in-flight or retry-eligible (cancelled/failed). A PR a
+  `updated_at` is older than `PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS` (default 24), or that carries
+  the `Stale` label, is skipped without fingerprinting unless a review is in-flight or retry-eligible
+  (cancelled/failed); an explicit `@greenlight recheck` (the `--pr` path) reviews it regardless. A PR a
   human has already decided — approved by a `merge_rules.yaml` approver (bots excluded) or with
   changes requested by any non-bot reviewer — is also skipped without fingerprinting or dispatch,
   and no state is written, so the scan resumes if that changes. Needs
@@ -113,10 +114,11 @@ logs the resolved `Config`.
 The end-to-end flow, per trusted-author PR:
 
 1. `review` scans the open PRs, and for each computes its fingerprint (`eval_hash`) — unless
-   the PR's `updated_at` is older than `PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS` (default 24)
-   and it has no in-flight or retry-eligible (cancelled/failed) review, or a human has already
-   decided it (approved by a `merge_rules.yaml` approver with bots excluded, or changes requested
-   by any non-bot reviewer), in which case it is skipped without fingerprinting.
+   the PR's `updated_at` is older than `PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS` (default 24) or it
+   carries the `Stale` label, and it has no in-flight or retry-eligible (cancelled/failed) review,
+   or a human has already decided it (approved by a `merge_rules.yaml` approver with bots excluded,
+   or changes requested by any non-bot reviewer), in which case it is skipped without fingerprinting
+   (an explicit `@greenlight recheck` via `--pr` reviews it regardless).
 2. It reads the PR's latest recorded state from `misc.greenlight_pr_state`.
 3. If the PR is new, or its fingerprint changed since that state, and no review is
    in-flight within the `--timeout-minutes` window, it dispatches the reviewer workflow

greenlight/CLAUDE.md

@@ -53,9 +53,10 @@ PyTorch Green Light has one unit of work — the `review` phase:
   fingerprint (`eval_hash`), reads the PR's latest state from `misc.greenlight_pr_state`,
   and dispatches the reviewer workflow (`greenlight-pr-review.yml` on `pytorch/test-infra`)
   for new or changed PRs, skipping any PR untouched beyond `PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS`
-  (default 24) that has no in-flight or retry-eligible (cancelled/failed) review, and skipping —
-  without fingerprinting or dispatching — any PR a human has already decided (approved by a
-  `merge_rules.yaml` approver, bots excluded, or changes requested by any non-bot reviewer).
+  (default 24) or carrying the `Stale` label that has no in-flight or retry-eligible
+  (cancelled/failed) review, and skipping — without fingerprinting or dispatching — any PR a human
+  has already decided (approved by a `merge_rules.yaml` approver, bots excluded, or changes
+  requested by any non-bot reviewer).
   Requires `PYTORCH_GREENLIGHT_GITHUB_TOKEN` and `CLICKHOUSE_*` read access.
 
 Approving or rejecting a PR lives in the dispatched reviewer workflow (through `verdict`),

greenlight/README.md

@@ -26,9 +26,11 @@ trusted authors in `pytorch/pytorch` and, for each one, computes its fingerprint
 `misc.greenlight_pr_state`, and dispatches the reviewer workflow
 (`greenlight-pr-review.yml` on `pytorch/test-infra`) for PRs that are new or changed since
 their last review. A PR whose `updated_at` is older than
-`PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS` (default 24) is skipped without fingerprinting unless
-it has an in-flight or retry-eligible (cancelled/failed) review to re-check. An in-flight review — one marked
-`AI_REVIEW_STARTED` — is left alone until the `--timeout-minutes` re-dispatch window elapses.
+`PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS` (default 24), or that carries the `Stale` label, is
+skipped without fingerprinting unless it has an in-flight or retry-eligible (cancelled/failed)
+review to re-check; an explicit `@greenlight recheck` (the `--pr` path) reviews it regardless. An
+in-flight review — one marked `AI_REVIEW_STARTED` — is left alone until the `--timeout-minutes`
+re-dispatch window elapses.
 The listing scan also skips a PR a human has already decided — approved by a merge-authorized
 login (any `approved_by` in `pytorch/pytorch`'s `merge_rules.yaml`, taken across all rules
 regardless of the PR's changed paths, bots excluded) or with changes requested by any non-bot
@@ -152,8 +154,9 @@ from a fixed set of trusted authors in `pytorch/pytorch`, computes each PR's fin
 (`eval_hash`), reads the PR's latest recorded state from `misc.greenlight_pr_state`, and
 dispatches the reviewer workflow (`greenlight-pr-review.yml` on `pytorch/test-infra`) for
 PRs that are new or changed. PRs whose `updated_at` is older than the review window
-(`PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS`, default 24) are skipped without fingerprinting
-unless a review is in-flight or retry-eligible (cancelled/failed). PRs a human has already decided
+(`PYTORCH_GREENLIGHT_REVIEW_WINDOW_HOURS`, default 24), or that carry the `Stale` label, are
+skipped without fingerprinting unless a review is in-flight or retry-eligible (cancelled/failed);
+an explicit `@greenlight recheck` (the `--pr` path) reviews such a PR regardless. PRs a human has already decided
 — approved by a merge-authorized login (bots excluded) or with changes requested by any non-bot
 reviewer — are also skipped without fingerprinting, and no state is written, so the scan resumes
 if that changes. An `AI_REVIEW_STARTED` marker is treated as an

greenlight/src/greenlight/constants.py

@@ -15,6 +15,10 @@
 RETRY_STATUSES: frozenset[str] = frozenset({STATUS_CANCELLED, STATUS_FAILED})
 VERDICT_STATUSES: frozenset[str] = TERMINAL_STATUSES | IN_FLIGHT_STATUSES | RETRY_STATUSES
 
+# GitHub labels are case-sensitive; the pytorch stale bot uses the exact name "Stale".
+STALE_LABEL = "Stale"
+EXCLUDED_LABELS: frozenset[str] = frozenset({STALE_LABEL})
+
 S3_KEY_PREFIX = "greenlight_pr_state"
 EVAL_HASH_RE = re.compile(r"[0-9a-f]{64}")
 HEAD_SHA_RE = re.compile(r"[0-9a-fA-F]{40}")

greenlight/src/greenlight/github_client.py

@@ -25,6 +25,10 @@ class _PRUser(Protocol):
         @property
         def login(self) -> str | None: ...
 
+    class _Label(Protocol):
+        @property
+        def name(self) -> str: ...
+
     class _PullRequest(Protocol):
         @property
         def number(self) -> int: ...
@@ -38,6 +42,8 @@ def html_url(self) -> str: ...
         def head(self) -> _PRBase: ...
         @property
         def updated_at(self) -> datetime | None: ...
+        @property
+        def labels(self) -> Iterable[_Label]: ...
 
     class _Repo(Protocol):
         def get_pulls(self, state: str) -> Iterable[_PullRequest]: ...
@@ -142,6 +148,7 @@ class OpenPR:
     url: str
     head_sha: str
     updated_at: datetime | None
+    labels: tuple[str, ...] = ()
 
 
 # Pin the request timeout so a future PyGithub default change can't let
@@ -175,6 +182,7 @@ def list_open_prs_by_authors(client: _RepoClient, repo: str, authors: Iterable[s
                     url=pr.html_url,
                     head_sha=pr.head.sha,
                     updated_at=naive_utc(updated_at) if updated_at is not None else None,
+                    labels=tuple(label.name for label in pr.labels),
                 )
             )
     return sorted(prs, key=lambda p: p.number)

greenlight/src/greenlight/review.py

@@ -24,7 +24,13 @@
 
 from greenlight import dispatch as dispatch_module
 from greenlight import github_client, scan_runner, state
-from greenlight.constants import DEFAULT_DISPATCH_REF, DEFAULT_TIMEOUT_MINUTES, TARGET_REPO, TERMINAL_STATUSES
+from greenlight.constants import (
+    DEFAULT_DISPATCH_REF,
+    DEFAULT_TIMEOUT_MINUTES,
+    EXCLUDED_LABELS,
+    TARGET_REPO,
+    TERMINAL_STATUSES,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
@@ -102,15 +108,22 @@ def _close_client(client: Github) -> None:
 
 def _candidate_numbers(
     client: Github, *, pr: int | None, fetch: Callable[[Github], list[OpenPR]]
-) -> tuple[list[int], dict[int, datetime | None]]:
+) -> tuple[list[int], dict[int, datetime | None], frozenset[int]]:
     if pr is not None:
         logger.info("targeting single PR #%d in %s", pr, TARGET_REPO)
-        return [pr], {}
+        return [pr], {}, frozenset()
     open_prs = fetch(client)
     logger.info("found %d open PR(s) from %d author(s) in %s", len(open_prs), len(TRUSTED_AUTHORS), TARGET_REPO)
     for open_pr in open_prs:
         logger.info("open PR #%d by %s: %s (%s)", open_pr.number, open_pr.author, open_pr.title, open_pr.url)
-    return [open_pr.number for open_pr in open_prs], {open_pr.number: open_pr.updated_at for open_pr in open_prs}
+    stale_labeled_numbers = frozenset(
+        open_pr.number for open_pr in open_prs if not EXCLUDED_LABELS.isdisjoint(open_pr.labels)
+    )
+    return (
+        [open_pr.number for open_pr in open_prs],
+        {open_pr.number: open_pr.updated_at for open_pr in open_prs},
+        stale_labeled_numbers,
+    )
 
 
 def _within_recency_window(updated_at: datetime | None, now: datetime, window: timedelta) -> bool:
@@ -124,28 +137,37 @@ def _recency_filter(
     pr_numbers: Sequence[int],
     updated_at_by_number: dict[int, datetime | None],
     states: dict[int, PRState],
+    stale_labeled_numbers: frozenset[int],
     *,
     now: datetime,
     window: timedelta,
 ) -> list[int]:
-    """Drop stale PRs the scan can safely leave alone this iteration.
-
-    A PR is kept when it was updated within ``window`` OR its recorded state is non-terminal
-    (in-flight or retry-eligible), so ``decide`` can still re-dispatch it on timeout/retry. A
-    stale PR is skipped without fingerprinting when it is terminal (its eval_hash cannot have
-    changed) or never reviewed (an untouched PR outside the window is not worth a first review).
+    """Drop PRs the scan can safely leave alone this iteration.
+
+    A PR is kept when it was updated within ``window`` AND is not ``Stale``-labeled, OR its
+    recorded state is non-terminal (in-flight or retry-eligible), so ``decide`` can still
+    re-dispatch it on timeout/retry. A PR is skipped without fingerprinting when it is stale or
+    ``Stale``-labeled and either terminal (its eval_hash cannot have changed) or never reviewed
+    (an untouched PR is not worth a first review). The ``Stale`` label matters because the pytorch
+    stale bot bumps ``updated_at`` when it applies the label, which would otherwise drag an
+    abandoned never-reviewed PR back into the window.
     """
     kept: list[int] = []
     for number in pr_numbers:
-        if _within_recency_window(updated_at_by_number.get(number), now, window):
+        active = _within_recency_window(updated_at_by_number.get(number), now, window)
+        stale_labeled = number in stale_labeled_numbers
+        if active and not stale_labeled:
             kept.append(number)
             continue
         recorded = states.get(number)
-        if recorded is None or recorded.status in TERMINAL_STATUSES:
-            detail = recorded.status if recorded is not None else "never reviewed"
-            logger.info("skipping stale PR #%d: no recent activity (%s)", number, detail)
+        if recorded is not None and recorded.status not in TERMINAL_STATUSES:
+            kept.append(number)
             continue
-        kept.append(number)
+        detail = recorded.status if recorded is not None else "never reviewed"
+        if stale_labeled:
+            logger.info("skipping PR #%d: Stale label (%s)", number, detail)
+        else:
+            logger.info("skipping stale PR #%d: no recent activity (%s)", number, detail)
     return kept
 
 
@@ -199,7 +221,7 @@ def run(
         # exits non-zero, daemon backs off) rather than silently revert to hashing all human comments.
         authorized_logins = resolve_authorized()
         logger.info("filtering fingerprint comments to %d merge-authorized login(s)", len(authorized_logins))
-        pr_numbers, updated_at_by_number = _candidate_numbers(client, pr=pr, fetch=fetch)
+        pr_numbers, updated_at_by_number, stale_labeled_numbers = _candidate_numbers(client, pr=pr, fetch=fetch)
         states = read_state(TARGET_REPO, pr_numbers)
         evaluated_at = now()
         timeout = timedelta(minutes=timeout_minutes)
@@ -213,6 +235,7 @@ def run(
                 pr_numbers,
                 updated_at_by_number,
                 states,
+                stale_labeled_numbers,
                 now=evaluated_at,
                 window=timedelta(hours=config.review_window_hours),
             )

greenlight/tests/test_github_client.py

@@ -15,6 +15,11 @@ def __init__(self, login: str) -> None:
         self.login = login
 
 
+class _FakeLabel:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+
 class _FakePull:
     def __init__(
         self,
@@ -24,13 +29,15 @@ def __init__(
         html_url: str,
         head_sha: str = "head-sha",
         updated_at: datetime | None = None,
+        labels: list[str] | None = None,
     ) -> None:
         self.number = number
         self.user = _FakeUser(login) if login is not None else None
         self.title = title
         self.html_url = html_url
         self.head = _FakeBase(head_sha)
         self.updated_at = updated_at
+        self.labels = [_FakeLabel(name) for name in (labels or [])]
 
 
 class _FakeRepo:
@@ -174,10 +181,21 @@ def test_list_open_prs_by_authors_maps_pull_fields():
             url="https://github.com/pytorch/pytorch/pull/42",
             head_sha="abc123",
             updated_at=datetime(2026, 7, 30, 9, 0, 0),
+            labels=(),
         )
     ]
 
 
+def test_list_open_prs_by_authors_maps_labels():
+    client = _client_with_pulls([_FakePull(1, "alice", "fix", "https://example.test/1", labels=["Stale", "ci-no-td"])])
+
+    prs = github_client.list_open_prs_by_authors(client, "pytorch/pytorch", ["alice"])
+
+    # Each label's name is carried onto OpenPR.labels in listing order, read from the get_pulls
+    # payload with no extra API call.
+    assert prs[0].labels == ("Stale", "ci-no-td")
+
+
 def test_list_open_prs_by_authors_normalizes_tz_aware_updated_at():
     client = _client_with_pulls(
         [_FakePull(1, "alice", "fix", "https://example.test/1", updated_at=datetime(2026, 7, 30, 9, 0, 0, tzinfo=UTC))]

greenlight/tests/test_review.py

@@ -45,7 +45,13 @@
 _NEW = _NOW - timedelta(hours=1)
 
 
-def _open_pr(number: int, *, head_sha: str | None = None, updated_at: datetime | None = None) -> OpenPR:
+def _open_pr(
+    number: int,
+    *,
+    head_sha: str | None = None,
+    updated_at: datetime | None = None,
+    labels: tuple[str, ...] = (),
+) -> OpenPR:
     return OpenPR(
         repo=TARGET_REPO,
         number=number,
@@ -54,6 +60,7 @@ def _open_pr(number: int, *, head_sha: str | None = None, updated_at: datetime |
         url=f"https://example.test/{number}",
         head_sha=head_sha or f"headsha{number}",
         updated_at=updated_at,
+        labels=labels,
     )
 
 
@@ -373,6 +380,82 @@ def test_recency_window_exactly_at_edge_is_out_of_window(make_config):
     assert scan.dispatched == []
 
 
+def test_stale_label_in_window_never_reviewed_is_skipped(make_config, caplog):
+    with caplog.at_level(logging.INFO, logger="greenlight"):
+        scan = _run_scan(
+            make_config,
+            listed=[_open_pr(1, updated_at=_NEW, labels=("Stale",))],
+            fingerprints={1: ("headsha1", _HASH_A)},
+        )
+
+    # The stale bot bumps updated_at when it applies "Stale", so this PR is inside the window yet
+    # abandoned. The label prunes it -- never fingerprinted, never dispatched.
+    assert scan.fingerprinted == []
+    assert scan.dispatched == []
+    assert "skipping PR #1: Stale label (never reviewed)" in caplog.text
+
+
+def test_stale_label_in_window_terminal_is_skipped(make_config, caplog):
+    with caplog.at_level(logging.INFO, logger="greenlight"):
+        scan = _run_scan(
+            make_config,
+            listed=[_open_pr(1, updated_at=_NEW, labels=("Stale",))],
+            fingerprints={1: ("headsha1", _HASH_A)},
+            states={1: _state(1, STATUS_LAND, _HASH_A, _NEW)},
+        )
+
+    # Stale-labeled and terminal (decided): its eval_hash cannot have changed, so the label prunes it
+    # without fingerprinting just as the never-reviewed case does -- but the skip log carries the
+    # recorded status, exercising the detail = recorded.status branch for a Stale-labeled PR.
+    assert scan.fingerprinted == []
+    assert scan.dispatched == []
+    assert f"skipping PR #1: Stale label ({STATUS_LAND})" in caplog.text
+
+
+@pytest.mark.parametrize("status", [STATUS_AI_REVIEW_STARTED, STATUS_CANCELLED, STATUS_FAILED])
+def test_stale_label_nonterminal_state_is_still_processed(make_config, status):
+    scan = _run_scan(
+        make_config,
+        listed=[_open_pr(1, updated_at=_NEW, labels=("Stale",))],
+        fingerprints={1: ("headsha1", _HASH_A)},
+        states={1: _state(1, status, _HASH_A, _STALE)},
+    )
+
+    # A non-terminal ledger state (in-flight / retry) survives the Stale label exactly as it survives
+    # the recency window: the PR is re-checked so decide can re-dispatch it on timeout/retry.
+    assert scan.fingerprinted == [1]
+    assert scan.dispatched == [(1, "headsha1", _HASH_A, DEFAULT_DISPATCH_REF)]
+
+
+@pytest.mark.parametrize("label", ["enhancement", "stale", "STALE"])
+def test_non_stale_label_in_window_is_not_skipped(make_config, label):
+    scan = _run_scan(
+        make_config,
+        listed=[_open_pr(1, updated_at=_NEW, labels=(label,))],
+        fingerprints={1: ("headsha1", _HASH_A)},
+    )
+
+    # Control: only the exact case-sensitive "Stale" prunes. Any other label -- including the
+    # lowercase/uppercase variants -- leaves an in-window never-reviewed PR fingerprinted.
+    assert scan.fingerprinted == [1]
+    assert scan.dispatched == [(1, "headsha1", _HASH_A, DEFAULT_DISPATCH_REF)]
+
+
+def test_stale_label_pr_target_is_exempt(make_config):
+    scan = _run_scan(
+        make_config,
+        pr=5,
+        listed=[_open_pr(5, updated_at=_OLD, labels=("Stale",))],
+        fingerprints={5: ("headsha5", _HASH_A)},
+    )
+
+    # A single --pr target bypasses listing entirely (listed_calls == 0), so the Stale label -- which
+    # only ever comes from the listing -- can never suppress a manual recheck.
+    assert scan.listed_calls == 0
+    assert scan.fingerprinted == [5]
+    assert scan.dispatched == [(5, "headsha5", _HASH_A, DEFAULT_DISPATCH_REF)]
+
+
 def test_max_caps_only_dispatches(make_config):
     scan = _run_scan(
         make_config,