felhom-agent/REPORT.md

REPORT — operator-opt-in CPU/RAM cap for the provisioned guest (agent v0.52.0)

Date: 2026-07-01 · Repo: felhom-agent · Class: Implementation (additive CLI→spec plumbing)

Colleague-safety batch #3 (agent half). New -cores/-memory flags let an operator cap the provisioned guest's CPU cores + RAM at provision time, before first boot, so a trial appliance on a colleague's SHARED production Proxmox doesn't pressure his existing guests. Pure CLI→spec wiring — the reconcile engine already applied the cap.

1. Confirmed baseline

Repo	main @ commit	Current	→ Target
felhom-agent	1502ca6	v0.51.0	v0.52.0

2. Files changed + commit

• cmd/felhom-agent/main.go — -cores/-memory flags; Cores/MemoryMB on bringUpSizing; passed in both dispatch literals + both BringUpSpec{} builds (runSelftestBringUp, runSelftestProvision); -selftest usage string updated; version 0.51.0→0.52.0.
• internal/reconcile/bringup_test.go — new TestBuildBringUpConfig_ResourceCaps.
• internal/reconcile/bringup.go — not changed (mechanism already correct; used only for the red-proof, reverted).
• CHANGELOG.md, README.md — updated.
• Commit 0573ec9 on main (parent 1502ca6).

3. Green gate

• Local (Go 1.26.0, Windows) and build server 192.168.0.180 (Go 1.26.0, linux): go build ./... OK, go vet ./... OK.
• go test ./... — all packages pass EXCEPT a pre-existing flake in internal/escrow (TestGenerateRecoveryCode_EntropyAndFormat): the random recovery code occasionally contains a hyphenated wordlist entry (e.g. "yo-yo"), so the test's --split counts 11 "words" instead of 10. Confirmed flaky by re-running 5×: 1 fail / 4 pass. It is in a package this task did NOT touch and is unrelated to the cap change (see Observations). My package internal/reconcile and everything else pass deterministically.

4. Test + omit-when-zero red-proof (§10)

• TestBuildBringUpConfig_ResourceCaps PASS: buildBringUpConfig(Cores:2,MemoryMB:4096) → cores="2",memory="4096"; buildBringUpConfig(Cores:0,MemoryMB:0) → both keys absent.
• Red-proof: temporarily replaced the if spec.Cores > 0 {…} guard with an unconditional params["cores"]=strconv.Itoa(spec.Cores) → the omit-when-zero assertion FAILED as designed (bringup_test.go:115: cores must be ABSENT when unset (golden default), got "0"). Reverted; test passes again; git diff shows bringup.go clean (no net change).

5. Deployed version + T-A scratch live proof (felhom-pve)

• Built felhom-agent 0.52.0 on 180 (sha256 5bfc690c421b7799…); deployed to felhom-pve (backup /usr/local/bin/felhom-agent.bak-0.51.0, install -m0755, systemctl restart). Verified: felhom-agent --version = 0.52.0, systemctl is-active = active, journal clean (normal host-report + sudo pct/docker activity).
• T-A (Scenario A, cap pre-boot) — PASS. Ran the SAFE scratch bring-up on a free vmid 9300:

  felhom-agent --config /etc/felhom-agent/agent.json --selftest=bring-up -mode provision \
    -archive local:backup/vzdump-lxc-9100-2026_06_27-11_42_51.tar.zst -vmid 9300 \
    -cores 1 -memory 1024 -keep
  → bring-up record: Pass=true, Verified="boot+running", 18s
  pct config 9300:
      cores: 1
      memory: 1024
      rootfs: local-lvm:vm-9300-disk-0,size=32G
  pct destroy 9300 → DESTROYED (confirmed gone)
  

  The guest booted+ran with cores:1/memory:1024 = the cap was written into the pre-start config PUT (guest never ran uncapped). Scratch guest torn down; guest 9201 untouched.

6. Served/published + hub manifest

• Gitea generic package published: admin/generic/felhom-agent/0.52.0/felhom-agent, sha256 5bfc690c421b7799f4e0640f13559c41e5933ee60962bf80471eca7eae0e94cb. Publish did delete-then-PUT + a round-trip GET sha verify (fetchable + intact end-to-end). Re-fetched independently: 12 964 463 bytes, sha 5bfc690c….
• Hub artifact manifest — NOT fully bumped (required operator follow-up). The env fallback on the hub deploy was set to ARTIFACT_AGENT_VERSION=0.52.0 / the new sha (live pod confirms). BUT the hub seeds env only into an empty DB field (cmd/hub/main.go L164 if m.AgentVersion == ""), and the stored manifest already holds 0.43.0, which wins. GET /api/v1/artifacts/{customer} therefore still returns agent 0.43.0. The only in-app editor is the password-gated operator UI (Configs → Day-0 artifacts / handleSetArtifacts), which I cannot submit; the alternative (a direct write to the live operator-backend DB — no sqlite3 in the pure-Go hub image) is beyond this task's risk envelope. ACTION REQUIRED before a colleague uses --cores/--memory on a fresh install: an operator must set the artifact manifest to agent 0.52.0 / sha 5bfc690c421b7799f4e0640f13559c41e5933ee60962bf80471eca7eae0e94cb in the hub UI (the binary + env fallback are already in place).

7. NOT yet live-validated — awaiting supervised run

• A capped real customer --selftest=provision (full slice-8A chain with -cores/-memory against a real customer/guest). The T-A scratch bring-up above is the safe mechanism proof; a real capped customer provision is the supervised step (colleague's box).

8. Observations (noticed, NOT acted on)

• Pre-existing flake internal/escrow/TestGenerateRecoveryCode_EntropyAndFormat — the wordlist contains hyphenated entries (e.g. "yo-yo"); the test derives word count via strings.Split(code,"-"), so a hyphenated word inflates the count to 11 and the == 10 assertion fails ~1/5 runs. Fix is a test/wordlist concern in a package outside this task's scope; left untouched.
• The hub artifact manifest was already stale (0.43.0) before this task — fresh installs were fetching an old agent regardless. Bumping it (item 6) also resolves that lag.