# 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 — `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.