--- paths: ["controller/internal/agentapi/**"] --- # Coupling to the host agent — felhom-controller `internal/agentapi` is **the disk seam**: the pinned-TLS client to the host agent's per-guest local API. The controller holds no Proxmox credentials; everything disk/host/Proxmox goes through here. ## Declaring a coupled feature Controller behaviour that depends on a specific agent version needs **all three**, or it ships broken on an older box: 1. a `featureProbes` table row in `internal/agentapi/features.go` 2. a `Supports` gate call **at the feature's entry point** — not somewhere on the path to it 3. `MinAgent: X.Y.Z` in the CHANGELOG entry header Rules: `felhom.eu/documentation/runbooks/publish-train-rules.md`. ## Never push a controller past the agent it depends on The R-216 guard compared the box's agent against the **golden's** MinAgent while serving a **floor** that could point elsewhere. Raise a floor above the vouched golden — which the day-0 runbook recommends and a per-customer override makes trivial — and the guard checks a version it is not serving. A box then landed on a controller needing a newer agent, and its customer was told a correct recovery code was wrong. **A floor above the vouched golden is HELD, with its own reason** (hub v0.97.0). ## Distinguish "could not reach" from "wrong answer" A failed bundle FETCH must not be reported to a customer as a bad recovery code. Classify by **value** (`ErrBundleFetch` → HTTP 502), never by error string — a string is not something a caller can branch on. Unknown class → neutral message, never the typing message.