feat: add 3 new error entries (runner-environment, silent-failures, known-unsolved)

errors/known-unsolved/macos-xcode-simctl-all-ios-simulators-missing-intermittent.yml

@@ -0,0 +1,111 @@
+id: 'known-unsolved-140'
+title: 'macOS Runner: `xcrun simctl list devices available` Returns No iOS/tvOS/watchOS Simulators — Intermittent Image-Specific Regression'
+category: known-unsolved
+severity: error
+tags:
+  - macos
+  - macos-15
+  - xcode
+  - ios
+  - simulator
+  - simctl
+  - intermittent
+  - runner-image
+patterns:
+  - regex: 'xcrun simctl list devices available.*== Devices ==\s*-- iOS'
+    flags: 'is'
+    multiline: true
+  - regex: 'Unable to find a destination.*no devices are available'
+    flags: 'i'
+  - regex: 'xcodebuild.*error.*The requested device could not be found.*simctl list.*shows no iOS'
+    flags: 'i'
+  - regex: 'simctl list devices.*-- iOS [0-9]+\.[0-9]+ --\s*-- iOS [0-9]+\.[0-9]+ --'
+    flags: 'is'
+    multiline: true
+error_messages:
+  - 'xcodebuild: error: Unable to find a destination matching the provided destination specifier'
+  - '== Devices ==\n-- iOS 18.4 --\n-- iOS 18.5 --\n-- iOS 18.6 --'
+  - 'xcrun simctl list devices available shows only visionOS simulators, iOS sections are empty'
+root_cause: |
+  On certain macOS-15-arm64 image versions (confirmed: 20250830.2281), `xcrun simctl list
+  devices available` returns empty iOS, tvOS, and watchOS device sections. Platform
+  section headers appear in the output (e.g., `-- iOS 18.4 --`, `-- iOS 18.5 --`) but
+  contain no device entries. Only visionOS simulators are listed.
+
+  This is an intermittent image-level regression — re-running the exact same workflow on
+  the same image version may succeed if the scheduler assigns a different runner instance
+  (which may have a different warm state for simctl). The failure is not reproducible
+  deterministically and does not produce a specific error from simctl itself; downstream
+  `xcodebuild` steps fail with "no matching destination" when attempting to test.
+
+  Root cause is believed to be a simctl/CoreSimulator state corruption in the image bake
+  process for affected image builds. The issue resolves when the image is rebuilt cleanly.
+  Not specific to any particular Xcode version — observed with Xcode 16.4 on
+  macos-15-arm64 image 20250830.2281.
+
+  Tracked in actions/runner-images#12948 (filed 2024, intermittent).
+fix: |
+  There is no reliable in-workflow fix. The following workarounds reduce the impact:
+
+  1. **Re-run the job** — the scheduler may assign a runner instance where simctl state
+     is intact. This is the only confirmed remediation for in-flight failures.
+
+  2. **Add a simctl diagnostic step** early in the job to detect the empty state and fail
+     fast with a clear error message rather than a confusing xcodebuild destination error.
+
+  3. **Boot a simulator explicitly** with `xcrun simctl boot <UDID>` before xcodebuild
+     if your workflow uses specific UDID-based destinations.
+
+  4. **Watch for image version updates** — affected image builds are typically replaced
+     within 1-3 days once the regression is reported. Pin to a known-good image version
+     if continuous failures are unacceptable.
+fix_code:
+  - language: yaml
+    label: 'Add early simctl health check to detect empty simulator list and fail fast'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # or macos-15-arm64
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Verify iOS simulators are available
+              run: |
+                SIM_COUNT=$(xcrun simctl list devices available | grep -c "iPhone\|iPad")
+                if [ "$SIM_COUNT" -eq 0 ]; then
+                  echo "::error::No iOS simulators available. This is a known intermittent image regression."
+                  echo "::error::Re-run the job to get a runner instance with intact simctl state."
+                  echo "Simctl output:"
+                  xcrun simctl list devices available
+                  exit 1
+                fi
+                echo "Found $SIM_COUNT iOS/iPadOS simulator devices."
+
+            - name: Build and test
+              run: |
+                xcodebuild test \
+                  -scheme MyScheme \
+                  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest'
+  - language: yaml
+    label: 'Reset CoreSimulator state before running tests (workaround for persistent corruption)'
+    code: |
+      - name: Reset CoreSimulator device registry (workaround)
+        run: |
+          # Shut down all running simulators
+          xcrun simctl shutdown all || true
+          # Erase all simulator content and settings
+          xcrun simctl erase all || true
+          # List available devices after reset
+          xcrun simctl list devices available
+prevention:
+  - 'Add a simulator availability check as a dedicated early step to detect the empty-simctl regression and fail fast with a descriptive message before reaching xcodebuild'
+  - 'Subscribe to actions/runner-images release notes and watch for image builds on macOS runners — affected builds are usually superseded within 1-3 days'
+  - 'Do not pin to specific affected image versions; instead pin to a known-good build or use the floating label and accept occasional re-runs'
+  - 'Consider caching simctl booted simulators across jobs using self-hosted runners if consistent simulator availability is critical'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/12948'
+    label: 'actions/runner-images#12948: [macOS] Xcode 16.4 sometimes missing simulators (2024–2025)'
+  - url: 'https://developer.apple.com/documentation/xcode/running-your-app-in-simulator-or-on-a-device'
+    label: 'Apple Developer Docs: Running your app in Simulator'
+  - url: 'https://developer.apple.com/forums/thread/651334'
+    label: 'Apple Developer Forums: xcrun simctl list — empty device list troubleshooting'

errors/runner-environment/windows-11-arm-llvm-libclang-x86-loadlibraryexw-failed.yml

@@ -0,0 +1,98 @@
+id: 'runner-environment-491'
+title: 'windows-11-arm Pre-installed LLVM is x86_64 — `libclang.dll` Fails to Load in Native ARM64 Process (LoadLibraryExW failed)'
+category: runner-environment
+severity: error
+tags:
+  - windows-11-arm
+  - llvm
+  - clang
+  - rust
+  - bindgen
+  - arm64
+  - runner-image
+patterns:
+  - regex: 'Unable to find libclang.*libclang\.dll could not be opened: LoadLibraryExW failed'
+    flags: 'i'
+  - regex: 'the `libclang` shared library at C:\\\\Program Files\\\\LLVM\\\\bin\\\\libclang\.dll could not be opened'
+    flags: 'i'
+  - regex: 'LoadLibraryExW failed.*libclang'
+    flags: 'i'
+  - regex: 'clang-sys.*unable to find libclang.*windows-11-arm'
+    flags: 'i'
+error_messages:
+  - 'Unable to find libclang: "the `libclang` shared library at C:\Program Files\LLVM\bin\libclang.dll could not be opened: LoadLibraryExW failed"'
+  - 'thread ''main'' panicked at ''Unable to find libclang: "could not open libclang.dll: LoadLibraryExW failed"'''
+root_cause: |
+  The `windows-11-arm` runner image pre-installs LLVM as an **x86_64 binary** under WoW64
+  emulation. When a native ARM64 process (such as a Rust build that uses `bindgen` or
+  `clang-sys`) attempts to load `C:\Program Files\LLVM\bin\libclang.dll`, the Windows
+  loader rejects it because the DLL is built for x86_64 and cannot be loaded into a
+  native ARM64 process.
+
+  The failure manifests as `LoadLibraryExW failed` — Windows silently returns an error
+  from the DLL loader rather than a meaningful architecture mismatch message. Build tools
+  that link against libclang (Rust's `clang-sys` crate, `bindgen`, LLDB Python bindings,
+  etc.) surface this as "Unable to find libclang".
+
+  Confirmed in actions/runner-images#14085 (June 2026, open). Upstream LLVM began
+  shipping prebuilt ARM64 Windows binaries in v20.1.0 (April 2025), but the runner image
+  was not updated to install the native ARM64 build.
+fix: |
+  Install a native ARM64 LLVM/Clang build before any step that requires libclang.
+  Use `KyleMayes/install-llvm-action@v2` (or later), which detects the runner architecture
+  and downloads the correct prebuilt LLVM binary from the LLVM GitHub releases.
+
+  Set `LIBCLANG_PATH` after installation so that `clang-sys`/`bindgen` find the correct
+  native library instead of falling back to the broken x86_64 system LLVM.
+fix_code:
+  - language: yaml
+    label: 'Install native ARM64 LLVM via KyleMayes/install-llvm-action'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-11-arm
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install native ARM64 LLVM
+              uses: KyleMayes/install-llvm-action@v2
+              with:
+                version: '20'     # First LLVM version with ARM64 Windows prebuilts
+
+            - name: Export LIBCLANG_PATH for clang-sys / bindgen
+              run: |
+                $llvmBin = (Get-Command clang).Source | Split-Path
+                echo "LIBCLANG_PATH=$llvmBin" >> $env:GITHUB_ENV
+              shell: pwsh
+
+            - name: Build (Rust with bindgen)
+              run: cargo build --release
+  - language: yaml
+    label: 'Set LIBCLANG_PATH manually if you install LLVM yourself'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-11-arm
+          steps:
+            - name: Download LLVM ARM64 and set LIBCLANG_PATH
+              run: |
+                $ver = "20.1.7"
+                $url = "https://github.com/llvm/llvm-project/releases/download/llvmorg-$ver/LLVM-$ver-woa64.exe"
+                Invoke-WebRequest $url -OutFile llvm-arm64.exe
+                Start-Process -Wait -FilePath llvm-arm64.exe -ArgumentList '/S', "/D=C:\LLVM-arm64"
+                echo "LIBCLANG_PATH=C:\LLVM-arm64\bin" >> $env:GITHUB_ENV
+              shell: pwsh
+prevention:
+  - 'Always verify that pre-installed tools on `windows-11-arm` are native ARM64 binaries and not x86_64 shims before relying on them in native ARM64 builds'
+  - 'Set `LIBCLANG_PATH` explicitly in workflows using `clang-sys` or `bindgen` on any Windows ARM64 runner'
+  - 'Check `llvm-project` releases for ARM64 Windows binaries before using the runner''s system LLVM — native builds have been available since v20.1.0'
+  - 'Use `file C:\Program Files\LLVM\bin\libclang.dll` (via Git Bash) or PowerShell `Get-Item` + `dumpbin /headers` to confirm whether the installed DLL is ARM64 or x86_64'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14085'
+    label: 'actions/runner-images#14085: [windows-11-arm] libclang broken (June 2026)'
+  - url: 'https://github.com/KyleMayes/install-llvm-action'
+    label: 'KyleMayes/install-llvm-action: Cross-platform LLVM installer for GitHub Actions'
+  - url: 'https://github.com/llvm/llvm-project/releases'
+    label: 'LLVM Project Releases: Native ARM64 Windows binaries available from v20.1.0'
+  - url: 'https://github.com/rust-lang/rust-bindgen'
+    label: 'rust-lang/rust-bindgen: Uses libclang and respects LIBCLANG_PATH'

errors/silent-failures/windows-11-arm-platform-machine-returns-amd64-not-arm64.yml

@@ -0,0 +1,115 @@
+id: 'silent-failures-229'
+title: 'windows-11-arm `platform.machine()` and `PROCESSOR_ARCHITECTURE` Return AMD64 Instead of ARM64 — Wrong Architecture Binaries Downloaded Silently'
+category: silent-failures
+severity: silent-failure
+tags:
+  - windows-11-arm
+  - arm64
+  - python
+  - architecture-detection
+  - runner-image
+  - silent-failure
+patterns:
+  - regex: 'platform\.machine\(\).*AMD64.*windows-11-arm|windows-11-arm.*platform\.machine.*AMD64'
+    flags: 'i'
+  - regex: 'PROCESSOR_ARCHITECTURE.*AMD64.*windows-11-arm|windows-11-arm.*PROCESSOR_ARCHITECTURE.*AMD64'
+    flags: 'i'
+  - regex: 'R\.version.*x86_64-w64-mingw32.*windows-11-arm'
+    flags: 'i'
+  - regex: 'arch.*x86_64.*windows-11-arm.*expected.*aarch64'
+    flags: 'i'
+error_messages:
+  - 'platform       x86_64-w64-mingw32'
+  - 'arch           x86_64'
+  - 'Python platform.machine(): AMD64'
+  - 'PROCESSOR_ARCHITECTURE: AMD64'
+root_cause: |
+  On `windows-11-arm`, the pre-installed Python interpreter and R runtime are **x86_64
+  binaries** running under WoW64 ARM64 emulation. When these tools report architecture
+  information, they report their own binary architecture (x86_64 / AMD64) rather than
+  the host hardware architecture (ARM64 / aarch64).
+
+  This affects:
+  - `python -c "import platform; print(platform.machine())"` → returns `"AMD64"`
+  - `$env:PROCESSOR_ARCHITECTURE` → returns `"AMD64"` (set by WoW64 for x86_64 processes)
+  - `Rscript -e 'print(R.version)'` → platform returns `"x86_64-w64-mingw32"`
+
+  Correct detection methods that reflect the true hardware:
+  - `$env:PROCESSOR_IDENTIFIER` → returns `"ARMv8 (64-bit) Family 8 Model D49 Revision 0, MICROSOFT CORPORATION"`
+  - `python -c "import platform; print(platform.processor())"` → returns the ARMv8 identifier
+
+  The silent failure occurs when a workflow script uses `platform.machine()` or
+  `PROCESSOR_ARCHITECTURE` to decide which binary to download. The script silently
+  selects an x86_64 artifact instead of the ARM64 one. The downloaded binary may run
+  under WoW64 emulation (appearing to succeed) but at significantly reduced performance,
+  or it may fail at link/runtime with a hard-to-diagnose error.
+
+  Tracked in actions/runner-images#14071 and #14089 (June 2026, open).
+fix: |
+  Use `PROCESSOR_IDENTIFIER` or `PROCESSOR_ARCHITEW6432` to detect ARM64 on
+  `windows-11-arm`. These environment variables are set by Windows for the native
+  hardware and are NOT overridden by WoW64.
+
+  For Python scripts:
+    processor_id = os.environ.get('PROCESSOR_IDENTIFIER', '')
+    is_arm64 = 'ARMv8' in processor_id or 'ARM64' in processor_id
+
+  For PowerShell/shell scripts:
+    Use `$env:PROCESSOR_IDENTIFIER` or check `[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture`
+    which returns `Arm64` correctly even from an x86_64 process.
+
+  For GitHub Actions expressions (setting matrix arch):
+    Use `runner.arch` context: `${{ runner.arch }}` returns `ARM64` on windows-11-arm.
+    This is the most reliable method for conditional workflow logic.
+fix_code:
+  - language: yaml
+    label: 'Use runner.arch context instead of platform.machine() for arch-conditional steps'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-11-arm
+          steps:
+            - name: Detect architecture via runner context (reliable)
+              run: echo "Runner arch is ${{ runner.arch }}"
+
+            - name: Download correct binary based on runner.arch
+              run: |
+                if ("${{ runner.arch }}" -eq "ARM64") {
+                  $arch = "arm64"
+                } else {
+                  $arch = "amd64"
+                }
+                Invoke-WebRequest "https://example.com/tool-windows-$arch.zip" -OutFile tool.zip
+              shell: pwsh
+  - language: yaml
+    label: 'Python arch detection that works correctly on windows-11-arm'
+    code: |
+      - name: Detect true host architecture in Python
+        run: |
+          python - <<'EOF'
+          import os, platform
+
+          # WRONG: returns AMD64 on windows-11-arm (reports x86_64 WoW64 process arch)
+          # print(platform.machine())
+
+          # CORRECT: check PROCESSOR_IDENTIFIER for true hardware arch
+          proc_id = os.environ.get('PROCESSOR_IDENTIFIER', '')
+          is_arm64 = 'ARMv8' in proc_id or 'ARM64' in proc_id
+          arch = 'arm64' if is_arm64 else 'amd64'
+          print(f"True arch: {arch}")
+          EOF
+        shell: bash
+prevention:
+  - 'Never use `platform.machine()`, `$env:PROCESSOR_ARCHITECTURE`, or `R.version$arch` for architecture detection on `windows-11-arm` — these return x86_64/AMD64 from WoW64 processes'
+  - 'Use `${{ runner.arch }}` in GitHub Actions workflow expressions for arch-conditional logic'
+  - 'Use `$env:PROCESSOR_IDENTIFIER` or `[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture` in PowerShell for reliable native arch detection'
+  - 'Add an architecture verification step early in workflows to print `runner.arch` and catch misdetection before it causes silent failures downstream'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14071'
+    label: 'actions/runner-images#14071: windows-11-arm PROCESSOR_ARCHITECTURE returns AMD64 (June 2026)'
+  - url: 'https://github.com/actions/runner-images/issues/14089'
+    label: 'actions/runner-images#14089: windows-11-arm R reports wrong arch x86_64 (June 2026)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#runner-context'
+    label: 'GitHub Docs: runner.arch context property'
+  - url: 'https://learn.microsoft.com/en-us/windows/win32/winprog64/wow64-implementation-details'
+    label: 'Microsoft Docs: WoW64 and PROCESSOR_ARCHITECTURE environment variable behaviour'