feat: add snapshot delete + fix backup progress heartbeats (#1861) (#1881)

* feat: add snapshot delete + fix backup progress heartbeats (#1861)

- ha_manage_backup(scope='snapshot', action='create'/'restore') now emits
  MCP progress heartbeats during the wait so clients don't idle-abort a
  long-running backup; raised the internal poll ceiling 300s -> 1800s
  (HA's own frontend imposes no timeout at all on backup creation)
- New (scope='snapshot', action='delete') action, off by default via
  enable_snapshot_delete, layered with guards even when enabled: requires
  confirm=True, never deletes scheduled/automatic backups, enforces a
  snapshot_delete_min_age_days floor (default 7, an HA-stamped date an
  agent can't forge), and never deletes the single newest snapshot
  remaining
- Wires the two new settings through both HA add-on flavors
  (config.yaml + start.py) and the web settings UI
- Unit + e2e coverage, including a real create->delete->verify-gone
  round trip against a live HA test instance

* fix: add missing translations for the two new backup settings

CI caught it: test_translations_cover_every_schema_key requires every
config.yaml schema key to have a matching translations/en.yaml entry.
enable_snapshot_delete and snapshot_delete_min_age_days were wired into
config.yaml + start.py but the translations file was missed, in both
add-on flavors.

* fix: guard against a null result key in backup/info + backup/delete responses

Gemini Code Assist review: info_result.get("result", {}) and
delete_result.get("result", {}) only substitute the default when the key
is ABSENT, not when it's present with value None — a well-formed-but-null
"result" would raise AttributeError on the following .get() call. Switch
to the (x.get("result") or {}) pattern already used elsewhere in this
file (_build_success_response_if_found, _poll_backup_completion).

* fix: wire enable_snapshot_delete through the embedded/HAOS e2e backends

The container-embedded (E2E_BACKEND=embedded) and HAOS embedded/inaddon
backends run ha-mcp inside the HA instance itself, in a separate process
from pytest — os.environ[...] set in the pytest process, and
monkeypatch.setenv + _reset_global_settings(), never reach it. Both need
their own delivery mechanism:

- container-embedded: seed backup_settings.json (BACKUP_OVERRIDE_FIELDS)
  in the embedded server's data dir, alongside the existing
  feature_flags.json (FEATURE_FLAG_FIELDS) — two different override
  files since ha_mcp.config reads the two registries separately.
- HAOS embedded/inaddon (qcow2): generalize
  stage_embedded_server_feature_flags_in_qcow2 to take a filename, and
  call it a second time for backup_settings.json.

Also skip the age-floor-disabled success-path e2e test under all three
out-of-process backends — the guard-rejection tests already exercise the
real delete path end-to-end there; only the "actually completes"
happy-path needs live settings mutation from the test process.

* fix: three codex-review gaps in snapshot delete

- Refuse deletion when backup/info reports agent_errors: an unreachable
  agent means the backups list may be incomplete, so the newest-snapshot
  and scheduled-backup guards can't be trusted.
- min_age_days=0 now unconditionally skips the age comparison instead of
  relying on the arithmetic reduction, which broke under clock skew
  between the ha-mcp host and the HA instance that stamped the date.
- backup/delete now passes an elevated _wait_timeout (60s vs the 30s
  client default): it fans out to every configured agent server-side,
  including slow/rate-limited remote ones, before responding.

* fix: skip TestSnapshotDelete on the HAOS inaddon e2e tier

The inaddon tier runs the real dev add-on against its own
Supervisor-managed options.json (config.yaml's shipped
enable_snapshot_delete=false default) — unlike container-embedded /
HAOS-embedded, which get the setting via a seeded backup_settings.json
override file, there is no in-process server here to seed a file for
(overriding would mean POSTing to the real Supervisor options API).

Mirrors the existing skip precedent in
tests/src/e2e/policy/test_readonly_mode.py for settings that can't be
forced under this tier.

* fix: address kingpanther13 review on snapshot delete

- Fail closed when with_automatic_settings is None, not just True
- Pin newest-before-age-floor evaluation order with a regression test
- Wire ctx heartbeat into delete_backup's WS wait
- Pin heartbeat throttle behavior with a regression test
- Fix docstring/comment ordering-accuracy nits

Author: sergeykad

homeassistant-addon-dev/config.yaml

@@ -57,6 +57,12 @@ options:
   enable_auto_backup: true
   auto_backup_throttle_minutes: 0
   auto_backup_retain_per_entity: 100
+  # Off by default (#1861) — an agent deleting a full HA snapshot is
+  # categorically riskier than the lightweight edits-scope auto-backups
+  # above (a snapshot may be the last recovery point after the agent
+  # itself broke something). A human opts in here, not the agent.
+  enable_snapshot_delete: false
+  snapshot_delete_min_age_days: 7
   tool_search_max_results: 5
   disabled_tools: ""
   pinned_tools: ""
@@ -82,6 +88,8 @@ schema:
   enable_auto_backup: bool?
   auto_backup_throttle_minutes: int(0,1440)?
   auto_backup_retain_per_entity: int(1,10000)?
+  enable_snapshot_delete: bool?
+  snapshot_delete_min_age_days: int(0,365)?
   tool_search_max_results: int(2,10)?
   disabled_tools: str?
   pinned_tools: str?

homeassistant-addon-dev/translations/en.yaml

@@ -156,6 +156,21 @@ configuration:
       Maximum number of snapshots kept per entity. Older snapshots beyond
       this cap are rotated out on each successful capture. Default 100,
       range 1–10000.
+  enable_snapshot_delete:
+    name: Allow snapshot deletion
+    description: >-
+      Lets ha_manage_backup delete full HA snapshot tarballs
+      (scope='snapshot', action='delete'). Off by default — a snapshot may
+      be the last recovery point after a mistaken change, so a human must
+      opt in here. Even when on, scheduled backups, the newest remaining
+      snapshot, and anything younger than the age floor below stay
+      protected.
+  snapshot_delete_min_age_days:
+    name: Minimum snapshot age to delete (days)
+    description: >-
+      A snapshot must be at least this old before it can be deleted. Range
+      0–365; 0 disables the floor (the newest-snapshot and
+      scheduled-backup protections still apply). Default 7.
   enable_lite_docstrings:
     name: Enable lite tool docstrings (beta)
     description: >-

homeassistant-addon/config.yaml

@@ -55,6 +55,12 @@ options:
   enable_auto_backup: true
   auto_backup_throttle_minutes: 0
   auto_backup_retain_per_entity: 100
+  # Off by default (#1861) — an agent deleting a full HA snapshot is
+  # categorically riskier than the lightweight edits-scope auto-backups
+  # above (a snapshot may be the last recovery point after the agent
+  # itself broke something). A human opts in here, not the agent.
+  enable_snapshot_delete: false
+  snapshot_delete_min_age_days: 7
   verify_ssl: true
 schema:
   backup_hint: list(strong|normal|weak|auto)
@@ -70,6 +76,8 @@ schema:
   enable_auto_backup: bool?
   auto_backup_throttle_minutes: int(0,1440)?
   auto_backup_retain_per_entity: int(1,10000)?
+  enable_snapshot_delete: bool?
+  snapshot_delete_min_age_days: int(0,365)?
   verify_ssl: bool?
 # Add-on exposes HTTP port for MCP communication (fixed internal port)
 ports:

homeassistant-addon/start.py

@@ -383,6 +383,11 @@ def main() -> int:
     )
     auto_backup_throttle_minutes = 0  # default — every write
     auto_backup_retain_per_entity = 100  # default
+    # Off by default (#1861 — a snapshot may be the last recovery point
+    # after the agent itself broke something; a human opts in, not the
+    # agent).
+    enable_snapshot_delete = False  # default
+    snapshot_delete_min_age_days = 7  # default
     tool_search_max_results = 5  # default
     disabled_tools_raw = ""  # default
     pinned_tools_raw = ""  # default
@@ -518,6 +523,14 @@ def main() -> int:
             auto_backup_retain_per_entity = (
                 raw_retain if isinstance(raw_retain, int) else 100
             )
+            raw_snapshot_delete = config.get("enable_snapshot_delete", False)
+            enable_snapshot_delete = (
+                raw_snapshot_delete if isinstance(raw_snapshot_delete, bool) else False
+            )
+            raw_min_age = config.get("snapshot_delete_min_age_days", 7)
+            snapshot_delete_min_age_days = (
+                raw_min_age if isinstance(raw_min_age, int) else 7
+            )
             raw_max_results = config.get("tool_search_max_results", 5)
             tool_search_max_results = (
                 raw_max_results if isinstance(raw_max_results, int) else 5
@@ -675,6 +688,8 @@ def main() -> int:
     os.environ["ENABLE_AUTO_BACKUP"] = str(enable_auto_backup).lower()
     os.environ["AUTO_BACKUP_THROTTLE_MINUTES"] = str(auto_backup_throttle_minutes)
     os.environ["AUTO_BACKUP_RETAIN_PER_ENTITY"] = str(auto_backup_retain_per_entity)
+    os.environ["ENABLE_SNAPSHOT_DELETE"] = str(enable_snapshot_delete).lower()
+    os.environ["SNAPSHOT_DELETE_MIN_AGE_DAYS"] = str(snapshot_delete_min_age_days)
     # Persist saved custom tools across addon restarts. /data is the
     # per-addon writable directory mapped by Supervisor and survives
     # add-on updates (but not uninstall/reinstall — users should copy

homeassistant-addon/translations/en.yaml

@@ -100,6 +100,21 @@ configuration:
       Maximum number of snapshots kept per entity. Older snapshots beyond
       this cap are rotated out on each successful capture. Default 100,
       range 1–10000.
+  enable_snapshot_delete:
+    name: Allow snapshot deletion
+    description: >-
+      Lets ha_manage_backup delete full HA snapshot tarballs
+      (scope='snapshot', action='delete'). Off by default — a snapshot may
+      be the last recovery point after a mistaken change, so a human must
+      opt in here. Even when on, scheduled backups, the newest remaining
+      snapshot, and anything younger than the age floor below stay
+      protected.
+  snapshot_delete_min_age_days:
+    name: Minimum snapshot age to delete (days)
+    description: >-
+      A snapshot must be at least this old before it can be deleted. Range
+      0–365; 0 disables the floor (the newest-snapshot and
+      scheduled-backup protections still apply). Default 7.
   verify_ssl:
     name: Verify TLS certificate
     description: >-

src/ha_mcp/config.py

@@ -347,6 +347,26 @@ class Settings(BaseSettings):
         7, ge=1, le=365, alias="HAMCP_AUTO_BACKUP_CALENDAR_LOOKAHEAD_DAYS"
     )
 
+    # Snapshot-tarball deletion gate (#1861). Off by default: an agent
+    # deleting a full HA snapshot is categorically riskier than the
+    # lightweight `edits`-scope auto-backups (which already delete freely),
+    # since a snapshot may be the last recovery point after the agent
+    # itself broke something. A human must opt in via env var, the web
+    # settings UI override file, or (in the add-on) the Supervisor options
+    # — never something the agent can flip on itself.
+    enable_snapshot_delete: bool = Field(False, alias="ENABLE_SNAPSHOT_DELETE")
+
+    # Minimum age (days) a snapshot must have before it's deletable. This is
+    # the load-bearing guard, not `enable_snapshot_delete`: a count-based
+    # "keep the last N" rule is defeatable by an agent flooding new
+    # snapshots before deleting old ones, but it cannot forge a backup's
+    # HA-stamped creation date. 0 disables the age floor (still gated by
+    # enable_snapshot_delete + the newest-snapshot / automatic-backup
+    # guards enforced in tools/backup.py).
+    snapshot_delete_min_age_days: int = Field(
+        7, ge=0, le=365, alias="SNAPSHOT_DELETE_MIN_AGE_DAYS"
+    )
+
     # Mirror the legacy ``os.getenv("FLAG", "").lower() in ("true", ...)``
     # semantics for the ex-direct-getenv ``enable_filesystem_tools`` flag (and
     # its sibling toggles listed above): an empty env var value MUST be treated
@@ -1486,6 +1506,10 @@ def _reset_embedded_connection() -> None:
         "HAMCP_AUTO_BACKUP_CALENDAR_LOOKAHEAD_DAYS",
         int,
     ),
+    BackupOverrideField("enable_snapshot_delete", "ENABLE_SNAPSHOT_DELETE", bool),
+    BackupOverrideField(
+        "snapshot_delete_min_age_days", "SNAPSHOT_DELETE_MIN_AGE_DAYS", int
+    ),
 )
 
 # Override-file location is the same data dir that holds tool_config.json
@@ -1640,6 +1664,13 @@ def _coerce_backup_int_value(field_name: str, raw: object) -> tuple[bool, Any]:
             coerced,
         )
         return False, None
+    if field_name == "snapshot_delete_min_age_days" and not 0 <= coerced <= 365:
+        logger.warning(
+            "backup_settings.json: snapshot_delete_min_age_days=%d out of "
+            "range 0..365; ignoring",
+            coerced,
+        )
+        return False, None
     return True, coerced
 
 

src/ha_mcp/settings_ui/_handlers_backups.py

@@ -278,6 +278,7 @@ async def _get_backup_config(
     "auto_backup_throttle_minutes": (0, 1440),
     "auto_backup_retain_per_entity": (1, 10_000),
     "auto_backup_calendar_lookahead_days": (1, 365),
+    "snapshot_delete_min_age_days": (0, 365),
 }
 
 

src/ha_mcp/settings_ui/settings.js

@@ -1053,6 +1053,14 @@ const BACKUP_FIELD_LABELS = {
     label: 'Calendar lookahead (days)',
     help: 'How far ahead to query for calendar events when capturing pre-edit snapshots. Range 1–365.',
   },
+  enable_snapshot_delete: {
+    label: 'Allow snapshot deletion',
+    help: 'Lets ha_manage_backup delete full HA snapshot tarballs. Off by default: a snapshot may be the last recovery point after a mistaken change. Even when on, scheduled backups, the newest remaining snapshot, and anything younger than the age floor below stay protected.',
+  },
+  snapshot_delete_min_age_days: {
+    label: 'Minimum snapshot age to delete (days)',
+    help: 'A snapshot must be at least this old before it can be deleted. Range 0–365; 0 disables the floor (the newest-snapshot and scheduled-backup protections still apply).',
+  },
 };
 
 const BACKUP_ORIGIN_LABELS = {
@@ -1104,6 +1112,7 @@ function renderBackupConfig() {
       let max = 10000;
       if (f.field === 'auto_backup_throttle_minutes') { min = 0; max = 1440; }
       else if (f.field === 'auto_backup_calendar_lookahead_days') { min = 1; max = 365; }
+      else if (f.field === 'snapshot_delete_min_age_days') { min = 0; max = 365; }
       controlHtml = `<input type="number" name="backup:${escapeHtml(f.field)}" data-field="${escapeHtml(f.field)}" aria-labelledby="label-backup-${escapeHtml(f.field)}" value="${Number(f.value)}" min="${min}" max="${max}" ${f.editable ? '' : 'disabled'}>`;
     }
     let originMsg;