feat(battery): close the gap with battery-cli — manual toggles, force-discharge, time remaining, daemon logs

Feature parity pass against actuallymentor/battery v1.3.2, all verified
live on M2 MacBook Air:

- `battery charging on|off` and `battery adapter on|off`: expose the
  existing setChargingEnabled/setAdapterEnabled XPC calls in the CLI.
  When a maintain policy is active the CLI warns that the toggle may be
  overridden on the next evaluation (verified: it is, within seconds).
- `battery maintain N --force-discharge`: the policy actively discharges
  down to the band by cutting adapter power while above the upper bound,
  and restores it once inside. Persisted as battery.force_discharge in
  config.toml. The evaluation loop re-asserts the cut every period,
  which makes it self-healing against the firmware quirk below.
  Switching back to a plain maintain hands the adapter back (daemon-side
  transition, verified both directions).
- `battery status` shows time-to-empty/full from IOKit power sources
  (nil while the gauge is settling — mirrors pmset's "(no estimate)").
- `daemon logs [--last 1h]`: wraps `log show` with the smctl subsystem
  predicate.

Field finding that shaped the design: writing the charging-enable key
(CHTE) while an adapter cut (CHIE) is active made the SMC silently
re-enable adapter power — observed live, it stalled a one-shot
`battery discharge` forever at 79%. The one-shot discharge loop now
re-asserts the cut every poll, and force-discharge inherits immunity
from the policy loop (verified: triggering the same reset under
force-discharge is corrected within one XPC call).

PolicyEngine: BatteryObservation gains isAdapterEnabled (nil when
adapter control is unsupported — the policy then never touches the
adapter, which also keeps it out of the way of manual discharges).
New transition-matrix tests for the force-discharge branches.

Author: harryisfish

README.md

@@ -31,15 +31,16 @@ $ smctl sensors --watch            # live temperatures, fan RPM, package power
 | Command | What it does |
 |---|---|
 | `smctl sensors [--watch] [--json]` | Temperatures by sensor group, fan RPM/mode, battery, package power |
-| `smctl battery status` | Charge level, charging state, configured limit |
-| `smctl battery maintain 80` / `70-80` / `stop` | Charge limit with dead-band (no charge/discharge flapping) |
+| `smctl battery status` | Charge level, charging state, configured limit, time estimate |
+| `smctl battery maintain 80` / `70-80` / `stop` | Charge limit with dead-band; add `--force-discharge` to drain down to the band |
+| `smctl battery charging on\|off` / `adapter on\|off` | Manual charging and adapter-power toggles |
 | `smctl battery charge 90` / `discharge 40` | One-shot top-up or supervised discharge |
 | `smctl fan status` | Per-fan actual/target/min/max RPM and control mode |
 | `smctl fan set 2500 [--fan N]` | Manual fan target |
 | `smctl fan profile quiet\|full\|auto\|<custom>` | Declarative fan curves (TOML), hysteresis + slew-rate limited |
 | `smctl power status [--watch] [--json]` | Thermal pressure, CPU throttling (% speed limit), system/package + input power |
 | `smctl alert list\|status\|test <name>` | Temperature/event alerts → webhook, command, or log (configured in TOML) |
-| `smctl daemon install\|uninstall\|status\|ping` | Manage the privileged helper |
+| `smctl daemon install\|uninstall\|status\|ping\|logs` | Manage the privileged helper and inspect recent daemon logs |
 
 Policies live in `/etc/smctl/config.toml` — declarative, diffable, dotfiles-friendly.
 

Sources/PolicyEngine/PolicyEngine.swift

@@ -100,11 +100,15 @@ public struct BatteryObservation: Codable, Equatable, Sendable {
     public var isChargingAllowed: Bool
     /// Whether wall power is present (AC-W).
     public var isPluggedIn: Bool
+    /// Whether the SMC currently allows adapter power input (CHIE / CH0I status).
+    /// nil when adapter control is unsupported or unreadable.
+    public var isAdapterEnabled: Bool?
 
-    public init(chargePercent: Int, isChargingAllowed: Bool, isPluggedIn: Bool = true) {
+    public init(chargePercent: Int, isChargingAllowed: Bool, isPluggedIn: Bool = true, isAdapterEnabled: Bool? = nil) {
         self.chargePercent = min(100, max(0, chargePercent))
         self.isChargingAllowed = isChargingAllowed
         self.isPluggedIn = isPluggedIn
+        self.isAdapterEnabled = isAdapterEnabled
     }
 
     /// Best available approximation of "actively charging": power present and charging allowed.
@@ -146,7 +150,8 @@ public struct ChargeStateMachine: Sendable {
     public mutating func evaluate(
         limit: ChargeLimit,
         observation: BatteryObservation,
-        now: Date
+        now: Date,
+        forceDischarge: Bool = false
     ) -> ChargeEvaluation {
         let slept = lastEvaluation.map { now.timeIntervalSince($0) > period * missedBeatMultiplier } ?? false
         lastEvaluation = now
@@ -182,6 +187,20 @@ public struct ChargeStateMachine: Sendable {
             actions.append(.setChargingEnabled(false))
         }
 
+        // Force-discharge: when enabled, the policy owns the adapter switch — cut
+        // adapter power while above the band so the battery drains down to it, and
+        // restore once inside. Acts only when the adapter state is readable, and
+        // never below the upper bound, so it cannot fight the charge dead-band.
+        // When disabled the policy never touches the adapter: a manual one-shot
+        // `discharge` owns it then.
+        if forceDischarge {
+            if effectiveObservation.chargePercent > limit.upperBound, effectiveObservation.isAdapterEnabled == true {
+                actions.append(.setAdapterEnabled(false))
+            } else if effectiveObservation.chargePercent <= limit.upperBound, effectiveObservation.isAdapterEnabled == false {
+                actions.append(.setAdapterEnabled(true))
+            }
+        }
+
         return ChargeEvaluation(
             actions: actions,
             sleptSinceLastEvaluation: slept,
@@ -193,9 +212,10 @@ public struct ChargeStateMachine: Sendable {
     public mutating func evaluate<C: PolicyClock>(
         limit: ChargeLimit,
         observation: BatteryObservation,
-        clock: C
+        clock: C,
+        forceDischarge: Bool = false
     ) -> ChargeEvaluation {
-        evaluate(limit: limit, observation: observation, now: clock.now)
+        evaluate(limit: limit, observation: observation, now: clock.now, forceDischarge: forceDischarge)
     }
 }
 

Sources/SMCtlDaemonCore/Daemon.swift

@@ -72,11 +72,15 @@ struct BatteryConfig: Codable, Equatable, Sendable {
     var limit: String
     var sleep_policy: String
     var magsafe_led: Bool
+    /// When true, maintain actively discharges down to the band by cutting
+    /// adapter power while above the upper bound (unreliable in clamshell mode).
+    var force_discharge: Bool
 
-    init(limit: String = "100", sleep_policy: String = "strict", magsafe_led: Bool = true) {
+    init(limit: String = "100", sleep_policy: String = "strict", magsafe_led: Bool = true, force_discharge: Bool = false) {
         self.limit = limit
         self.sleep_policy = sleep_policy
         self.magsafe_led = magsafe_led
+        self.force_discharge = force_discharge
     }
 
     // Defensive decoding: missing keys fall back to defaults. Synthesized decoding
@@ -87,6 +91,7 @@ struct BatteryConfig: Codable, Equatable, Sendable {
         limit = try container.decodeIfPresent(String.self, forKey: .limit) ?? "100"
         sleep_policy = try container.decodeIfPresent(String.self, forKey: .sleep_policy) ?? "strict"
         magsafe_led = try container.decodeIfPresent(Bool.self, forKey: .magsafe_led) ?? true
+        force_discharge = try container.decodeIfPresent(Bool.self, forKey: .force_discharge) ?? false
     }
 }
 
@@ -376,18 +381,30 @@ public final class SmctlDaemon: @unchecked Sendable {
 
     func reloadConfig() {
         queue.sync {
+            let wasForcing = config.battery.force_discharge
             config = Self.loadConfig(path: configPath)
             let policy = (try? SleepPolicy.parse(config.battery.sleep_policy)) ?? .strict
             sleepMachine.setPolicy(policy)
+            if wasForcing, !config.battery.force_discharge, readAdapterEnabledLocked() == false {
+                try? applyAdapterLocked(true)
+            }
             evaluateLocked()
         }
     }
 
-    func setChargeLimit(_ limit: String) throws {
-        _ = try ChargeLimit.parse(limit)
+    func setChargeLimit(_ limit: String, forceDischarge: Bool = false) throws {
+        let parsedLimit = try ChargeLimit.parse(limit)
+        let effectiveForceDischarge = parsedLimit.isLimiting && forceDischarge
         try queue.sync {
+            let wasForcing = config.battery.force_discharge
             config.battery.limit = limit
+            config.battery.force_discharge = effectiveForceDischarge
             try Self.writeConfig(config, path: configPath)
+            // Leaving force-discharge with the adapter cut would strand the Mac
+            // on battery; hand the adapter back before the policy stops owning it.
+            if wasForcing, !effectiveForceDischarge, readAdapterEnabledLocked() == false {
+                try? applyAdapterLocked(true)
+            }
             evaluateLocked()
         }
     }
@@ -521,7 +538,12 @@ public final class SmctlDaemon: @unchecked Sendable {
         }
         let now = Date()
         let limit = currentChargeLimitLocked()
-        let evaluation = chargeMachine.evaluate(limit: limit, observation: observation, now: now)
+        let evaluation = chargeMachine.evaluate(
+            limit: limit,
+            observation: observation,
+            now: now,
+            forceDischarge: config.battery.force_discharge
+        )
         do {
             try applyActionsLocked(evaluation.actions)
             lastEvaluation = now
@@ -547,7 +569,8 @@ public final class SmctlDaemon: @unchecked Sendable {
         return BatteryObservation(
             chargePercent: Int(charge.rounded()),
             isChargingAllowed: chargingAllowed,
-            isPluggedIn: pluggedIn
+            isPluggedIn: pluggedIn,
+            isAdapterEnabled: readAdapterEnabledLocked()
         )
     }
 
@@ -558,6 +581,13 @@ public final class SmctlDaemon: @unchecked Sendable {
         return value.bytes.allSatisfy { $0 == 0 }
     }
 
+    private func readAdapterEnabledLocked() -> Bool? {
+        guard let group = capabilities.adapterControl, let value = try? backend?.readValue(group.statusKey) else {
+            return nil
+        }
+        return value.bytes.allSatisfy { $0 == 0 }
+    }
+
     private func readPluggedInLocked() -> Bool? {
         guard let value = readNumericLocked("AC-W") else {
             return nil
@@ -980,6 +1010,7 @@ public final class SmctlDaemon: @unchecked Sendable {
             statusMessage = nil
         }
 
+        let timeEstimate = PowerSourceTimeEstimate.read()
         return BatteryStatusDTO(
             timestamp: Date(),
             chargePercent: observation?.chargePercent,
@@ -993,7 +1024,10 @@ public final class SmctlDaemon: @unchecked Sendable {
             lowerBound: limit.lowerBound,
             upperBound: limit.upperBound,
             sleepPolicy: sleepMachine.policy.rawValue,
-            message: statusMessage
+            message: statusMessage,
+            timeToEmptyMinutes: timeEstimate.toEmpty,
+            timeToFullMinutes: timeEstimate.toFull,
+            forceDischarge: config.battery.force_discharge
         )
     }
 
@@ -1064,6 +1098,7 @@ public final class SmctlDaemon: @unchecked Sendable {
         limit = "\(config.battery.limit)"
         sleep_policy = "\(config.battery.sleep_policy)"
         magsafe_led = \(config.battery.magsafe_led ? "true" : "false")
+        force_discharge = \(config.battery.force_discharge ? "true" : "false")
 
         [fan]
         profile = "\(config.fan.profile)"
@@ -1214,7 +1249,7 @@ final class XPCService: NSObject, SMCtlDaemonXPCProtocol {
     func setChargeLimit(_ requestData: Data, withReply reply: @escaping (Data?, String?) -> Void) {
         doWrite(reply) {
             let request = try SMCtlProtocolCoding.decode(SetChargeLimitRequestDTO.self, from: requestData)
-            try daemon.setChargeLimit(request.limit)
+            try daemon.setChargeLimit(request.limit, forceDischarge: request.forceDischarge ?? false)
         }
     }
 

Sources/SMCtlDaemonCore/PowerSourceTimeEstimate.swift

@@ -0,0 +1,32 @@
+import Foundation
+import IOKit.ps
+
+/// Time-remaining estimates from IOKit power sources. These come from the OS
+/// gauge (not the SMC), so they live here as presentation data for battery
+/// status rather than in SMCCore.
+enum PowerSourceTimeEstimate {
+    /// Minutes to empty (discharging) and to full (charging) for the internal
+    /// battery. IOKit reports -1 while still calculating; that and missing
+    /// keys both map to nil.
+    static func read() -> (toEmpty: Int?, toFull: Int?) {
+        guard
+            let blob = IOPSCopyPowerSourcesInfo()?.takeRetainedValue(),
+            let list = IOPSCopyPowerSourcesList(blob)?.takeRetainedValue() as? [CFTypeRef]
+        else {
+            return (nil, nil)
+        }
+
+        for source in list {
+            guard
+                let description = IOPSGetPowerSourceDescription(blob, source)?.takeUnretainedValue() as? [String: Any],
+                description[kIOPSTypeKey] as? String == kIOPSInternalBatteryType
+            else {
+                continue
+            }
+            let toEmpty = (description[kIOPSTimeToEmptyKey] as? Int).flatMap { $0 > 0 ? $0 : nil }
+            let toFull = (description[kIOPSTimeToFullChargeKey] as? Int).flatMap { $0 > 0 ? $0 : nil }
+            return (toEmpty, toFull)
+        }
+        return (nil, nil)
+    }
+}

Sources/SMCtlProtocol/SMCtlProtocol.swift

@@ -91,6 +91,12 @@ public struct BatteryStatusDTO: Codable, Equatable, Sendable {
     public var upperBound: Int
     public var sleepPolicy: String
     public var message: String?
+    /// IOKit power-source estimates in minutes; nil when unknown, still
+    /// calculating, or talking to an older daemon (missing keys decode to nil).
+    public var timeToEmptyMinutes: Int?
+    public var timeToFullMinutes: Int?
+    /// Whether maintain actively discharges down to the band (nil from older daemons).
+    public var forceDischarge: Bool?
 
     public init(
         timestamp: Date,
@@ -105,7 +111,10 @@ public struct BatteryStatusDTO: Codable, Equatable, Sendable {
         lowerBound: Int,
         upperBound: Int,
         sleepPolicy: String,
-        message: String?
+        message: String?,
+        timeToEmptyMinutes: Int? = nil,
+        timeToFullMinutes: Int? = nil,
+        forceDischarge: Bool? = nil
     ) {
         self.timestamp = timestamp
         self.chargePercent = chargePercent
@@ -120,6 +129,9 @@ public struct BatteryStatusDTO: Codable, Equatable, Sendable {
         self.upperBound = upperBound
         self.sleepPolicy = sleepPolicy
         self.message = message
+        self.timeToEmptyMinutes = timeToEmptyMinutes
+        self.timeToFullMinutes = timeToFullMinutes
+        self.forceDischarge = forceDischarge
     }
 }
 
@@ -178,9 +190,13 @@ public struct DaemonStatusDTO: Codable, Equatable, Sendable {
 
 public struct SetChargeLimitRequestDTO: Codable, Equatable, Sendable {
     public var limit: String
+    /// Actively discharge down to the band by cutting adapter power while above
+    /// the upper bound. Optional so requests from older CLIs decode to nil (off).
+    public var forceDischarge: Bool?
 
-    public init(limit: String) {
+    public init(limit: String, forceDischarge: Bool? = nil) {
         self.limit = limit
+        self.forceDischarge = forceDischarge
     }
 }