Panama/docs/superpowers/specs/2026-08-24-power-lock-redesign.md

Power & Lock redesign — one timeline, honest sleep

Approved mock: home-mocks/power.html (scratchpad, :8642). Spec wins over mock on conflict. Single tabless page stays.

Goals

1. Idle timeline: one visualization (Active → Screen off → Lock → Suspend) above the sliders, switching wall-power/battery by live source; the ordering warnings become part of the picture. A "Keeping the machine awake right now" row lists live inhibitors.
2. Power profile tiles (existing service; presentation only, "via tuned" honesty).
3. Battery health: design-capacity %, charge cycles, and a charge-stop readback tile — dormant here, real on the laptop.
4. Power button adjustable without root: logind keeps HandlePowerKey=ignore; the compositor bind reads a new preference. Options: Shows the power menu (default) / Suspends / Powers off (two-press: opens the power menu with Power Off pre-selected, so the second press fires it) / Does nothing.
5. Honesty rows: lid card presents its inhibitor design; hibernate row states the zram reason, gated on the live CanHibernate probe; Management shows the generated path.
6. The panama-lid clobber dies: cmd_open emits the full stored record (position from stored x/y when present, scale, transform, vrr, bitdepth, cm, sdr fields — conditional, mirroring monitors.lua's validation) instead of the 4-key rule that wipes extended fields.

Non-goals: lid behavior override (deliberately read-only, per LidPolicy's argued design), scheduled shutdown, suspend-then-hibernate, time-to-empty (deliberate omission stays), per-app power, conditional suspend rules (hypridle has no conditional listener — the inhibitor row is the honest substitute).

Schema (A)

New group power (groupPages → power): powerButtonAction — enum, def "menu", values menu | suspend | poweroff | nothing, label "Pressing the power button", detail per mock. No hypr block (consumed by keybinds.lua via prefs, like workspace rules — reload-applied is fine for a power-button preference; if the keybind can read it live via a dispatcher branch, better — A investigates which pattern keybinds.lua supports and documents the choice).

Settled (A): per-press, no reload. The bind is hl.dsp.exec_cmd of a one-line shell case over jq -r '.powerButtonAction // empty' against the settings file, so the branch is evaluated when the key goes down rather than when the config is read. All four values branch inside keybinds.lua; a missing jq, missing file, malformed file or unknown value falls through to *) and opens the menu. prefs.get was rejected because prefs.lua loads the store once at config time, which would have made this the one Power-page control that needs hyprctl reload.

Plumbing (A)

• config/dot/hypr/keybinds.lua: the XF86PowerOff bind branches on the preference: menu → existing power-menu IPC; suspend → systemctl suspend; poweroff → power-menu IPC with a poweroff preselect argument; nothing → no-op bind (still locked = true).
• shell.qml + modules/powermenu/PowerMenu.qml: the powermenu IPC accepts an optional entry id to pre-select (arming Power Off so one more press fires — the existing two-press semantics preserved); no other menu behavior changes.
  • Settled (A). Each entry gains a stable entryId: lock | logout | suspend | hibernate | restart | poweroff. qs ipc call powermenu open <entryId> calls PowerMenu.preselect(entryId), which opens the menu and calls the entry's own trigger() — the same one a click calls — so a destructive entry arms on the first press and fires on the second, inside the existing 4-second confirm window. Nothing bypasses the confirm; an id this machine has no entry for (hibernate without swap) just opens the menu. toggle is unchanged.
• scripts/panama-idle: new inhibitors verb → [{ who, why, what, mode }] (sleep/idle/handle-lid-switch holds only, Panama's own lid inhibitor included honestly); services/IdleLock.qml exposes inhibitors + inhibitorsKnown + refreshInhibitors(), which B calls on page open.
  • Settled (A), two additions to the pinned shape. Source is logind's ListInhibitors over busctl --json=short, not systemd-inhibit --list: that table is padded display output whose why column contains spaces and whose who column is a free string the inhibiting program picks, so no column split is reliable. And each row carries mode, because delay and block are not the same claim — NetworkManager, UPower and hypridle hold permanent delay holds on every machine, and a list that did not distinguish them would report the desktop as pinned awake at all times. Only block keeps a machine awake; B should read the empty state off the blocks, not the row count. Rows sort blocks first, then by who. On failure the verb prints NOTHING and exits non-zero (never []), which is what inhibitorsKnown is derived from.
• scripts/panama-battery: status gains healthPercent (energy_full/energy_full_design or charge_ equivalents, summed across packs), cycleCount — both JSON null when sysfs lacks them, and a reported cycle_count of 0 counts as absent rather than as a new battery; services/Battery.qml exposes healthPercent/cycleCount as property var defaulting to null (an int property would coerce null back to 0), filled by a new refreshHealth() that runs once when the sysfs paths resolve and again whenever the page asks — never on the 20-second poll.
• scripts/panama-lid: cmd_open reads the stored record's full field set via jq and emits hl.monitor({...}) with every valid field, conditional per key, position from stored x/y when both present else "auto" — validation mirroring monitors.lua (regex-safe values only; invalid extended fields drop per-field, geometry survives). Header's "NOT YET VERIFIED ON A LAPTOP" honesty stays.

UI (B)

PowerPage.qml rebuilt per mock: Power profile tiles (icon, label, one-line detail, active highlight, degraded note); Idle card (NEW IdleTimeline.qml: proportional stops on a piecewise scale with labels, driven by the same schema values — draggable with snap-to-step if robust, read-only visualization otherwise [flag which]; the source header "on wall power" / "on battery" from Battery.acOnline; the battery-variant sliders swap in below when on battery — one card, not two; ordering warnings rendered inline on the timeline rather than a separate card); Lock before sleeping toggle; inhibitors row ("Nothing — no application holds a wake lock" empty state); Battery card (health tiles + charge-stop readback + existing low/critical/action rows; charge-limit slider keeps firmware-confirm detail); Lid card (read-only, DOCKED/WILL SUSPEND badge from LidPolicy, the inhibitor-design prose); Power button card (OptionPickerRow on powerButtonAction, the mock's detail); Session card (Lock now — through a service or execDetached as today, hibernate row gated !canHibernate showing the zram reason [read the live probe from PowerMenu's existing CanHibernate source — lift it into a small service property if needed], power menu pointer row); Management card (managed toggle + IdleLock.generatedPath + service state in the detail).

Search & docs (C)

Extra entries: Hibernate, Power profile, Power button, Lid, Suspend, Sleep → power. Schema regen: docs + commands after the new key (orchestrator can also run it; C verifies the group comment shape).

Contracts (C — write; hermetic runs only)

• NEW power-page-contract: page structure (profile tiles, IdleTimeline present and fed by the schema keys, one idle card not two, inhibitors row with empty state, hibernate row gated on the live probe with the zram copy, power button row bound to powerButtonAction, generatedPath rendered); powerButtonAction consumed in keybinds.lua (all four values branch); the poweroff branch goes through the power menu (никогда a direct poweroff — pin that systemctl poweroff appears nowhere in the bind path).
• lid-contract / a new static half: fixture settings.json with extended display fields → the generated hl.monitor line carries them; invalid values drop per-field; stored x/y become position; absent → auto. The old 4-key emission must FAIL it.
• battery-contract: health fields present when sysfs provides them, absent-tolerant when not (desktop fixture), never fabricated.
• idle-config-contract/idle-defaults-contract: verify unaffected (inhibitors verb is additive).
• Backlog Phase 13; README count (173 → 174 expected).

Agent ownership (parallel)

• A: config/PreferenceSchema.qml, config/dot/hypr/keybinds.lua, shell.qml, modules/powermenu/PowerMenu.qml, scripts/panama-idle, scripts/panama-battery, scripts/panama-lid, services/IdleLock.qml, services/Battery.qml.
• B: modules/settings/PowerPage.qml, NEW IdleTimeline.qml, other components (+ qmldir).
• C: services/SettingsSearch.qml, contracts above, backlog, README count line.

Hard rules: NO live mutations — no systemctl suspend/poweroff, no logind writes, no threshold writes, no hyprctl keyword/eval, no powermenu triggering; keybinds.lua edits must keep hyprctl reload UNRUN (the user reloads naturally later — but the shell hot-reloads QML, so PowerMenu/shell.qml edits land live and must stay valid). Read-only probes and stubs only. B programs against the pinned APIs; A updates this spec before changing them.