felhom-agent/REPORT.md

REPORT — build-golden.sh v2.0.0: golden 0.98.3 rebuild (drill B5 + B1)

Date: 2026-07-03 · Class: implementation + clean-room drill (script-only — no Go code, no binary, no agent version bump; docs-only precedent) · Source findings: felhom.eu/documentation/audits/DRILL-day0-cleanroom-2026-07-03.md B5/B1 + the stale backlog note FOLLOWUP-golden-default-controller-tag.md (now resolved). Full drill evidence: felhom.eu/documentation/audits/DRILL-golden-098-2026-07-03.md.

Baselines & commits

What	Value
Base	c9f963d
Script commit	ceca355 — configs/build-golden.sh v2.0.0 + CHANGELOG
Docs commit	(this one — REPORT/CONTEXT)
felhom.eu	guide/ledger/backlog/evidence-doc push (see that repo's REPORT)
Controller tag baked	0.98.3 (reconfirmed current: CHANGELOG top + manifest HTTP 200 pre-bake)

What changed (configs/build-golden.sh only)

1. B5 — CONTROLLER_IMAGE (arg 6) MANDATORY: no default; missing → die with usage naming the convention. Rationale in-file: the hand-bumped default rotted twice (0.43.0 → 0.85.1 → stale again); a required arg cannot rot; auto-"latest" could bake an unvouched tag. Red-proof: the no-arg invocation exits 1 with the usage BEFORE any pct op (run locally + in the drill VM).
2. B1 — baked felhom-controller-bootstrap.path (PathExists=/etc/felhom-bootstrap/bootstrap.json, enabled, WantedBy=multi-user.target): starts the Condition-gated oneshot service when the agent back-half hot-plugs the bootstrap mount into the RUNNING guest. Service unchanged (RemainAfterExit=yes prevents re-trigger loops; the enabled service still covers the plain boot case). The mp0/mp1 vzdump-inclusion guards untouched.
3. GOLDEN_SCRIPT_VERSION=2.0.0 + [golden] provenance line (script version + baked tag) opening every bake transcript. Gates: bash -n clean; usage renders.

Clean-room validation (drill VM on 192.168.0.180, virgin-restored per scenario)

Scenario	Result
A — bake integrity	PASS: provenance line; controller 0.98.3 + infra images baked; docker logout + config.json removal before archive (line present, ran); vzdump including mp0 AND mp1; archive 583 MB, sha256 b9a02ef1b6f02b9b58babc4c6aad9cf6c053ebdfba116c78c8e7830de757fd01; guest 9100 destroyed
B — isolated hot-plug (STOP gate)	PASS: fresh restore w/o mount → service inactive (dead) condition-unmet, path active (waiting); back-half-identical pct set -mp9 …,mp=/etc/felhom-bootstrap,ro=1 on the RUNNING guest → service SUCCESS ~1 s later, controller Up (healthy) 0.98.3, uptime -s unchanged (no reboot)
C — local-golden Day-0 (publish gate)	PASS: served installer v1.9.1, canonical command w/o --force-gitea-golden → [SKIP] using local golden (resolution order); first boot controller 0.98.3, NO D.1b; selfupdate/check → update_available:false (self-manages); selftest all-OK incl. pool read; bentopdf deployed via the dashboard endpoint → 200 via traefik; hub rows: agent 0.63.0 / controller 0.98.3
Publish	PUT …/felhom-golden/0.98.3/golden.tar.zst → 201; round-trip GET sha matches (publish-agent.sh pattern mirrored)
Vouch	operator vouched golden 0.98.3 in the Day-0 manifest (agent 0.63.0 already vouched — the v0.63.0 follow-up is DONE); confirmed via /api/v1/artifacts
D — published-artifact Day-0	PASS: virgin box, no local golden → fetching golden v0.98.3 from Gitea → verified sha256 b9a02ef1… matches the hub manifest → SUCCESS; first boot 0.98.3; up-to-date. The exact fresh-customer path

Cleanup: all drill-1 hub rows deleted (8 tables, counts 0; demo-felhom/peti-felhom intact); drill VM reverted to virgin and kept; bake credential env (0600) removed. Registry read-cred handled via env only — never logged/committed.

Deviations & observations

• Premature publish (caught + corrected): the script's opt-in publish block triggers on the same REGISTRY_* vars the pull needs — the Scenario A bake published immediately, before the Scenario C gate. Package DELETEd (204, anon 404 verified) and re-published only after C passed. Candidate cleanup (not done — no-"while-here" rule): a separate GOLDEN_PUBLISH=1 opt-in.
• SECURITY (operator follow-up): the pull credential — the demo customer's git.token, i.e. what every customer box holds — turned out to be a Gitea admin token with package-WRITE (the premature publish proved it). Scope down to read-only + rotate.
• Installer v1.9.1's post-provision reboot is now a redundant belt (the path unit deploys first) — removal recorded as a candidate installer cleanup, kept for now.
• Drill-env: dhcpstart=10.0.2.30 + explicit hostfwd…-10.0.2.15:22 on the QEMU command removes the prior drill's slirp IP-collision quirk entirely.
• Guide follow-through (felhom.eu): D.1b retired to a one-line version check; troubleshooting row covers pre-0.86.0 goldens; ledger B1/B5 FIXED; backlog note resolved.