feat(power): real metered-network detection on macOS and Linux (#95)

## What

Metered-network detection was real on Windows only
(`INetworkCostManager::GetCost`); macOS and Linux returned a
conservative unmetered stub, so `skip_on_metered` was inert on those
platforms (issue #32). This wires both.

- **Linux** - reads NetworkManager's aggregate `Metered` property
(`org.freedesktop.NetworkManager`) over the system bus via zbus's
blocking API, dispatched through `tokio::task::spawn_blocking` (zbus's
blocking API must not be driven from inside an async runtime) and
bounded by a 5 s timeout so a wedged bus can never stall the AC/battery
poll. `NMMetered` YES/GUESS_YES -> metered, NO/GUESS_NO -> not metered,
UNKNOWN or a failed read (no NetworkManager / no system bus) ->
`Unknown` -> not metered.
- **macOS** - there is no literal "metered" bit. A long-lived
`NWPathMonitor` (Network.framework C API; its update handler is an
Objective-C block via `block2`, delivered on a libdispatch global queue)
caches `nw_path_is_expensive` (cellular / personal hotspot) `||
nw_path_is_constrained` (Low Data Mode) - the documented metered proxies
- into an `AtomicU8` that the 30 s power poll reads cheaply.

## Design

The per-OS raw read is separated from the decision logic. Three pure
`classify_*` functions (`classify_windows_cost`, `classify_nm_metered`,
`classify_nw_path`) plus `MeteredStatus`/`on_metered` turn each OS's raw
value into the `on_metered_network` bool. They are `#[cfg(any(test,
target_os = ...))]`, so **all three are compiled and unit-tested on
every OS** - the classification is CI-covered on Windows, macOS, and
Linux alike; only the thin OS-call adapters (COM / D-Bus /
`NWPathMonitor`) are compile-checked-only off their native OS.

Every read collapses ambiguity to `MeteredStatus::Unknown`, which maps
to `false` (not metered) - the safe direction, since a wrong "not
metered" only fails to skip a rare metered link whereas a wrong
"metered" would stall ALL sync.

No stored-format or public-API changes: `PowerState` shape and the
`PowerSource` trait are unchanged; this is purely additive.

## Tested vs compile-only

Development was on Windows, so the non-Windows adapters are
compile-verified via the 3-OS CI matrix, not locally:

- **Unit-tested on all three CI OSes** (run on Windows locally too): the
three `classify_*` functions, `MeteredStatus::on_metered`, `from_u8`,
`reachable_hint` - the full decision logic.
- **Runtime-tested on the Windows CI runner** (and locally):
`detect_metered()` real COM read is total
(`windows_detect_metered_is_total`); the existing `RealPowerSource`
construction tests exercise the read path.
- **Runtime-tested on the macOS CI runner**:
`macos_monitor_start_and_read_is_total` starts the real `NWPathMonitor`
and reads its cache - the only runtime exercise of the Network.framework
/ `block2` / libdispatch FFI (a wrong signature or bad link fails here).
- **Compile-only (CI matrix)**: the macOS FFI adapter body and the Linux
zbus D-Bus adapter body. There is no metered hardware in CI, and
NetworkManager may be absent on the Linux runner, so the Linux read's
happy path is not asserted in CI - the D-Bus/classification split keeps
the classification (the part with real logic) fully covered, and the
adapter is a thin, safe-defaulting wrapper.

APIs were taken from documented sources (zbus proxy/blocking docs; Apple
Network.framework; objc2/block2 encoding), not guessed.

## Nothing deferred

macOS `isExpensive`/`isConstrained` is the documented, feasible proxy
(macOS exposes no literal metered bit), so #32 is fully addressed rather
than scope-reduced.

Closes #32.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: pmaxhogan

Cargo.lock

@@ -16,9 +16,9 @@ tokio.workspace = true
 async-trait.workspace = true
 
 # Per-OS power / metered-network / sleep-wake backends (DESIGN s5.7,
-# s5.10.1). Declared now so the M3 implement phase has them; features are
-# kept minimal here (the impl widens them to the specific Win32 / DBus
-# modules it calls) to keep `cargo build --workspace` light.
+# s5.10.1). Features are kept minimal (the impl widens them only to the
+# specific Win32 / DBus / Network.framework modules it calls) to keep
+# `cargo build --workspace` light.
 [target.'cfg(windows)'.dependencies]
 # GetSystemPowerStatus (Win32_System_Power) for AC/battery (DESIGN s5.7).
 # Win32_Foundation pulls the shared BOOL/handle types its signature uses.
@@ -35,15 +35,21 @@ windows = { version = "0.62", features = [
 ] }
 
 [target.'cfg(target_os = "linux")'.dependencies]
-# Battery/AC is read from /sys/class/power_supply with std only. The
-# systemd-logind PrepareForSleep DBus signal + NetworkManager Metered /
-# Connectivity are TODO seams (linux.rs / network.rs); zbus is declared now
-# for when those DBus hooks land (DESIGN s5.7, s5.10.1).
+# Battery/AC is read from /sys/class/power_supply with std only. zbus backs the
+# real metered-network read in network.rs: the aggregate `Metered` property on
+# org.freedesktop.NetworkManager over the system bus, via the default
+# (async-io) blocking API dispatched through tokio's spawn_blocking (DESIGN
+# s5.7). The systemd-logind PrepareForSleep sleep/wake signal remains a TODO
+# seam (linux.rs, s5.10.1).
 zbus = "5"
 
 [target.'cfg(target_os = "macos")'.dependencies]
 # IOKit IOPowerSources for AC/battery, read via CoreFoundation types
-# (DESIGN s5.7). NSWorkspace sleep/wake bridging via objc2 is a TODO seam
-# in macos.rs; objc2 is declared now for when that hook lands (s5.10.1).
+# (DESIGN s5.7). block2 backs the real metered-network read in network.rs: an
+# NWPathMonitor whose update handler (an Objective-C block) caches
+# nw_path_is_expensive / nw_path_is_constrained (DESIGN s5.7's NWPath.isExpensive
+# proxy). NSWorkspace sleep/wake bridging via objc2 is a TODO seam in macos.rs;
+# objc2 is declared now for when that hook lands (s5.10.1).
 core-foundation = "0.10"
 objc2 = "0.6"
+block2 = "0.6"

crates/driven-power/Cargo.toml

@@ -23,7 +23,7 @@ use async_trait::async_trait;
 use tokio::sync::broadcast;
 use tokio::sync::Mutex;
 
-use crate::network::detect_metered_and_reachable;
+use crate::network::{detect_metered_blocking, reachable_hint, MeteredStatus};
 use crate::{PowerSource, PowerState};
 
 /// Poll cadence for the sysfs power read (DESIGN s5.7).
@@ -32,6 +32,13 @@ const POLL_INTERVAL: Duration = Duration::from_secs(30);
 /// Broadcast channel capacity (transitions are rare).
 const BROADCAST_CAPACITY: usize = 16;
 
+/// Upper bound on the per-poll NetworkManager D-Bus read. It runs on a blocking
+/// thread (via [`tokio::task::spawn_blocking`]) so it never parks a tokio
+/// worker, but this cap guarantees a wedged system bus can never stall the
+/// AC/battery poll for more than this: on timeout the metered value falls back
+/// to [`MeteredStatus::Unknown`] (not metered) and the poll proceeds.
+const METERED_READ_TIMEOUT: Duration = Duration::from_secs(5);
+
 /// sysfs root for power-supply devices. A constant so tests can reason
 /// about the layout; the reader takes the root as a parameter.
 const POWER_SUPPLY_ROOT: &str = "/sys/class/power_supply";
@@ -47,8 +54,13 @@ impl RealPowerSource {
     /// Builds the source with an initial snapshot read synchronously from
     /// sysfs. Never fails: a host with no power-supply devices (server /
     /// container) resolves to "on AC, no battery".
+    ///
+    /// The initial snapshot reports metered as [`MeteredStatus::Unknown`] (not
+    /// metered): the NetworkManager read is a blocking D-Bus call that cannot be
+    /// awaited here, so the first real metered verdict lands on the first poll
+    /// tick. The safe default in the meantime never wrongly stalls sync.
     pub fn new() -> anyhow::Result<Self> {
-        let initial = read_power_state();
+        let initial = read_power_state(MeteredStatus::Unknown);
         let (tx, _rx) = broadcast::channel(BROADCAST_CAPACITY);
         Ok(Self {
             latest: Arc::new(Mutex::new(initial)),
@@ -69,7 +81,8 @@ impl RealPowerSource {
             ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
             loop {
                 ticker.tick().await;
-                let next = read_power_state();
+                let metered = read_metered().await;
+                let next = read_power_state(metered);
                 let mut guard = latest.lock().await;
                 if *guard != next {
                     tracing::debug!(?next, "power state transition");
@@ -81,6 +94,27 @@ impl RealPowerSource {
     }
 }
 
+/// Reads NetworkManager's metered state off the async executor, bounded by
+/// [`METERED_READ_TIMEOUT`]. The blocking D-Bus read runs on a
+/// [`tokio::task::spawn_blocking`] thread (zbus's blocking API must not be
+/// driven from within an async runtime); a join error or timeout resolves to
+/// [`MeteredStatus::Unknown`] (not metered) so the AC/battery poll is never
+/// blocked by a wedged bus.
+async fn read_metered() -> MeteredStatus {
+    let read = tokio::task::spawn_blocking(detect_metered_blocking);
+    match tokio::time::timeout(METERED_READ_TIMEOUT, read).await {
+        Ok(Ok(status)) => status,
+        Ok(Err(join_err)) => {
+            tracing::warn!(error = %join_err, "metered read task failed; treating as unknown");
+            MeteredStatus::Unknown
+        }
+        Err(_elapsed) => {
+            tracing::warn!("metered read timed out; treating as unknown");
+            MeteredStatus::Unknown
+        }
+    }
+}
+
 #[async_trait]
 impl PowerSource for RealPowerSource {
     async fn current(&self) -> PowerState {
@@ -92,15 +126,17 @@ impl PowerSource for RealPowerSource {
     }
 }
 
-/// Reads a full [`PowerState`] snapshot.
-fn read_power_state() -> PowerState {
+/// Reads a full [`PowerState`] snapshot. AC / battery come from sysfs; the
+/// `metered` verdict is supplied by the caller (read separately off the async
+/// executor via [`read_metered`], or [`MeteredStatus::Unknown`] for the initial
+/// synchronous snapshot).
+fn read_power_state(metered: MeteredStatus) -> PowerState {
     let (ac_connected, battery_percent) = read_ac_and_battery(Path::new(POWER_SUPPLY_ROOT));
-    let (on_metered_network, network_reachable) = detect_metered_and_reachable();
     PowerState {
         ac_connected,
         battery_percent,
-        on_metered_network,
-        network_reachable,
+        on_metered_network: metered.on_metered(),
+        network_reachable: reachable_hint(),
     }
 }
 

crates/driven-power/src/linux.rs

@@ -28,7 +28,7 @@ use async_trait::async_trait;
 use tokio::sync::broadcast;
 use tokio::sync::Mutex;
 
-use crate::network::detect_metered_and_reachable;
+use crate::network::{reachable_hint, MacosMeteredMonitor, MeteredStatus};
 use crate::{PowerSource, PowerState};
 
 /// Poll cadence for the OS power query (DESIGN s5.7).
@@ -56,18 +56,29 @@ type CFTypeRefRaw = *const c_void;
 pub struct RealPowerSource {
     latest: Arc<Mutex<PowerState>>,
     tx: broadcast::Sender<PowerState>,
+    /// Live `NWPathMonitor` caching the active path's metered proxy
+    /// (`isExpensive` / `isConstrained`). Cloneable (shares an `Arc<AtomicU8>`)
+    /// so the poll loop reads the latest verdict cheaply each tick.
+    metered: MacosMeteredMonitor,
 }
 
 impl RealPowerSource {
     /// Builds the source with an initial snapshot read synchronously from
     /// IOKit. Never fails: a host with no battery / unreadable IOPS info
     /// resolves to "on AC, no battery".
+    ///
+    /// Starts the `NWPathMonitor` here; its first path arrives asynchronously,
+    /// so the initial snapshot may read metered as [`MeteredStatus::Unknown`]
+    /// (not metered) until the first update lands - a safe default that never
+    /// wrongly stalls sync.
     pub fn new() -> anyhow::Result<Self> {
-        let initial = read_power_state();
+        let metered = MacosMeteredMonitor::start();
+        let initial = read_power_state(metered.status());
         let (tx, _rx) = broadcast::channel(BROADCAST_CAPACITY);
         Ok(Self {
             latest: Arc::new(Mutex::new(initial)),
             tx,
+            metered,
         })
     }
 
@@ -79,12 +90,13 @@ impl RealPowerSource {
     pub fn spawn_poller(&self) -> tokio::task::JoinHandle<()> {
         let latest = Arc::clone(&self.latest);
         let tx = self.tx.clone();
+        let metered = self.metered.clone();
         tokio::spawn(async move {
             let mut ticker = tokio::time::interval(POLL_INTERVAL);
             ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
             loop {
                 ticker.tick().await;
-                let next = read_power_state();
+                let next = read_power_state(metered.status());
                 let mut guard = latest.lock().await;
                 if *guard != next {
                     tracing::debug!(?next, "power state transition");
@@ -107,15 +119,15 @@ impl PowerSource for RealPowerSource {
     }
 }
 
-/// Reads a full [`PowerState`] snapshot.
-fn read_power_state() -> PowerState {
+/// Reads a full [`PowerState`] snapshot. AC / battery come from IOKit; the
+/// `metered` verdict is the caller-supplied cached `NWPathMonitor` reading.
+fn read_power_state(metered: MeteredStatus) -> PowerState {
     let (ac_connected, battery_percent) = read_ac_and_battery();
-    let (on_metered_network, network_reachable) = detect_metered_and_reachable();
     PowerState {
         ac_connected,
         battery_percent,
-        on_metered_network,
-        network_reachable,
+        on_metered_network: metered.on_metered(),
+        network_reachable: reachable_hint(),
     }
 }