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 — felhom pool as a Day-0 default (+ --adopt-pool retrofit + uninstall teardown) (host-install v1.5.0)

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

Colleague-safety batch #4 phase a. Every Felhom-managed guest now joins a dedicated felhom pool (fleet uniformity + the environment 3b will spike the pool-scoped ACL against). Script-only, all pool ops run as root@pam from the installer → NO agent/token/ACL change, zero permission risk (PVE_PRIVS untouched; the FelhomAgent token stays scoped at /).

1. Confirmed baseline

Repo	main @ commit	Current	→ Target
felhom.eu (scripts/felhom-host-install.sh)	6148e61	script v1.4.0	v1.5.0

PVE 9 pveum pool syntax + /pools JSON shape confirmed live before wiring: pveum pool add <id> [--comment] / pool delete <id> / pool modify <id> --vms <ids> (additive); pvesh get /pools → [{poolid,comment}], pvesh get /pools/<id> → {poolid,comment,members:[{vmid,type,status,…}]}.

2. Files changed + commit

• scripts/felhom-host-install.sh (v1.4.0 → v1.5.0) — the only code file.
• scripts/CHANGELOG.md — v1.5.0 entry.
• REPORT.md — this file (overwritten).
• Commit 482dbec on main (parent 6148e61).

3. What was implemented

• Part 1 — pool default: const PVE_POOL="felhom"; helpers pool_exists / pool_members (.members[].vmid) / ensure_felhom_pool / pool_add_guest (skip-if-member). step_provision ensures the pool then adds the guest after a successful provision (dry-run prints both).
• Part 2 — --adopt-pool: early root-only dispatch + run_adopt_pool — resolves the vmid (--vmid else recorded provisioned_vmid), requires the guest to exist, ours-checks the /etc/felhom-bootstrap mount (refuse non-Felhom unless --force), ensures the pool, adds the guest. Membership-only; never reconfigures/restarts the guest; no hub contact.
• Part 3 — uninstall teardown (step 5b): after the pveum removal, pveum pool delete felhom only if empty; otherwise log_skip naming the members. Summary line notes the pool when removed. Not reached on the Spec-1 safe-skip path.
• Usage header gains a "Retrofit" group; every pool mutation goes through run() (dry-run-aware).

4. Green gate

• bash -n scripts/felhom-host-install.sh → OK (local + felhom-pve).
• shellcheck v0.10.0 → 2× SC2015 (info) at lines 1286 & 1296, both the pre-existing step_verify A && B || C lines. 0 new warnings.

5. Tests → §7 mapping (felhom-pve; dry-run + SAFE live)

#	Scenario	Result
T-A	fresh install (dry-run)	PASS — --customer-id demo-felhom --vmid 9300 --dry-run at step 8/8 prints [DRY-RUN] pveum pool add felhom --comment Felhom-managed guests + [DRY-RUN] add guest 9300 to pool felhom.
T-B	live adopt of 9201	PASS — --adopt-pool --vmid 9201 → ours-check passes, guest 9201 added to pool felhom. pvesh get /pools/felhom → members:[{…,"vmid":9201,"status":"running","type":"lxc"}]; 9201 still running, config unchanged (membership-only). The demo node is now pool-uniform.
T-D	idempotency	PASS — re-run --adopt-pool --vmid 9201 → [SKIP] pool felhom already exists + [SKIP] guest 9201 already in pool felhom (no-op).
T-B'	ours red-proof	PASS — --adopt-pool --vmid 9001 (no bootstrap mount) → die "does not look like a Felhom-provisioned guest … Refusing to adopt. Pass --force", exit 1, pool membership unchanged.
T-C	uninstall empty-guard	PASS — --uninstall --vmid 9201 --dry-run → [SKIP] pool felhom not empty (members: 9201) — leaving it (guest not destroyed in dry-run, so the pool retains 9201 → the delete-only-if-empty guard is proven).

6. Served-copy version

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

→ SCRIPT_VERSION="1.5.0" (confirmed ~1 min after push).

7. NOT yet live-validated — awaiting supervised run

• A live --uninstall (now also deletes the pool when empty) — the destroy path remains the supervised STOP carried over from Spec 1; the pool-delete-if-empty branch is proven only in dry-run.

8. Observations (for 3b, not acted on)

• /pools API shape confirmed for 3b: list = [{poolid,comment}]; detail = {members:[{vmid,type, status,node,…}]}. pveum pool modify <id> --vms <ids> is additive (a --delete 1 variant removes; --allow-move if a guest is already in another pool).
• 3b (the actual permission change) will add a /pool/felhom-scoped ACL + Pool.Allocate and make the agent restore INTO the pool under a scoped token — deliberately NOT attempted here (spike-gated).
• The demo felhom pool now exists with 9201 as its member — a ready environment for the 3b spike.