felhom-agent/REPORT.md

# REPORT — felhom-agent v0.44.0: privileged-capability self-probe

**Date:** 2026-06-29 · **Class:** Implementation (agent self-health, slice 1) · **Baseline:**
`main` @ `1958204` (v0.43.0) → **v0.44.0** @ `25024d9`. Companion hub: felhom.eu **v0.19.0**.

## What & why

A non-root agent that can't run a privileged command it depends on is **degraded** and must say so —
at cutover, not days later. Five casualties of the 2026-06-28 root→non-root migration (leaf/token/
lxc-info/make-private/controller-swap) went undetected until user-visible breakage. This adds a
self-check that catches the class at BUILD time (CI) and RUNTIME (startup + each hub-report cycle),
serve-degraded + loud. (The controller↔agent channel check is a separate later task.)

## `internal/capability` — manifest + probe

- **Manifest** (`Manifest()`): the required `(binary, representative-arg)` vectors, seeded from the
  2026-06-29 sudoers audit (the OK + CLOSED rows). The SURFACED/DEFERRED rows are **excluded**:
  general `pct exec * ` (controller-swap, arbitrary exec — an open operator decision), `pct create`
  (golden build, no daemon caller), `mount UUID=…` (legacy), `sensors -j` (callerless + uninstalled).
- **Critical** (hub alerts on these): `guest-init-pid` (lxc-info), the intermediary mount surface
  (`parent-self-bind`, `parent-make-shared`, `parent-make-private`, `drive-bind`, `drive-umount`),
  and the disk format/inspect gate (`disk-blkid`, `disk-lsblk`, `disk-mkfs-ext4`). The rest
  (provision/dnsmasq/guesthook/mount-units/smart/lvs) are non-critical (degrade reported, no alert).
- **Probe** (`Prober.Probe`): per entry, `sudo -n -l -- <binary> <reprArgs>` — a sudo policy LIST
  (exit 0 ⇔ permitted), run via a **DIRECT** runner so it never executes the command (safe for
  mkfs/pct entries) — plus an `os.Stat` existence check. Maps to `ok` / `degraded` ("sudo policy
  denied" | "binary not found"). A total sudo failure (drop-in missing) collapses to ONE aggregate
  signal. **Never** blocks startup, panics, or errors (serve-degraded).

## Build-time gate (the headline) + red-proof

`manifest_test.go` parses `configs/felhom-agent.sudoers`, glob→regex translates each grant, and
asserts **every manifest vector is covered** — exactly what would have caught the dropped
`lxc-info`/`make-private` lines in CI. **Red-proof** (`TestRedProof_DroppedGrantFailsCheck`): with
the `lxc-info` line removed from an in-memory copy, the check FAILS for `guest-init-pid`, and passes
on the real file. Demonstrated: ran with the line dropped → **FAIL**; restored → **PASS** (not
hollow).

## Runtime wiring + report

`Probe` runs once at startup (`logCapabilities`: INFO `capabilities self-check N/N ok` + an ERROR per
degraded naming the gated feature) and on every collect (`Collector.SetCapabilityProber`); the
snapshot rides the report as the new non-nil `HostReport.Capabilities []capability.Status`. Golden +
contract test updated; the cross-repo hub golden mirrors `capabilities: []`.

## Tests (all green: `go build/vet/test ./...`)

- `TestManifestCoveredBySudoers` (manifest ⊆ sudoers, 40 vectors) + `TestRedProof_...`.
- Probe: `AllOK`, `OneDenied` (critical degraded, sibling ok, serve-degraded), `BinaryMissing`,
  `SudoUnavailableAggregates`, `NilRunnerNoPanic`. Asserted the probe never executes a non-`-l` call.

## Live validation (felhom-pve, guest 9201) — deployed + verified

- **Deploy:** built `0.44.0` on 180 (sha `675b711e…`), shipped 180→local→felhom-pve (sha verified
  identical), backed up the prior binary (`felhom-agent.bak-0.43.0`), `install` + `systemctl restart`.
  `systemctl is-active` = **active**.
- **OK-path (live):** startup log `capabilities self-check ok=40 total=40 degraded=0` — N/N ok, a
  live proof the probe agrees with the post-audit-complete sudoers. Hub (v0.19.0) logged
  `Host capability checker initialized: 1 ok, 0 degraded`.
- **Degraded detection (live, non-intrusive):** on the real host, a granted vector
  `sudo -n -l -- /usr/bin/lxc-info -n 9201 -p -H` → exit 0 (ok); a bogus vector → exit 1 (degraded) —
  proving the probe's grant discrimination without mutating the freshly-certified live sudoers.

## NOT yet live-validated (deferred — see §16 forward note)

- **Full live agent→hub→operator-email degraded transition.** The hub alert fires only on a
  **Critical** capability degraded, which would require removing a Critical grant on the live host
  (forbidden — would re-break drives) or a separate test host, and would send a real operator email.
  It is **fully covered by unit tests** (`hub` `TestHostCapabilityChecker`: one event on ok→degraded,
  none steady, recovered, non-critical ignored, old-agent ok). Deferred to a scratch-host exercise.
- **Build-test in CI:** runs in `go test ./...`; no CI runner is wired in this repo yet (the test is
  the gate, run on every local/build-server `go test`).

## Forward note (NOT this task)

The manifest is hand-curated; the build-test locks **manifest ⊆ sudoers** but **code → manifest**
drift (a new `runner.Run` call not added to the manifest) is not auto-caught — a future static check
of `runner.Run` call sites against the manifest would close that. The controller↔agent channel check
is the next self-health slice.