felhom-agent/REPORT.md

REPORT — v0.62.0: A1 pool-membership ownership check for the stale-lock reaper

Date: 2026-07-03 · Class: implementation (agent v0.61.0 → v0.62.0, live on felhom-pve) Spec basis: audit A1 (AUDIT-blast-radius-hostroot-localapi-2026-07-02 §A) via the spike verdict (felhom.eu/documentation/audits/SPIKE-a1-pool-membership-read-2026-07-03.md Q3/Q4/Q5). Companion: felhom.eu felhom-host-install.sh v1.8.0 → v1.9.0 (Pool.Audit in FelhomAgentGuest).

1. Baselines & commits

Repo	Baseline	Shipped commit
felhom-agent	3e760a559a (v0.61.0)	3f37c5f — v0.62.0 code + tests + REUSE/CHANGELOG/CONTEXT
felhom.eu	5e3dfcb714 (script v1.8.0)	639a57e — script v1.9.0 + scripts/CHANGELOG + REUSE §2 errata + CONTEXT

2. What changed (agent)

• Client.Pool(ctx, name) (proxmox/query.go): GET /pools/{name} → PoolInfo{PoolID, Members[]{VMID,Type}}. API-side read — the Client-never-shells / Privileged-never-HTTPs fence is untouched.
• staleLockController.Guests() (localapi/stalelock.go): ListLXC ∩ pool members (nonzero-vmid, non-storage entries). Pool-read failure → wrapped error pool membership read (pool=felhom): … → rides the pre-existing "guest list unavailable — skipping recovery" guard (stalelock.go Server path). NEVER falls back to the unfiltered list. One INFO line per scan: stale-lock: scanning pool guests (pool, listed, scanned). Note (spec deviation, by necessity): the spec located this line in RecoverStaleLockedGuests; it is emitted by the production controller instead, because the unchanged StaleLockController seam cannot carry the pool name + pre-intersect count to the Server without breaking the 9 existing fake-based tests. Net startup-log effect is identical (Scenario D line observed live, §5).
• NewStaleLockController(px, runner, pool, logger); main.go threads reconcile.DefaultPool.
• Capability: composed closure in main.go appends pve:pool-read (non-critical) to the sudo prober's snapshot; internal/capability/ untouched. --selftest gained a "pool read" line.

3. Test results (all green: go build ./... && go vet ./... && go test ./..., 17 pkgs ok)

Test	Result
TestStaleLock_ForeignGuestNotReaped (Scenario A)	PASS — foreign 5000 never unlocked/snap-deleted/started
TestStaleLock_PoolGuestStillReaped (Scenario B)	PASS — owned 9201 fully recovered (unlock+delsnap+start)
TestStaleLock_PoolReadFails_SkipsAll (Scenario C)	PASS — zero mutations on pool-read error; error text names the pool read
TestStaleLockController_GuestsIntersect (§8 edges)	PASS — storage-type/vmid-0 members excluded; empty pool = empty scan, no error
9 pre-existing stalelock tests	PASS unmodified (Server-level fakeStaleLock seam untouched by design)

Red-proofs (both run and reverted):

• A: intersect replaced with raw-ListLXC passthrough → TestStaleLock_ForeignGuestNotReaped FAILED with runner calls=[[pct unlock 5000]] (the exact A1 exploit) and TestStaleLockController_GuestsIntersect failed with both vmids returned. Restored.
• C: pool-read error changed to fall back to the unfiltered list → TestStaleLock_PoolReadFails_SkipsAll FAILED with runner=[[pct unlock 9201]] delsnap=[9201] started=[9201]. Restored.

4. Live rescope (felhom-pve, PUSHED v1.9.0 script fetched from Gitea raw, --rescope-acl --vmid 9201)

Roles after (only Guest changed; Base/Store byte-identical):

FelhomAgentStore → Datastore.Allocate,Datastore.AllocateSpace
FelhomAgentGuest → Pool.Allocate,Pool.Audit,VM.Allocate,VM.Audit,VM.Backup,VM.Config.CPU,
                   VM.Config.Disk,VM.Config.Memory,VM.Config.Network,VM.Config.Options,
                   VM.PowerMgmt,VM.Snapshot,VM.Snapshot.Rollback
FelhomAgentBase  → Datastore.Audit,SDN.Use,Sys.Audit

Production-token GET /pools/felhom (403 in the spike) → HTTP 200, members [9201]. The running v0.61.0 agent stayed active through the rescope (order: rescope BEFORE agent deploy, per spec).

5. Agent deploy verification (felhom-pve)

• Binary built on 180 from 3f37c5f, deployed with backup felhom-agent.bak-0.61.0; felhom-agent --version → felhom-agent 0.62.0; service active.
• Startup log (live excerpt): msg="capabilities self-check" ok=47 total=47 degraded=0 (46 → 47: the new pve:pool-read, OK) and msg="stale-lock: scanning pool guests" pool=felhom listed=1 scanned=1 (listed=1 because the scoped token's ListLXC is already pool-filtered — spike T1, expected). ReassertGuestBinds clean (logs only on action/failure; none emitted). No new warnings — the pre-existing PBS token-secret WARN (BUNDLE leftover, CONTEXT open thread) is unchanged.
• --selftest: [ ok ] pool read pool "felhom", 1 member(s) / - 9201 type=lxc; suite OK.
• Hub-side: latest stored host report (agent_version 0.62.0) carries {"name":"pve:pool-read","feature":"stale-lock recovery scoping (pool ownership check)", "critical":false,"status":"ok"} — 47 capabilities, 0 degraded. Verified against a snapshot of the hub DB (host_reports.report_json), since the operator UI is password-gated.
• Published: Gitea generic package felhom-agent/0.62.0, round-trip sha256 verified: ed1192c9ae8f355dee19128cf4b01984ba7398e860b4a16a8009655b84b32d81.

6. Operator follow-ups

• Hub Day-0 artifact manifest still vouches 0.60.0 → bump to 0.62.0 (sha256 above; password-gated UI — CC cannot).
• Rotation + de-git of the 3 committed secrets in felhom.eu/manifests/felhom.secret.yaml (spike appendix; REUSE §2 errata now records that gitea-creds is NOT out-of-band).

7. Observations (not acted on)

• Hub capability-name handling confirmed generic: the checker keys on Critical && status=="degraded" only (hub/internal/monitor/host_capability.go), names are data — the new non-critical entry rides the report/UI without paging and needed no hub change.
• The spike Q6 consumer observations (hub collect / disks / reconcile ListLXC users) remain observations; no other consumer touched, per spec.
• _state_get provisioned_vmid was empty on felhom-pve (state.json holds only completed), so --rescope-acl needed the explicit --vmid 9201 — worth knowing for other boxes.