docs: F3 provisioning runbook (vmid from full host list) + campaign F1/F2 resolution banner

Companion to felhom-agent v0.60.0 (proof-of-launch destroy gating + restore- test band-advance). New documentation/runbooks/provisioning.md; campaign doc updated with the resolution status and the operator manifest-bump follow-up. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 10:27:17 +02:00
parent e59e3c0ae2
commit 6dae9d7558
3 changed files with 65 additions and 20 deletions
@@ -0,0 +1,40 @@
+# Runbook — provisioning a customer guest (operator notes)
+
+> Operational guardrails for `--selftest=provision` / bring-up on a Felhom host. The mechanics live in
+> `felhom-agent` (RUNBOOK-provisioning-storage.md + the selftest flags); this runbook records the
+> operator-side decisions those mechanics assume.
+
+## Picking the provision `-vmid` (F3 — campaign pool-effects)
+
+**Pick the vmid from the host's FULL guest list, never from the hub inventory.**
+
+On the node, as root:
+
+```
+pct list; qm list
+```
+
+Why this is load-bearing (CAMPAIGN-pool-effects-2026-07-01, F3): the agent's token is pool-scoped, so
+the hub's per-host guest inventory contains ONLY the Felhom-pool guests. On a shared box (the
+colleague's-box model), other guests — another customer's, spike/golden/scratch guests — are invisible
+in the hub view, and there is deliberately NO automatic vmid assignment anywhere (agent or hub): the
+operator-supplied `-vmid` is the only source. A vmid picked from the hub view can therefore collide
+with an existing, hub-invisible guest.
+
+What happens on a collision (belt-and-suspenders, agent >= v0.60.0): PVE refuses the restore
+("CT <vmid> already exists"), the agent arms NO destroy (proof-of-launch gating — it never destroys a
+guest the transaction didn't create), and the provision fails cleanly. So a collision is safe — but it
+is still a failed provision and an ERROR in the logs; pick from `pct list` + `qm list` and it never
+happens.
+
+Reserved — never provision on these (the agent refuses them):
+- `9999` — standing selftest scratch
+- `990000–990009` — restore-test scratch band, **reserved fleet-wide on every Felhom host**: a foreign
+  guest parked in this band forces the self-restore-test to advance around it (agent >= v0.60.0) and,
+  if the band fills, to skip entirely.
+
+## Related
+
+- Storage/sizing flags: `felhom-agent/RUNBOOK-provisioning-storage.md`
+- Pool + scoped-ACL model: `documentation/audits/SPIKE-pool-scoped-acl-2026-07-01.md`
+- Collision/pool-blindness analysis: `documentation/audits/CAMPAIGN-pool-effects-2026-07-01.md`