Mirror the Mac battery into the guest as a real power_supply device

[NimbleAINinja]

What this does

Mirrors the Mac's battery into the Omarchy guest as a real power_supply
device, so the Quattro bar and every other UPower consumer show it with no
configuration. The guest behaves like the laptop it is running on.

Omarchy Quattro's bar is Quickshell, which reads UPower, which reads
/sys/class/power_supply. The VM exposes no power supply, so the widget is
simply absent today.

How

A fifth virtio-serial port carries newline-delimited JSON, host to guest only.
The guest may send exactly one request line ({"type":"refresh"}) on start,
because a guest opening the port is not observable on the host's socket
chardev; nothing else it sends can influence Mac power state.

IOKit power sources -> NativeBatteryBridge (Swift, in the helper)
                          |  dev.tryomarchy.battery (virtserialport, nr=5)
                          v
                       omarchy-native-battery-bridge (root system service)
                          |  one whole-snapshot line per write()
                          v
                       try_omarchy_battery.ko (DKMS)
                          v
                       /sys/class/power_supply/{BAT0,ADP0}  ->  UPower -> bar

Each snapshot is complete rather than a delta, so a restarted agent is never
half-informed, and one write() is one consistent state: consumers cannot
observe a new percentage beside a stale charging flag.

Design decisions worth reviewing

• A purpose-built DKMS module, not upstream's test_power. The pinned
  linux-aarch64 ships no test_power.ko, and test_power names its devices
  test_battery/test_ac, carries a USB supply and wakeup timer we do not
  want, and its per-parameter writes allow torn state on every update. DKMS is
  already proven in this image by v4l2loopback.
• BAT0 / ADP0, the conventional names, so tools that special-case them
  (acpi, fastfetch, status scripts) work. Honesty lives in the properties
  instead: manufacturer Apple, model Mac Battery.
• Warn only. The UPower drop-in sets CriticalPowerAction=Ignore and
  AllowRiskyCriticalPowerAction=true. Both are required: upower 1.91.4
  classifies Ignore as risky and silently falls back to
  HybridSleep -> Hibernate -> PowerOff without the second key, which would
  suspend the VM on a low Mac battery. The Mac's own power management stays the
  only authority. Please do not "simplify" that file.
• Always on, no start-menu surface. It needs no macOS permission and
  exposes nothing sensitive. On a Mac with no internal battery the guest gets
  only mains, so the bar shows nothing — correct for a desktop.
• Root-only port (MODE="0600", no GROUP), following the authentication
  rule's posture rather than the clipboard's, since no user process needs it.

Existing guests

App updates retain persistent guest disks, so an existing VM does not receive
the module from an app update — though it does receive the port immediately,
since QEMU's command line comes from the host. No factory reset is needed:
the factory image already carries dkms, gcc, make, kmod and matching
headers, so guest/scripts/install-battery-into-existing-guest.sh builds the
module in place from files staged through the shared Mac folder. No network
fetch. Because it goes through DKMS, the pacman hook rebuilds it on a guest
kernel upgrade.

Verification

make test and guest/test pass. Beyond that, exercised on real hardware on
two machines, both with guest kernel 7.2.2-2:

• Retrofit installed via the documented procedure; module built by DKMS;
  BAT0/ADP0 present; agent service active.
• Live tracking confirmed: unplug propagated to sysfs and UPower's
  DisplayDevice within 5 seconds, replug likewise.
• On a genuinely discharging battery (22%), icon-name became
  battery-low-symbolic and warning-level was correctly none (UPower's
  threshold is 10%).
• Clean teardown: on ACPI powerdown the bridge exited 0, the supervisor made
  its one restart attempt, and the restart correctly refused to attach to a
  non-QEMU pid — identical behaviour to the camera and authentication bridges.
• The module was also compiled against the pinned linux-aarch64-headers 7.2.6-1 in an ARM64 container, and the register script was run end to end
  against a staged root.

Tests added: guest agent unit tests, a host-testable harness driving the real
tob_parse source (the cross-language seam, where two token tables must
agree), Swift tests for snapshot mapping and the exact wire contract, a
nr=5 assertion in the launcher contract test, and verify.py checks for the
unit, the root-only rule, both UPower keys, and the DKMS build line.

Known limitation: no time remaining in the bar

The time estimates reach sysfs correctly and live — measured at
time_to_empty=3180, then 3600 at 22% — but upower 1.91.4 does not read
time_to_empty_avg, and a capacity-only device gives it no energy or power
values to derive from, so it reports 0 Wh / 0 W and prints no time field.
The bar therefore shows level, charge state and AC presence only; anything
reading sysfs directly does see the estimates. The docs state this plainly.

The fix I would recommend is publishing real energy figures read from IOKit's
AppleSmartBattery (mAh x mV = uWh, mA x mV = uW), so UPower derives a
true time from true inputs, rather than synthesizing a fake capacity scale.
That is deliberately not in this PR.

Note for anyone building this

make guest currently fails on main for reasons unrelated to this branch:
Arch Linux ARM has moved hyprland to 0.56.2-3, which needs
libaquamarine.so=14-64, while the ABI-pinned aquamarine 0.14.0-2 provides
so=13-64. A coordinated hyprland/aquamarine pin bump is a prerequisite for
building an image containing this feature, and the feature itself is
unaffected — the failure occurs before its registration step runs.

🤖 Generated with Claude Code