ci(auto-update): wait for state to settle and surface real errors (#5958)

## Summary
First run of \`auto-update-pr-branches.yml\` after #5957 found 0 BEHIND
PRs even though three were stuck behind main (#5916, #5870, #5902). Two
issues:

1. **Timing.** The workflow runs ~4s after the push to main, but GitHub
recomputes \`mergeStateStatus\` and the cached PR head SHA
asynchronously. Right after the push the field is still UNKNOWN and the
cached head can be stale → \`update-branch\` returns *expected head sha
didn't match current head ref*. Add a 30s sleep at the start.
2. **Over-strict filter.** The script only iterated PRs where
\`mergeStateStatus == "BEHIND"\`, skipping UNKNOWN candidates — exactly
the ones we wanted to fix. Drop the filter: after a push to main, every
open auto-merge PR is behind, and \`update-branch\` is a no-op when the
head is already up-to-date.

Also:
- Bump permissions to \`contents: write\` (update-branch creates a merge
commit on the head ref).
- Drop \`--silent\` and capture stderr so the actual GitHub error lands
in the log.

Verified manually: calling \`PUT /pulls/{num}/update-branch\` from the
CLI on #5916 and #5870 worked and they auto-merged within seconds. The
422 on #5902 was a real history-divergence conflict (4 ahead / 58 behind
/ merge_base differs) — separate problem.

## Test plan
- [ ] After this merges, push something to main and confirm the workflow
finds N>0 PRs (where N is open auto-merge PRs).
- [ ] Confirm any genuinely stuck PR (conflict) gets a clear error in
the log instead of \`likely conflict or stale ref\`.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarkusNeusinger

.github/workflows/auto-update-pr-branches.yml

@@ -22,7 +22,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read       # required for actions/checkout (not strictly needed here, but cheap)
+  contents: write      # update-branch creates a merge commit on the head ref
   pull-requests: write # required to call PUT /pulls/:num/update-branch
 
 concurrency:
@@ -33,50 +33,59 @@ jobs:
   update:
     runs-on: ubuntu-latest
     steps:
-      - name: Update behind PRs with auto-merge enabled
+      - name: Wait for PR mergeable state to settle
+        # GitHub recomputes `mergeStateStatus` asynchronously after a
+        # push to main. If we list PRs immediately the field can still
+        # be "UNKNOWN" — and the cached head SHA on the PR can lag
+        # behind the actual ref, so update-branch returns "expected
+        # head sha didn't match current head ref." Give GitHub a
+        # moment to settle.
+        run: sleep 30
+
+      - name: Update PRs with auto-merge enabled
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}
         run: |
           set -eo pipefail
 
-          # Pull every open PR targeting main that has auto-merge enabled.
-          # `mergeStateStatus` is the field that surfaces "BEHIND" — the
-          # exact state we want to fix. Skip everything else (CLEAN,
-          # BLOCKED for missing reviews, DIRTY for conflicts, etc.).
+          # After a push to main, every open PR with auto-merge is by
+          # definition behind. Don't filter on `mergeStateStatus`:
+          # right after the push it can still be UNKNOWN, and we'd
+          # skip valid candidates. Just iterate every open
+          # auto-merge PR — update-branch is a no-op when the head
+          # is already up-to-date.
           PRS=$(gh pr list \
             --repo "$GH_REPO" \
             --state open \
             --base main \
             --limit 200 \
-            --json number,title,headRefName,mergeStateStatus,autoMergeRequest)
+            --json number,title,headRefName,autoMergeRequest)
 
-          BEHIND=$(echo "$PRS" | jq -c '
-            [ .[] | select(.autoMergeRequest != null and .mergeStateStatus == "BEHIND") ]
+          CANDIDATES=$(echo "$PRS" | jq -c '
+            [ .[] | select(.autoMergeRequest != null) ]
           ')
 
-          COUNT=$(echo "$BEHIND" | jq 'length')
-          echo "::notice::Found $COUNT PR(s) BEHIND with auto-merge enabled"
+          COUNT=$(echo "$CANDIDATES" | jq 'length')
+          echo "::notice::Found $COUNT open PR(s) with auto-merge enabled"
 
           if [[ "$COUNT" -eq 0 ]]; then
             exit 0
           fi
 
-          echo "$BEHIND" | jq -c '.[]' | while read -r pr; do
+          echo "$CANDIDATES" | jq -c '.[]' | while read -r pr; do
             NUM=$(echo "$pr" | jq -r '.number')
             TITLE=$(echo "$pr" | jq -r '.title')
             BRANCH=$(echo "$pr" | jq -r '.headRefName')
             echo "::notice::Updating PR #${NUM} (${BRANCH}): ${TITLE}"
 
-            # update-branch merges the base ref into the head ref; this
-            # is what the "Update branch" button does in the UI.
-            # Failures here (e.g. merge conflict, branch deleted) are
-            # logged as a warning but don't fail the whole workflow —
+            # Capture stderr so the actual GitHub error (conflict,
+            # SHA mismatch, etc.) lands in the workflow log instead
+            # of being swallowed. Failures here don't fail the job —
             # one stuck PR shouldn't block the others.
-            if ! gh api -X PUT \
+            if ! OUT=$(gh api -X PUT \
                 "repos/${GH_REPO}/pulls/${NUM}/update-branch" \
-                -H "Accept: application/vnd.github+json" \
-                --silent 2>&1; then
-              echo "::warning::Could not update PR #${NUM} (likely conflict or stale ref)"
+                -H "Accept: application/vnd.github+json" 2>&1); then
+              echo "::warning::Could not update PR #${NUM}: ${OUT}"
             fi
           done