[Visual Test] Label preflight aborts before screenshot capture

[MichaelFisher1997]

Workflow run

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

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.

build-output.log is absent because the game did not run. The Ensure visual-test label exists step failed first; Setup Lavapipe Vulkan and Run menu screenshot capture were consequently skipped.

Diagnosis

The failure originates in the Ensure visual-test label exists shell step at .github/workflows/visual-test.yml:55, specifically the second check at .github/workflows/visual-test.yml:62:

if ! gh label list --json name --jq '.[].name' | grep -q "^run-visual-test$"; then
  gh label create "run-visual-test" ...
fi

gh label list defaults to 30 results. This repository has more than 30 labels, and run-visual-test is outside that first page. The check therefore reports a false absence, gh label create attempts to create the existing label, and bash -e terminates the step with exit code 1.

This is a workflow preflight failure, not a Vulkan, swapchain, shader, HomeScreen, or screenshot-readback failure. No Zig function was reached. In particular, captureFrame in modules/engine-graphics/src/rhi_vulkan.zig:415 and requestCapture in modules/engine-graphics/src/vulkan/screenshot.zig:24 were never called. The current workflow also passes screenshot.png at .github/workflows/visual-test.yml:81, which is supported by detectScreenshotFormat in modules/engine-graphics/src/vulkan/screenshot.zig:262; the diagnosis prompt still describing a PPM capture is stale.

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

Alternatively, query each label directly with gh label view <name> before creating it. Also update .github/prompts/visual-test-diagnose.md to match the current PNG workflow and modules/game-ui/src/screens/home.zig path so future diagnosis starts from accurate context.

[github-actions]

Confirmed and validated against the live repo. Two corroborating observations:

1. gh label list --json name returns exactly 30 entries (the default --limit), and run-visual-test is not among them. With --limit 100 it appears, confirming the pagination false-negative.
2. .github/workflows/visual-test.yml:62 is still the pre---force version, identical to what was reported.

This is the seventh open issue with the same root cause (#916, #931, #935, #937, #942, #944, plus this one). None of them have a linked PR — every fix attempt has either been superseded by another regression or has not landed. The recurring nature suggests the workflow is being edited faster than label setup is being made idempotent.

The --force suggestion is the cleanest fix: gh label create ... --force succeeds whether or not the label exists, eliminating the pagination race entirely. A complementary safety net would be to move label bootstrap into a composite action or .github/actions/setup-labels so it isn't reimplemented per-workflow. If you want to keep the existence-check semantics, query each label by name with the GraphQL endpoint (gh api graphql -f query='query{repository(labels(first:1, query:"run-visual-test")){totalCount}}') which is not subject to the CLI's 30-item cap.

Also confirming the stale-context claim in the issue: .github/prompts/visual-test-diagnose.md still says -Dscreenshot-path=screenshot.ppm (line 7), "capture a screenshot as PPM" (line 8), and src/game/screens/home.zig (line 29). The actual screen now lives at modules/game-ui/src/screens/home.zig and the workflow captures PNG directly. Future diagnoses triggered off that prompt will start from wrong context.

Scope note: this is a single-step CI fix, not multi-subsystem. It should NOT be broken into sub-issues. The right follow-ups (composite action for labels, refresh of the diagnose prompt) can be tracked as separate small issues if desired, but the immediate blocker is one git change to the workflow file.

Classification: Bug (CI preflight, fully diagnosed, fix understood).

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.