CLI for SidePulse
Python
Polish closed-lid sleep prevention control
Peter Kuhar0d1082ccc0cd
diff --git a/src/sidepulse/audit.py b/src/sidepulse/audit.pyindex 5bab8f1..8e68b8a 100644--- a/src/sidepulse/audit.py+++ b/src/sidepulse/audit.py@@ -7,11 +7,14 @@ from datetime import datetime, timezonefrom pathlib import Pathfrom typing import Any, Iterable+from .battery import BatterySnapshot+from .lid_sleep import MacSleepSnapshotfrom .models import AgentStatus, HookEventfrom .providers import default_state_dirSTATUS_AUDIT_LOG_NAME = "event-status.jsonl"+STATUS_HISTORY_LOG_NAME = "status-history.jsonl"RAW_PREVIEW_LIMIT = 2000MESSAGE_PREVIEW_LIMIT = 240AUDIT_COLUMNS = (@@ -36,6 +39,10 @@ def default_status_audit_log_path(home: Path | None = None) -> Path:return default_state_dir(home) / STATUS_AUDIT_LOG_NAME+def default_status_history_log_path(home: Path | None = None) -> Path:+ return default_state_dir(home) / STATUS_HISTORY_LOG_NAME++def append_status_audit_record(event: HookEvent,status: AgentStatus | None,@@ -58,6 +65,88 @@ def append_status_audit_record(pass+def append_status_history_record(+ record: dict[str, object],+ *,+ path: Path | None = None,+) -> None:+ target = path or default_status_history_log_path()+ target.parent.mkdir(parents=True, exist_ok=True)+ with target.open("a", encoding="utf-8") as handle:+ handle.write(+ json.dumps(+ record,+ ensure_ascii=False,+ separators=(",", ":"),+ default=str,+ )+ + "\n"+ )+++def status_history_record(+ *,+ agent_mode: str,+ display_status: str,+ battery: BatterySnapshot | None,+ mac_sleep: MacSleepSnapshot | None,+ lid_closed: bool | None,+ keep_awake_requested: bool,+ keep_awake_active: bool,+ sleep_prevention_policy: str,+ sleep_prevention_battery_safeguard_active: bool,+ sleep_prevention_min_battery_percent: float | None,+ closed_lid_awake_requested: bool,+ closed_lid_awake_active: bool,+ recorded_at: datetime | None = None,+) -> dict[str, object]:+ at = recorded_at or datetime.now(timezone.utc)+ battery_percent = battery.percent if battery is not None else None+ adapter_power = battery.adapter_power if battery is not None else None+ return {+ "recorded_at": at.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),+ "agent_status": agent_mode,+ "display_status": display_status,+ "battery_level": battery_percent,+ "battery_charging": battery.is_charging if battery is not None else None,+ "battery_charged": battery.is_charged if battery is not None else None,+ "battery_present": battery.battery_present if battery is not None else None,+ "battery_power_watts": round(battery.battery_watts, 2) if battery is not None else None,+ "charger_connected": battery.is_plugged if battery is not None else None,+ "adapter_connected": battery.adapter_connected if battery is not None else None,+ "charger_power_watts": round(adapter_power, 2) if adapter_power is not None else None,+ "adapter_watts": battery.adapter_watts if battery is not None else None,+ "adapter_voltage": round(battery.adapter_voltage, 2) if battery is not None else None,+ "adapter_current": round(battery.adapter_current, 2) if battery is not None else None,+ "adapter_name": battery.adapter_name if battery is not None else "",+ "adapter_manufacturer": battery.adapter_manufacturer if battery is not None else "",+ "adapter_model": battery.adapter_model if battery is not None else "",+ "lid_closed": lid_closed,+ "lid_status": bool_label(lid_closed, true_label="closed", false_label="open"),+ "sidepulse_keep_awake_requested": keep_awake_requested,+ "sidepulse_keep_awake_active": keep_awake_active,+ "sleep_prevention_policy": sleep_prevention_policy,+ "sleep_prevention_battery_safeguard_active": sleep_prevention_battery_safeguard_active,+ "sleep_prevention_min_battery_percent": sleep_prevention_min_battery_percent,+ "sidepulse_closed_lid_awake_requested": closed_lid_awake_requested,+ "sidepulse_closed_lid_awake_active": closed_lid_awake_active,+ "mac_sleep_prevented": mac_sleep.sleep_prevented if mac_sleep is not None else None,+ "mac_sleep_disabled": mac_sleep.sleep_disabled if mac_sleep is not None else None,+ "mac_prevent_system_sleep": (+ mac_sleep.prevent_system_sleep if mac_sleep is not None else None+ ),+ "mac_prevent_user_idle_system_sleep": (+ mac_sleep.prevent_user_idle_system_sleep if mac_sleep is not None else None+ ),+ "mac_prevent_user_idle_display_sleep": (+ mac_sleep.prevent_user_idle_display_sleep if mac_sleep is not None else None+ ),+ "mac_user_is_active": mac_sleep.user_is_active if mac_sleep is not None else None,+ "mac_sleep_status": sleep_status_label(mac_sleep),+ "mac_sleep_error": mac_sleep.error if mac_sleep is not None and mac_sleep.error else "",+ }++def status_audit_record(event: HookEvent, status: AgentStatus | None) -> dict[str, str]:return {"audited_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),@@ -85,6 +174,30 @@ def raw_message(raw: dict[str, Any]) -> str:return ""+def bool_label(+ value: bool | None,+ *,+ true_label: str = "true",+ false_label: str = "false",+) -> str:+ if value is True:+ return true_label+ if value is False:+ return false_label+ return "unknown"+++def sleep_status_label(mac_sleep: MacSleepSnapshot | None) -> str:+ if mac_sleep is None:+ return "unknown"+ prevented = mac_sleep.sleep_prevented+ if prevented is True:+ return "prevented"+ if prevented is False:+ return "allowed"+ return "unknown"++def json_preview(value: object) -> str:try:return json.dumps(value, ensure_ascii=False, sort_keys=True, default=str)@@ -117,6 +230,31 @@ def read_status_audit_records(path: Path | None = None) -> list[dict[str, str]]:return records+def read_status_history_records(+ path: Path | None = None,+ *,+ limit: int | None = None,+) -> list[dict[str, object]]:+ source = path or default_status_history_log_path()+ try:+ lines = source.read_text(encoding="utf-8").splitlines()+ except OSError:+ return []++ if limit is not None and limit > 0:+ lines = lines[-limit:]++ records: list[dict[str, object]] = []+ for line in lines:+ try:+ obj = json.loads(line)+ except json.JSONDecodeError:+ continue+ if isinstance(obj, dict):+ records.append(obj)+ return records++def export_status_audit_csv(destination: Path,*,diff --git a/src/sidepulse/keep_awake.py b/src/sidepulse/keep_awake.pyindex db99dc1..85fc37f 100644--- a/src/sidepulse/keep_awake.py+++ b/src/sidepulse/keep_awake.py@@ -63,8 +63,12 @@ class KeepAwakeController:def update(self, mode: AgentMode, *, now: float | None = None) -> bool:current = time.monotonic() if now is None else nowshould_hold = self.should_hold_for_mode(mode, current)+ return self.update_requested(should_hold, mode=mode)++ def update_requested(self, should_hold: bool, *, mode: AgentMode | None = None) -> bool:self.holding_requested = should_hold- self.last_mode = mode+ if mode is not None:+ self.last_mode = modeif not self.enabled or not should_hold:self.release()diff --git a/src/sidepulse/lid_sleep.py b/src/sidepulse/lid_sleep.pyindex 62f9b93..feca43a 100644--- a/src/sidepulse/lid_sleep.py+++ b/src/sidepulse/lid_sleep.py@@ -20,6 +20,7 @@ from .settings import (CAFFEINATE_CLOSED_LID_COMMAND = ("/usr/bin/caffeinate", "-dimsu")IOREG_CLAMSHELL_COMMAND = ("/usr/sbin/ioreg", "-r", "-k", "AppleClamshellState", "-d", "4")IOREG_SLEEP_DISABLED_COMMAND = ("/usr/sbin/ioreg", "-r", "-k", "SleepDisabled", "-d", "4")+PMSET_ASSERTIONS_COMMAND = ("/usr/bin/pmset", "-g", "assertions")SUDO_PMSET_DISABLE_SLEEP_COMMAND = ("/usr/bin/sudo","-n",@@ -47,6 +48,30 @@ class SleepHelperRequiredError(RuntimeError):pass+@dataclass(frozen=True)+class MacSleepSnapshot:+ sleep_disabled: bool | None = None+ prevent_system_sleep: bool | None = None+ prevent_user_idle_system_sleep: bool | None = None+ prevent_user_idle_display_sleep: bool | None = None+ user_is_active: bool | None = None+ assertions: dict[str, bool] | None = None+ error: str | None = None++ @property+ def sleep_prevented(self) -> bool | None:+ known = [+ self.sleep_disabled,+ self.prevent_system_sleep,+ self.prevent_user_idle_system_sleep,+ ]+ if any(value is True for value in known):+ return True+ if any(value is None for value in known):+ return None+ return False++def closed_lid_awake_should_hold(policy: str, *, agents_active: bool) -> bool:if policy == CLOSED_LID_AWAKE_ALWAYS:return True@@ -85,6 +110,50 @@ def read_sleep_disabled(return parse_bool_ioreg_property(result.stdout, "SleepDisabled")+def read_pmset_assertions(+ *,+ runner: CommandRunner = subprocess.run,+ command: Sequence[str] = PMSET_ASSERTIONS_COMMAND,+) -> dict[str, bool]:+ result = runner(+ list(command),+ check=True,+ capture_output=True,+ text=True,+ timeout=2,+ )+ return parse_pmset_assertions(result.stdout)+++def read_mac_sleep_snapshot(+ *,+ runner: CommandRunner = subprocess.run,+) -> MacSleepSnapshot:+ errors: list[str] = []+ sleep_disabled: bool | None = None+ assertions: dict[str, bool] = {}++ try:+ sleep_disabled = read_sleep_disabled(runner=runner)+ except Exception as exc:+ errors.append(f"SleepDisabled: {exc}")++ try:+ assertions = read_pmset_assertions(runner=runner)+ except Exception as exc:+ errors.append(f"pmset assertions: {exc}")++ return MacSleepSnapshot(+ sleep_disabled=sleep_disabled,+ prevent_system_sleep=assertions.get("PreventSystemSleep"),+ prevent_user_idle_system_sleep=assertions.get("PreventUserIdleSystemSleep"),+ prevent_user_idle_display_sleep=assertions.get("PreventUserIdleDisplaySleep"),+ user_is_active=assertions.get("UserIsActive"),+ assertions=assertions,+ error="; ".join(errors) if errors else None,+ )++def parse_bool_ioreg_property(text: str | bytes, property_name: str) -> bool | None:if isinstance(text, bytes):text = text.decode("utf-8", errors="replace")@@ -100,6 +169,18 @@ def parse_bool_ioreg_property(text: str | bytes, property_name: str) -> bool | Nreturn None+def parse_pmset_assertions(text: str | bytes) -> dict[str, bool]:+ if isinstance(text, bytes):+ text = text.decode("utf-8", errors="replace")+ assertions: dict[str, bool] = {}+ for line in text.splitlines():+ match = re.match(r"\s*([A-Za-z][A-Za-z0-9]+)\s+([01])\s*$", line)+ if match is None:+ continue+ assertions[match.group(1)] = match.group(2) == "1"+ return assertions++def run_sudo_pmset_disablesleep(enabled: bool,*,@@ -278,6 +359,7 @@ class ClosedLidAwakeController:self.process = Noneself.changed_system_disable = Falseself.system_disable_attempted = False+ self.last_system_disable_request: bool | None = Noneself.last_error: str | None = Noneself.last_policy = CLOSED_LID_AWAKE_NEVERself.last_requested = False@@ -286,10 +368,11 @@ class ClosedLidAwakeController:enabled = bool(enabled)if self.use_system_disable == enabled:return- self.use_system_disable = enabled- self.system_disable_attempted = Falseif not enabled:self.release_system_disable()+ self.last_system_disable_request = None+ self.use_system_disable = enabled+ self.system_disable_attempted = Falsedef update(self, policy: str, *, agents_active: bool) -> bool:should_hold = closed_lid_awake_should_hold(policy, agents_active=agents_active)@@ -307,18 +390,15 @@ class ClosedLidAwakeController:errors: list[str] = []if (self.use_system_disable- and not self.changed_system_disable+ and self.last_system_disable_request is not Trueand not self.system_disable_attempted):self.system_disable_attempted = Truetry:- already_disabled = self.sleep_disabled_reader()- if already_disabled is False:- self.sleep_disabled_setter(True)- self.changed_system_disable = True- elif already_disabled is None:- self.sleep_disabled_setter(True)- self.changed_system_disable = True+ self.sleep_disabled_setter(True)+ self.changed_system_disable = True+ self.last_system_disable_request = True+ self.system_disable_attempted = Falseexcept Exception as exc:errors.append(f"disablesleep: {exc}")@@ -356,10 +436,16 @@ class ClosedLidAwakeController:def release_system_disable(self, *, errors: list[str] | None = None) -> None:active_errors = errors if errors is not None else []- if self.changed_system_disable:+ should_apply = (+ self.use_system_disable+ or self.changed_system_disable+ or self.last_system_disable_request is True+ )+ if should_apply and self.last_system_disable_request is not False:try:self.sleep_disabled_setter(False)self.changed_system_disable = False+ self.last_system_disable_request = Falseself.system_disable_attempted = Falseexcept Exception as exc:active_errors.append(f"disablesleep: {exc}")diff --git a/src/sidepulse/settings.py b/src/sidepulse/settings.pyindex a4710bf..52fe71c 100644--- a/src/sidepulse/settings.py+++ b/src/sidepulse/settings.py@@ -33,14 +33,22 @@ LED_DISPLAY_AGENT = "agent"LED_DISPLAY_BATTERY = "battery"LED_DISPLAY_CUSTOM = "custom"LED_DISPLAY_CHOICES = (LED_DISPLAY_AGENT, LED_DISPLAY_BATTERY, LED_DISPLAY_CUSTOM)-CLOSED_LID_AWAKE_NEVER = "never"-CLOSED_LID_AWAKE_AGENTS = "agents"-CLOSED_LID_AWAKE_ALWAYS = "always"-CLOSED_LID_AWAKE_CHOICES = (- CLOSED_LID_AWAKE_NEVER,- CLOSED_LID_AWAKE_AGENTS,- CLOSED_LID_AWAKE_ALWAYS,+SLEEP_PREVENTION_NEVER = "never"+SLEEP_PREVENTION_AGENTS = "agents"+SLEEP_PREVENTION_ALWAYS = "always"+SLEEP_PREVENTION_CHOICES = (+ SLEEP_PREVENTION_NEVER,+ SLEEP_PREVENTION_AGENTS,+ SLEEP_PREVENTION_ALWAYS,)+CLOSED_LID_AWAKE_NEVER = SLEEP_PREVENTION_NEVER+CLOSED_LID_AWAKE_AGENTS = SLEEP_PREVENTION_AGENTS+CLOSED_LID_AWAKE_ALWAYS = SLEEP_PREVENTION_ALWAYS+CLOSED_LID_AWAKE_CHOICES = SLEEP_PREVENTION_CHOICES+OPEN_LID_AWAKE_NEVER = SLEEP_PREVENTION_NEVER+OPEN_LID_AWAKE_AGENTS = SLEEP_PREVENTION_AGENTS+OPEN_LID_AWAKE_ALWAYS = SLEEP_PREVENTION_ALWAYS+OPEN_LID_AWAKE_CHOICES = SLEEP_PREVENTION_CHOICESLID_ANIMATION_CLOSED = "closed"LID_ANIMATION_OPEN = "open"LID_ANIMATION_CHOICES = (LID_ANIMATION_CLOSED, LID_ANIMATION_OPEN)@@ -77,6 +85,20 @@ DEFAULT_LID_CLOSED_ANIMATION_SECONDS = 0.9DEFAULT_LID_OPEN_ANIMATION_SECONDS = 1.0DEFAULT_RECENT_SESSION_RETENTION_SECONDS = 48 * 60 * 60DEFAULT_IDLE_TIMEOUT_SECONDS = 60 * 60+DEFAULT_SLEEP_PREVENTION_MIN_BATTERY_PERCENT = 20.0+HISTORY_TIMEFRAME_1H_SECONDS = 60 * 60+HISTORY_TIMEFRAME_6H_SECONDS = 6 * 60 * 60+HISTORY_TIMEFRAME_12H_SECONDS = 12 * 60 * 60+HISTORY_TIMEFRAME_24H_SECONDS = 24 * 60 * 60+HISTORY_TIMEFRAME_48H_SECONDS = 48 * 60 * 60+DEFAULT_HISTORY_TIMEFRAME_SECONDS = HISTORY_TIMEFRAME_12H_SECONDS+HISTORY_TIMEFRAME_CHOICES = (+ HISTORY_TIMEFRAME_1H_SECONDS,+ HISTORY_TIMEFRAME_6H_SECONDS,+ HISTORY_TIMEFRAME_12H_SECONDS,+ HISTORY_TIMEFRAME_24H_SECONDS,+ HISTORY_TIMEFRAME_48H_SECONDS,+)@dataclass(frozen=True)@@ -115,8 +137,8 @@ class AgentMonitorSettings:claude_transcripts_enabled: bool = Falseled_display: str = LED_DISPLAY_AGENTdevices: tuple[DeviceDisplaySetting, ...] = ()+ sleep_prevention_policy: str = SLEEP_PREVENTION_AGENTSvirtual_status_device_enabled: bool = False- closed_lid_awake_policy: str = CLOSED_LID_AWAKE_NEVERclosed_lid_system_override_enabled: bool = Falselid_closed_animation: LedAnimationSetting = field(default_factory=lambda: default_lid_animation(LID_ANIMATION_CLOSED)@@ -133,6 +155,8 @@ class AgentMonitorSettings:custom_terminal_path: str = ""recent_session_retention_seconds: float = DEFAULT_RECENT_SESSION_RETENTION_SECONDSidle_timeout_seconds: float = DEFAULT_IDLE_TIMEOUT_SECONDS+ sleep_prevention_min_battery_percent: float = DEFAULT_SLEEP_PREVENTION_MIN_BATTERY_PERCENT+ history_timeframe_seconds: float = DEFAULT_HISTORY_TIMEFRAME_SECONDSsetup_screen_completed: bool = Falsedef transcript_enabled(self, provider: str) -> bool:@@ -370,9 +394,15 @@ class AgentMonitorSettings:raise ValueError(f"Unknown lid animation: {kind}")def with_closed_lid_awake_policy(self, policy: str) -> "AgentMonitorSettings":- if policy not in CLOSED_LID_AWAKE_CHOICES:- raise ValueError(f"Unknown closed-lid awake policy: {policy}")- return replace(self, closed_lid_awake_policy=policy)+ return self.with_sleep_prevention_policy(policy)++ def with_open_lid_awake_policy(self, policy: str) -> "AgentMonitorSettings":+ return self.with_sleep_prevention_policy(policy)++ def with_sleep_prevention_policy(self, policy: str) -> "AgentMonitorSettings":+ if policy not in SLEEP_PREVENTION_CHOICES:+ raise ValueError(f"Unknown sleep prevention policy: {policy}")+ return replace(self, sleep_prevention_policy=policy)def with_closed_lid_system_override(self, enabled: bool) -> "AgentMonitorSettings":return replace(self, closed_lid_system_override_enabled=bool(enabled))@@ -418,12 +448,21 @@ class AgentMonitorSettings:idle_timeout_seconds=idle_timeout,)+ def with_sleep_prevention_battery_safeguard(self, percent: float) -> "AgentMonitorSettings":+ return replace(+ self,+ sleep_prevention_min_battery_percent=normalize_percent_setting(percent),+ )++ def with_history_timeframe(self, seconds: float) -> "AgentMonitorSettings":+ return replace(self, history_timeframe_seconds=normalize_history_timeframe(seconds))+def to_dict(self) -> dict[str, Any]:return {"led_display": self.led_display,"devices": [device.to_dict() for device in self.devices],+ "sleep_prevention_policy": self.sleep_prevention_policy,"virtual_status_device_enabled": self.virtual_status_device_enabled,- "closed_lid_awake_policy": self.closed_lid_awake_policy,"closed_lid_system_override_enabled": self.closed_lid_system_override_enabled,"lid_closed_animation": self.lid_closed_animation.to_dict(),"lid_open_animation": self.lid_open_animation.to_dict(),@@ -446,6 +485,12 @@ class AgentMonitorSettings:"recent_session_retention_seconds": self.recent_session_retention_seconds,"idle_timeout_seconds": self.idle_timeout_seconds,},+ "sleep_prevention": {+ "min_battery_percent": self.sleep_prevention_min_battery_percent,+ },+ "history": {+ "timeframe_seconds": self.history_timeframe_seconds,+ },"setup_screen_completed": self.setup_screen_completed,}@@ -493,6 +538,14 @@ def load_settings(path: Path | None = None) -> AgentMonitorSettings:if not isinstance(agent_list, dict):agent_list = {}+ sleep_prevention = data.get("sleep_prevention")+ if not isinstance(sleep_prevention, dict):+ sleep_prevention = {}++ history = data.get("history")+ if not isinstance(history, dict):+ history = {}+led_display = _led_display_setting(data.get("led_display"), LED_DISPLAY_AGENT)session_open_preferences = _session_open_preferences(data.get("session_open_preferences")@@ -511,12 +564,10 @@ def load_settings(path: Path | None = None) -> AgentMonitorSettings:claude_transcripts_enabled=_bool_setting(transcript.get("claude"), False),led_display=led_display,devices=_device_display_settings(data.get("devices"), led_display),+ sleep_prevention_policy=_sleep_prevention_policy_from_settings(data),virtual_status_device_enabled=_bool_setting(data.get("virtual_status_device_enabled"), False),- closed_lid_awake_policy=_closed_lid_awake_policy(- data.get("closed_lid_awake_policy"),- ),closed_lid_system_override_enabled=_bool_setting(data.get("closed_lid_system_override_enabled"),False,@@ -555,6 +606,21 @@ def load_settings(path: Path | None = None) -> AgentMonitorSettings:agent_list.get("idle_timeout_seconds", data.get("idle_timeout_seconds")),DEFAULT_IDLE_TIMEOUT_SECONDS,),+ sleep_prevention_min_battery_percent=normalize_percent_setting(+ sleep_prevention.get(+ "min_battery_percent",+ data.get(+ "sleep_prevention_min_battery_percent",+ DEFAULT_SLEEP_PREVENTION_MIN_BATTERY_PERCENT,+ ),+ )+ ),+ history_timeframe_seconds=normalize_history_timeframe(+ history.get(+ "timeframe_seconds",+ data.get("history_timeframe_seconds", DEFAULT_HISTORY_TIMEFRAME_SECONDS),+ )+ ),setup_screen_completed=_bool_setting(data.get("setup_screen_completed"), False),)@@ -591,10 +657,32 @@ def _string_setting(value: object) -> str:return value if isinstance(value, str) else ""-def _closed_lid_awake_policy(value: object) -> str:- if isinstance(value, str) and value in CLOSED_LID_AWAKE_CHOICES:+def _sleep_prevention_policy(value: object, default: str = SLEEP_PREVENTION_AGENTS) -> str:+ if isinstance(value, str) and value in SLEEP_PREVENTION_CHOICES:return value- return CLOSED_LID_AWAKE_NEVER+ return default+++def _sleep_prevention_policy_from_settings(data: dict[str, Any]) -> str:+ direct = _sleep_prevention_policy(data.get("sleep_prevention_policy"), "")+ if direct:+ return direct++ legacy_values = (+ data.get("open_lid_awake_policy"),+ data.get("closed_lid_awake_policy"),+ )+ legacy_policies = [+ _sleep_prevention_policy(value, "")+ for value in legacy_values+ ]+ if SLEEP_PREVENTION_ALWAYS in legacy_policies:+ return SLEEP_PREVENTION_ALWAYS+ if SLEEP_PREVENTION_AGENTS in legacy_policies:+ return SLEEP_PREVENTION_AGENTS+ if SLEEP_PREVENTION_NEVER in legacy_policies:+ return SLEEP_PREVENTION_NEVER+ return SLEEP_PREVENTION_AGENTSdef _device_display_settings(value: object, default_display: str) -> tuple[DeviceDisplaySetting, ...]:@@ -688,6 +776,21 @@ def normalize_seconds_setting(value: object) -> float:return 0.0+def normalize_percent_setting(value: object) -> float:+ if isinstance(value, (int, float)):+ return max(0.0, min(100.0, float(value)))+ return DEFAULT_SLEEP_PREVENTION_MIN_BATTERY_PERCENT+++def normalize_history_timeframe(value: object) -> float:+ if isinstance(value, (int, float)):+ candidate = float(value)+ for choice in HISTORY_TIMEFRAME_CHOICES:+ if abs(candidate - float(choice)) < 0.5:+ return float(choice)+ return float(DEFAULT_HISTORY_TIMEFRAME_SECONDS)++def normalize_brightness(value: object) -> int:if value is None:return 255diff --git a/src/sidepulse/status_bar.py b/src/sidepulse/status_bar.pyindex 9cdda9c..0147e9f 100644--- a/src/sidepulse/status_bar.py+++ b/src/sidepulse/status_bar.py@@ -6,7 +6,7 @@ import subprocessimport threadingimport timefrom dataclasses import dataclass-from datetime import datetime+from datetime import datetime, timezonefrom pathlib import Pathtry:@@ -68,9 +68,13 @@ from .battery import (read_battery_snapshot,)from .audit import (+ append_status_history_record,default_status_audit_log_path,+ default_status_history_log_path,export_status_audit_csv,export_status_audit_html,+ read_status_history_records,+ status_history_record,)from .collector import LiveAgentMonitor, SourceSpec, read_recent_linesfrom .device_writer import (@@ -109,7 +113,9 @@ from .virtual_device import VIRTUAL_DEVICE_ID, VIRTUAL_DEVICE_NAME, VirtualStatufrom .lid_sleep import (LID_POLL_SECONDS,ClosedLidAwakeController,+ MacSleepSnapshot,read_lid_closed,+ read_mac_sleep_snapshot,sleep_helper_install_command,sleep_helper_installed,)@@ -139,17 +145,25 @@ from .session_actions import (session_open_target,)from .settings import (- CLOSED_LID_AWAKE_AGENTS,- CLOSED_LID_AWAKE_ALWAYS,- CLOSED_LID_AWAKE_CHOICES,- CLOSED_LID_AWAKE_NEVER,DEFAULT_IDLE_TIMEOUT_SECONDS,+ DEFAULT_HISTORY_TIMEFRAME_SECONDS,DEFAULT_RECENT_SESSION_RETENTION_SECONDS,+ DEFAULT_SLEEP_PREVENTION_MIN_BATTERY_PERCENT,+ HISTORY_TIMEFRAME_1H_SECONDS,+ HISTORY_TIMEFRAME_6H_SECONDS,+ HISTORY_TIMEFRAME_12H_SECONDS,+ HISTORY_TIMEFRAME_24H_SECONDS,+ HISTORY_TIMEFRAME_48H_SECONDS,+ HISTORY_TIMEFRAME_CHOICES,LED_DISPLAY_AGENT,LED_DISPLAY_BATTERY,LED_DISPLAY_CUSTOM,LID_ANIMATION_CLOSED,LID_ANIMATION_OPEN,+ SLEEP_PREVENTION_AGENTS,+ SLEEP_PREVENTION_ALWAYS,+ SLEEP_PREVENTION_CHOICES,+ SLEEP_PREVENTION_NEVER,TERMINAL_APP_ALACRITTY,TERMINAL_APP_CUSTOM,TERMINAL_APP_GHOSTTY,@@ -221,15 +235,25 @@ STATUS_BAR_SESSION_HISTORY_LIMIT = 10SCREEN_BAR_FEATURE_ENABLED = TrueSTATUS_BAR_MAX_LINES_PER_SOURCE = 500STATUS_BAR_STARTUP_REPLAY_LINES = 200+STATUS_BAR_HISTORY_CHART_RECORD_LIMIT = 2400+STATUS_BAR_HISTORY_CHART_RECORD_LIMIT_PADDING = 300+STATUS_BAR_HISTORY_CHART_RECORD_LIMIT_MULTIPLIER = 3.0LID_ANIMATION_RESTORE_FUDGE_SECONDS = 0.15LID_ANIMATION_LABELS = {LID_ANIMATION_CLOSED: "Lid Closed",LID_ANIMATION_OPEN: "Lid Open",}-CLOSED_LID_AWAKE_LABELS = {- CLOSED_LID_AWAKE_NEVER: "Never",- CLOSED_LID_AWAKE_AGENTS: "When Agents Work",- CLOSED_LID_AWAKE_ALWAYS: "Always",+SLEEP_PREVENTION_LABELS = {+ SLEEP_PREVENTION_NEVER: "Never",+ SLEEP_PREVENTION_AGENTS: "When Agents Work",+ SLEEP_PREVENTION_ALWAYS: "Always",+}+HISTORY_TIMEFRAME_LABELS = {+ HISTORY_TIMEFRAME_1H_SECONDS: "Last 1h",+ HISTORY_TIMEFRAME_6H_SECONDS: "Last 6h",+ HISTORY_TIMEFRAME_12H_SECONDS: "Last 12h",+ HISTORY_TIMEFRAME_24H_SECONDS: "Last 24h",+ HISTORY_TIMEFRAME_48H_SECONDS: "Last 48h",}TERMINAL_APP_LABELS = {TERMINAL_APP_TERMINAL: "Terminal",@@ -279,6 +303,41 @@ def state_for_mode(mode: AgentMode) -> StatusBarState:return STATE_IDLE+def awake_policy_should_hold(policy: str, *, agents_active: bool) -> bool:+ if policy == SLEEP_PREVENTION_ALWAYS:+ return True+ if policy == SLEEP_PREVENTION_AGENTS:+ return agents_active+ return False+++def sleep_prevention_battery_safeguard(+ snapshot: BatterySnapshot | None,+ threshold_percent: float,+) -> tuple[bool, str]:+ threshold = max(0.0, min(100.0, float(threshold_percent)))+ threshold_text = format_percent_value(threshold)+ if threshold <= 0:+ return False, "disabled"+ if snapshot is None:+ return False, f"battery unknown, threshold {threshold_text}"+ if not snapshot.battery_present:+ return False, f"no battery, threshold {threshold_text}"+ battery_text = format_percent_value(snapshot.percent)+ if snapshot.is_plugged:+ return False, f"battery {battery_text}, plugged in, threshold {threshold_text}"+ if snapshot.percent < threshold:+ return True, f"battery {battery_text}, threshold {threshold_text}"+ return False, f"battery {battery_text}, threshold {threshold_text}"+++def format_percent_value(value: float | int) -> str:+ number = float(value)+ if number.is_integer():+ return f"{int(number)}%"+ return f"{number:.1f}%"++def replay_recent_debug_logs(monitor: LiveAgentMonitor,*,@@ -345,8 +404,16 @@ class StatusBarController(NSObject):)self.last_keep_awake_error = Noneself.last_closed_lid_awake_error = None+ self.last_mac_sleep_error = None+ self.last_mac_sleep_snapshot = None+ self.last_status_history_error = Noneself.last_status_read_error = Noneself.event_refresh_pending = False+ self.agent_awake_last_mode = None+ self.agent_awake_grace_until_monotonic = None+ self.agent_awake_requested = False+ self.battery_sleep_safeguard_active = False+ self.battery_sleep_safeguard_reason = ""self.last_lid_closed = Noneself.last_lid_error = Noneself.led_animation_until_monotonic = 0.0@@ -404,8 +471,16 @@ class StatusBarController(NSObject):except Exception as exc:log_status_bar(f"refresh error: {exc}")self.set_status(STATE_ASK)- self.sync_keep_awake(AgentMode.BLOCKED_ERROR)- self.sync_leds(AgentMode.BLOCKED_ERROR, None, LED_DISPLAY_AGENT)+ battery_snapshot = self.read_battery_snapshot()+ self.sync_keep_awake(AgentMode.BLOCKED_ERROR, battery_snapshot)+ mac_sleep_snapshot = self.read_mac_sleep_snapshot()+ self.record_status_history(+ AgentMode.BLOCKED_ERROR,+ STATE_ASK,+ battery_snapshot,+ mac_sleep_snapshot,+ )+ self.sync_leds(AgentMode.BLOCKED_ERROR, battery_snapshot, LED_DISPLAY_AGENT)self.status_item.setMenu_(build_error_menu(exc))return@@ -414,7 +489,14 @@ class StatusBarController(NSObject):state = state_for_mode(snapshot.aggregate.mode)self.observe_connected_devices()self.set_status(state)- self.sync_keep_awake(snapshot.aggregate.mode)+ self.sync_keep_awake(snapshot.aggregate.mode, battery_snapshot)+ mac_sleep_snapshot = self.read_mac_sleep_snapshot()+ self.record_status_history(+ snapshot.aggregate.mode,+ state,+ battery_snapshot,+ mac_sleep_snapshot,+ )self.sync_leds(snapshot.aggregate.mode,battery_snapshot,@@ -518,6 +600,26 @@ class StatusBarController(NSObject):returnself.set_session_terminal(terminal)+ @objc.IBAction+ def setHistoryTimeframe_(self, sender):+ selected = sender.selectedItem()+ value = selected.representedObject() if selected is not None else None+ if not isinstance(value, (int, float)):+ return+ try:+ self.settings = self.settings.with_history_timeframe(float(value))+ save_settings(self.settings)+ except Exception as exc:+ self.set_settings_message(f"Could not save history timeframe: {exc}")+ self.settings = load_settings()+ self.refresh_settings_window()+ return++ self.refresh_history_chart()+ self.set_settings_message(+ f"History timeframe: {history_timeframe_label(self.settings.history_timeframe_seconds)}."+ )+@objc.IBActiondef chooseSessionTerminal_(self, _sender):self.choose_session_terminal_app()@@ -538,7 +640,15 @@ class StatusBarController(NSObject):@objc.IBActiondef setClosedLidAwakePolicy_(self, sender):- self.set_closed_lid_awake_policy(sender.representedObject())+ self.set_sleep_prevention_policy(sender.representedObject())++ @objc.IBAction+ def setOpenLidAwakePolicy_(self, sender):+ self.set_sleep_prevention_policy(sender.representedObject())++ @objc.IBAction+ def setSleepPreventionPolicy_(self, sender):+ self.set_sleep_prevention_policy(sender.representedObject())@objc.IBActiondef openSettings_(self, _sender):@@ -972,6 +1082,39 @@ class StatusBarController(NSObject):self.settings_fields.get("idle_timeout_minutes"),f"{self.settings.idle_timeout_seconds / 60:g}",)+ set_text_control_value(+ self.settings_fields.get("sleep_prevention_min_battery_percent"),+ f"{self.settings.sleep_prevention_min_battery_percent:g}",+ )+ timeframe_popup = self.settings_fields.get("status_history_timeframe")+ if timeframe_popup is not None:+ refresh_history_timeframe_popup(+ timeframe_popup,+ self.settings.history_timeframe_seconds,+ )+ self.refresh_history_chart()++ def refresh_history_chart(self) -> None:+ chart = self.settings_fields.get("status_history_chart")+ status_label = self.settings_fields.get("status_history_status")+ timeframe_seconds = self.settings.history_timeframe_seconds+ try:+ records = read_status_history_records(+ limit=history_record_limit_for_timeframe(timeframe_seconds)+ )+ records = filter_status_history_records(records, timeframe_seconds)+ except Exception as exc:+ records = []+ set_field_value(status_label, f"History: {exc}")+ else:+ set_field_value(+ status_label,+ status_history_status_text(records, timeframe_seconds),+ )+ if chart is not None and hasattr(chart, "setRecords_"):+ if hasattr(chart, "setTimeframeSeconds_"):+ chart.setTimeframeSeconds_(timeframe_seconds)+ chart.setRecords_(records)def set_settings_message(self, message: str) -> None:set_field_value(self.settings_fields.get("message"), message)@@ -1016,6 +1159,10 @@ class StatusBarController(NSObject):def exportDebugHtml_(self, _sender):self.export_debug_log("html")+ @objc.IBAction+ def refreshHistoryChart_(self, _sender):+ self.refresh_history_chart()+def export_debug_log(self, format_name: str) -> None:path = choose_debug_export_path(format_name)if path is None:@@ -1079,6 +1226,9 @@ class StatusBarController(NSObject):self.settings_fields.get("recent_session_retention_hours"))idle_text = text_control_value(self.settings_fields.get("idle_timeout_minutes"))+ battery_text = text_control_value(+ self.settings_fields.get("sleep_prevention_min_battery_percent")+ )try:retention_hours = float(retention_text) if retention_text else (DEFAULT_RECENT_SESSION_RETENTION_SECONDS / 3600@@ -1086,8 +1236,11 @@ class StatusBarController(NSObject):idle_minutes = float(idle_text) if idle_text else (DEFAULT_IDLE_TIMEOUT_SECONDS / 60)+ min_battery_percent = float(battery_text) if battery_text else (+ DEFAULT_SLEEP_PREVENTION_MIN_BATTERY_PERCENT+ )except ValueError:- self.set_settings_message("Agent list timing must be numeric.")+ self.set_settings_message("Behavior settings must be numeric.")returntry:@@ -1095,15 +1248,18 @@ class StatusBarController(NSObject):recent_session_retention_seconds=retention_hours * 3600,idle_timeout_seconds=idle_minutes * 60,)+ self.settings = self.settings.with_sleep_prevention_battery_safeguard(+ min_battery_percent+ )save_settings(self.settings)except Exception as exc:- self.set_settings_message(f"Could not save agent list timing: {exc}")+ self.set_settings_message(f"Could not save behavior settings: {exc}")self.settings = load_settings()self.refresh_settings_window()returnself.reload_monitor()- self.set_settings_message("Agent list timing saved.")+ self.set_settings_message("Behavior settings saved.")self.refresh_settings_window()self.refresh_(None)@@ -1250,24 +1406,29 @@ class StatusBarController(NSObject):self.virtual_status_device.hide()self.refresh_(None)- def set_closed_lid_awake_policy(self, policy: str | None) -> None:- if policy not in CLOSED_LID_AWAKE_CHOICES:+ def set_sleep_prevention_policy(self, policy: str | None) -> None:+ if policy not in SLEEP_PREVENTION_CHOICES:returntry:- self.settings = self.settings.with_closed_lid_awake_policy(str(policy))+ self.settings = self.settings.with_sleep_prevention_policy(str(policy))save_settings(self.settings)except Exception as exc:- self.set_settings_message(f"Could not save lid sleep setting: {exc}")+ self.set_settings_message(f"Could not save sleep prevention setting: {exc}")self.settings = load_settings()returnself.set_settings_message(- f"Closed-lid awake: {CLOSED_LID_AWAKE_LABELS[self.settings.closed_lid_awake_policy]}."+ f"Sleep prevention: {SLEEP_PREVENTION_LABELS[self.settings.sleep_prevention_policy]}.")- self.sync_closed_lid_awake()self.refresh_settings_window()self.refresh_(None)+ def set_closed_lid_awake_policy(self, policy: str | None) -> None:+ self.set_sleep_prevention_policy(policy)++ def set_open_lid_awake_policy(self, policy: str | None) -> None:+ self.set_sleep_prevention_policy(policy)+def lid_animation_from_fields(self, kind: str) -> LedAnimationSetting | None:program_field = self.settings_fields.get(f"{kind}_animation_program")duration_field = self.settings_fields.get(f"{kind}_animation_duration")@@ -1458,6 +1619,52 @@ class StatusBarController(NSObject):)self.last_power_connected = plugged+ def read_mac_sleep_snapshot(self) -> MacSleepSnapshot | None:+ snapshot = read_mac_sleep_snapshot()+ error = snapshot.error or None+ if error != self.last_mac_sleep_error:+ self.last_mac_sleep_error = error+ if error:+ log_status_bar(f"mac_sleep error: {error}")+ self.last_mac_sleep_snapshot = snapshot+ return snapshot++ def record_status_history(+ self,+ mode: AgentMode,+ state: StatusBarState,+ battery_snapshot: BatterySnapshot | None,+ mac_sleep_snapshot: MacSleepSnapshot | None,+ ) -> None:+ try:+ record = status_history_record(+ agent_mode=mode.value,+ display_status=state.label,+ battery=battery_snapshot,+ mac_sleep=mac_sleep_snapshot,+ lid_closed=self.last_lid_closed,+ keep_awake_requested=bool(self.keep_awake.holding_requested),+ keep_awake_active=bool(self.keep_awake.process_running()),+ sleep_prevention_policy=self.settings.sleep_prevention_policy,+ sleep_prevention_battery_safeguard_active=bool(+ self.battery_sleep_safeguard_active+ ),+ sleep_prevention_min_battery_percent=(+ self.settings.sleep_prevention_min_battery_percent+ ),+ closed_lid_awake_requested=bool(self.closed_lid_awake.last_requested),+ closed_lid_awake_active=bool(self.closed_lid_awake.active()),+ )+ append_status_history_record(record)+ except Exception as exc:+ error = str(exc)+ if error != self.last_status_history_error:+ self.last_status_history_error = error+ log_status_bar(f"status_history error: {error}")+ return++ self.last_status_history_error = None+def active_led_display_kind(self, snapshot: BatterySnapshot | None) -> str:if self.settings.led_display == LED_DISPLAY_CUSTOM:return LED_DISPLAY_CUSTOM@@ -1955,9 +2162,31 @@ class StatusBarController(NSObject):if self.last_snapshot is not None:self.refresh_(None)- def sync_keep_awake(self, mode: AgentMode) -> None:+ def sync_keep_awake(+ self,+ mode: AgentMode,+ battery_snapshot: BatterySnapshot | None = None,+ ) -> None:+ agents_active = self.update_agent_awake_request(mode)+ safeguard_active, safeguard_reason = sleep_prevention_battery_safeguard(+ battery_snapshot,+ self.settings.sleep_prevention_min_battery_percent,+ )+ if safeguard_active != self.battery_sleep_safeguard_active:+ log_status_bar(+ "sleep_battery_safeguard="+ f"{'active' if safeguard_active else 'released'} "+ f"{safeguard_reason}"+ )+ self.battery_sleep_safeguard_active = safeguard_active+ self.battery_sleep_safeguard_reason = safeguard_reason+ policy = self.settings.sleep_prevention_policy+ should_hold = awake_policy_should_hold(+ policy,+ agents_active=agents_active,+ ) and not safeguard_activewas_running = self.keep_awake.process_running()- self.keep_awake.update(mode)+ self.keep_awake.update_requested(should_hold, mode=mode)is_running = self.keep_awake.process_running()if was_running != is_running:log_status_bar(f"keep_awake={'active' if is_running else 'released'}")@@ -1966,7 +2195,7 @@ class StatusBarController(NSObject):if self.last_keep_awake_error:log_status_bar(f"keep_awake error: {self.last_keep_awake_error}")- self.sync_closed_lid_awake()+ self.sync_closed_lid_awake(agents_active=agents_active)if not self.leds_enabled:return@@ -1981,18 +2210,53 @@ class StatusBarController(NSObject):if self.last_status_read_error:log_status_bar(f"sd_keepalive error: {self.last_status_read_error}")- def sync_closed_lid_awake(self) -> None:+ def update_agent_awake_request(self, mode: AgentMode) -> bool:+ current = time.monotonic()+ if mode in {+ AgentMode.WORKING,+ AgentMode.TOOL_RUNNING,+ AgentMode.LONG_TASK_PROGRESS,+ }:+ self.agent_awake_grace_until_monotonic = None+ requested = True+ elif mode in {+ AgentMode.COMPLETED,+ AgentMode.WAITING_FOR_INPUT,+ AgentMode.BLOCKED_ERROR,+ }:+ if (+ self.agent_awake_last_mode != mode+ or self.agent_awake_grace_until_monotonic is None+ ):+ self.agent_awake_grace_until_monotonic = (+ current + self.keep_awake.grace_seconds+ )+ requested = current < self.agent_awake_grace_until_monotonic+ else:+ requested = (+ self.agent_awake_grace_until_monotonic is not None+ and current < self.agent_awake_grace_until_monotonic+ )++ self.agent_awake_last_mode = mode+ self.agent_awake_requested = requested+ return requested++ def sync_closed_lid_awake(self, *, agents_active: bool | None = None) -> None:was_active = self.closed_lid_awake.active()self.closed_lid_awake.set_use_system_disable(sleep_helper_installed())+ policy = self.settings.sleep_prevention_policy+ if self.battery_sleep_safeguard_active:+ policy = SLEEP_PREVENTION_NEVERself.closed_lid_awake.update(- self.settings.closed_lid_awake_policy,- agents_active=self.keep_awake.holding_requested,+ policy,+ agents_active=self.agent_awake_requested if agents_active is None else agents_active,)is_active = self.closed_lid_awake.active()if was_active != is_active:log_status_bar(f"closed_lid_awake={'active' if is_active else 'released'} "- f"policy={self.settings.closed_lid_awake_policy}"+ f"policy={self.settings.sleep_prevention_policy}")if self.closed_lid_awake.last_error != self.last_closed_lid_awake_error:self.last_closed_lid_awake_error = self.closed_lid_awake.last_error@@ -2056,11 +2320,9 @@ def build_menu(snapshot, state: StatusBarState, target: StatusBarController) ->menu.addItem_(virtual_toggle)menu.addItem_(NSMenuItem.separatorItem())- menu.addItem_(disabled_menu_item("Keep Awake With Lid Closed"))- for policy in CLOSED_LID_AWAKE_CHOICES:- menu.addItem_(build_closed_lid_awake_policy_item(policy, target))- if target.closed_lid_awake.last_error:- menu.addItem_(disabled_menu_item(f"Sleep warning: {target.closed_lid_awake.last_error}"))+ menu.addItem_(disabled_menu_item("Closed-Lid Sleep Prevention"))+ for policy in SLEEP_PREVENTION_CHOICES:+ menu.addItem_(build_sleep_prevention_policy_item(policy, target))menu.addItem_(NSMenuItem.separatorItem())setup = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(@@ -2090,15 +2352,15 @@ def build_menu(snapshot, state: StatusBarState, target: StatusBarController) ->return menu-def build_closed_lid_awake_policy_item(policy: str, target: StatusBarController) -> NSMenuItem:+def build_sleep_prevention_policy_item(policy: str, target: StatusBarController) -> NSMenuItem:item = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(- CLOSED_LID_AWAKE_LABELS[policy],- "setClosedLidAwakePolicy:",+ SLEEP_PREVENTION_LABELS[policy],+ "setSleepPreventionPolicy:","",)item.setTarget_(target)item.setRepresentedObject_(policy)- item.setState_(1 if target.settings.closed_lid_awake_policy == policy else 0)+ item.setState_(1 if target.settings.sleep_prevention_policy == policy else 0)return item@@ -2320,6 +2582,607 @@ def format_byte_count(size: int) -> str:value /= 1024+class StatusHistoryChartView(NSView):+ def initWithFrame_(self, frame):+ self = objc.super(StatusHistoryChartView, self).initWithFrame_(frame)+ if self is None:+ return None+ self.records = ()+ self.timeframe_seconds = DEFAULT_HISTORY_TIMEFRAME_SECONDS+ return self++ def setRecords_(self, records):+ self.records = tuple(records or ())+ self.setNeedsDisplay_(True)++ def setTimeframeSeconds_(self, seconds):+ if isinstance(seconds, (int, float)):+ self.timeframe_seconds = float(seconds)+ self.setNeedsDisplay_(True)++ def drawRect_(self, _dirty_rect):+ draw_status_history_chart(+ self.bounds(),+ getattr(self, "records", ()),+ getattr(self, "timeframe_seconds", DEFAULT_HISTORY_TIMEFRAME_SECONDS),+ )+++def status_history_status_text(+ records: list[dict[str, object]],+ timeframe_seconds: float | None = None,+) -> str:+ timeframe = history_timeframe_label(timeframe_seconds)+ if not records:+ return f"History: {timeframe} - no samples"++ latest = records[-1]+ pieces = [+ timeframe,+ f"{len(records)} samples",+ f"latest {compact_history_time(latest.get('recorded_at'))}",+ ]+ battery = numeric_history_value(latest.get("battery_level"))+ if battery is not None:+ pieces.append(f"battery {battery:.0f}%")+ charger = numeric_history_value(latest.get("charger_power_watts"))+ if charger is not None:+ pieces.append(f"charger {charger:.0f}W")+ return "History: " + " - ".join(pieces)+++def compact_history_time(value: object) -> str:+ parsed = parse_history_timestamp(value)+ if parsed is None:+ return "unknown"+ return datetime.fromtimestamp(parsed, timezone.utc).astimezone().strftime("%H:%M:%S")+++def history_timeframe_label(seconds: float | None) -> str:+ if seconds is None:+ seconds = DEFAULT_HISTORY_TIMEFRAME_SECONDS+ try:+ value = float(seconds)+ except (TypeError, ValueError):+ value = float(DEFAULT_HISTORY_TIMEFRAME_SECONDS)+ for choice, label in HISTORY_TIMEFRAME_LABELS.items():+ if abs(value - float(choice)) < 0.5:+ return label+ hours = max(1.0, value / 3600.0)+ return f"Last {hours:g}h"+++def history_record_limit_for_timeframe(seconds: float | None) -> int:+ try:+ value = float(seconds)+ except (TypeError, ValueError):+ value = float(DEFAULT_HISTORY_TIMEFRAME_SECONDS)+ estimate = value / max(1.0, STATUS_BAR_REFRESH_SECONDS)+ return max(+ STATUS_BAR_HISTORY_CHART_RECORD_LIMIT,+ int(estimate * STATUS_BAR_HISTORY_CHART_RECORD_LIMIT_MULTIPLIER)+ + STATUS_BAR_HISTORY_CHART_RECORD_LIMIT_PADDING,+ )+++def filter_status_history_records(+ records: list[dict[str, object]],+ timeframe_seconds: float | None,+) -> list[dict[str, object]]:+ if not records:+ return []+ try:+ window = float(timeframe_seconds)+ except (TypeError, ValueError):+ window = float(DEFAULT_HISTORY_TIMEFRAME_SECONDS)+ if window <= 0:+ return list(records)++ dated: list[tuple[float, dict[str, object]]] = []+ for record in records:+ if not isinstance(record, dict):+ continue+ timestamp = parse_history_timestamp(record.get("recorded_at"))+ if timestamp is None:+ continue+ dated.append((timestamp, record))+ if not dated:+ return []++ end = max(timestamp for timestamp, _record in dated)+ start = end - window+ return [record for timestamp, record in dated if timestamp >= start]+++def draw_status_history_chart(bounds, records, timeframe_seconds: float | None = None) -> None:+ x, y, width, height = rect_parts(bounds)+ fill_rounded_rect(x, y, width, height, 8, chart_color("#FBFBFD"))++ points = history_points(records)+ if not points:+ draw_chart_text("No history yet", x + 18, y + height / 2 - 8, width - 36, 16)+ return++ end = max(points[-1][0], points[0][0] + 1.0)+ try:+ window = float(timeframe_seconds)+ except (TypeError, ValueError):+ window = float(DEFAULT_HISTORY_TIMEFRAME_SECONDS)+ if window > 0:+ start = end - max(60.0, window)+ else:+ start = points[0][0]+ if end - start < 60.0:+ end = start + 60.0++ label_width = 96.0+ value_width = 58.0+ chart_x = x + label_width+ chart_width = max(20.0, width - label_width - value_width - 18.0)+ top_padding = 16.0+ legend_height = 54.0+ bottom_padding = legend_height + 14.0+ rows = (+ ("Agent", "agent"),+ ("Battery", "battery"),+ ("Charger", "charger"),+ ("SidePulse", "sidepulse"),+ ("macOS Sleep", "mac_sleep"),+ ("Lid", "lid"),+ )+ row_height = (height - top_padding - bottom_padding) / len(rows)+ for index, (label, kind) in enumerate(rows):+ row_y = y + height - top_padding - (index + 1) * row_height+ if index % 2 == 1:+ fill_rect(+ chart_x,+ row_y + 2.0,+ chart_width,+ max(1.0, row_height - 4.0),+ chart_color("#FFFFFF", 0.42),+ )+ fill_rect(+ chart_x,+ row_y + row_height / 2 - 0.5,+ chart_width,+ 1.0,+ chart_color("#E6E6E8"),+ )+ draw_chart_text(label, x + 12, row_y + row_height / 2 - 7, label_width - 18, 14)+ if kind == "agent":+ draw_history_segments(+ points,+ start,+ end,+ chart_x,+ chart_width,+ row_y + row_height * 0.33,+ row_height * 0.34,+ history_status_color,+ )+ elif kind == "battery":+ draw_history_line(+ points,+ "battery_level",+ 100.0,+ start,+ end,+ chart_x,+ chart_width,+ row_y + row_height * 0.16,+ row_height * 0.68,+ chart_color("#1F7AFF", 0.95),+ chart_color("#1F7AFF", 0.09),+ )+ draw_current_history_value(+ points,+ "battery_level",+ "%",+ chart_x + chart_width + 8.0,+ row_y + row_height / 2 - 7,+ value_width - 8.0,+ )+ elif kind == "charger":+ charger_max = nice_history_max(+ numeric_history_value(record.get("charger_power_watts")) or 0.0+ for _timestamp, record in points+ )+ draw_history_line(+ points,+ "charger_power_watts",+ charger_max,+ start,+ end,+ chart_x,+ chart_width,+ row_y + row_height * 0.16,+ row_height * 0.68,+ chart_color("#1FA463", 0.95),+ chart_color("#1FA463", 0.08),+ )+ draw_current_history_value(+ points,+ "charger_power_watts",+ "W",+ chart_x + chart_width + 8.0,+ row_y + row_height / 2 - 7,+ value_width - 8.0,+ )+ elif kind == "sidepulse":+ draw_history_segments(+ points,+ start,+ end,+ chart_x,+ chart_width,+ row_y + row_height * 0.33,+ row_height * 0.34,+ sidepulse_awake_color,+ )+ elif kind == "mac_sleep":+ draw_history_segments(+ points,+ start,+ end,+ chart_x,+ chart_width,+ row_y + row_height * 0.33,+ row_height * 0.34,+ mac_sleep_color,+ )+ else:+ draw_history_segments(+ points,+ start,+ end,+ chart_x,+ chart_width,+ row_y + row_height * 0.33,+ row_height * 0.34,+ lid_color,+ )++ draw_history_legend(chart_x, y + 8.0, chart_width + value_width, legend_height)+++def draw_history_line(+ points,+ key: str,+ max_value: float,+ start: float,+ end: float,+ x: float,+ width: float,+ y: float,+ height: float,+ line_color,+ fill_color,+) -> None:+ if max_value <= 0:+ return+ draw_metric_grid(x, width, y, height)+ baseline = y + 1.0+ segments = history_line_segments(points, key, max_value, start, end, x, width, y, height)+ for segment in segments:+ if len(segment) == 1:+ point_x, point_y = segment[0]+ fill_rect(point_x - 0.5, point_y - 0.5, 1.0, 1.0, line_color)+ continue+ area_path = NSBezierPath.bezierPath()+ area_path.moveToPoint_((segment[0][0], baseline))+ for point_x, point_y in segment:+ area_path.lineToPoint_((point_x, point_y))+ area_path.lineToPoint_((segment[-1][0], baseline))+ area_path.closePath()+ fill_color.set()+ area_path.fill()++ line_path = NSBezierPath.bezierPath()+ line_path.moveToPoint_(segment[0])+ for point in segment[1:]:+ line_path.lineToPoint_(point)+ line_path.setLineWidth_(1.8)+ line_color.set()+ line_path.stroke()+++def draw_metric_grid(x: float, width: float, y: float, height: float) -> None:+ for ratio, alpha in ((0.0, 0.65), (0.5, 0.42), (1.0, 0.65)):+ fill_rect(+ x,+ y + height * ratio,+ width,+ 1.0,+ chart_color("#D9DADD", alpha),+ )+++def history_line_segments(+ points,+ key: str,+ max_value: float,+ start: float,+ end: float,+ x: float,+ width: float,+ y: float,+ height: float,+) -> list[list[tuple[float, float]]]:+ segments: list[list[tuple[float, float]]] = []+ current: list[tuple[float, float]] = []+ if max_value <= 0:+ return segments+ for timestamp, record in points:+ value = numeric_history_value(record.get(key))+ if value is None:+ if current:+ segments.append(current)+ current = []+ continue+ clamped = max(0.0, min(max_value, value))+ point_x = x_for_history_time(timestamp, start, end, x, width)+ point_y = y + height * (clamped / max_value)+ current.append((point_x, point_y))+ if current:+ segments.append(current)+ return segments+++def draw_current_history_value(+ points,+ key: str,+ suffix: str,+ x: float,+ y: float,+ width: float,+) -> None:+ value = latest_numeric_history_value(points, key)+ if value is None:+ text = "-"+ elif suffix == "%":+ text = f"{value:.0f}%"+ elif suffix == "W":+ text = f"{value:.0f}W"+ else:+ text = f"{value:g}{suffix}"+ draw_chart_text(text, x, y, width, 14)+++def latest_numeric_history_value(points, key: str) -> float | None:+ for _timestamp, record in reversed(points):+ value = numeric_history_value(record.get(key))+ if value is not None:+ return value+ return None+++def nice_history_max(values) -> float:+ peak = max((float(value) for value in values), default=0.0)+ if peak <= 30.0:+ return 30.0+ for ceiling in (45.0, 60.0, 75.0, 90.0, 100.0, 140.0, 180.0, 240.0):+ if peak <= ceiling:+ return ceiling+ return ((int(peak) // 50) + 1) * 50.0+++def draw_history_segments(+ points,+ start: float,+ end: float,+ x: float,+ width: float,+ y: float,+ height: float,+ color_fn,+) -> None:+ for index, (timestamp, record) in enumerate(points):+ next_timestamp = points[index + 1][0] if index + 1 < len(points) else end+ left = x_for_history_time(timestamp, start, end, x, width)+ right = x_for_history_time(next_timestamp, start, end, x, width)+ fill_rect(left, y, max(1.0, right - left), height, color_fn(record))+++def history_points(records) -> list[tuple[float, dict[str, object]]]:+ points: list[tuple[float, dict[str, object]]] = []+ for record in records:+ if not isinstance(record, dict):+ continue+ timestamp = parse_history_timestamp(record.get("recorded_at"))+ if timestamp is None:+ continue+ points.append((timestamp, record))+ points.sort(key=lambda item: item[0])+ return points+++def parse_history_timestamp(value: object) -> float | None:+ if not isinstance(value, str) or not value:+ return None+ try:+ parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))+ except ValueError:+ return None+ if parsed.tzinfo is None:+ parsed = parsed.replace(tzinfo=timezone.utc)+ return parsed.timestamp()+++def numeric_history_value(value: object) -> float | None:+ if isinstance(value, bool) or value is None:+ return None+ try:+ return float(value)+ except (TypeError, ValueError):+ return None+++def x_for_history_time(+ timestamp: float,+ start: float,+ end: float,+ x: float,+ width: float,+) -> float:+ return x + width * ((timestamp - start) / max(1.0, end - start))+++def history_status_color(record: dict[str, object]):+ status = " ".join(+ str(record.get(key, "")).lower()+ for key in ("display_status", "agent_status")+ )+ if "ask" in status or "waiting" in status or "blocked" in status:+ return chart_color("#FF8A00", 0.9)+ if "work" in status or "tool" in status or "progress" in status:+ return chart_color("#00AEEF", 0.9)+ if "done" in status or "complete" in status:+ return chart_color("#22B14C", 0.9)+ return chart_color("#A8A8A8", 0.72)+++def sidepulse_awake_color(record: dict[str, object]):+ if record.get("sleep_prevention_battery_safeguard_active") is True:+ return chart_color("#FF4A00", 0.9)+ if (+ record.get("sidepulse_keep_awake_active") is True+ or record.get("sidepulse_closed_lid_awake_active") is True+ ):+ return chart_color("#7B61FF", 0.86)+ if (+ record.get("sidepulse_keep_awake_requested") is True+ or record.get("sidepulse_closed_lid_awake_requested") is True+ ):+ return chart_color("#B7A7FF", 0.86)+ return chart_color("#C9CDD3", 0.72)+++def mac_sleep_color(record: dict[str, object]):+ status = str(record.get("mac_sleep_status", "")).lower()+ if record.get("mac_sleep_prevented") is True or status == "prevented":+ return chart_color("#FFB000", 0.88)+ if record.get("mac_sleep_prevented") is False or status == "allowed":+ return chart_color("#36B37E", 0.78)+ return chart_color("#C9CDD3", 0.72)+++def lid_color(record: dict[str, object]):+ if record.get("lid_closed") is True or record.get("lid_status") == "closed":+ return chart_color("#FF6B00", 0.88)+ if record.get("lid_closed") is False or record.get("lid_status") == "open":+ return chart_color("#4AA3FF", 0.72)+ return chart_color("#C9CDD3", 0.72)+++def history_legend_rows() -> tuple[tuple[object, ...], ...]:+ return (+ (+ "Agent",+ ("#FF8A00", "Ask"),+ ("#00AEEF", "Working"),+ ("#22B14C", "Done"),+ ("#A8A8A8", "Idle"),+ ("#1F7AFF", "Battery"),+ ("#1FA463", "Charger"),+ ),+ (+ "SidePulse",+ ("#7B61FF", "Awake"),+ ("#B7A7FF", "Requested"),+ ("#FF4A00", "Safeguard"),+ ("#C9CDD3", "Off"),+ ),+ (+ "macOS",+ ("#FFB000", "Prevented"),+ ("#36B37E", "Allowed"),+ ("#FF6B00", "Lid closed"),+ ("#4AA3FF", "Lid open"),+ ),+ )+++def draw_history_legend(x: float, y: float, width: float, height: float) -> None:+ rows = history_legend_rows()+ row_height = height / max(1, len(rows))+ for row_index, row in enumerate(rows):+ cursor = x+ row_y = y + height - (row_index + 1) * row_height + 2.0+ heading = str(row[0])+ draw_chart_text(heading, cursor, row_y, 58.0, 14.0)+ cursor += 62.0+ for item in row[1:]:+ if not isinstance(item, tuple) or len(item) != 2:+ continue+ color, label = item+ label_text = str(label)+ fill_rounded_rect(+ cursor,+ row_y + 3.0,+ 10.0,+ 8.0,+ 2.0,+ chart_color(str(color), 0.92),+ )+ draw_chart_text(label_text, cursor + 14.0, row_y, 92.0, 14.0)+ cursor += min(108.0, max(44.0, 18.0 + len(label_text) * 6.5))+ if cursor > x + width - 48.0:+ break+++def fill_rounded_rect(+ x: float,+ y: float,+ width: float,+ height: float,+ radius: float,+ color,+) -> None:+ color.set()+ path = NSBezierPath.bezierPathWithRoundedRect_xRadius_yRadius_(+ ((x, y), (width, height)),+ radius,+ radius,+ )+ path.fill()+++def fill_rect(x: float, y: float, width: float, height: float, color) -> None:+ color.set()+ path = NSBezierPath.bezierPathWithRect_(((x, y), (width, height)))+ path.fill()+++def draw_chart_text(text: str, x: float, y: float, width: float, height: float) -> None:+ attrs = {+ NSFontAttributeName: NSFont.systemFontOfSize_(11.0),+ NSForegroundColorAttributeName: chart_color("#676767"),+ }+ NSString.stringWithString_(str(text)).drawInRect_withAttributes_(+ ((x, y), (width, height)),+ attrs,+ )+++def chart_color(hex_color: str, alpha: float = 1.0):+ text = hex_color.strip().lstrip("#")+ if len(text) != 6:+ return NSColor.colorWithCalibratedWhite_alpha_(0.5, alpha)+ red = int(text[0:2], 16) / 255.0+ green = int(text[2:4], 16) / 255.0+ blue = int(text[4:6], 16) / 255.0+ return NSColor.colorWithCalibratedRed_green_blue_alpha_(red, green, blue, alpha)+++def rect_parts(rect) -> tuple[float, float, float, float]:+ return (+ float(rect.origin.x),+ float(rect.origin.y),+ float(rect.size.width),+ float(rect.size.height),+ )++def build_settings_window(target: StatusBarController) -> NSWindow:width = 680height = 560@@ -2364,6 +3227,13 @@ def build_settings_window(target: StatusBarController) -> NSWindow:tab_width,tab_height,)+ history_tab = add_settings_tab(+ tab_view,+ "history",+ "History",+ tab_width,+ tab_height,+ )diagnostics_tab = add_settings_tab(tab_view,"diagnostics",@@ -2471,7 +3341,28 @@ def build_settings_window(target: StatusBarController) -> NSWindow:add_label(behavior_tab, "Idle timeout", 32, 316, 120, 22)idle_minutes = add_editable_field(behavior_tab, "", 224, 314, 58, 24)add_label(behavior_tab, "minutes", 292, 316, 80, 22)- add_button(behavior_tab, "Save", 32, 266, 90, 28, target, "saveAgentListTiming:")+ add_separator(behavior_tab, 24, 272, tab_width - 48)+ add_label(behavior_tab, "Sleep Prevention", 24, 238, 240, 24)+ add_label(behavior_tab, "Let Mac sleep on battery below", 32, 196, 210, 22)+ min_battery_percent = add_editable_field(behavior_tab, "", 260, 194, 58, 24)+ add_label(behavior_tab, "%", 328, 196, 24, 22)+ add_button(behavior_tab, "Save", 32, 112, 90, 28, target, "saveAgentListTiming:")++ add_label(history_tab, "Status History", 24, 398, 240, 24)+ add_label(history_tab, "Timeframe", 430, 398, 76, 22)+ history_timeframe = add_history_timeframe_popup(history_tab, 508, 394, target)+ history_status = add_label(history_tab, "", 32, 360, 588, 22)+ history_chart = StatusHistoryChartView.alloc().initWithFrame_(((24, 86), (612, 250)))+ history_tab.addSubview_(history_chart)+ add_button(history_tab, "Refresh", 32, 42, 90, 28, target, "refreshHistoryChart:")+ add_label(+ history_tab,+ "Rows: agent display, battery %, charger W, SidePulse awake, macOS sleep, lid.",+ 134,+ 46,+ 480,+ 22,+ )add_label(diagnostics_tab, "Debug Log", 24, 398, 240, 24)debug_log_status = add_label(diagnostics_tab, "", 32, 360, 588, 22)@@ -2499,6 +3390,10 @@ def build_settings_window(target: StatusBarController) -> NSWindow:"open_animation_duration": open_duration,"recent_session_retention_hours": retention_hours,"idle_timeout_minutes": idle_minutes,+ "sleep_prevention_min_battery_percent": min_battery_percent,+ "status_history_timeframe": history_timeframe,+ "status_history_status": history_status,+ "status_history_chart": history_chart,"message": message,"settings_path": settings_path,}@@ -2601,6 +3496,19 @@ def add_terminal_popup(parent, x: int, y: int, target):return popup+def add_history_timeframe_popup(parent, x: int, y: int, target):+ popup = NSPopUpButton.alloc().initWithFrame_pullsDown_(+ ((x, y), (112, 26)), False+ )+ popup.setTarget_(target)+ popup.setAction_("setHistoryTimeframe:")+ for seconds in HISTORY_TIMEFRAME_CHOICES:+ popup.addItemWithTitle_(history_timeframe_label(seconds))+ popup.lastItem().setRepresentedObject_(float(seconds))+ parent.addSubview_(popup)+ return popup++def provider_open_actions(provider: str) -> tuple[str, ...]:if provider == "claude":return (SESSION_OPEN_VSCODE, SESSION_OPEN_APP, SESSION_OPEN_TERMINAL)@@ -2657,6 +3565,15 @@ def refresh_terminal_popup(popup, terminal_app: str) -> None:popup.selectItemAtIndex_(index)+def refresh_history_timeframe_popup(popup, selected_seconds: float) -> None:+ for index in range(popup.numberOfItems()):+ item = popup.itemAtIndex_(index)+ value = item.representedObject()+ if isinstance(value, (int, float)) and abs(float(value) - selected_seconds) < 0.5:+ popup.selectItemAtIndex_(index)+ return++def terminal_app_label(terminal_app: str) -> str:return TERMINAL_APP_LABELS.get(normalize_terminal_app(terminal_app), "Terminal")diff --git a/tests/test_sidepulse.py b/tests/test_sidepulse.pyindex c7da148..8981479 100644--- a/tests/test_sidepulse.py+++ b/tests/test_sidepulse.py@@ -15,9 +15,13 @@ from unittest.mock import patchfrom sidepulse.audit import (append_status_audit_record,+ append_status_history_record,+ default_status_history_log_path,export_status_audit_csv,export_status_audit_html,+ read_status_history_records,read_status_audit_records,+ status_history_record,)from sidepulse.battery import (BATTERY_CHARGING_MINT,@@ -66,9 +70,14 @@ from sidepulse.led_status import ()from sidepulse.lid_sleep import (ClosedLidAwakeController,+ IOREG_SLEEP_DISABLED_COMMAND,+ MacSleepSnapshot,+ PMSET_ASSERTIONS_COMMAND,SleepHelperRequiredError,closed_lid_awake_should_hold,parse_bool_ioreg_property,+ parse_pmset_assertions,+ read_mac_sleep_snapshot,run_sudo_pmset_disablesleep,sleep_helper_sudoers_rule,)@@ -107,10 +116,16 @@ from sidepulse.settings import (CLOSED_LID_AWAKE_ALWAYS,CLOSED_LID_AWAKE_NEVER,DEFAULT_IDLE_TIMEOUT_SECONDS,+ DEFAULT_HISTORY_TIMEFRAME_SECONDS,DEFAULT_RECENT_SESSION_RETENTION_SECONDS,+ HISTORY_TIMEFRAME_24H_SECONDS,+ HISTORY_TIMEFRAME_48H_SECONDS,LID_ANIMATION_CLOSED,LID_ANIMATION_OPEN,LED_DISPLAY_CUSTOM,+ SLEEP_PREVENTION_AGENTS,+ SLEEP_PREVENTION_ALWAYS,+ SLEEP_PREVENTION_NEVER,TERMINAL_APP_ALACRITTY,TERMINAL_APP_CUSTOM,TERMINAL_APP_GHOSTTY,@@ -429,6 +444,92 @@ class AgentMonitorTests(unittest.TestCase):self.assertIn("hook_event,status", csv_path.read_text())self.assertIn("SidePulse Agent Debug Log", html_path.read_text())+ def test_status_history_record_includes_charger_power_and_sleep_state(self) -> None:+ record = status_history_record(+ agent_mode=AgentMode.WORKING.value,+ display_status="Working",+ battery=BatterySnapshot(+ percent=57,+ is_charging=True,+ is_plugged=True,+ battery_watts=42.53,+ adapter_connected=True,+ adapter_watts=86,+ adapter_voltage=20.2,+ adapter_current=4.25,+ adapter_name="USB-C Power Adapter",+ adapter_manufacturer="Apple",+ adapter_model="A2166",+ ),+ mac_sleep=MacSleepSnapshot(+ sleep_disabled=False,+ prevent_system_sleep=True,+ prevent_user_idle_system_sleep=False,+ prevent_user_idle_display_sleep=True,+ user_is_active=True,+ ),+ lid_closed=False,+ keep_awake_requested=True,+ keep_awake_active=True,+ sleep_prevention_policy=SLEEP_PREVENTION_AGENTS,+ sleep_prevention_battery_safeguard_active=False,+ sleep_prevention_min_battery_percent=20,+ closed_lid_awake_requested=False,+ closed_lid_awake_active=False,+ recorded_at=datetime(2026, 7, 20, 12, 30, tzinfo=timezone.utc),+ )++ self.assertEqual(record["recorded_at"], "2026-07-20T12:30:00Z")+ self.assertEqual(record["agent_status"], AgentMode.WORKING.value)+ self.assertEqual(record["display_status"], "Working")+ self.assertEqual(record["battery_level"], 57)+ self.assertEqual(record["battery_power_watts"], 42.53)+ self.assertTrue(record["charger_connected"])+ self.assertTrue(record["adapter_connected"])+ self.assertEqual(record["charger_power_watts"], 86.0)+ self.assertEqual(record["adapter_watts"], 86)+ self.assertEqual(record["adapter_voltage"], 20.2)+ self.assertEqual(record["adapter_current"], 4.25)+ self.assertEqual(record["adapter_name"], "USB-C Power Adapter")+ self.assertEqual(record["sleep_prevention_policy"], SLEEP_PREVENTION_AGENTS)+ self.assertFalse(record["sleep_prevention_battery_safeguard_active"])+ self.assertEqual(record["sleep_prevention_min_battery_percent"], 20)+ self.assertEqual(record["mac_sleep_status"], "prevented")+ self.assertTrue(record["mac_sleep_prevented"])+ self.assertEqual(record["lid_status"], "open")++ def test_status_history_log_round_trips_and_uses_xdg_state_dir(self) -> None:+ with tempfile.TemporaryDirectory() as tmp:+ log = Path(tmp) / "status-history.jsonl"+ first = {"recorded_at": "2026-07-20T12:00:00Z", "display_status": "Idle"}+ second = {"recorded_at": "2026-07-20T12:01:00Z", "display_status": "Done"}++ append_status_history_record(first, path=log)+ append_status_history_record(second, path=log)++ self.assertEqual(read_status_history_records(log), [first, second])+ self.assertEqual(read_status_history_records(log, limit=1), [second])+ self.assertEqual(+ default_status_history_log_path(Path("/Users/example")),+ Path("/Users/example")+ / ".local"+ / "state"+ / "sidepulse"+ / "agent-monitor"+ / "status-history.jsonl",+ )++ def test_status_history_log_write_errors_are_visible(self) -> None:+ with tempfile.TemporaryDirectory() as tmp:+ blocking_file = Path(tmp) / "not-a-directory"+ blocking_file.write_text("", encoding="utf-8")++ with self.assertRaises(OSError):+ append_status_history_record(+ {"recorded_at": "2026-07-20T12:00:00Z"},+ path=blocking_file / "status-history.jsonl",+ )+def test_hook_event_server_receives_socket_message(self) -> None:with tempfile.TemporaryDirectory() as tmp:received: list[tuple[str, dict]] = []@@ -1523,7 +1624,7 @@ class AgentMonitorTests(unittest.TestCase):self.assertEqual(fake.settings.display_for_device(device.device_id), LED_DISPLAY_CUSTOM)self.assertEqual(messages[-1], "SidePulse Dot: Manual, LEDs cleared.")- def test_status_bar_menu_has_closed_lid_awake_policy_choices(self) -> None:+ def test_status_bar_menu_has_sleep_prevention_title_and_policy_choices(self) -> None:try:from sidepulse import status_barexcept SystemExit as exc:@@ -1535,25 +1636,50 @@ class AgentMonitorTests(unittest.TestCase):)target = SimpleNamespace(settings=AgentMonitorSettings(- closed_lid_awake_policy=CLOSED_LID_AWAKE_AGENTS,+ sleep_prevention_policy=SLEEP_PREVENTION_AGENTS,),- closed_lid_awake=SimpleNamespace(last_error=None),+ keep_awake=SimpleNamespace(process_running=lambda: True),+ closed_lid_awake=SimpleNamespace(+ last_error=None,+ process_running=lambda: False,+ ),+ last_mac_sleep_snapshot=MacSleepSnapshot(+ sleep_disabled=False,+ prevent_user_idle_system_sleep=True,+ ),+ last_lid_closed=False,+ agent_awake_requested=True,+ battery_sleep_safeguard_active=False,+ battery_sleep_safeguard_reason="battery 87%, threshold 20%",status_bar_devices=lambda: [],)menu = status_bar.build_menu(snapshot, status_bar.STATE_IDLE, target)items = [menu.itemAtIndex_(index) for index in range(menu.numberOfItems())]- by_title = {item.title(): item for item in items if item.title()}- titles = [item.title() for item in items if item.title()]+ titled_items = [item for item in items if item.title()]+ titles = [item.title() for item in titled_items]self.assertLess(titles.index("Agents"), titles.index("Devices"))- self.assertIn("Keep Awake With Lid Closed", by_title)- self.assertEqual(by_title["Never"].state(), 0)- self.assertEqual(by_title["When Agents Work"].state(), 1)- self.assertEqual(by_title["Always"].state(), 0)- self.assertNotIn("Strong Sleep Override...", by_title)- self.assertNotIn("Sleep Helper Missing", by_title)- self.assertIn("Setup...", by_title)+ self.assertIn("Closed-Lid Sleep Prevention", titles)+ self.assertNotIn(+ "Status: caffeinate active, closed-lid support off, disablesleep off, macOS prevented",+ titles,+ )+ self.assertNotIn("Lid: open; agent keep-awake window active", titles)+ self.assertNotIn("Battery safeguard: standby; battery 87%, threshold 20%", titles)+ policy_index = titles.index("Closed-Lid Sleep Prevention")+ policy_items = titled_items[policy_index + 1 : policy_index + 4]++ self.assertEqual(+ [item.title() for item in policy_items],+ ["Never", "When Agents Work", "Always"],+ )+ self.assertEqual([item.state() for item in policy_items], [0, 1, 0])+ self.assertNotIn("Keep Awake With Lid Open", titles)+ self.assertNotIn("Keep Awake With Lid Closed", titles)+ self.assertNotIn("Strong Sleep Override...", titles)+ self.assertNotIn("Sleep Helper Missing", titles)+ self.assertIn("Setup...", titles)def test_lid_animation_program_uses_device_brightness(self) -> None:try:@@ -1616,18 +1742,149 @@ class AgentMonitorTests(unittest.TestCase):if hasattr(view, "numberOfTabViewItems")]self.assertEqual(len(tab_views), 1)- self.assertEqual(tab_views[0].numberOfTabViewItems(), 5)+ self.assertEqual(tab_views[0].numberOfTabViewItems(), 6)self.assertIn("debug_log_status", target.settings_fields)+ self.assertIn("status_history_status", target.settings_fields)+ self.assertIn("status_history_chart", target.settings_fields)self.assertIn("session_terminal", target.settings_fields)self.assertIn("custom_terminal_path", target.settings_fields)self.assertIn("recent_session_retention_hours", target.settings_fields)self.assertIn("idle_timeout_minutes", target.settings_fields)+ self.assertIn("sleep_prevention_min_battery_percent", target.settings_fields)+ self.assertIn("status_history_timeframe", target.settings_fields)self.assertIn("closed_animation_program", target.settings_fields)self.assertIn("closed_animation_duration", target.settings_fields)self.assertIn("open_animation_program", target.settings_fields)self.assertIn("open_animation_duration", target.settings_fields)self.assertNotIn("closed_lid_system_override", target.settings_buttons)+ def test_status_history_status_text_is_compact(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ text = status_bar.status_history_status_text(+ [+ {+ "recorded_at": "2026-07-20T12:30:00Z",+ "battery_level": 76,+ "charger_power_watts": 86,+ }+ ]+ )++ self.assertIn("History: Last 12h", text)+ self.assertIn("1 samples", text)+ self.assertIn("battery 76%", text)+ self.assertIn("charger 86W", text)+ self.assertNotIn("/Users/", text)++ def test_status_history_filters_to_selected_timeframe(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ records = [+ {"recorded_at": "2026-07-20T00:00:00Z", "display_status": "Idle"},+ {"recorded_at": "2026-07-20T11:30:00Z", "display_status": "Working"},+ {"recorded_at": "2026-07-20T12:00:00Z", "display_status": "Done"},+ ]++ filtered = status_bar.filter_status_history_records(records, 60 * 60)++ self.assertEqual(filtered, records[1:])+ self.assertEqual(status_bar.history_timeframe_label(60 * 60), "Last 1h")+ self.assertEqual(+ status_bar.history_timeframe_label(DEFAULT_HISTORY_TIMEFRAME_SECONDS),+ "Last 12h",+ )+ self.assertGreaterEqual(+ status_bar.history_record_limit_for_timeframe(HISTORY_TIMEFRAME_48H_SECONDS),+ 2400,+ )++ def test_status_history_line_segments_scale_metric_values(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ points = [+ (0.0, {"battery_level": 0}),+ (30.0, {"battery_level": 50}),+ (60.0, {"battery_level": 100}),+ ]++ segments = status_bar.history_line_segments(+ points,+ "battery_level",+ 100.0,+ 0.0,+ 60.0,+ 10.0,+ 90.0,+ 20.0,+ 40.0,+ )++ self.assertEqual(+ segments,+ [[(10.0, 20.0), (55.0, 40.0), (100.0, 60.0)]],+ )++ def test_status_history_legend_names_major_colors(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ text = " ".join(+ str(item)+ for row in status_bar.history_legend_rows()+ for item in row+ )++ self.assertIn("Ask", text)+ self.assertIn("Working", text)+ self.assertIn("Battery", text)+ self.assertIn("Charger", text)+ self.assertIn("Lid closed", text)++ def test_status_history_line_segments_split_missing_values(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ points = [+ (0.0, {"charger_power_watts": 0}),+ (30.0, {"charger_power_watts": None}),+ (60.0, {"charger_power_watts": 30}),+ ]++ segments = status_bar.history_line_segments(+ points,+ "charger_power_watts",+ 30.0,+ 0.0,+ 60.0,+ 10.0,+ 90.0,+ 20.0,+ 40.0,+ )++ self.assertEqual(segments, [[(10.0, 20.0)], [(100.0, 60.0)]])+ self.assertEqual(+ status_bar.latest_numeric_history_value(points, "charger_power_watts"),+ 30,+ )+ self.assertEqual(status_bar.nice_history_max([0, 12, 30]), 30.0)+ self.assertEqual(status_bar.nice_history_max([31]), 45.0)+ self.assertEqual(status_bar.nice_history_max([96]), 100.0)+def test_status_bar_monitor_uses_idle_timeout_setting(self) -> None:try:from sidepulse import status_bar@@ -3596,6 +3853,211 @@ class AgentMonitorTests(unittest.TestCase):closed_lid_awake_should_hold(CLOSED_LID_AWAKE_ALWAYS, agents_active=False))+ def test_status_bar_sleep_prevention_never_releases_all_sleep_prevention(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ fake = SimpleNamespace(+ settings=AgentMonitorSettings(+ sleep_prevention_policy=SLEEP_PREVENTION_NEVER,+ ),+ keep_awake=KeepAwakeController(process_factory=lambda *_args, **_kwargs: FakeProcess()),+ closed_lid_awake=ClosedLidAwakeController(+ process_factory=lambda *_args, **_kwargs: FakeProcess()+ ),+ last_keep_awake_error=None,+ last_closed_lid_awake_error=None,+ last_status_read_error=None,+ leds_enabled=False,+ agent_awake_last_mode=None,+ agent_awake_grace_until_monotonic=None,+ agent_awake_requested=False,+ battery_sleep_safeguard_active=False,+ battery_sleep_safeguard_reason="",+ )+ fake.update_agent_awake_request = (+ lambda mode: status_bar.StatusBarController.update_agent_awake_request(fake, mode)+ )+ fake.sync_closed_lid_awake = (+ lambda *, agents_active=None: status_bar.StatusBarController.sync_closed_lid_awake(+ fake,+ agents_active=agents_active,+ )+ )++ with patch("sidepulse.status_bar.sleep_helper_installed", return_value=False):+ status_bar.StatusBarController.sync_keep_awake(fake, AgentMode.WORKING)++ self.assertFalse(fake.keep_awake.process_running())+ self.assertFalse(fake.closed_lid_awake.process_running())+ self.assertTrue(fake.agent_awake_requested)++ def test_status_bar_sleep_prevention_always_holds_caffeinate_while_agents_idle(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ fake = SimpleNamespace(+ settings=AgentMonitorSettings(+ sleep_prevention_policy=SLEEP_PREVENTION_ALWAYS,+ ),+ keep_awake=KeepAwakeController(process_factory=lambda *_args, **_kwargs: FakeProcess()),+ closed_lid_awake=ClosedLidAwakeController(+ process_factory=lambda *_args, **_kwargs: FakeProcess()+ ),+ last_keep_awake_error=None,+ last_closed_lid_awake_error=None,+ last_status_read_error=None,+ leds_enabled=False,+ agent_awake_last_mode=None,+ agent_awake_grace_until_monotonic=None,+ agent_awake_requested=False,+ battery_sleep_safeguard_active=False,+ battery_sleep_safeguard_reason="",+ )+ fake.update_agent_awake_request = (+ lambda mode: status_bar.StatusBarController.update_agent_awake_request(fake, mode)+ )+ fake.sync_closed_lid_awake = (+ lambda *, agents_active=None: status_bar.StatusBarController.sync_closed_lid_awake(+ fake,+ agents_active=agents_active,+ )+ )++ with patch("sidepulse.status_bar.sleep_helper_installed", return_value=False):+ status_bar.StatusBarController.sync_keep_awake(fake, AgentMode.IDLE_READY)++ self.assertTrue(fake.keep_awake.process_running())+ self.assertTrue(fake.closed_lid_awake.process_running())+ self.assertFalse(fake.agent_awake_requested)++ def test_status_bar_sleep_prevention_agents_drives_both_paths(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ fake = SimpleNamespace(+ settings=AgentMonitorSettings(+ sleep_prevention_policy=SLEEP_PREVENTION_AGENTS,+ ),+ keep_awake=KeepAwakeController(process_factory=lambda *_args, **_kwargs: FakeProcess()),+ closed_lid_awake=ClosedLidAwakeController(+ process_factory=lambda *_args, **_kwargs: FakeProcess()+ ),+ last_keep_awake_error=None,+ last_closed_lid_awake_error=None,+ last_status_read_error=None,+ leds_enabled=False,+ agent_awake_last_mode=None,+ agent_awake_grace_until_monotonic=None,+ agent_awake_requested=False,+ battery_sleep_safeguard_active=False,+ battery_sleep_safeguard_reason="",+ )+ fake.update_agent_awake_request = (+ lambda mode: status_bar.StatusBarController.update_agent_awake_request(fake, mode)+ )+ fake.sync_closed_lid_awake = (+ lambda *, agents_active=None: status_bar.StatusBarController.sync_closed_lid_awake(+ fake,+ agents_active=agents_active,+ )+ )++ with patch("sidepulse.status_bar.sleep_helper_installed", return_value=False):+ status_bar.StatusBarController.sync_keep_awake(fake, AgentMode.WORKING)++ self.assertTrue(fake.keep_awake.process_running())+ self.assertTrue(fake.closed_lid_awake.process_running())++ fake.agent_awake_grace_until_monotonic = None+ with patch("sidepulse.status_bar.sleep_helper_installed", return_value=False):+ status_bar.StatusBarController.sync_keep_awake(fake, AgentMode.IDLE_READY)++ self.assertFalse(fake.keep_awake.process_running())+ self.assertFalse(fake.closed_lid_awake.process_running())++ def test_sleep_prevention_battery_safeguard_activates_only_on_battery(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ active, reason = status_bar.sleep_prevention_battery_safeguard(+ BatterySnapshot(percent=19, is_plugged=False),+ 20,+ )+ plugged_active, plugged_reason = status_bar.sleep_prevention_battery_safeguard(+ BatterySnapshot(percent=19, is_plugged=True),+ 20,+ )+ disabled_active, disabled_reason = status_bar.sleep_prevention_battery_safeguard(+ BatterySnapshot(percent=5, is_plugged=False),+ 0,+ )++ self.assertTrue(active)+ self.assertEqual(reason, "battery 19%, threshold 20%")+ self.assertFalse(plugged_active)+ self.assertEqual(plugged_reason, "battery 19%, plugged in, threshold 20%")+ self.assertFalse(disabled_active)+ self.assertEqual(disabled_reason, "disabled")++ def test_status_bar_battery_safeguard_releases_all_sleep_prevention(self) -> None:+ try:+ from sidepulse import status_bar+ except SystemExit as exc:+ self.skipTest(str(exc))++ fake = SimpleNamespace(+ settings=AgentMonitorSettings(+ sleep_prevention_policy=SLEEP_PREVENTION_ALWAYS,+ sleep_prevention_min_battery_percent=20,+ ),+ keep_awake=KeepAwakeController(process_factory=lambda *_args, **_kwargs: FakeProcess()),+ closed_lid_awake=ClosedLidAwakeController(+ process_factory=lambda *_args, **_kwargs: FakeProcess()+ ),+ last_keep_awake_error=None,+ last_closed_lid_awake_error=None,+ last_status_read_error=None,+ leds_enabled=False,+ agent_awake_last_mode=None,+ agent_awake_grace_until_monotonic=None,+ agent_awake_requested=False,+ battery_sleep_safeguard_active=False,+ battery_sleep_safeguard_reason="",+ )+ fake.update_agent_awake_request = (+ lambda mode: status_bar.StatusBarController.update_agent_awake_request(fake, mode)+ )+ fake.sync_closed_lid_awake = (+ lambda *, agents_active=None: status_bar.StatusBarController.sync_closed_lid_awake(+ fake,+ agents_active=agents_active,+ )+ )++ with patch("sidepulse.status_bar.sleep_helper_installed", return_value=False):+ status_bar.StatusBarController.sync_keep_awake(+ fake,+ AgentMode.WORKING,+ BatterySnapshot(percent=19, is_plugged=False),+ )++ self.assertFalse(fake.keep_awake.process_running())+ self.assertFalse(fake.closed_lid_awake.process_running())+ self.assertTrue(fake.battery_sleep_safeguard_active)+ self.assertEqual(+ fake.battery_sleep_safeguard_reason,+ "battery 19%, threshold 20%",+ )+def test_closed_lid_awake_controller_sets_and_restores_system_disable(self) -> None:processes: list[FakeProcess] = []disabled_calls: list[bool] = []@@ -3644,7 +4106,7 @@ class AgentMonitorTests(unittest.TestCase):self.assertTrue(controller.process_running())self.assertFalse(controller.changed_system_disable)- def test_closed_lid_awake_controller_preserves_existing_system_disable(self) -> None:+ def test_closed_lid_awake_controller_drives_existing_system_disable(self) -> None:disabled_calls: list[bool] = []controller = ClosedLidAwakeController(process_factory=lambda *_args, **_kwargs: FakeProcess(),@@ -3656,7 +4118,25 @@ class AgentMonitorTests(unittest.TestCase):controller.update(CLOSED_LID_AWAKE_ALWAYS, agents_active=False)controller.update(CLOSED_LID_AWAKE_NEVER, agents_active=False)- self.assertEqual(disabled_calls, [])+ self.assertEqual(disabled_calls, [True, False])++ def test_closed_lid_awake_controller_clears_system_disable_once_when_idle(self) -> None:+ disabled_calls: list[bool] = []+ controller = ClosedLidAwakeController(+ process_factory=lambda *_args, **_kwargs: FakeProcess(),+ sleep_disabled_reader=lambda: True,+ sleep_disabled_setter=disabled_calls.append,+ use_system_disable=True,+ )++ self.assertFalse(+ controller.update(CLOSED_LID_AWAKE_NEVER, agents_active=False)+ )+ self.assertFalse(+ controller.update(CLOSED_LID_AWAKE_NEVER, agents_active=False)+ )++ self.assertEqual(disabled_calls, [False])def test_sleep_override_uses_noninteractive_sudo(self) -> None:calls = []@@ -3711,6 +4191,60 @@ class AgentMonitorTests(unittest.TestCase):self.assertTrue(parse_bool_ioreg_property('"SleepDisabled" = true', "SleepDisabled"))self.assertIsNone(parse_bool_ioreg_property('"Other" = Yes', "SleepDisabled"))+ def test_pmset_assertion_parser_reads_sleep_prevention(self) -> None:+ assertions = parse_pmset_assertions(+ """+ Assertion status system-wide:+ PreventUserIdleDisplaySleep 1+ PreventSystemSleep 0+ PreventUserIdleSystemSleep 1+ UserIsActive 1+ """+ )++ self.assertTrue(assertions["PreventUserIdleDisplaySleep"])+ self.assertFalse(assertions["PreventSystemSleep"])+ self.assertTrue(assertions["PreventUserIdleSystemSleep"])+ self.assertTrue(assertions["UserIsActive"])++ def test_read_mac_sleep_snapshot_reads_sleep_disabled_from_ioreg(self) -> None:+ commands: list[tuple[str, ...]] = []++ def runner(command, **_kwargs):+ commands.append(tuple(command))+ if "ioreg" in command[0]:+ return subprocess.CompletedProcess(+ command,+ 0,+ '"SleepDisabled" = No\n',+ "",+ )+ return subprocess.CompletedProcess(+ command,+ 0,+ """+ PreventSystemSleep 0+ PreventUserIdleSystemSleep 1+ PreventUserIdleDisplaySleep 0+ UserIsActive 1+ """,+ "",+ )++ snapshot = read_mac_sleep_snapshot(runner=runner)++ self.assertFalse(snapshot.sleep_disabled)+ self.assertFalse(snapshot.prevent_system_sleep)+ self.assertTrue(snapshot.prevent_user_idle_system_sleep)+ self.assertFalse(snapshot.prevent_user_idle_display_sleep)+ self.assertTrue(snapshot.user_is_active)+ self.assertTrue(snapshot.sleep_prevented)+ self.assertIsNone(snapshot.error)+ self.assertEqual(commands[0], IOREG_SLEEP_DISABLED_COMMAND)+ self.assertEqual(commands[1], PMSET_ASSERTIONS_COMMAND)+ self.assertNotIn(("/usr/bin/pmset", "-g"), commands)+ self.assertNotIn(("/usr/bin/pmset", "-g", "custom"), commands)+def test_default_logs_use_sidepulse_xdg_state_dir(self) -> None:home = Path("/Users/example")@@ -3942,12 +4476,14 @@ class AgentMonitorTests(unittest.TestCase):self.assertEqual(loaded.session_terminal_app, TERMINAL_APP_ITERM)self.assertNotIn("grok", loaded.session_open_preferences)- def test_settings_round_trip_closed_lid_policy_and_animations(self) -> None:+ def test_settings_round_trip_sleep_prevention_policy_and_animations(self) -> None:with tempfile.TemporaryDirectory() as tmp:settings_path = Path(tmp) / "settings.json"- settings = AgentMonitorSettings().with_closed_lid_awake_policy(- CLOSED_LID_AWAKE_AGENTS+ settings = AgentMonitorSettings().with_sleep_prevention_policy(+ SLEEP_PREVENTION_ALWAYS)+ settings = settings.with_sleep_prevention_battery_safeguard(25)+ settings = settings.with_history_timeframe(HISTORY_TIMEFRAME_24H_SECONDS)settings = settings.with_lid_animation(LID_ANIMATION_CLOSED,program="off\n#FF3A00 200ms ease",@@ -3962,7 +4498,9 @@ class AgentMonitorTests(unittest.TestCase):save_settings(settings, settings_path)loaded = load_settings(settings_path)- self.assertEqual(loaded.closed_lid_awake_policy, CLOSED_LID_AWAKE_AGENTS)+ self.assertEqual(loaded.sleep_prevention_policy, SLEEP_PREVENTION_ALWAYS)+ self.assertEqual(loaded.sleep_prevention_min_battery_percent, 25)+ self.assertEqual(loaded.history_timeframe_seconds, HISTORY_TIMEFRAME_24H_SECONDS)self.assertEqual(loaded.lid_animation(LID_ANIMATION_CLOSED).program,"off\n#FF3A00 200ms ease",@@ -3989,7 +4527,9 @@ class AgentMonitorTests(unittest.TestCase):loaded = load_settings(settings_path)- self.assertEqual(loaded.closed_lid_awake_policy, CLOSED_LID_AWAKE_NEVER)+ self.assertEqual(loaded.sleep_prevention_policy, SLEEP_PREVENTION_AGENTS)+ self.assertEqual(loaded.sleep_prevention_min_battery_percent, 20)+ self.assertEqual(loaded.history_timeframe_seconds, DEFAULT_HISTORY_TIMEFRAME_SECONDS)self.assertFalse(loaded.closed_lid_system_override_enabled)self.assertFalse(loaded.setup_screen_completed)self.assertEqual(