Two agents hit this independently today (while building #676 and #669), each losing a gate run to it.
The contradiction
CLAUDE.md:54 documents, under "Tests":
xvfb-run cargo test --features system-tests -p hytte-ui # display tests headless
and CLAUDE.md:62 says "The GTK-dependent system tests need a display server (xvfb-run works)."
But xvfb-run is not in the devShell. It is absent from nix/devshell.nix, and flake.nix:347 states the situation outright in a comment — that neither dbus-daemon nor xvfb-run is in the devShell; flake.nix:361 adds pkgs.xvfb-run only to the CI system-tests check.
So CLAUDE.md — the file whose whole premise is "you must work inside the Nix devShell" — documents a command that exits 127 inside that devShell. The working invocation is:
nix shell nixpkgs#xvfb-run --command cargo test --features system-tests -p hytte-ui
Why it is worth fixing rather than shrugging at
The failure is not self-explaining. xvfb-run: command not found in the middle of a long gate run reads like an environment problem with the machine, not a documented-but-absent tool — and both agents that hit it spent time re-running before working it out. Anyone following CLAUDE.md literally, human or agent, hits the same wall.
It also undermines the gate: the path of least resistance after hitting 127 is to skip the display tests, which is precisely the bucket most likely to catch a GTK regression.
Two fixes, and I lean strongly to the first
- Add
pkgs.xvfb-run to nix/devshell.nix. The documentation is right and the environment is wrong. CI already depends on xvfb-run, so this introduces no new dependency to the flake — it makes the local shell match the checks it is meant to reproduce. Cheap, and CLAUDE.md then needs no change.
- Correct
CLAUDE.md to show the nix shell nixpkgs#xvfb-run --command … form. Honest, but it leaves a documented workflow more awkward than it needs to be, and the same friction reappears every time.
Worth checking dbus-daemon at the same time — flake.nix:347 groups them together, and CLAUDE.md:63-65 says hytte-bus's system tests "spawn a real dbus-daemon (one ephemeral broker per test; must be on PATH)". If that is also devShell-absent, it has the identical problem and should be fixed in the same commit.
Sequencing note
If fix (2) is chosen it touches CLAUDE.md, which is currently owned by open PR #672 and also by issue #670. Fix (1) touches only nix/devshell.nix and has no such collision — another small point in its favour.
Severity
Low. No shipped defect; this is developer and agent experience. Filed because it is a documented command that does not work, it has now cost two contributors time on the same day, and the fix is one line.
Refs #677, #683, #670.
Two agents hit this independently today (while building #676 and #669), each losing a gate run to it.
The contradiction
CLAUDE.md:54documents, under "Tests":and
CLAUDE.md:62says "The GTK-dependent system tests need a display server (xvfb-runworks)."But
xvfb-runis not in the devShell. It is absent fromnix/devshell.nix, andflake.nix:347states the situation outright in a comment — that neitherdbus-daemonnorxvfb-runis in the devShell;flake.nix:361addspkgs.xvfb-runonly to the CIsystem-testscheck.So
CLAUDE.md— the file whose whole premise is "you must work inside the Nix devShell" — documents a command that exits 127 inside that devShell. The working invocation is:nix shell nixpkgs#xvfb-run --command cargo test --features system-tests -p hytte-uiWhy it is worth fixing rather than shrugging at
The failure is not self-explaining.
xvfb-run: command not foundin the middle of a long gate run reads like an environment problem with the machine, not a documented-but-absent tool — and both agents that hit it spent time re-running before working it out. Anyone followingCLAUDE.mdliterally, human or agent, hits the same wall.It also undermines the gate: the path of least resistance after hitting 127 is to skip the display tests, which is precisely the bucket most likely to catch a GTK regression.
Two fixes, and I lean strongly to the first
pkgs.xvfb-runtonix/devshell.nix. The documentation is right and the environment is wrong. CI already depends onxvfb-run, so this introduces no new dependency to the flake — it makes the local shell match the checks it is meant to reproduce. Cheap, andCLAUDE.mdthen needs no change.CLAUDE.mdto show thenix shell nixpkgs#xvfb-run --command …form. Honest, but it leaves a documented workflow more awkward than it needs to be, and the same friction reappears every time.Worth checking
dbus-daemonat the same time —flake.nix:347groups them together, andCLAUDE.md:63-65sayshytte-bus's system tests "spawn a realdbus-daemon(one ephemeral broker per test; must be onPATH)". If that is also devShell-absent, it has the identical problem and should be fixed in the same commit.Sequencing note
If fix (2) is chosen it touches
CLAUDE.md, which is currently owned by open PR #672 and also by issue #670. Fix (1) touches onlynix/devshell.nixand has no such collision — another small point in its favour.Severity
Low. No shipped defect; this is developer and agent experience. Filed because it is a documented command that does not work, it has now cost two contributors time on the same day, and the fix is one line.
Refs #677, #683, #670.