felhom.eu/REPORT.md

felhom.eu — task reports

Overwrite this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in hub/CHANGELOG.md; the scripts history lives in scripts/CHANGELOG.md.

---

REPORT — appliance CPU/RAM cap passthrough (--cores / --memory) (host-install v1.4.0)

Date: 2026-07-01 · Repo: felhom.eu (scripts/ only)

Colleague-safety batch #3 (host-install half; the cap mechanism is agent v0.52.0, a separate repo/task). Adds optional --cores/--memory passthrough so an operator can cap the provisioned appliance guest and keep it from pressuring a colleague's existing guests on a shared production host.

1. Confirmed baseline

Repo	main @ commit	Current	→ Target
felhom.eu (scripts/felhom-host-install.sh)	710afb0	script v1.3.0	v1.4.0

2. Files changed + commit

• scripts/felhom-host-install.sh (v1.3.0 → v1.4.0).
• scripts/CHANGELOG.md — v1.4.0 entry.
• REPORT.md — this file (overwritten).
• Commit f7905b7 on main (parent 710afb0).

3. What was implemented

• --cores N / --memory M (MiB) — new vars CPU_CORES/MEM_MIB; arg-parse entries; usage() header gains an "Appliance cap (optional)" group (needs agent ≥ v0.52.0; 0/unset = golden default).
• Conditional passthrough — step_provision builds a cap_args array (-cores/-memory appended only when set) and passes it to BOTH the dry-run log and the real agent --selftest=provision call. Never sent unset, so an agent < v0.52.0 never sees an unknown flag.
• Pre-flight sanity WARN (soft, provision only) — if --cores > host nproc or --memory > host MemTotal, log_warn; never die.

4. Green gate

• bash -n scripts/felhom-host-install.sh → OK (locally + on felhom-pve).
• shellcheck v0.10.0: v1.4.0 = 2× SC2015 (info) at lines 1160 & 1170 — both the pre-existing step_verify A && B || C lines, unchanged. 0 new warnings vs. the v1.3.0 baseline.

5. Tests → §7 mapping (dry-run transcripts on felhom-pve; real demo customer via 0600 passphrase-file, free vmid 9300)

#	Scenario	Result
T-C	script passthrough	PASS — --cores 2 --memory 4096 --dry-run → provision command shows … -sysdata-grow 42 -cores 2 -memory 4096.
T-C⁻	no cap → flags absent	PASS — without --cores/--memory the provision command ends … -sysdata-grow 42 with NEITHER flag.
T-D	sanity WARN	PASS — --cores 64 --memory 65536 --dry-run (host = 4 cores / ~15771 MiB) → two WARN lines: "requested cap (64 cores) exceeds host cores (4)…" and "requested cap (65536 MiB) exceeds host RAM (~15771 MiB)…"; does not die.

(T-A cap-pre-boot + T-B omit-when-zero are the AGENT side — see felhom-agent/REPORT.md: live scratch bring-up on vmid 9300 showed cores:1/memory:1024, then destroyed; TestBuildBringUpConfig_ResourceCaps

• red-proof.)

6. Served-copy version check

curl -fsSL https://felhom.eu/scripts/felhom-host-install.sh | grep SCRIPT_VERSION

→ SCRIPT_VERSION="1.4.0" (served copy confirmed ~1 min after push).

7. Hub artifact manifest status — REQUIRED FOLLOW-UP

The --cores/--memory passthrough depends on a fresh install fetching agent ≥ v0.52.0. Status:

• ✅ Agent v0.52.0 published to Gitea (admin/generic/felhom-agent/0.52.0/felhom-agent, sha 5bfc690c421b7799f4e0640f13559c41e5933ee60962bf80471eca7eae0e94cb, round-trip verified).
• ✅ Hub deploy env fallback bumped to ARTIFACT_AGENT_VERSION=0.52.0 + new sha (seeds an empty manifest).
• ❌ The served manifest still returns agent 0.43.0 — the hub seeds env only into an empty DB field and the stored value (0.43.0) wins. The manifest can only be changed via the password-gated operator UI (Configs → Day-0 artifacts), which is out of CC's reach. An operator must set the artifact manifest to agent 0.52.0 / sha 5bfc690c421b7799f4e0640f13559c41e5933ee60962bf80471eca7eae0e94cb before the colleague uses --cores/--memory on a fresh install. (Details in felhom-agent/REPORT.md §6.)

8. NOT yet live-validated — awaiting supervised run

• A capped real customer provision end-to-end via the script (--cores/--memory without --dry-run against a real customer/guest) — the supervised step on the colleague's box.

9. Observations (noticed, NOT acted on)

• The hub artifact manifest was already stale (agent 0.43.0) before this task; fresh installs fetched an old agent regardless of this change. The operator manifest bump in §7 also clears that lag.
• Spec 2's sibling items #4 (pool-scoped ACL) is a separate later task; not touched here.