fix(brightness): guard keyboard backlight state across lock and idle blanking

[cleon01day]

Summary

Guard keyboard backlight saved state against zero-clobbering and ensure reliable brightness restoration across lock-screen blanking, idle sleep, and system resume.

---

Context & Problem

When locking the session in Omarchy, or when displays blank while locked, the keyboard backlight fails to turn back on after unlocking or waking the system (brightness = 0). The user is left in the dark until they manually adjust brightness using the brightness function keys.

This issue is especially prominent on laptops with autonomous firmware LED power management, such as Apple T2 MacBooks (106b:180[12]) where the internal keyboard and backlight hang off the t2bce_vhci virtual USB host controller (configured via install/hardware/apple/fix-t2.sh):

1. The T2 firmware independently dims and shuts off keyboard LEDs during input inactivity or panel blanking.
2. In shell/plugins/lock/Service.qml, blankProcess executes omarchy-brightness-keyboard off; omarchy-brightness-display off.
3. In bin/omarchy-brightness-keyboard, direction == "off" executes brightnessctl -sd "$device" set 0.
4. Because the LEDs are frequently already at 0 when off is called (either from the autonomous hardware timeout, repeated blanking events, or screen sleep preceding lock), brightnessctl -s blindly writes 0 into the state file (${XDG_RUNTIME_DIR}/brightnessctl/leds/<device>).
5. On wake or unlock, finishUnlock() invokes omarchy-system-wake, which calls omarchy-brightness-keyboard restore.
6. Because restore reads 0 from the corrupted state file, and because the virtual USB controller initializes registers at 0 upon resume, userspace actively commands the backlight to remain dark.

---

Solution

1. Guard off against Zero-Clobbering in bin/omarchy-brightness-keyboard:
   Only pass -s (save) to brightnessctl when current_brightness > 0. If the backlight is already at 0, turn off without overwriting the positive saved state buffer.
2. Persistent State Tracking:
   Persist non-zero user target levels to ${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/keyboard-brightness upon explicit adjustments (up, down, cycle) and positive off calls.
3. Multi-Tier restore with Graceful Fallback:
   • First attempt standard brightnessctl -rd "$device".
   • If the restored value remains 0 (or if runtime state was cleared/missing), restore from the persistent state file.
   • If no recorded positive state exists (e.g. fresh boot), fall back to 30% of max brightness rather than leaving the user in the dark.
4. Post-Resume Hibernate Hook:
   Update default/systemd/system-sleep/keyboard-backlight to include a post resume handler that restores the backlight level after hibernation.
5. Automated Unit Test:
   Added test/shell.d/brightness-keyboard-test.sh asserting zero-clobber protection, state fallback resolution, and step calculations.

---

Verification

• Tested on Apple T2 MacBook Pro (linux-t2 with t2bce_vhci) running Hyprland + Quickshell.
• Verified consecutive off calls preserve saved positive brightness.
• Verified wake restoration from lock and display blanking successfully restores target brightness.
• Verified fallback restoration to 30% when runtime and persistent state files are absent.
• Ran ./test/cli: all 105 tests passed.
• Ran test/shell.d/brightness-keyboard-test.sh: all 6 assertions passed.
• Ran test/shell.d/system-sleep-ownership-migration-test.sh: all 32 assertions passed.