# 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](hub/CHANGELOG.md); the scripts history lives in [scripts/CHANGELOG.md](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.