Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/cursor-review/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -435,6 +435,7 @@ All optional except `workflows_ref` (required, no default) — pass them under
| `approve_only_max_runs` | `10` | Re-checks per panel round, read off the re-check sentinel, which names the round it counts for; clamped to `card.RECHECK_HEADS_KEPT` (50), past which the count could not grow. |
| `carry_forward_unchanged_diff` | `false` | Opt-in: `dismiss-stale-approval` re-approves the live head before dismissing when the PR's own changes (compare API, merge base → head, hunk line numbers ignored, headings and inter-hunk distances kept) equal the ones the approving round reviewed under a threshold no looser than today's — the stacked-PR rebase, re-merge or retarget. What the round reviewed comes only from the approver's own records: the merge base the approval recorded (`approval_merge_base`, when the compare API and the round's sentinel agree — the sentinel can veto a record, never supply one) or what a carried approval copied forward (`carry_baseline`), and the compare API must show it as an ancestor of the reviewed commit; an approval with neither never carries. Only under `pull_request_target`, only for the approver's latest verdict, failing closed (dismissing as before) on anything it cannot compare (`try_carry_forward`); `mark_card_stale` leaves the card alone while such an approval stands. See [the setup guide](../../docs/callers/cursor-review.md#auto-approve). |
| `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed, except a round whose own decision found the PR head had moved (a push superseded it), at most once per reviewed commit and at most `max_rounds` times; at or over the cap the panel is skipped, the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Fails open on a read error. See [the setup guide](../../docs/callers/cursor-review.md#round-cap-and-the-approve_gate-output). |
| `count_superseded_rounds` | `false` | Count delivered reviews even when a later decision found the head moved. Does not count undelivered panels or change resets. |
| `fail_closed_round_cap` | `false` | Stop the panel if cap evaluation or handoff fails. Requires a positive `max_rounds`; does not change resets, superseded-round exemptions or concurrency. |
| `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` (same shape as `cursor-review-auto-label.yml`'s) for the four credential-free heavy jobs only: `diff-size`, `preflight`, the `review` panel and `consolidate`. The gate, ledger, Slack notices and every job holding the App token or `pull-requests: write` stay on GitHub-hosted `ubuntu-latest`. Those four run models with unsandboxed shell over PR code, so use a self-hosted pool only if each job gets a fresh pod (fresh filesystem and `$HOME`), holds no cloud identity or token, and can't reach private networks or the metadata server. The image must be linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. |
| `approver_environment` | `''` | The caller-repo environment holding `APPROVER_TOKEN` (an environment secret, base-branch-only deployment policy), declared on `post-review`, `dismiss-stale-approval`, `auto-retry`, `auto-rereview`, `approve-only` and `axes-closeout` only (and passed to cursor-approve.yml from `approve-start-early`, which declares it there), and only under `pull_request_target`. Pair with a `pull_request_target` caller — see the [trust model](../../docs/callers/cursor-review.md#trust-model). |
Expand Down
3 changes: 2 additions & 1 deletion .github/cursor-review/auto-approve.py
Original file line number Diff line number Diff line change
Expand Up @@ -4257,7 +4257,7 @@ def cmd_round_cap(args) -> int:
_paginate(f"repos/{args.repo}/issues/{args.pr_number}/timeline?per_page=100"), HUMAN_REVIEW_LABEL
)
rounds = round_reviews(list_reviews(args.repo, args.pr_number), args.poster_login, since, marker,
max_rounds)
0 if getattr(args, "count_superseded_rounds", False) else max_rounds)
except (RuntimeError, ValueError) as e:
# Legacy callers fail open; strict callers stop the panel.
if strict:
Expand Down Expand Up @@ -4738,6 +4738,7 @@ def main() -> int:
c.add_argument("--threshold", default="")
c.add_argument("--poster-login", required=True)
c.add_argument("--fail-closed-round-cap", action="store_true")
c.add_argument("--count-superseded-rounds", action="store_true")
e = sub.add_parser("approve-external")
e.add_argument("--repo", required=True)
e.add_argument("--pr-number", required=True)
Expand Down
18 changes: 15 additions & 3 deletions .github/cursor-review/tests/test_auto_approve.py
Original file line number Diff line number Diff line change
Expand Up @@ -1856,12 +1856,13 @@ def test_count_step_passes_the_opt_in_to_the_real_entrypoint(self):
f.write("import json, os, sys\nopen(os.environ['ARGS'], 'w').write(json.dumps(sys.argv[1:]))\n")
path = os.path.join(d, "args")
env = {"PATH": os.environ["PATH"], "CURSOR_REVIEW_ASSETS": d, "ARGS": path,
"APP_SLUG": "review", "FAIL_CLOSED_ROUND_CAP": "true", "REPO": "o/r",
"APP_SLUG": "review", "FAIL_CLOSED_ROUND_CAP": "true", "COUNT_SUPERSEDED_ROUNDS": "true", "REPO": "o/r",
"PR_NUMBER": "1", "MAX_ROUNDS": "3", "THRESHOLD": ""}
subprocess.run(["bash", "-e", "-c", script], env=env, check=True, capture_output=True)
with open(path, encoding="utf-8") as f:
args = json.load(f)
self.assertIn("--fail-closed-round-cap", args)
self.assertIn("--count-superseded-rounds", args)
self.assertEqual(args[args.index("--max-rounds") + 1], "3")
self.assertEqual(args[args.index("--poster-login") + 1], "review[bot]")

Expand All @@ -1871,7 +1872,7 @@ class RoundCapCommandTest(unittest.TestCase):
"""The cap path end to end, with gh stubbed by endpoint."""

def run_cap(self, reviews, max_rounds="5", timeline=(), comments=(), label_exists=True, fail=(), labels=(),
probe_error="HTTP 404", strict=False):
probe_error="HTTP 404", strict=False, count_superseded=False):
writes = []

def fake_gh(args, payload=None):
Expand Down Expand Up @@ -1908,7 +1909,7 @@ def fake_gh(args, payload=None):
out = os.path.join(d, "out")
open(out, "w").close()
args = argparse.Namespace(repo="o/r", pr_number="1", max_rounds=max_rounds, threshold="medium",
poster_login=BOT, fail_closed_round_cap=strict)
poster_login=BOT, fail_closed_round_cap=strict, count_superseded_rounds=count_superseded)
with mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}), \
mock.patch.object(AA, "gh", fake_gh), \
mock.patch.object(AA, "open_thread_ids", lambda *a: {"11", "12"}), \
Expand Down Expand Up @@ -1966,6 +1967,17 @@ def test_unreadable_reviews_fail_open(self):
rc, out, writes = self.run_cap(self.FIVE, fail=("/reviews",))
self.assertEqual((rc, out["capped"], writes), (0, "false", []))

def test_opt_in_counts_a_delivered_review_superseded_by_a_push(self):
fixture = RoundCounterTest()
moved = fixture._panel(1, "2026-01-01T00:00:00Z", OLD)
decision = fixture._decision(2, "2026-01-01T00:05:00Z", OLD, [AA.REASON_HEAD_MOVED])
reviews = [moved, decision, review(3, "2026-01-02T00:00:00Z"),
review(4, "2026-01-03T00:00:00Z")]
_, default, _ = self.run_cap(reviews, max_rounds="3")
_, counted, _ = self.run_cap(reviews, max_rounds="3", count_superseded=True)
self.assertEqual((default["capped"], default["rounds"]), ("false", "2"))
self.assertEqual((counted["capped"], counted["rounds"]), ("true", "3"))

def test_strict_cap_allows_two_and_hands_off_at_three(self):
rc, out, _ = self.run_cap(self.FIVE[:2], max_rounds="3", strict=True)
self.assertEqual((rc, out["capped"], out["rounds"]), (0, "false", "2"))
Expand Down
11 changes: 10 additions & 1 deletion .github/workflows/cursor-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -765,6 +765,13 @@ on:
type: number
required: false
default: 5
count_superseded_rounds:
description: >-
Include delivered reviews whose decisions found the head moved in the
round cap. Does not count undelivered panels or change reset behavior.
type: boolean
required: false
default: false
fail_closed_round_cap:
description: >-
Stop the panel if review history or the handoff label cannot be read or
Expand Down Expand Up @@ -1928,12 +1935,14 @@ jobs:
MAX_ROUNDS: ${{ inputs.max_rounds }}
THRESHOLD: ${{ inputs.approve_max_severity }}
FAIL_CLOSED_ROUND_CAP: ${{ inputs.fail_closed_round_cap }}
COUNT_SUPERSEDED_ROUNDS: ${{ inputs.count_superseded_rounds }}
PR_NUMBER: ${{ github.event.pull_request.number }}
REPO: ${{ github.repository }}
run: |
if [ -n "$APP_SLUG" ]; then LOGIN="${APP_SLUG}[bot]"; else LOGIN="github-actions[bot]"; fi
STRICT_FLAG=()
if [ "$FAIL_CLOSED_ROUND_CAP" = true ]; then STRICT_FLAG=(--fail-closed-round-cap); fi
if [ "$FAIL_CLOSED_ROUND_CAP" = true ]; then STRICT_FLAG+=(--fail-closed-round-cap); fi
if [ "$COUNT_SUPERSEDED_ROUNDS" = true ]; then STRICT_FLAG+=(--count-superseded-rounds); fi
python3 "$CURSOR_REVIEW_ASSETS/auto-approve.py" round-cap \
--repo "$REPO" \
--pr-number "$PR_NUMBER" \
Expand Down
1 change: 1 addition & 0 deletions docs/callers/cursor-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ pull-requests: write # posting the consolidated review (and, at the round cap,
| `approve_only_max_runs` | `10` | Cap on `approve_only_on_push` re-checks per panel round, counted on the status card; a new panel round resets it. At the cap a push is left to a relabel (or `auto_rereview_after_dismissal`). Clamped to `50`, the heads the card's record keeps; unparsable re-checks nothing. |
| `carry_forward_unchanged_diff` | `false` | Opt-in, for stacked PRs: when a push or a retarget would dismiss the approver's approval but the PR's **own** changes are identical to the ones a round reviewed (a rebase or re-merge onto a moved base, e.g. a lower PR of the stack changed or landed), re-approve the live head, then dismiss the old approval; the card keeps its approval and no round is scheduled. Identical is the compare API's diff from the merge base the approval recorded to the reviewed commit against the diff from the live base to the live head, file by file, context lines and hunk headings included, hunk line numbers ignored. Anything it cannot vouch for dismisses as before, and an approval that records no merge base (every one an earlier version posted, too) never carries. Only under `pull_request_target`, and only with `approve_max_severity` set and `bot_app_id` posting the rounds (with `defer_approval`, pass cursor-approve that App's `poster_login` too). See [Auto-approve](#auto-approve) for every condition and the [trust model](#trust-model) for what it trusts. |
| `max_rounds` | `5` | Cap on review rounds per PR (`0` → no cap). At or over it, no panel runs: the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. A round whose own decision found the PR head had moved (a newer push superseded it) does not count, at most once per reviewed commit and at most `max_rounds` times. Removing the label resets the count. See [round cap](#round-cap-and-the-approve_gate-output). |
| `count_superseded_rounds` | `false` | Count delivered reviews even when a later decision found the head moved. Does not count undelivered panels or change resets. |
| `fail_closed_round_cap` | `false` | Stop the panel if the cap cannot be evaluated or handoff fails. Requires a positive `max_rounds` and, when configured, the posting bot token and identity. This preserves the existing reset, superseded-round exemptions and concurrency behavior; it does not guarantee a lifetime limit on all reviewer executions. |
| `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` for `diff-size`, `preflight`, the `review` panel and `consolidate` only — the jobs that hold no write credential. Every other job stays on GitHub-hosted `ubuntu-latest`. A self-hosted pool is fine only if it is one-job-per-fresh-pod, identity-free and private-network-isolated (those jobs run models with shell over PR code), on linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. Empty falls back to the default, so `${{ vars.CURSOR_REVIEW_RUNS_ON }}` is safe while the variable is unset; e.g. `'["self-hosted", "linux", "x64"]'`. |
| `approver_environment` | `''` | The caller-repo environment that holds `APPROVER_TOKEN` (as an environment secret). Declared as `environment:` on the jobs that read the token, only under `pull_request_target`, and on none that checks out PR code. With a deployment-branch policy of the base branch only, the token is unreachable from `pull_request` runs. Use with a `pull_request_target` caller — see the [trust model](#trust-model). Empty = no environment. |
Expand Down
Loading