INC-2026-04-07-002: Prevention

Lessons Learned

What Went Well

  • Reverse SSH tunnel established quickly for remote investigation

  • hyprctl dispatch exec workaround kept machine partially usable

  • md5sum comparison eliminated config content early

  • Git checkout of known-good commit was the breakthrough

What Could Be Improved

  • Should have checked file existence first, not file content. ls ~/.config/hypr/env-gpu.conf would have shown "No such file" immediately. Instead, 2.5 hours was spent comparing checksums of files that existed.

  • Should have run git diff between working and broken state in the first 10 minutes. The breaking change was a single file deletion.

  • "Empty config" test was misleading. On a hybrid GPU machine, no GPU config ≠ "clean baseline." It means "different broken state."

  • Chased kernel/driver hypotheses too long. User repeatedly said "this worked before the dots-quantum pull." Should have trusted that signal and focused on what the pull changed.

Key Takeaways

  1. Stow directory symlinks are transparent. If ~/.config/hypr is a symlink to the stow package, deleting a file from git deletes it from the deployed config. There is no separate "deployed copy" — they are the same files.

  2. When the user says "it broke after X," investigate X first. Not the kernel, not the driver, not the session state — the thing that changed.

  3. ls before md5sum. Verify the file exists before comparing its contents.

  4. GPU environment variables affect input devices. On NVIDIA hybrid GPU machines, missing GBM_BACKEND and __GLX_VENDOR_LIBRARY_NAME can cause the compositor to use the wrong rendering backend, which cascades to input device initialization failures on USB controllers connected to the discrete GPU.

  5. Per-machine config via hostname ($HOST) is more robust than symlinks. Symlinks can be deleted, gitignored, tracked/untracked. A $HOST-based path in the config file is self-contained and survives any git operation.

Related