the power button on the desktop did literally nothing when i pressed it. i told the agent i want that button to turn the screen off and leave everything else running. the first attempt made it go blank and then immediately come back, like it just dimmed and woke itself. the diagnosis was that two things were fighting. the compositor had a bind for the key, and the acpi daemon had its own handler for the same button, so both fired about half a second apart. the first blank ran, the key press woke the panel, then the second blank cut it to black. that is the exact flicker i was seeing.
dropping the compositor bind fixed that round, but then the separate acpi rule never actually ran. the box ships with a catch-all handler that swallows every acpi event, so my custom rule was loaded but never matched. the helper was not being called at all. the real fix was to put the power handling inside that catch-all script and delete the extra rule, so there is exactly one path and one call.
the second half of the mystery was the wake itself. the compositor was set to wake the panel on any key press, and the button press, or its release, counts as a key event. so the button was waking the exact screen it had just dimmed. i turned key wake off and left mouse wake on. now a single press blanks it smoothly after about a second and it holds. the tradeoff is that after it goes dark, a key press no longer wakes it, you move the mouse instead. i actually miss keyboard wake, so the plan is to bring it back with a short delay so the button event finishes before the panel goes down.