felhom-controller/REPORT.md

# REPORT — v0.114.0: agent-capability gate for coupled features (option-1) + publish-train rules (option-2)

**Date:** 2026-07-11 · **Version:** controller v0.114.0 (from v0.113.0) · **MinAgent:** — (the gate
itself works against agents 0.79–0.81 as they exist; that is the point) · **Agent/hub: UNTOUCHED.**

## What shipped

The 0.81/0.113 publish train's 9-minute controller-before-agent skew (Peti's box) answered at the
box level: the controller detects whether its agent supports a coupled feature (route probe on
`GET /netstorage/verify-status` — the route that shipped WITH the v0.81.0 coupled add semantics)
and refuses the NAS add up front with an honest Hungarian message instead of failing mid-pipeline
with a misleading rollback. Riding along: the publish-train conventions codified in
`felhom.eu/documentation/runbooks/publish-train-rules.md`.

## Baselines (verified live before work)

| Repo | main @ start | → main @ end |
|---|---|---|
| felhom-controller | `5d06ecf374` (v0.113.0) | `53ab971` (v0.114.0) |
| felhom.eu | `a487ab2fc4` | `4eaabb2` |
| felhom-agent | `1e60e88eb2` (v0.81.0) — read-only, NOT touched | unchanged |

## Commits

| Hash | Content |
|---|---|
| `d347dc4` | Commit 1 — agentapi typed `StatusError` (1.1) + `features.go` (Feature/SupportState/`featureProbes`/`SupportCache` TTL 5m/`Client.Supports`) + the add gate before the single-flight claim + T1–T4, T6 |
| `50da732` | Commit 2 — `NetAddSupport` threaded to `storage_network.html` (banner on `no`; list+remove in every state; JS load guard) + T5 |
| `4a5c40b` | Pre-existing scheduling flake fixed in `TestBackupTier2Restore_DoubleClickRefused` (IsRunning flips before StopStack lands — wait for the first stop, then assert) |
| `d9da5a0` | Docs — CHANGELOG v0.114.0 (MinAgent header convention starts), README NAS gate paragraph, CONTEXT, REUSE rows, CLAUDE.md coupled-feature rule |
| `53ab971` | `[DEBUG]` gate-verdict log per add + `SupportState.String()` |
| felhom.eu `4eaabb2` | `documentation/runbooks/publish-train-rules.md` (the 4 standing gates, each citing its incident) + CONTEXT entry — pushed |

## Files touched (controller)

`internal/agentapi/client.go` (StatusError; `get` non-200 branch — same message text),
`internal/agentapi/features.go` + `features_test.go` (NEW),
`internal/web/server.go` (`netFeatures` field), `internal/web/netstorage_handlers.go` (gate +
`netAddOutdatedMsg` + `netAddSupport`), `internal/web/handlers.go` (`networkStoragePageData`),
`internal/web/templates/storage_network.html`, `internal/web/netstorage_gate_test.go` (NEW),
`internal/web/storage_network_template_test.go` (T5 + `NetAddSupport` in C8's data),
`internal/web/async_restore_test.go` (flake fix). Docs: CHANGELOG/CONTEXT/REUSE/CLAUDE/README.

## Verify-first (1.1) finding

`Client.get` returned a generic `fmt.Errorf("agentapi: GET %s: HTTP %d")` on non-200 — a 404 was
NOT typed. Added `StatusError{Path, Code}` returned by that branch (identical message text, so no
behavior shift elsewhere); classification uses `errors.As` + `Code==404` only. Pinned wire-level by
`TestClient_404IsTypedAndSupportsSaysNo` (httptest TLS + real leaf pin, routeless mux).

## Tests + red-proofs (every red-proof run → predicted failure observed → reverted; final tree clean)

Counts: web 76 → 80 test funcs; agentapi 28 → 33.

| Test | Scenario | Result | Red-proof (verbatim failure) |
|---|---|---|---|
| `TestNetAddGate_OldAgent_RefusedUpFront` (T1) | A | PASS — 412 + `"code":"agent_outdated"` + the §Part-3 message; job slot nil; 0 agent add calls; 0 removes; 0 registered; slot re-acquirable | RP1 gate disabled → `gate: got 200 want 412 ({"data":{"name":"media","started":true},"ok":true})` — the exact pre-gate WRONG behavior |
| `TestNetAddGate_CurrentAgent_UnchangedAndProbeCached` (T2) | B | PASS — two adds both `done`, registered, no rollback; probe count across both = 1 | RP2 cache disabled → `probe (verify-status) calls across two adds = 2, want exactly 1 (cached)` |
| `TestNetAddGate_ProbeIndeterminate_PassesThrough` (T3) | C | PASS — transport error AND 5xx: 200 `{started:true}`, job fails `agent_error` (the existing path), never `agent_outdated` | RP3 classify-any-error-as-No → both subtests: `indeterminate probe must pass the gate: got 412 ({"data":{"code":"agent_outdated"},"error":"Az ügynök frissítése szükséges…"})` — the false "too old" trap, caught |
| `TestSupports_Classification` (T4) | 2xx/404/wrapped-404/401/500/502/refused/timeout/**plain-error-with-404-text** → Yes/No/No/U/U/U/U/U/**U** | PASS | RP4 string-match mutant → `plain_error_with_404_text: Supports(agentapi: GET /netstorage/verify-status: HTTP 404) = 2, want 0` (RP3 also failed 6 T4 cases) |
| `TestStorageNetworkTemplate_AgentOutdatedBanner` (T5) | D | PASS — `no`: banner present, `ns-add-form` absent, list+Eltávolítás present; `yes`/`unknown`: form, no banner | RP5 conditional dropped → `the §Part-3 banner is missing on an old agent` + `the add form must NOT render on an old agent` |
| `TestSupports_CacheTTL` (T6) | warm-cache negative (calls stays 1), re-fire after TTL+1s, negative polarity cached, Unknown NEVER cached | PASS | covered by RP2 (`probe calls on a warm cache = 2, want 1`; `after TTL expiry = 3, want 2`; `negative verdict not cached (calls=2)`) |
| `TestClient_404IsTypedAndSupportsSaysNo` / `TestClient_SupportsYesOnLiveRoute` | wire-level 1.1 | PASS — real TLS+pin client: routeless mux ⇒ `*StatusError{404}` ⇒ `SupportNo`; live route ⇒ `SupportYes` | — (pins the verify-first finding) |
| `TestSupports_UnknownFeature` | table gap fails open, no probe fired | PASS | — |

Green gate `go build && go vet && go test ./...`: PASS per commit (template_id_gate + emoji_gate
green for the template commit). One unrelated failure surfaced under parallel load —
`TestBackupTier2Restore_DoubleClickRefused` — diagnosed as a PRE-EXISTING race in the test itself
(asserted StopStack count right after IsRunning flips; goroutine not yet parked), fixed in
`4a5c40b`; full suite green since.

## Deployed + verified

Guest 9201 (golden/bootstrap mechanism, built on 180, image pushed):
`gitea.dooplex.hu/admin/felhom-controller:0.114.0 Up (healthy)`; startup log clean; selfupdate:
`Current version 0.114.0 is up to date`. Agent on felhom-pve: 0.81.0 (untouched).

## Live validation (the supported branch; anti-F9 — the exact endpoint the UI invokes)

Method: `curl` from inside guest 9201 to the controller container (`http://172.17.0.2:8080` +
`Host: felhom.demo-felhom.eu`; the demo has no password so auth/CSRF do not apply) — the residual
vs a browser is client-side rendering only. Demo agent = 0.81 ⇒ the SUPPORTED branch. Done inside
one cache window.

1. **Gate-pass + real pipeline** — POST add `gatecheck114` (nfs, server 192.168.0.180 = reachable,
   export `/srv/nonexistent-gate-check` = bogus): response `{"data":{"name":"gatecheck114",
   "started":true},"ok":true}` (identical shape to 0.113.0); controller log
   `[DEBUG] [web] netstorage add "gatecheck114" capability gate: netstorage_verify=yes` (the probe
   verdict, visible); status poll → `failed` in ~2.5 s, category `nfs_export`, the exact merged
   Hungarian message, real journal detail — byte-for-byte the 0.113.0 behavior.
2. **Nothing changed state** — share list `{"network_storage":[]}`; felhom-pve: 0 unit files;
   the known residuals only (one `not-found failed` unit listing → `systemctl reset-failed`; the
   empty `/mnt/felhom-drives/gatecheck114` dir → removed; both documented v0.113.0 observations,
   re-confirmed, no new gaps). Host+guest now show only `felhom-usb`.
3. **Page render** — GET `/storage/network`: `ns-add-form` present (2 occurrences), the banner text
   `régebbi verziójú` 0 occurrences ⇒ the SupportYes render; list intact.

## NOT live-validated

- **The `agent_outdated` refusal branch (SupportNo)** — test-proven only (T1/T4/T5 with red-proofs
  RP1/RP3/RP4/RP5). The demo agent is current (0.81.0); downgrading a live agent to prove a banner
  is not justified. Stays on this list until a future old-agent window shows it naturally.
- Concurrent double-probe on a cold cache (documented harmless: one extra cheap GET) — not raced live.

## STOP honored

NOT published (Day-0 manifest untouched, no `publish-agent.sh`, no golden bake), NO floor movement,
NO hub changes, NO agent changes, Peti untouched on 0.113.0. The gate is inert protection until the
next train. Note: the `0.114.0` registry tag was rebuilt once (the `[DEBUG]` gate-log commit) before
any vouch existed — demo-only, nothing references it.

## Observations (out of scope, documented NOT acted on)

- **Hub floor-UI separation** (decoupling the floor field from the manifest-save screen / staging
  it) — its own task; the rules doc only references it (rule 2's "save LAST" is the interim control).
- **Agent version-in-envelope** — the documented future upgrade of `Supports` (prefer version
  comparison over route probing); the `featureProbes` table comment + rules doc carry the pointer.
- `Client.Supports` exists as the spec'd public API; the web layer drives the same `SupportCache`
  machinery through its `netAgent` seam (`Server.netFeatures`) so unit tests fake the probe — one
  code path in production and tests.
- The known v0.113.0 remove-residuals (failed-unit listing needs `reset-failed`; empty mountpoint
  dir lingers) reproduced on the failed-add rollback path too — same cleanup, still LOW.