[Visual Test] Label pagination aborts workflow before screenshot capture

[MichaelFisher1997]

Workflow run

https://github.com/OpenStaticFish/ZigCraft/actions/runs/30795834741

Head SHA: 8d205ff0b27a951ac7136cb72796ecd8e2e91ed4

Exact failure

The failure is not in Vulkan or screenshot readback. The game command never ran, so build-output.log was never created. Actions reports Ensure visual-test label exists as failed, followed by Setup Lavapipe Vulkan and Run menu screenshot capture as skipped.

The failing branch invokes:

gh label create "run-visual-test" \
  --description "Run deterministic visual regression workflow on a PR" \
  --color "E06C75"

The resulting error is:

label with name "run-visual-test" already exists; use `--force` to update its color and description

Root cause

.github/workflows/visual-test.yml:55 attempts to make label creation conditional by piping gh label list into grep. In particular, .github/workflows/visual-test.yml:62 checks for run-visual-test, then .github/workflows/visual-test.yml:63 creates it when the check misses.

gh label list returns only 30 labels by default. This repository currently has 41 labels, and run-visual-test is after the first 30. The check therefore reports it as absent even though it exists. The subsequent duplicate create fails and, because the step runs with -e, aborts the job before Lavapipe setup or the screenshot command.

There is consequently no Vulkan instance/device, swapchain, shader, panic, or screenshot-capture error to diagnose. The Zig paths were never entered: VulkanSwapchain.createSwapchain at modules/engine-graphics/src/vulkan_swapchain.zig:127, screenshot-mode initialization at src/game/app.zig:268, and screenshot.requestCapture at modules/engine-graphics/src/vulkan/screenshot.zig:24 were not executed.

The diagnosis prompt is also stale but did not cause this run failure: .github/prompts/visual-test-diagnose.md:7 says screenshot.ppm, while the actual command at .github/workflows/visual-test.yml:81 uses the supported screenshot.png; the current encoder rejects .ppm at modules/engine-graphics/src/vulkan/screenshot.zig:39.

Suggested fix

Make the bootstrap idempotent without relying on paginated list output:

- name: Ensure visual-test labels exist
  run: |
    gh label create "visual-test" \
      --description "Issues from automated visual regression tests" \
      --color "E06C75" \
      --force
    gh label create "run-visual-test" \
      --description "Run deterministic visual regression workflow on a PR" \
      --color "E06C75" \
      --force
  env:
    GH_TOKEN: ${{ secrets.OPENCODE_PAT }}

Alternatively, query each exact label through gh api repos/$GITHUB_REPOSITORY/labels/<name> before creating it. Adding --limit 100 would fix the current repository but retains a future pagination threshold.

Also update .github/prompts/visual-test-diagnose.md to describe PNG output and the current HomeScreen path (modules/game-ui/src/screens/home.zig).

[github-actions]

Validation

Report is accurate. Confirmed against the current tree:

• .github/workflows/visual-test.yml:55-66 runs gh label list --json name --jq '.[].name' | grep -q '^run-visual-test$' then unconditionally calls gh label create when the lookup misses. gh label list paginates at 30 entries; gh label list --limit 100 --json name confirms the repo now has 41 labels and run-visual-test is on page 2, so the grep always misses on a fully-labeled repo and gh label create returns the error you quoted. -e (default for run:) then aborts the job before the Lavapipe setup, screenshot step, and downstream opencode diagnostics ever run, which matches the observed "skipped" downstream steps and absence of build-output.log.
• No Vulkan / swapchain / screenshot code path executes on this run, so the callouts to modules/engine-graphics/src/vulkan_swapchain.zig:127, src/game/app.zig:268, and modules/engine-graphics/src/vulkan/screenshot.zig:24 are correctly framed as not relevant to this particular failure.
• The secondary prompt drift is real but harmless to this run: .github/prompts/visual-test-diagnose.md:7 still documents screenshot.ppm, while visual-test.yml:81 invokes zig build run -Dscreenshot-path=screenshot.png, and modules/engine-graphics/src/vulkan/screenshot.zig:39-41 rejects .ppm ("use .png, .jpg, .jpeg, .gif, or .webp"). The HomeScreen reference at line 29 (src/game/screens/home.zig) is also stale; the canonical location is modules/game-ui/src/screens/home.zig.

Duplicate history

This is the latest in a long sequence of essentially identical reports for the same workflow run-day failure. Cross-referenced open issues filed against the visual-test workflow / label preflight:

• [Visual Test] Label preflight fails: gh label list only returns first 30 labels, run-visual-test is on page 2 #916 "Label preflight fails: gh label list only returns first 30 labels, run-visual-test is on page 2"
• [Visual Test] Label preflight regressed: gh label list pagination skips run-visual-test on run #19 #931 "Label preflight regressed: gh label list pagination skips run-visual-test on run 🔍 Conduct Comprehensive Code Audit - Architecture, Performance, SOLID, and Quality Standards #19"
• [Visual Test] Label preflight regressed again: unpaginated gh label list still misses run-visual-test on run #20 #935 "Label preflight regressed again: unpaginated gh label list still misses run-visual-test on run Refactor: Comprehensive Audit Fixes (Critical & Performance) #20"
• [Visual Test] Label preflight prevents screenshot capture on run #26 #942 "Label preflight prevents screenshot capture on run Full Codebase Audit v3 #26"
• [Visual Test] Label preflight aborts before screenshot capture #945 "Label preflight aborts before screenshot capture"
• [Visual Test] Label preflight skips Lavapipe screenshot capture #946 "Label preflight skips Lavapipe screenshot capture"
• [Visual Test] Workflow fails before game runs: 'Ensure visual-test label exists' step rejected by duplicate label #947 "Workflow fails before game runs: 'Ensure visual-test label exists' step rejected by duplicate label"
• [Visual Test] Label preflight rejects duplicate label, skipping Lavapipe screenshot capture #950 "Label preflight rejects duplicate label, skipping Lavapipe screenshot capture"
• [Visual Test] Label preflight rejects duplicate label on run #30192579914, skipping Lavapipe screenshot capture #952 "Label preflight rejects duplicate label on run #30192579914, skipping Lavapipe screenshot capture"
• [Visual Test] Label preflight skips Lavapipe screenshot capture on run #30248571304 #954 "Label preflight skips Lavapipe screenshot capture on run #30248571304"
• [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30431891169 #958 "Label preflight pagination skips Lavapipe screenshot capture on run #30431891169"
• [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30522565636 #960 "Label preflight pagination skips Lavapipe screenshot capture on run #30522565636"
• [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30689332702 #964 "Label preflight pagination skips Lavapipe screenshot capture on run #30689332702"
• [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30737520741 #966 "Label preflight pagination skips Lavapipe screenshot capture on run #30737520741"

There are also automated follow-up PRs from opencode for several of these (e.g. #953, #955, #957, #959, #961, #963, #965, #967, #969) that re-state the same fix without landing it, which strongly suggests the underlying visual-test.yml change has never been merged.

Recommended next steps (smallest scope)

1. Fix the workflow (primary): drop the grep guard and make the step idempotent. The --force form proposed in the issue is the simplest and removes the pagination class of bug entirely. Suggested patch:

   - name: Ensure visual-test labels exist
     run: |
       gh label create "visual-test" \
         --description "Issues from automated visual regression tests" \
         --color "E06C75" --force
       gh label create "run-visual-test" \
         --description "Run deterministic visual regression workflow on a PR" \
         --color "E06C75" --force
     env:
       GH_TOKEN: ${{ secrets.OPENCODE_PAT }}

   Do not use --limit 100 as the only fix; the label set will keep growing and the same failure will recur. The gh api repos/$GITHUB_REPOSITORY/labels/<name> lookup pattern is fine but is strictly more code than just passing --force.

2. Close the duplicate opencode follow-up PRs (Label preflight paginates, skips screenshot run. #953, Filed #954: label preflight pagination bug. #955, Filed issue #956: label preflight skips game run. #957, Filed issue #958: label preflight pagination skips screenshot. #959, Filed issue #960; same label-preflight bug. #961, Black golden image fails the visual-test comparison. #963, Label preflight pagination skips game run. #965, Filed #966: label preflight pagination bug. #967, Issue #968: label pagination failure #969, and any later ones) once the workflow fix lands, and either close or duplicate this stack of issues ([Visual Test] Label preflight fails: gh label list only returns first 30 labels, run-visual-test is on page 2 #916, [Visual Test] Label preflight regressed: gh label list pagination skips run-visual-test on run #19 #931, [Visual Test] Label preflight regressed again: unpaginated gh label list still misses run-visual-test on run #20 #935, [Visual Test] Label preflight prevents screenshot capture on run #26 #942, [Visual Test] Label preflight aborts before screenshot capture #945, [Visual Test] Label preflight skips Lavapipe screenshot capture #946, [Visual Test] Workflow fails before game runs: 'Ensure visual-test label exists' step rejected by duplicate label #947, [Visual Test] PPM screenshot path is rejected before Vulkan readback #949, [Visual Test] Label preflight rejects duplicate label, skipping Lavapipe screenshot capture #950, [Visual Test] Label preflight rejects duplicate label on run #30192579914, skipping Lavapipe screenshot capture #952, [Visual Test] Label preflight skips Lavapipe screenshot capture on run #30248571304 #954, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30431891169 #958, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30522565636 #960, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30689332702 #964, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30737520741 #966, [Visual Test] Label pagination aborts workflow before screenshot capture #968) against a single canonical tracking issue so the next failure doesn't reopen N copies.

3. Update the diagnosis prompt (secondary): refresh .github/prompts/visual-test-diagnose.md so it matches the current command line. Specifically: change line 7 to -Dscreenshot-path=screenshot.png, change line 8/43 references from "PPM" to "PNG" (and remove the "PPM is then converted to PNG" step on line 9), and change line 29 to point at modules/game-ui/src/screens/home.zig. Without this, the diagnosis prompt will misattribute the next failure into the screenshot encoder even though the screenshot path will not be the failing step.

4. Optional hardening: while editing the workflow, consider also having the screenshot step write its log even on early failure (e.g. run: with tee build-output.log | cat) so the diagnosis prompt always has a log to read, and keep the Ensure visual-test labels exist step continue-on-error: true guarded with an explicit if: so it can never block Lavapipe setup. Neither is required to fix this run, but both reduce the chance of another no-log triage loop.

None of the above requires code changes outside .github/workflows/visual-test.yml and .github/prompts/visual-test-diagnose.md; the Vulkan/RHI screenshot path is not implicated.

[github-actions]

Comment posted on #968: #968 (comment)

Validation summary:

• Bug, validated. The pagination/duplicate-label diagnosis is correct against .github/workflows/visual-test.yml:55-66 (confirmed repo has 41 labels, run-visual-test past the 30-row default page). The secondary prompt drift at .github/prompts/visual-test-diagnose.md:7 (.ppm vs .png) and stale src/game/screens/home.zig reference are also confirmed.
• Duplicate of at least 14 prior open issues ([Visual Test] Label preflight fails: gh label list only returns first 30 labels, run-visual-test is on page 2 #916, [Visual Test] Label preflight regressed: gh label list pagination skips run-visual-test on run #19 #931, [Visual Test] Label preflight regressed again: unpaginated gh label list still misses run-visual-test on run #20 #935, [Visual Test] Label preflight prevents screenshot capture on run #26 #942, [Visual Test] Label preflight aborts before screenshot capture #945, [Visual Test] Label preflight skips Lavapipe screenshot capture #946, [Visual Test] Workflow fails before game runs: 'Ensure visual-test label exists' step rejected by duplicate label #947, [Visual Test] Label preflight rejects duplicate label, skipping Lavapipe screenshot capture #950, [Visual Test] Label preflight rejects duplicate label on run #30192579914, skipping Lavapipe screenshot capture #952, [Visual Test] Label preflight skips Lavapipe screenshot capture on run #30248571304 #954, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30431891169 #958, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30522565636 #960, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30689332702 #964, [Visual Test] Label preflight pagination skips Lavapipe screenshot capture on run #30737520741 #966) plus the opencode follow-up PRs that keep re-proposing the same --force fix without it landing.
• Smallest next step: one-file fix to visual-test.yml using --force (not --limit 100, which only delays the recurrence), then refresh the diagnosis prompt and close the duplicate stack. No Vulkan/RHI changes needed.

opencode session  |  github run