# Changelog

All notable changes to **felhom-agent** are recorded here. Update on every code
change that gets pushed.

## v0.1.0 — Scaffold + `proxmox` interaction layer (slice 1) (2026-06-08)

First slice: stand up the host-agent project and its foundation — the typed
Proxmox interaction layer every other module will call. No reconcile loop, hub
client, signing, or storage/backup orchestration yet (later slices).

### Added
- **Project scaffold**: module `gitea.dooplex.hu/admin/felhom-agent`, binary
  `felhom-agent` (`cmd/felhom-agent/`), Go 1.24, zero external dependencies
  (pure stdlib). `--version` flag; `version` var overridable via
  `-ldflags "-X main.version=<v>"`.
- **`internal/proxmox` — API backend (`Client`)**: hand-rolled REST client over
  `https://<host>:8006/api2/json` with `PVEAPIToken` auth. Typed read ops
  (`Version`, `Nodes`, `NodeStatus`, `ListLXC`, `GuestStatus`, `GuestConfig`,
  `ListStorage`, `NodeStorage`, `StorageContent`) and async mutating ops
  returning a UPID (`RestoreLXC` — the primary create path, `Vzdump`, `Snapshot`,
  `Rollback`, `DeleteSnapshot`, `SetConfig`, `Start`, `Stop`).
- **`WaitTask`**: polls `GET /nodes/{node}/tasks/{upid}/status` until stopped, then
  asserts `exitstatus == "OK"` (authorization can surface at task execution, not
  the POST — phase1-2 §1.3). Exponential backoff (1s→5s cap), context
  cancellation + timeout. `*APIError` parses the offending privilege from a 403;
  `*TaskError` parses it from a failed task exitstatus + log tail.
- **`internal/proxmox` — fenced root-CLI backend (`Privileged`)**: limited to the
  three proven OS-root exceptions only — `CreateGoldenLXC` (keyctl `pct create`),
  `MountUSBByUUID`, `SMART`, `Sensors`; each cites why it can't be the API. Fence
  is structural (Client never shells out, Privileged never makes an HTTP call) and
  asserted in tests.
- **TLS trust**: SHA-256 leaf-cert pinning (the host serves a self-signed cert) or
  a CA file; an explicitly-named `insecure_skip_verify` that is off by default. No
  blanket verification disable.
- **`internal/config`**: JSON config file + `FELHOM_AGENT_*` env overrides; the
  token secret is never logged (`Redacted()`).
- **`internal/log`**: slog setup (text, stderr, configurable level).
- **`cmd/felhom-agent --selftest`**: read-only health report against a live host
  (version/nodes/status/guests/storage); `--selftest=task --vmid N` exercises
  `WaitTask` on a reversible snapshot→rollback→delete op (gated; default selftest
  mutates nothing).
- **Tests**: unit tests with a mock HTTP transport + mock runner (UPID parse,
  `WaitTask` running→OK / failed-403 / timeout / ctx-cancel, 403→privilege error,
  response decoding against shapes captured live from `demo-felhom`, config
  redaction, and the API-vs-root routing fence).

### Notes
- Types are grounded in the spike findings
  (`felhom.eu/documentation/proxmox-platform.md`, `tests/phase{0,1-2,3}-findings.md`)
  and the exact JSON shapes captured live from `demo-felhom` (PVE 9.2.2).
- Verified: `go build/vet/test` green on Go 1.24.4 (build server) and a live
  read-only `--selftest` against the demo host with TLS fingerprint pinning.
- The 16-privilege `FelhomAgent` role + privsep token (role on **both** user and
  token) is provisioned out-of-band; the agent only consumes the token.