Keep the model cache out of Home Assistant backups, allow /share as backup target

[NerdyHank]

Addresses two of the three points in #33. Stacked on #35, which introduces the map: block both changes build on — merge #35 first and the base retargets to main on its own.

The report came with measurements, which made this easy to act on:

part of the app backup	size
image.tar (built locally, so stored every time)	1,448 MB
data/model-cache/.insightface	601 MB
gallery, history, settings — the irreplaceable part	~11 MB

What this does

backup_exclude for the model cache — roughly 600 MB that re-downloads by itself on the next start. Nothing in it can be lost.

backup_dir as an app option, /share mounted writable. Point the built-in daily gallery backup at /share/faceid and it lands where Home Assistant's own backups already look, at a few MB. The gallery is the one thing that cannot be re-created, and until now it only lived inside the app's data volume.

/media deliberately stays read-only. It is where recordings are read from, never written to; only the backup target needed write access. There is a test pinning that distinction so it cannot drift.

Not addressed

The image itself, ~1.4 GB per backup, because the app is built locally rather than pulled from a registry. Fixing it means publishing prebuilt images for amd64 and aarch64 and setting image: — a build pipeline and a registry, not a config line. Left in #33 as the remaining item, and noted in DOCS.md so nobody expects the backup to be 11 MB yet.

76 tests green.

🤖 Generated with Claude Code

[the-codemole]

🧪 Automated PR Checks

Profile: python-app · auto-detected · ⚙ Configurable

✅ python-syntax — 6 Python file(s) compile cleanly
✅ ruff — 6 Python file(s) — ruff clean (E9/F)
⚪ json-valid — ⏭️ No JSON files in the diff
✅ diff-size — Diff +596/-21 in 13 files
✅ secret-scan — No plaintext secrets in the added lines
✅ conflict-markers — No merge conflict markers
✅ sensitive-files — No sensitive file types in the diff

_{hermes-work · branch smaller-ha-backups · base main · What do these checks do?}

[NerdyHank]

Half right, and the half that is right was worth the fix.

The pruning claim does not hold. prune_backups has always globbed only its own
archives:

files = sorted(backup_dir.glob("faceid-backup-*.tar.gz"), reverse=True)

A shared folder keeps everything else. There is now a test that says so — it drops
family-photos.tar.gz, notes.txt and movie.mkv next to three backups, prunes to
keep=1, and asserts the three unrelated files are still there.

The missing validation was real, and worse than "no validation": a backup_dir under
the read-only /media mount was accepted by the Settings form, by the add-on at start-up,
and by the auto-backup thread, which caught the OSError, wrote one line to the log and
carried on. That is a failure you find out about when you need the backup. Fixed in three
places, all of them write-probing with a real temporary file — /media is readable, so
os.access and -d both say yes and only the write attempt reveals the mount:

• check_backup_dir() in backup_util.py: absolute path, creatable, directory, writable;
  returns the reason or None, and leaves nothing behind.
• POST /api/settings refuses an unusable path with HTTP 400 and the reason, so nothing is
  stored. POST /api/backup/now turns the OSError into a 400 instead of a 500.
• run.sh probes it at start-up and exits with the way out named:
  /media is mounted read-only; put the backup under /share (e.g. /share/faceid).

The UI swallowed it too — saveBackupCfg() had no catch, so an invalid path produced no
toast at all. It now shows the reason, as does "Back up now".

Measured against the running router on a spare port (no MQTT, no Frigate, separate data
directory):

read-only dir : 400 backup_dir unusable: cannot write to …/readonly: Permission denied
relative path : 400 backup_dir unusable: backups/x is not an absolute path
good dir      : 200 {"applied":{"backup_dir":"…/good"}}
backup now    : 200 …/faceid-backup-20261006-124724.tar.gz
now on ro dir : 400 cannot write to …/readonly: Permission denied
probe left    : []

and the start-up block as an unprivileged user:

FATAL: backup_dir '…/ro/faceid' cannot be created.
FATAL: Only /media (read-only) and /share (writable) are mounted — use /share/faceid.

88 tests green.

[the-codemole]

Approved — review complete.

• Checks: 6 passed, 1 skipped, 0 failed
• 4 finding(s) addressed, no open threads

No longer clean — approval withdrawn.

[the-codemole]

Approved — review complete.

• Checks: 6 passed, 1 skipped, 0 failed
• 5 finding(s) addressed, no open threads

[the-codemole]

Approved — review complete.

• Checks: 6 passed, 1 skipped, 0 failed
• 5 finding(s) addressed, no open threads