[Visual Test] Label preflight skips Lavapipe screenshot capture

[MichaelFisher1997]

Workflow run

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

Exact failure output

label with name "run-visual-test" already exists; use `--force` to update its color and description
##[error]Process completed with exit code 1.

There is no build-output.log in the workspace for this run. The workflow failed at step 8, Ensure visual-test label exists; Setup Lavapipe Vulkan and Run menu screenshot capture were then skipped, so the game never started and the log/artifact was never created.

Observed step state:

Ensure visual-test label exists     failure
Setup Lavapipe Vulkan               skipped
Run menu screenshot capture         skipped
Upload build log artifact           skipped

Weston itself started successfully at 1280x720 and was terminated after the preflight failure; weston.log contains no compositor initialization error.

Diagnosis

The root cause is the label bootstrap logic in .github/workflows/visual-test.yml:55-68, specifically the second guard and create at .github/workflows/visual-test.yml:62-65:

if ! gh label list --json name --jq '.[].name' | grep -q '^run-visual-test$'; then
  gh label create "run-visual-test" \
    --description "Run deterministic visual regression workflow on a PR" \
    --color "E06C75"
fi

gh label list defaults to 30 results. This repository currently has 41 labels: visual-test is position 21 and run-visual-test is position 41 in the returned order. The unbounded existence check therefore cannot see run-visual-test, concludes that it is missing, and calls gh label create. GitHub rejects that duplicate create, and the step exits with status 1.

This is a workflow preflight failure, not a Vulkan instance/device, swapchain, shader, HomeScreen, or screenshot readback failure. No Zig function in the requested rendering path was reached:

• initContext in modules/engine-graphics/src/rhi_vulkan.zig:36-39
• headless createSwapchain path in modules/engine-graphics/src/vulkan_swapchain.zig:127-174
• menu selection in src/game/app.zig:268-276
• HomeScreen.init in modules/game-ui/src/screens/home.zig:33-41
• screenshot request in src/game/app.zig:545-556
• captureFrame in modules/engine-graphics/src/rhi_vulkan.zig:415-420
• requestCapture in modules/engine-graphics/src/vulkan/screenshot.zig:24-87

The workflow currently passes -Dscreenshot-path=screenshot.png at .github/workflows/visual-test.yml:81, not screenshot.ppm. PNG is accepted by detectScreenshotFormat in modules/engine-graphics/src/vulkan/screenshot.zig:262-267; PPM is not. The diagnosis prompt/context should be updated separately so future investigations match the actual workflow.

Failure origin

• File: .github/workflows/visual-test.yml
• Step: Ensure visual-test label exists
• Failing command: gh label create "run-visual-test" at .github/workflows/visual-test.yml:63
• Trigger: paginated gh label list guard at .github/workflows/visual-test.yml:62

No game-side function originated this failure because the game command at .github/workflows/visual-test.yml:81 was skipped.

Suggested fix

Make label setup idempotent without relying on a paginated list:

- 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 label directly with gh label view <name> before creating it. Merely increasing --limit would work today but can regress again as the label count grows.

[github-actions]

Analysis

Classification: Bug (CI infrastructure / workflow preflight failure). Validated against .github/workflows/visual-test.yml:55-66.

Diagnosis confirmed. gh label list defaults to --limit 30. With 41+ labels in the repo, run-visual-test (position 41) falls outside the default page, the grep -q '^run-visual-test$' guard misses it, and gh label create rejects the duplicate. The same pattern on line 57 for visual-test works today only because that label is inside the first 30; it will break as soon as the label count grows, so the --force fix should be applied to both labels, not just run-visual-test.

Suggested fix is correct and minimal. gh label create --force <name> is idempotent and removes the paginated existence check entirely, which is the right approach. gh label view <name> would also work but adds a round trip per label per run. Bumping --limit is a bad fix as the report notes - it will regress.

No game-side action required. The issue correctly identifies that none of the rendering, RHI, swapchain, menu, HomeScreen, or screenshot code paths were reached. The Lavapipe/Weston/screenshot pipeline is fine; only the label bootstrap needs changing. Confirming the validation points cited all exist:

• modules/engine-graphics/src/rhi_vulkan.zig:36-39 (initContext)
• modules/engine-graphics/src/vulkan_swapchain.zig:127-174 (createSwapchain headless path)
• src/game/app.zig:268-276 (menu selection)
• modules/game-ui/src/screens/home.zig:33-41 (HomeScreen.init)
• src/game/app.zig:545-556 (screenshot request)
• modules/engine-graphics/src/rhi_vulkan.zig:415-420 (captureFrame)
• modules/engine-graphics/src/vulkan/screenshot.zig:24-87 (requestCapture)

Additional notes for the fix PR:

1. Apply --force to both visual-test (line 58) and run-visual-test (line 63) so the latent bug on visual-test is fixed at the same time.
2. Consider removing the gh label list guards entirely since --force covers the create-update idempotency path, simplifying the step.
3. The report mentions the diagnosis prompt at .github/prompts/visual-test-diagnose.md still references screenshot.ppm but the workflow passes -Dscreenshot-path=screenshot.png (line 81). That is a separate, prompt-only fix and should be tracked independently so it doesn't gate this CI fix.

Scope: Single-file workflow change, suitable for one PR. No need to break into sub-issues. This is not a duplicate of any open PR/issue in this repo (only the one workflow uses this pattern; verified via grep across .github/).

No reproduction steps needed from author - the diagnosis is internally complete and the fix is unambiguous.

opencode session  |  github run

[github-actions]

This issue has had no activity for 60 days. It will be closed in 14 days unless there is new activity or an exemption label is added.