lock-dpms: waking is the machine's, and the compositor must not do it itself

The panel had no way back: apply_gesture answers a tap on a dark panel
with Restore, which is brightness, and there was no unblank in the action
table. Invisible while hyprland bound the keys straight to the toggle;
under viewtop it became a phone that could sleep and never wake.

Records the wake loop too, because building it wrong is the obvious move:
viewtop waking directly worked, then sessiond resolved the same press,
found the panel lit, and blanked it again. One press woke the phone and
put it back to sleep. Plus why dt2w is a wake and not a button, and the
deploy order that has to hold between the two halves.

docs/LOCK-DPMS-LESSONS.md

@@ -111,6 +111,47 @@ entirely, so it proved DPMS worked and proved *nothing* about the ordering. A
 blank must be triggered the way the machine triggers one — a power tap or a real
 idle — and the trail read afterwards, or the invariant is untested.
 
+### Waking is the machine's too, and finding that out cost a wake loop
+
+**The panel had no way back.** `apply_gesture` answers a power tap on a dark
+panel with `Restore` — which is *brightness* — and there was no unblank in the
+action table at all. That was invisible for as long as the wake never came
+through the daemon: `hyprland.lua` bound `XF86PowerOff` and `XF86WakeUp`
+straight to `blueline-power-button` / `blueline-screen-toggle on`, so the
+compositor woke the panel and sessiond only heard about it afterwards. viewtop
+consumes those keys on purpose — the control that locks the phone must not be
+interceptable by whatever is fullscreen — and the gap became **a phone that
+could sleep and never wake**. Measured 2026-08-02: `panel_on: false`, presses
+arriving and logged, no way back short of ssh.
+
+`Action::Unblank` closes it, a power tap now returns `[Unblank, Restore]` in
+that order (the brightness a panel comes back at means nothing until the panel
+is back), and there is a `screen` verb so waking is something the **agent** can
+reach rather than a keybinding in a compositor config she has no say over. It is
+not a bypass: `on` is immediate, `off` routes through `request_blank()` like
+every other path.
+
+**The wake must not be performed by the compositor, and this is the part that is
+counter-intuitive enough to have been built wrong first.** Waking directly from
+viewtop's input path *worked* — the log says "power button on a dark panel:
+waking" and the screen came back. Three seconds later sessiond resolved the same
+press into a `Tap`, looked at the panel, found it lit (because viewtop had just
+lit it), and did what a tap on a lit panel means: locked the session and blanked
+it again. **One press woke the phone and put it back to sleep.** That is §1's
+seven blind actors with the serial numbers filed off, reintroduced by the fix for
+a different bug. The compositor reports the edge; the authority decides; the
+executor acts.
+
+**dt2w is a wake and not a button**, and the distinction is load-bearing: a
+double tap is the one wake *a pocket can produce by itself*, so it carries the
+proximity veto (`suppress_wake`) that a power button never gets — §4's table,
+"can it lie? no — hardware signal" for the button and yes for the tap. Reporting
+both through one verb would hand a pocket the authority of a deliberate press.
+
+**Deploy order is not optional.** sessiond's `Unblank` must be on the device
+*before* a viewtop that no longer wakes the panel itself, or the window between
+them is a phone that cannot wake at all.
+
 ## 2. One DPMS authority
 
 `blueline-screen-toggle` serializes every panel power transition. Nothing