felhom-agent/REPORT.md

REPORT — agent v0.83.0: observability pass (capture ring + /debug/logs + heartbeat log-pull + sweep)

Date: 2026-07-11 · Commit: cb692f8 · Deployed: felhom-pve (backup .bak-0.82.0) · NOT published (Peti stays 0.81.0; reaches him with the next publish train)

What shipped

• Capture layer (internal/log): applog.New → (logger, *Ring). slog fan-out: stderr/journald at the configured level (unchanged), a 1000-entry ring FIXED at LevelDebug. Ring.Lines(maxBytes) renders newest-kept plain text (the heartbeat tail source).
• GET /debug/logs on the local API (token-authed, self-scoped like every sibling; ?raw=1 plain text; 503 unwired) + request-level DEBUG middleware (method/path/status/duration, never bodies).
• Heartbeat log-pull: ControlEnvelope.log_tail_requested (additive) → the NEXT heartbeat carries log_tail {collected_at, lines[]} (128 KB cap, newest kept). Consume-once mirrored from report logtail.go: local pending drains onto the carrying push; a failed push is re-armed by the next envelope (retry proven in tests). Serving a pull logs operator log pull served (INFO).
• Gap-fill sweep: netverify (job start / trigger outcome / /proc/mounts verdict / journal byte-count / classification code / rollback outcome / durations), netstorage add (pre-probe PASS verdict, creds staged/removed — path only), netmount (unit install/enable/remove-step results), signedjobs (jobs fetched ids+duration; op received class/host/expiry — never signatures), selfupdate (invariants passed, download sha-match+duration), disks (assign/eject/decommission outcome INFO), ReassertGuestBinds pass summary, controller-swap (pre-pull verify, negative health verdict), desired syncer + hub loop per-exchange DEBUG.

Red-proofs (all demonstrated, then restored)

Scenario	Reverted shape	Failure seen
S1 capture-at-info	ring handler gated at the emit level	ring holds 1 entries, want 2
S2 consume-once	logTailPending = false drain removed	report 3 carries a tail again — consume-once broken
S7 log sequence	/proc/mounts verdict Debug dropped	phase line "netverify: /proc/mounts verdict" missing

Live validation (felhom-pve, 2026-07-11 ~17:00 CEST)

• felhom-agent 0.83.0 live; journal clean (ReassertGuestBinds bound felhom-usb, local-api listening, no capability degradation).
• A real NAS add from controller 0.116.1 at logging.level=info: the agent ring (via the controller's Ügynök tab) shows the request middleware lines including POST /netstorage/add status=502 duration_ms=2001 — the refusal flow is reconstructable remotely.
• Heartbeat log-pull live round-trip: pending the operator's hub button click (hub UI is password-gated; CC cannot log in). The channel is fully proven by hub API tests incl. the S6 stays-pending case.

Green gate

go build ./... && go vet ./... && go test ./... — all green (no flakes this run).

Observations

• Pre-existing (not from this change): lanresolver: cannot list provisioned guests — permission denied on /var/lib/felhom-agent/guests WARN at startup — worth a follow-up look.
• The 20 s reconcile tick adds one DEBUG ring line per pass (guest-bind re-assert pass) — accepted ring churn (~180/h; the ring holds ~1000).