---
okf: "0.1"
type: incident
visibility: private
status: active
updated: 2026-08-03
links:
  - ../phases/backlog.md
---

## Bug: ha-diag-agent emituje eventy z node="unknown" do katalogu innego węzła (2026-07-14) — ZROBIONE (2026-07-15, `f2ba81b`)

**Kontekst.** To był plik-truciciel z buga checkpointu wyżej:
`evt-unknown-1781254800-ha_update_available-homeassistant-951.json` w
`events/piha/`. Node w evencie = `unknown`, ale plik wylądował w katalogu `piha/`.
Sufiks `-951` to `_seq` emittera → agent nachodził długo, wyemitował 951 eventów,
wszystkie jako `node="unknown"`.

**Root cause (config-wiring).** Tożsamość agenta (`node_name`) i KATALOG eventów
pochodzą z DWÓCH niezależnych źródeł:
- `services/ha-diag-agent/src/ha_diag/config.py:20` → `node_name: str = "unknown"`
  (domyślne, gdy env `NODE_NAME` nie dotrze do procesu w kontenerze).
- `services/ha-diag-agent/docker-compose.yml:12` → wolumen
  `/opt/homelab/events/${NODE_NAME:-ha-diag}:/events` — `${NODE_NAME}` jest
  interpolowane po stronie HOSTA (compose), a katalog jest dodatkowo twardo
  przypięty do `piha` w `hosts/piha/runtime/ha-diag-agent/docker-compose.override.yml`.

Jeśli `NODE_NAME` trafi do interpolacji wolumenu/override (→ `piha`), ale NIE do
`environment:` procesu (albo `Settings.load()` przez `os.environ.setdefault` go nie
nadpisze), aplikacja czyta `node_name="unknown"` i pisze eventy `node="unknown"`
do katalogu `events/piha/`. Rozjazd między nazwą w evencie a katalogiem docelowym.

**Skutek.** Poza zatruciem checkpointu (już naprawione osobno): eventy `node="unknown"`
są bezużyteczne dla world_state (observer tworzy węzeł-widmo `unknown`, potem prune go
kasuje bo nie ma go w topologii) — realny sygnał z ha-diag na piha przepada.

**Fix — ZROBIONE (2026-07-15, `f2ba81b`, `docs/sessions/2026-07-15.md`).** Wariant (a):
`node_name` NIGDY nie może być `"unknown"` w produkcji. `config.py`
`Field(default="unknown", validate_default=True)` + validator odrzuca `""`/`"unknown"`;
`main.py` → `SystemExit(1)` FATAL przy braku `NODE_NAME`; `EventEmitter.__init__` jako
ostatnia bramka przed nazwą pliku eventu. +18 testów, 0 regresji. Zmergowany i
zdeployowany na PIHA (rebuild, `NODE_NAME=piha` dochodzi do procesu). Pliki
`evt-unknown-*` na VPS/PIHA: 0 (potwierdzone).
**Pozostaje osobno (druga warstwa obrony, nadal TODO):** observer/emitter powinien
docelowo odrzucać/kwarantannować event, którego `node` w treści != katalog docelowy —
dzisiejszy fix zamyka źródło (`unknown` nie powstaje), ale nie waliduje spójności
node↔katalog dla innych, przyszłych źródeł eventów.