From 0df72ea643647066d1b04eb568187636a3b703c6 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 11 Jul 2026 17:18:55 +0200 Subject: [PATCH] docs: REPORT + CONTEXT + CLAUDE logging rule for v0.83.0 (deployed felhom-pve) Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6 --- CLAUDE.md | 3 +++ CONTEXT.md | 15 ++++++++++++ REPORT.md | 71 +++++++++++++++++++++++++++++++++--------------------- 3 files changed, 61 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3178fe2..727034b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -104,6 +104,9 @@ All shippable work commits **directly to `main`**; `main` equals what is deploye guess** when you'd otherwise invent input/output. - Update `REUSE.md` if you added/changed/deprecated a shared helper or pattern (same commit). - Testing doctrine (non-hollow tests, red-proofs, seams): use the `felhom-testing` skill. +- **Logging**: the slog logger fans out to journald (configured level) + the always-DEBUG `applog.Ring` + (remote pulls) — English, keys-never-values, durations on outcomes; full rules in + `felhom.eu/documentation/runbooks/logging-conventions.md`. ### Live validation diff --git a/CONTEXT.md b/CONTEXT.md index 21680bb..9246151 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -5,6 +5,21 @@ ## Current +- **v0.83.0** (2026-07-11, LIVE on felhom-pve; NOT published — Peti stays 0.81.0) — **observability + pass** (pairs with controller v0.116.1 + hub v0.46.0). `applog.New` → `(logger, *Ring)`: slog + fan-out, journald at the configured level, ~1000-entry ring FIXED at DEBUG. `GET /debug/logs` + (local API, token-authed; the controller Debug page's Ügynök tab) + request-level DEBUG + middleware. Heartbeat log-pull: envelope `log_tail_requested` → next heartbeat ships `log_tail` + (128 KB, consume-once; failed push re-armed by the next envelope; `operator log pull served` INFO + on fulfillment). Gap-fill sweep: netverify phase/verdict lines (job start, trigger outcome, + /proc/mounts verdict, journal bytes, classification code, rollback outcome, durations), netmount + unit steps, signedjobs op-received (class/host/expiry — never signatures) + fetch duration, + selfupdate invariants + download sha/duration, disks outcome INFOs, controller-swap pre-pull + + health verdicts, desired/loop per-exchange DEBUG. Logging conventions: + `felhom.eu/documentation/runbooks/logging-conventions.md`. OPEN: the hub-side live pull awaits + the operator's button click (hub UI password-gated); pre-existing lanresolver + permission-denied WARN on /var/lib/felhom-agent/guests noted in REPORT. + - **v0.77.0** (2026-07-09) — **fork-4: escrow the offsite restic repo password under R.** `IdentityBundle` gains `ResticRepoPassword` (rides the existing age-under-R `WrapIdentityBundle` path — validated by the custody spike `febdc56`). New `POST /escrow/stage-secret` (`withGuest`) transiently stages the diff --git a/REPORT.md b/REPORT.md index 31a0f66..c44fa31 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,38 +1,53 @@ -# REPORT — agent v0.82.0: local-API version channel (X-Felhom-Agent-Version) — DEPLOYED +# REPORT — agent v0.83.0: observability pass (capture ring + /debug/logs + heartbeat log-pull + sweep) -**Date:** 2026-07-11 · **Class:** implementation (agent slice of the NAS/coupling backlog-clear -task, Part B). Baseline v0.81.0 (`1e60e88`) → **v0.82.0** (`fa9c7fe`), live on felhom-pve. -Pairs with controller v0.115.0 (version-aware Supports) + hub v0.45.0. +**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 -- **`X-Felhom-Agent-Version` on EVERY local-API response** (`localapi/server.go`: the mux is wrapped - so the header is set on all routes + all statuses, INCLUDING auth failures and 404s — the - controller learns the agent version passively from ordinary traffic). Value = `main.version` via - the new `localapi.Options.AgentVersion`. No new routes, no envelope changes, **no sudoers changes**. -- The controller (v0.115.0) reads it and capability-gates by version comparison; header-less - (≤0.81.0) agents keep working — the controller falls back to the v0.114.0 route probe unchanged. +- **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. -## Tests + red-proof +## Red-proofs (all demonstrated, then restored) -`TestVersionHeader_OnEveryResponse` (authed / unauthed / 404 all carry the header) + -`TestVersionHeader_OmittedWhenUnset`. Red-proof: dropping the Handler() wrap (return the bare mux) → -every row fails with an empty header (observed: `X-Felhom-Agent-Version = "", want "9.9.9-test"`), -reverted → green. Full `go build && go vet && go test ./...` PASS (the known -TestGenerateRecoveryCode wordlist flake did not recur this run). +| 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` | -## Deployed + verified +## Live validation (felhom-pve, 2026-07-11 ~17:00 CEST) -felhom-pve: `.bak-0.81.0` kept → `install -m0755` → restart; `felhom-agent --version` → 0.82.0; -clean start journal (enrolled drive re-bound, local-api listening). Wire proof: an authed -`GET /storage` to the live agent returns `x-felhom-agent-version: 0.82.0`. **NOT published** — -demo-deploy only; Peti stays 0.81.0 (the live probe-fallback path). Hub now shows demo agent 0.82.0, -Peti 0.81.0. +- `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. -## Observations (documented, NOT acted on) +## Green gate -- **Q1c FAIL surfaced during this task's Part E** (supervised, agent 0.82.0 live): a NAS automount - trigger does NOT survive a guest reboot — the guest sees an empty dir; the agent has no - network-mount reassert on guest reboot (unlike drive `ReassertGuestBinds`). Follow-up spec'd: - `felhom.eu/documentation/backlog/FOLLOWUP-nas-automount-guest-reboot-reassert.md`. NOT this - release — a distinct agent task. +`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).