feat(label): mark stacked pull requests so reviewers can filter them

.github/workflows/label-pr-review-state.yml

@@ -47,12 +47,15 @@ on:
 
 permissions:
     # This privileged workflow only reads PR/check metadata and writes issue labels,
-    # comments, and commit statuses. All unspecified permissions, including contents,
-    # are none; no fork code or configuration is checked out or executed.
+    # comments, and commit statuses. All unspecified permissions are none; contents is
+    # read-only and used only for the commit-parent lookup below. No fork code or
+    # configuration is checked out or executed.
     pull-requests: write
     issues: write
     checks: read
     statuses: write
+    # Reading a commit's parents is metadata only; no PR code is checked out or executed.
+    contents: read
 
 # Concurrency is keyed at two levels (issue #1707):
 #
@@ -100,6 +103,7 @@ jobs:
         runs-on: ubuntu-latest
         outputs:
             pr_numbers: ${{ steps.resolve.outputs.pr_numbers }}
+            open_pr_heads: ${{ steps.resolve.outputs.open_pr_heads }}
         env:
             # Mirrors the workflow-level concurrency group so the run's queueing
             # identity is visible in the logs (kept in sync by the workflow tests).
@@ -146,6 +150,7 @@ jobs:
                       // pull_request_review runs report the base repository as
                       // head_repository (issue #2133).
                       let prNumbers = [];
+                      let openPrsCache = null;
                       if (context.payload.pull_request?.number) {
                         prNumbers = [context.payload.pull_request.number];
                       } else if (context.eventName === 'issue_comment') {
@@ -178,14 +183,14 @@ jobs:
                           );
                         }
                       } else {
-                        const openPrs = await github.paginate(github.rest.pulls.list, {
+                        openPrsCache = await github.paginate(github.rest.pulls.list, {
                           owner, repo, state: 'open', per_page: 100,
                         });
                         // GitHub rejects matrices over 256 jobs, so the sweep pages the
                         // sorted open-PR list: consecutive runs rotate through
                         // fixed-size windows by run number, covering every open PR on a
                         // bounded cadence without ever exceeding the limit.
-                        const allNumbers = openPrs.map(pr => pr.number).sort((a, b) => a - b);
+                        const allNumbers = openPrsCache.map(pr => pr.number).sort((a, b) => a - b);
                         const sweepPageSize = 200;
                         const pageCount = Math.max(1, Math.ceil(allNumbers.length / sweepPageSize));
                         const page = context.runNumber % pageCount;
@@ -204,6 +209,50 @@ jobs:
                       );
                       core.setOutput('pr_numbers', JSON.stringify(prNumbers));
 
+                      // Build the open-PR head map once here for every shard: a sweep would otherwise
+                      // multiply the paginated open-PR read by every shard against the Actions token
+                      // budget. Sweep triggers already hold the full open list, so the map costs them
+                      // no extra read.
+                      //
+                      // The map only describes which commits are open pull request heads, so it can
+                      // only change when a pull request's head is (re)published: opened, reopened, or
+                      // synchronize. Reviews, comments, workflow_run completions, and manual dispatch
+                      // cannot change it, so they skip the paginated read entirely and pass a sentinel
+                      // that tells shards the label was not evaluated. Reading it on every direct event
+                      // would add one full open-PR listing to each review and status-comment run.
+                      //
+                      // An empty output means the map was unavailable this run; shards then skip the
+                      // stacked label rather than deciding from an empty map.
+                      const stackMayHaveChanged =
+                        context.eventName === 'pull_request_target' &&
+                        ['opened', 'reopened', 'synchronize'].includes(context.payload.action);
+                      let openPrHeadsOutput = '';
+                      if (prNumbers.length > 0 && (openPrsCache || stackMayHaveChanged)) {
+                        try {
+                          const openPrsForMap = openPrsCache ?? (await github.paginate(github.rest.pulls.list, {
+                            owner, repo, state: 'open', per_page: 100,
+                          }));
+                          const heads = {};
+                          for (const candidate of openPrsForMap) {
+                            if (candidate.head?.sha) heads[candidate.head.sha.toLowerCase()] = candidate.number;
+                          }
+                          // An open-PR list with no entries is anomalous (the reconciliation
+                          // target itself is open), so treat it like an unavailable map:
+                          // shards must not decide from a map that looks empty.
+                          if (Object.keys(heads).length > 0) openPrHeadsOutput = JSON.stringify(heads);
+                        } catch (error) {
+                          core.warning(`Could not read the open pull request map: ${error.message}; shards will skip the stacked label this run`);
+                        }
+                      } else if (prNumbers.length > 0) {
+                        // Sentinel: this event cannot change a stacked relationship, so the label was
+                        // not evaluated rather than found unavailable. Shards skip it silently.
+                        openPrHeadsOutput = 'not-evaluated';
+                        core.info(
+                          `Open-PR head map not read: ${context.eventName} cannot change a stacked unit; shards skip the stacked label.`
+                        );
+                      }
+                      core.setOutput('open_pr_heads', openPrHeadsOutput);
+
     reconcile:
         name: Zoo Code / reconcile PR review state
         needs: resolve
@@ -245,6 +294,7 @@ jobs:
         runs-on: ubuntu-latest
         env:
             PR_NUMBER: ${{ matrix.pr_number }}
+            OPEN_PR_HEADS: ${{ needs.resolve.outputs.open_pr_heads }}
             # Mirrors this job's concurrency group so a superseded shard's queueing
             # identity is visible in the logs (kept in sync by the workflow tests).
             CONCURRENCY_GROUP: >-
@@ -307,6 +357,11 @@ jobs:
                           color: 'c2e0c6',
                           description: 'Fresh community approval on the current head; maintainer review still required',
                         },
+                        {
+                          name: 'stacked',
+                          color: 'c2c2c2',
+                          description: 'Head commit sits on another open PR, so its diff is only this unit',
+                        },
                       ];
                       const guideMarker = '<!-- zoo-code-pr-review-process -->';
                       const codeRabbitLabelMarkerPrefix = '<!-- coderabbit-review-label:';
@@ -351,6 +406,7 @@ jobs:
                         return pr.head?.repo?.full_name && pr.head.repo.full_name !== pr.base?.repo?.full_name;
                       }
 
+                      const stackedLabel = 'stacked';
                       if (!isReadOnlyRun) {
                         // One paginated list keeps the per-shard API budget flat no matter
                         // how many labels are managed; per-label getLabel calls would
@@ -364,6 +420,14 @@ jobs:
                           try {
                             await github.rest.issues.createLabel({ owner, repo, ...label });
                           } catch (createError) {
+                            if (label.name === stackedLabel) {
+                              // stacked is only a reviewer filter, so a failed provisioning must not stop
+                              // reconciliation for every PR. Every other managed label still fails closed,
+                              // because reconciliation cannot work without it. A concurrent shard winning
+                              // the creation race lands the label anyway; the next sweep reconciles it.
+                              core.warning(`Could not create the ${stackedLabel} label: ${createError.message}; continuing without it`);
+                              continue;
+                            }
                             // Concurrent shards for other PRs can win the creation race.
                             // Tolerate only the duplicate-label payload; any other 422
                             // must fail the shard.
@@ -431,6 +495,49 @@ jobs:
                         }
                       }
 
+                      // A stacked unit is detected from the commit graph: its head commit has exactly one
+                      // parent, and that parent is another open PR's head. The label describes that detected
+                      // relationship only -- it does not claim the PR targets the branch below it, which is
+                      // how GitHub describes a focused stacked diff. Reviewers filter on this label to tell a
+                      // unit apart from a standalone PR. It is orthogonal to the review-state labels, so it is
+                      // reconciled separately and never removed by reconcileLabels.
+
+                      async function reconcileStackedLabel(pr, openPrHeads) {
+                        if (openPrHeads === null) {
+                          // The map could not be read this run; leave the label as it is rather than
+                          // deciding from an empty map.
+                          return;
+                        }
+                        if (isReadOnlyRun && isForkPR(pr)) {
+                          core.info(`PR #${pr.number}: fork PR on a read-only run — skipping the stacked label`);
+                          return;
+                        }
+                        try {
+                          const { data: commit } = await github.rest.git.getCommit({ owner, repo, commit_sha: pr.head.sha });
+                          const parents = Array.isArray(commit.parents) ? commit.parents : [];
+                          const matchedPr = parents.length === 1
+                            ? openPrHeads.get(String(parents[0].sha).toLowerCase())
+                            : undefined;
+                          // The open-PR map can predate a push to this PR: its own previous (or now
+                          // base) head resolves back to this PR. That is not a parent PR, and it is
+                          // also not evidence that an existing stacked label is stale - leave every
+                          // stacked-label mutation untouched for this ambiguous self-match.
+                          if (matchedPr === pr.number) return;
+                          const parentPr = matchedPr;
+                          const hasLabel = pr.labels.some(label => label.name === stackedLabel);
+                          if (hasLabel && parentPr === undefined) {
+                            await github.rest.issues.removeLabel({ owner, repo, issue_number: pr.number, name: stackedLabel });
+                            pr.labels = pr.labels.filter(label => label.name !== stackedLabel);
+                          } else if (parentPr && !hasLabel) {
+                            await github.rest.issues.addLabels({ owner, repo, issue_number: pr.number, labels: [stackedLabel] });
+                            pr.labels = pr.labels.concat([{ name: stackedLabel }]);
+                            core.info(`PR #${pr.number}: stacked on #${parentPr}`);
+                          }
+                        } catch (error) {
+                          core.warning(`PR #${pr.number}: could not reconcile the stacked label: ${error.message}`);
+
+                        }
+                      }
                       // Reconciles the independent has-conflicts flag (issue #2089).
                       // `present` is a mergeability fact, so callers pass a known read
                       // only: true for a known dirty read, false for a known read that
@@ -764,8 +871,34 @@ jobs:
 
                       const failures = [];
 
+                      // The open-PR head map is built once in the resolve job and passed through the
+                      // job env, so a sweep pays one paginated read instead of one per shard. The resolve
+                      // job passes NOT_EVALUATED_MAP when the event could not change a stacked
+                      // relationship, and an empty value when it tried to read the map and failed.
+                      // Either way existing stacked labels are left as they are: a map that is absent,
+                      // empty, or not read must never look like "no open parents" and remove them.
+                      const NOT_EVALUATED_MAP = 'not-evaluated';
+                      let openPrHeads = null;
+                      if (prs.length > 0) {
+                        const emittedMap = process.env.OPEN_PR_HEADS;
+                        if (emittedMap === NOT_EVALUATED_MAP) {
+                          core.info(
+                            `PR #${prs[0].number}: this event cannot change a stacked unit; skipping the stacked label`
+                          );
+                        } else if (emittedMap) {
+                          try {
+                            openPrHeads = new Map(Object.entries(JSON.parse(emittedMap)));
+                          } catch (error) {
+                            core.warning(`Could not read the open pull request map: ${error.message}; skipping the stacked label for this run`);
+                          }
+                        } else {
+                          core.warning('Could not read the open pull request map: the resolve job provided none; skipping the stacked label for this run');
+                        }
+                      }
+
                       for (const pr of prs) {
                         let failurePhase = 'ci-pending';
+                        await reconcileStackedLabel(pr, openPrHeads);
                         try {
                           // The matrix job reports one check per shard named
                           // "<reconciliationCheckName> (<pr_number>)", so catch both the