v2.3.0 - Zombie Overhaul, Power Supply Detection & Smarter Scoring

Hey there! Thanks for using HAGHS, i really appreciate it 👍
☕ Do you enjoy it? If you've ever gotten value from HAGHS, buying me a coffee is the nicest way to say so ❤️ buy me a coffee, it keeps the project and me going 😉 Thank you!

---

What's New

Power Supply Detection

HAGHS now auto-detects under-voltage conditions on Raspberry Pi devices. If your power supply is unstable, a 20-point penalty is applied to the hardware score. No configuration needed — the check is skipped on non-RPi hardware.

Smarter Zombie Detection

• 22 domains monitored (up from 9) — covers climate, cover, camera, lock, media_player, vacuum and more
• Configurable grace periods — zombie grace (default 5 min) and battery grace (default 60 min) adjustable in Options Flow
• Per-domain breakdown — new zombie_count_per_domain attribute shows exactly where zombies live
• Disabled entities auto-ignored — no label needed, just disable the entity in HA
• Ghost zombies surfaced — entities without a registry entry are now marked [unregistered] so you can find them
• Hard cap at 99 — score 100 is only possible with zero detected issues

Easier Setup

• haghs_ignore label auto-created and pre-selected during setup
• CPU/RAM sensors optional on systems with PSI — no System Monitor setup needed on Linux-based HA installations
• Multiple ignore labels — assign vacation, guest_mode or any label and toggle exclusions at runtime via label.assign / label.remove
• Pattern-based ignore — use glob patterns to exclude entities without a unique ID (e.g. from monitor_docker)
• Repairs flow — if PSI becomes unavailable after setup (e.g. Docker host change), HAGHS guides you through adding fallback sensors via the Repairs UI

Fairer Scoring

• 7-day update grace period — pending updates only count toward the penalty after 7 days
• Restart grace — entities restored from the recorder database no longer bypass the grace period after a HA restart
• Denominator fix — zombie ratio is no longer diluted by automations, scripts and helpers

Better Advisor

• PSI-aware text — advisor messages now distinguish between PSI stall time and classic CPU/RAM utilization
• Config Audit tips — dashboard cards show which bonus points you can still earn
• 10 boolean rec_* flags — stable attributes for automations and custom dashboard cards

Migration

Existing installations are migrated automatically. Users who encountered "Migration handler not found" after upgrading from v2.1.x (#75) will be fixed by this release.

---

Score Impact

Most users will see a small increase (fewer noisy update penalties, disabled entities no longer counted). Instances with previously unnoticed zombies in the newly monitored domains may see a small drop. The in-card Tips block explains exactly which factors are active.

Breaking Changes

None. All existing attributes and sensor behavior are preserved. New attributes and features are additive.

License

Changed from MIT to Apache 2.0.

Full Changelog

See v2.3_CHANGELOG.md for the complete list of changes including file-level details.

Thanks

This release wouldn't have been possible without:

• @banister4728
• @claude
• @gustavakerstrom

v2.2.2 - External Database Support

The Problem:
When v2.2.0 introduced zero-config auto-detection, the database scoring was hardcoded to measure the built-in SQLite file. Users running external databases (MariaDB, PostgreSQL) lost the ability to feed their database size into the health score, an oversight from the migration.

The Fix:
HAGHS now offers an optional Database Size Sensor field in both the Setup and Options flow. If you run an external database, simply point HAGHS to a sensor that reports your DB size in MB, the rest works exactly like before.
What changed

New: Optional "Database size sensor" field in Setup and Options UI
Behavior: When a sensor is configured, HAGHS reads its value (in MB) instead of measuring the local SQLite file. When left empty, the default SQLite auto-detection remains active, no change for existing users.
Migration: None required. Existing installations are completely unaffected by this update.

How to use (external DB users only)

• Create a sensor that reports your database size in MB (e.g., via the SQL integration)
• Go to Settings → Integrations → HAGHS → Configure
• Select your sensor in the "Database size sensor (optional)" field
• Save, changes apply immediately

Technical details

• Only _async_get_db_size_mb() was modified, the penalty calculation, thresholds, and dynamic limit formula are unchanged
• The field uses vol.Optional with no default, old config entries without the key automatically fall back to SQLite detection
• No ConfigFlow.VERSION bump needed (purely additive, no schema migration)

v2.2.1 - Patch

Bugfix: Fixed absurd percentage values in hardware recommendations (e.g. "Memory pressure is impacting score (5698.1%)") when a
manually configured CPU or RAM sensor reports absolute values (MB, MHz) instead of percent.

Root cause: On systems without PSI support, HAGHS falls back to the user-configured sensors. If a sensor like sensor.memory_use
(reporting MB) was selected instead of sensor.memory_use_percent, the raw value was passed directly into both the penalty calculation
and the recommendation display, resulting in wildly inflated percentages and maximum penalties.

What changed:

• CPU and RAM classic sensor values are now clamped to a 0–100 range
• A WARNING log entry is written when an out-of-range value is detected, guiding the user to select the correct sensor

User action: If you see the warning in your HA logs, go to Settings → Integrations → HAGHS → Configure and ensure your RAM/CPU sensors report percent (e.g. sensor.memory_use_percent, not sensor.memory_use).

v2.2.0 - Async Architecture, PSI Integration & More

Architecture

• Full async migration to DataUpdateCoordinator, no more blocking calls on the HA event loop.
• Safety-net timeouts on every pillar calculation. If a sub-calculation fails or times out, HAGHS falls back to a neutral score (100 /
  no penalty) and logs a warning. The sensor never crashes.

Hardware Pillar (40%)

• PSI Integration: HAGHS now reads Linux Pressure Stall Information (/proc/pressure/cpu, /proc/pressure/memory, /proc/pressure/io) for
  high-precision hardware metrics. Automatic fallback to classic CPU/RAM sensors if PSI is unavailable (Windows, older Docker, non-Linux).
• Separate penalty tiers for PSI (stall time) vs. classic sensors (utilization), because their scales differ fundamentally.
• I/O Scoring: PSI I/O pressure is now actively scored. When available, the hardware pillar uses 4 components (CPU + RAM + I/O + Disk)
  instead of 3.
• CPU Threshold Adjustment: Classic CPU penalty now starts at >25% (was >10%) to avoid penalizing normal system activity.
• Smart Disk Thresholds: Storage-type-aware penalties, SD-Card/eMMC uses absolute GB (critical <3 GB, warning <5 GB), SSD uses
  percentage-based (<10% free).
• Auto-detected disk usage via psutil, no manual disk sensor needed.

Application Pillar (60%)

• Dynamic Database Limit: DB threshold scales with your entity count (1000 + entities × 2.5 MB). Auto-detected via SQLite file size, no
  manual FileSize sensor or YAML allowlist needed.
• Zombie Improvements: Ratio-based penalties (max 20 pts), 15-minute grace period to prevent false positives during reboots, attribute
  list capped at 20 entries to protect the state machine.
• Update Improvements: Ignore label (haghs_ignore) works on update entities. Core lag threshold raised to ≥3 months. Pending updates
  listed by name in attributes. 5 pts per pending update + 20 pts core lag, capped at 35 pts total.
• Integration Health: Native detection of unhealthy integrations via HA's ConfigEntry state API (SETUP_ERROR, SETUP_RETRY,
  FAILED_UNLOAD), the same states shown as "error" on the Integrations page. 5 pts per unhealthy integration, capped at 15 pts.
• Config Audit Bonus: Awards up to +10 points for good recorder hygiene, purge days configured (+5) and entity filters active (+5).
• Backup penalty: Static 30 pts deduction for stale backups.

Configuration & UX

• Zero-YAML: Database size and disk usage are now fully auto-detected. No configuration.yaml changes needed.
• Options Flow: All settings (CPU/RAM sensors, storage type, ignore label, update interval) adjustable at runtime via Settings >
  Integrations > HAGHS > Configure. No restart required.
• Configurable Update Interval: Adjustable from 10s to 3600s (default: 60s).
• i18n Ready: All user-facing strings externalized to strings.json / translations/en.json.

Removed

• Log file monitoring (deprecated since v2.0.2).

v2.1.2 Maintenance Release

v2.1.2 - Documentation Fix & HACS Preparation
This maintenance release ensures that the documentation and versioning are perfectly aligned as we prepare for the official HACS store inclusion.

What's New?
HACS README Sync: Fixed an issue where the HACS store was showing outdated documentation. The latest instructions and project goals are now correctly displayed.

Manifest Alignment: Version bumped to 2.1.2 in manifest.json to ensure seamless update tracking within Home Assistant.

Branding Preparation: Finalized the internal metadata structure to support the upcoming branding merge from the home-assistant/brands repository.

Under the Hood
Improved repository health by cleaning up metadata.

Pre-checks for the upcoming v2.2 logic (Zombie-Ratio and Core-Integrations monitoring).

Note for Power Users: If you are testing via a custom repository in HACS, please use the "Update Information" button to see the latest README changes immediately.

v2.1.1 - Initial HACS Release

This is the initial HACS release 2. The code remains the same to v2.0.2.

v2.0.2 HAOS Compatibility Hotfix

This release addresses a configuration error for Home Assistant OS users regarding Log File monitoring.

• Fixed: Removed the deprecated logger configuration from the documentation which caused validation errors ("invalid option 'filename'") on newer Home Assistant versions.
• Changed: Log File Hygiene is now optional. The system utilizes "graceful degradation": if you are on HAOS and do not want to enable file logging via CLI, HAGHS will simply skip this check (0 penalty) and focus on Database Hygiene.
• Doc Update: Clarified Prerequisites to explicitly separate essential (System Monitor, Database) from advanced/optional (Log File) sensors.

v2.0.0: The Hygiene Standard – Database, Logs & Deep Labeling

v2.0.0 marks a significant architectural shift for HAGHS. This release transforms the score from a passive health monitor into an active system hygiene administrator. It introduces deep monitoring for database bloating and log file flooding—the two most common causes of system instability—while simplifying configuration through native Home Assistant Labels.

New Features

• Database Hygiene Monitoring: Now monitors the size of 'home-assistant_v2.db'. Penalties apply for databases exceeding 1GB (Warning) and 2.5GB (Critical).
• Log File Hygiene: Now monitors 'home-assistant.log'. Penalties apply for logs exceeding 20MB, helping identify silent error loops and I/O stress.
• Deep Label Support (haghs_ignore): Removed hardcoded regex filters. You can now simply assign the 'haghs_ignore' label to any Device or Entity. HAGHS effectively "whitelists" all entities belonging to a labeled device automatically.
• Core Age Penalty: Introduced a specific penalty for systems where the Core version lags behind by 2 months or more.
• Cumulative Updates: Pending updates are now counted cumulatively (capped at 35 points) rather than a flat penalty.

Critical Prerequisites (Breaking Change)

To utilize the new Database and Log monitoring, you must allow Home Assistant to read its own configuration directory.

1. Add this to your 'configuration.yaml' and restart Home Assistant:

   homeassistant:
     allowlist_external_dirs:
       - "/config"

2. Add the File Size integration (via Settings > Devices & Services) and track:
   • '/config/home-assistant_v2.db'
   • '/config/home-assistant.log'

How to Update

1. Copy the new code from 'haghs.yaml'.
2. Update the 'variables' section with your entity IDs (especially the new 'db_size_id' and 'log_size_id').
3. Create a label named 'haghs_ignore' in Home Assistant and tag your sleeping devices (e.g., tablets, battery sensors).

The "Precision" Update

🛡️ HAGHS v1.3.0 – The "Precision" Update

This is a major architectural milestone. v1.3.0 moves HAGHS from a "feeling-based" gauge to a high-precision instrument.

💎 Key Changes

• One-Point Configuration: You no longer need to hunt for entity IDs. Set them once in the variables: block at the top, and the state, attributes, and advisor will update automatically.
• Heavyweight CPU Tiers: A "Perfect 100" is now a true achievement. CPU load over 10% now carries significant weight, encouraging users to hunt down rogue background tasks.
• The "Honest" Integer: We removed decimal rounding. If your system is 99.9% healthy, HAGHS will show 99. We believe a 100 should be earned.
• Integration Health: HAGHS now monitors integration status sensors and penalizes the score if your core integrations are struggling.

📋 Formula Refinement

$$Score_{Global} = \text{int}(Hardware \cdot 0.4 + App \cdot 0.6)$$

Full implementation details available in haghs.yaml.

HAGHS Technical Specification & PoC

🛡️ HAGHS v1.1.0 - The Foundation

This is the initial release of the Home Assistant Global Health Score (HAGHS). This project establishes a logical framework for measuring system stability through a weighted 0-100 index.

💎 Key Features

• The 40/60 Logic: A balanced weighting system that prioritizes long-term software maintenance over transient hardware spikes.
• Self-Healing Advisor: A built-in recommendation engine that provides actionable repair steps via sensor attributes.
• Standardized Naming: Full compliance with the Area: Object - Function naming convention for a clean entity registry.
• Fair-Play Engine: Intelligent filtering for "Zombie" entities to prevent false negatives on intentional sleepers (e.g., battery-powered trackers).

🛠️ Reference Implementation

Included in this release is the haghs.yaml reference code. This Proof of Concept (PoC) uses the native Home Assistant Template engine to demonstrate the HAGHS calculation logic.

📋 Technical Abstract

The score is derived from two primary pillars:

1. Hardware Integrity (40%): CPU, Memory, and Disk analysis with non-linear penalty curves.
2. System Hygiene (60%): Maintenance debt tracking including Entity states, Backups, and Updates.

---

Architectural Note: This release serves as a functional specification for the ongoing proposal to integrate HAGHS logic natively into the Home Assistant Core.