ci(workflows): objectui-pin-freshness 补 merge_group 触发器,队列世代走 advisory 车道 (#6121)

.github/workflows/objectui-pin-freshness.yml

@@ -31,16 +31,35 @@ name: Console Pin Freshness
 # either way, so a green run on an ordinary PR still shows how far the pin has
 # drifted.
 #
-# REQUIRED-CHECK ENFORCEMENT IS NOT SELF-DECLARED
-# -----------------------------------------------
+# REQUIRED-CHECK ENFORCEMENT IS NOT SELF-DECLARED — AND IT HAS A PRECONDITION
+# ----------------------------------------------------------------------------
 # A workflow cannot make itself required. A maintainer must add the
 # `Console Pin Freshness` context to the branch-protection rule for `main`
 # (Settings → Branches → main → Require status checks to pass). Until then this
 # workflow REPORTS on the release PR without blocking the merge button.
+#
+# ⚠️ THE PRECONDITION IS THE `merge_group:` TRIGGER BELOW (#6121). Adding this
+# context to a required set is safe ONLY BECAUSE that trigger now exists. The
+# paragraph above states the PR half of the rule — "a required context that
+# reports nothing leaves every PR stuck" — and until #6121 this file invited
+# maintainers into the required set while missing the QUEUE half: branch
+# protection is evaluated AGAIN on the `gh-readonly-queue/**` generation, so a
+# required context that produces no run THERE parks every queue generation
+# forever (#3622 is the prototype for that deadlock).
+#
+# FUTURE EDITORS: before this context is added to — or left in — any required
+# set, confirm `merge_group:` is still in `on:` below. Deleting that trigger
+# does not fail loudly; it deadlocks the merge queue for every PR in the repo.
 
 on:
   pull_request:
     branches: [main]
+  # Merge queue (see ci.yml for the full note): a required context must report
+  # on queue generations too, or queue builds wait forever on a check that never
+  # arrives. This is the precondition documented above (#6121). Which LANE the
+  # event lands in — blocking vs reporting — is decided in the pin-freshness
+  # step below, not here.
+  merge_group:
   workflow_dispatch:
 
 concurrency:
@@ -87,12 +106,33 @@ jobs:
           # with the title configured in release.yml. Either identifies the lane;
           # both are checked so a future rename of one does not silently disarm
           # the gate.
-          if [ "$EVENT" != "pull_request" ] \
+          #
+          # LANE BY EVENT — classify every new trigger HERE, explicitly (#6121).
+          # This test used to read `[ "$EVENT" != "pull_request" ]`, a negation
+          # that meant "workflow_dispatch" back when `on:` had exactly two
+          # entries. Adding `merge_group:` is the moment that proxy breaks: the
+          # negation would sweep every queue generation into the BLOCKING lane,
+          # where this gate goes red whenever the pin lags — the repo's normal
+          # state between bumps (see WHERE IT BLOCKS at the top) — and a required
+          # context that is systematically red EJECTS every PR from the queue.
+          # That would trade one deadlock for another rather than fix it.
+          #
+          #   workflow_dispatch → BLOCKS. A human asked for the full check.
+          #   merge_group       → reports. The queue generation of an ordinary PR
+          #                       is an ordinary PR; the Version Packages PR is
+          #                       enforced on its own `pull_request` run, and
+          #                       release.yml runs this same script on the publish
+          #                       path — the backstop with no override input.
+          #   pull_request      → BLOCKS on the release lane only.
+          #
+          # HEAD_REF and PR_TITLE are empty on merge_group (no `pull_request` in
+          # the payload), so the two release-lane tests are false there anyway.
+          if [ "$EVENT" = "workflow_dispatch" ] \
             || [ "$HEAD_REF" = "changeset-release/main" ] \
             || [ "$PR_TITLE" = "chore: version packages" ]; then
-            echo "::notice::Release lane — the objectui pin-freshness gate BLOCKS here (#3340)."
+            echo "::notice::Release lane or manual run — the objectui pin-freshness gate BLOCKS here (#3340)."
             node scripts/check-objectui-pin-fresh.mjs
           else
-            echo "::notice::Not the Version Packages PR — pin freshness is reported but does not block (a pin lagging between bumps is normal). It blocks on the release PR."
+            echo "::notice::Not the release lane — pin freshness is reported but does not block (a pin lagging between bumps is normal). It blocks on the Version Packages PR and on the publish path."
             node scripts/check-objectui-pin-fresh.mjs --advisory
           fi