felhom.eu/REPORT-iso-release.md

REPORT — the universal ISO: built and gated, NOT PUBLISHED (2026-07-31)

Nothing was published. Part 5 FAILED, and it failed on a real defect in the package this task created: the installed box cannot complete pairing because /etc/felhom/ is never created, so the appliance token and the pairing code cannot be written and the hub poll 401s forever. Per the task: "If either fails, stop. Report it and publish nothing." — §6 is the finding.

Written as REPORT-iso-release.md, not root REPORT.md, per the task and the shared-clone rule.

1. Venue and baselines

Host	demo-hp (t740), Tier 0
VMs	500 spike5-gfx, 501 spike5-tui — both created with qm so the run is visible in the web console
Storage	spike5, dir at /mnt/nvme-1tb — the mount ROOT, content=images. Root chosen deliberately: a storage at a subdirectory reads disconnected forever via the agent's exactMount check. It coexisted with felhom-backup on the same path, which was not modified
Console	web console → VM → Console, or qm terminal/qm monitor <vmid>
Disposition	both VMs purged, storage removed — §9

Baseline	Value
ISO_VERSION	1.26.0 (was 1.25.0) — scripts/iso/build-felhom-iso.sh:51
SCRIPT_VERSION	1.22.0 — scripts/felhom-host-install.sh:187
felhom-bootstrap.sh @ HEAD	21bf6a6bde0cb13e3809e2f5c136a49929dcc82eb8d40bbdf6f290a886ee8ab7
PVE base	proxmox-ve_9.2-1.iso, 4e88fe416df9b527624a175f24c9aa07c714d3332afb1ee3dbf3879573ef2c6c
controller on main	0.188.0 (4115e88)
felhom.eu HEAD at build	clean, pushed, == origin/main

2. The release gate — committed first, on its own

documentation/runbooks/iso-release-gate.md, commit e787391, written and pushed before the first build so it could not be rationalised afterwards. Twelve criteria, each checkable against the uploaded file rather than the build inputs, each carrying the spike measurement that justifies it.

One criterion was amended before the build, with its reasoning recorded in the runbook. G6 was first written with the six-token ban iso-repack.sh:160-164 enforces, on the rationale "no live route to a manual disk-picker". That rationale is obsolete for a public image — the ruling makes the manual installer the product. proxtui (the Terminal-UI installer we deliberately ship) and nomodeset (its graphics fallback) are dropped for release images only; proxdebug, Rescue Boot, memtest and fwsetup stay banned in both modes, and the six-token list is unchanged for appliance images.

3. The stub package

scripts/iso/pkg/ — source committed, built by build-deb.sh.

Contents: exactly two files, deliberately not three.

-rwxr-xr-x ./usr/local/sbin/felhom-bootstrap.sh
-rw-r--r-- ./lib/systemd/system/felhom-bootstrap.service

The old first-boot stub also wrote /etc/felhom/bootstrap.env (0600). This package does not: felhom-bootstrap.sh:91 reads it only if [[ -r ]], and its defaults at :95-96 (https://hub.felhom.eu, https://felhom.eu/scripts/felhom-host-install.sh) are exactly what the generic pairing env set (build-felhom-iso.sh:257-258). Shipping it would add a 0600 file to a public package to express values the script already defaults to.

Dependencies: none, and that is a finding. dpkg-deb -I shows no Depends line. The payload is a shell script and a unit file; the binaries the script calls (curl, ip, dhclient, python3, systemctl) run at first boot, not at postinst time. Spike 4's open dpkg --configure -a ordering question therefore does not arise — confirmed, not carried.

How the postinst is structurally incapable of failing — no set -e, every statement individually guarded with || true or an if, and an unconditional exit 0. build-deb.sh refuses to emit a package that violates any of it.

The guarantee was tested, not asserted. Seven hostile conditions, each requiring exit 0:

Condition	Exit
no systemd running, systemctl present (the real chroot)	0
systemctl removed entirely	0
systemctl replaced by a binary that always exits 7	0
/var/log read-only	0
/etc/systemd read-only	0
called abort-upgrade	0
called with no argument	0

4. The repack — two changes, both narrowing rather than deleting

R-155's guard (iso-repack.sh:100-106) protected the single-entry mode's promise: that menu shows one item labelled "Felhom telepítés" which boots the automated installer, and without auto-installer-mode.toml the same label would drop the user into a manual disk-picker — a button promising an unattended install that silently does the opposite. That promise is real, so the guard is kept unchanged for FELHOM_MENU=single and simply does not apply to release, where the absence of that file is release-gate criterion G1 rather than a defect.

The menu collapse happens at iso-repack.sh:144-148 (the stock grub.cfg is replaced by a rendered template). A release template now renders two interactive entries; entry-count and banned-token gates are per-mode; the post-remaster verification reads the count back out of final.iso.

Ruling — default entry and timeout. Default is the graphical interactive entry; timeout 15 s. Reasoning: Spike 1 measured that no automated disk selection can be safe on unseen hardware (no property distinguishes an internal disk from a customer's backup drive; a two-disk match silently wipes one), so a public image whose default is unattended puts the unsafe path in front of anyone who boots and walks away. And Spike 2 lost a probe to a 1-second menu — a person reading two options needs longer than a machine.

The automated entry is absent, not broken. Skipping prepare-iso means no auto-installer-mode.toml, and the stock grub.cfg emits the Automated entry only inside if [ -f auto-installer-mode.toml ]. There is no entry that could fail in front of a customer.

5. R-128 — FIXED, by correcting the claim rather than asserting it

build-felhom-iso.sh:44 claimed ISO_VERSION "aligns with felhom-host-install SCRIPT_VERSION". Nothing evaluated it and the two had drifted. I did not turn it into a real assertion, because the coupling it claimed does not exist: the ISO is a frozen artifact, while felhom-host-install.sh is fetched at run time from the website's git-sync of main (R-94/R-110), so whatever version an ISO carries, the script a box runs is always current. An assertion would invent a constraint. The comment now states the independence, and ISO_VERSION is 1.26.0.

6. Part 5 — FAILED. A real defect in the package. Nothing was published.

The Terminal UI entry — 3 of 4 observables pass, the fourth fails

Normal manual install from the release image: own disk (/dev/sda, shown by the installer with its data-loss warning), own password, own FQDN. Installed host spikefive.felhom.eu, pve-manager/9.2.2. Completion signal: the installer wrote 7.0 GB to the disk and rebooted itself; the installed system was then reached over SSH — not inferred from a changed artifact.

#	Observable	Result
1	the .deb is installed	PASS — ii felhom-bootstrap 1.26.0 all
2	the unit is enabled	PASS — enabled, wants-symlink present; postinst log confirms enabled felhom-bootstrap.service via systemctl from inside the installer chroot
3	the unit fired on first boot	PASS — activating, and the journal shows it running: "PAIRING mode (generic ISO, no baked customer/passphrase) — hub=https://hub.felhom.eu" → "registering unclaimed appliance at the hub"
4	the box reaches the point of wanting a claim code	FAIL

The defect, and it is mine

felhom-bootstrap.sh[1105]: /usr/local/sbin/felhom-bootstrap.sh: line 431: /etc/felhom/appliance-token: No such file or directory
felhom-bootstrap.sh[1067]: /usr/local/sbin/felhom-bootstrap.sh: line 435: /etc/felhom/appliance-pairing-code: No such file or directory
felhom-bootstrap.sh[1067]: felhom-bootstrap: poll returned HTTP 401 — still retrying

/etc/felhom/ does not exist on the installed system, so the appliance token and the pairing code cannot be written, and the poll then 401s forever because there is no token to authenticate with. The box can never finish pairing, and the customer never sees a claim code.

Root cause. The old stub-first-boot.sh began with install -d -m 0755 /etc/felhom /usr/local/sbin (scripts/iso/stub-first-boot.sh). §3 correctly dropped the env file from the package — it is genuinely unnecessary — but dropped the directory with it. felhom-bootstrap.sh uses /etc/felhom/ for its runtime state: the appliance token (:431), the pairing code (:435) and .bootstrap-done (the unit's ConditionPathExists).

Why the gate did not catch it. G9 asserts the packaged felhom-bootstrap.sh is byte-identical to repo HEAD, and it is. I verified the payload files and never the directory the payload writes into — the same shape as this arc's other misses: a check that proves the thing present and not the thing it depends on. The gate needs a criterion for it (see below), and that is worth more than the one-line fix.

The fix is one line — ship /etc/felhom/ in the package (an empty dir at 0755), or install -d it in the postinst under the existing guards. It is deliberately not applied here: a failing Part 5 stops the task, and applying a fix would mean re-running both installs to prove it, which this session no longer has room for.

The Graphical entry — not completed

VM 500 booted the graphical entry from the same image and reached the installer: the KVM-support dialog, the EULA, and the Target Harddisk screen showing /dev/sda (20.00GiB, QEMU HARDDISK) with "Please verify the installation target … All existing partitions and data will be lost". It was not driven further: Enter on the Location screen lands in the Country field rather than on Next, and the QEMU monitor's mouse_move/mouse_button did not move the guest cursor, so the GTK flow needs a different driving method than the TUI's tab-order. Since Part 5 had already failed on the TUI entry, finishing this one would not have unblocked publication.

A fixture bug of mine, recorded because it cost a diagnosis

qm set <vmid> --scsi0 … --boot order="scsi0;ide2" silently produced boot: order=net0;ide2 — PVE processed --boot before --scsi0 existed and substituted a default. Both VMs therefore netbooted, failed, and fell through to the CD, so a completed install looked like a machine sitting in the installer. Diagnosed from qm config and the 7.0 GB disk, not from the screen. Set --boot in a separate qm set after the disk exists.

7. Part 6 — the gate, run against the built artifact

Run against felhom-installer-1.26.0-pve9.2-1.iso, sha256 24977bafd24d73262745fc1b3040939469c9b23b87ead927a8af86de73044a90, 1 705 322 496 bytes.

#	Criterion	Scanned for	Result
G1	no answer.toml / auto-installer-mode.toml	both names at ISO root	PASS — 0
G2	no root password or hash	.rootpw.txt companion; the answer file that would carry a hash	PASS — no .rootpw.txt emitted; no answer file exists to hold one
G3	no SSH key	root-ssh-keys, ssh-rsa, ssh-ed25519	PASS — no answer file; package carries only a script and a unit
G4	no customer identity	FELHOM_CUSTOMER_ID/RETRIEVAL_PASSPHRASE with values, claim code, api key, Bearer	PASS — only the empty initialisers at felhom-bootstrap.sh:89
G5	credential scan by enumeration vs the stock PVE ISO	full recursive file-list diff, both directions	PASS — exactly four added paths: the three felhomtheme/ files and /proxmox/packages/felhom-bootstrap_1.26.0_all.deb; three removed (pvetheme/)
G6	menu present, both paths, human timeout	entry count, set default/timeout/timeout_style, banned tokens	PASS — 2 entries, default=0 (graphical), timeout=15, timeout_style underscore
G7	one felhom-*.deb, version recorded	/proxmox/packages/felhom-*	PASS — exactly 1, Package: felhom-bootstrap, Version: 1.26.0, no Depends
G8	postinst cannot fail	live (comment-stripped) systemctl start|daemon-reload|restart, network commands, set -e, last line	PASS — 0, 0, 0, ends exit 0
G9	felhom-bootstrap.sh == repo HEAD	sha256 of the packaged file vs the repo file	PASS — both 21bf6a6bde0cb13e3809e2f5c136a49929dcc82eb8d40bbdf6f290a886ee8ab7
G10	build inputs committed	git status --porcelain, HEAD vs origin	PASS — clean and pushed at build time
G11	published checksum + round trip	—	NOT RUN — nothing was published
G12	bucket stays private	—	NOT RUN — the bucket was never touched
G13	(new, from Part 5's failure) the package creates every directory its payload writes into	/etc/felhom/ present after install	would have FAILED — see §6

A gate refinement found by running it. G7 also asked that the ISO's copy of the .deb sha256-match the package built from source. It does not, and cannot: dpkg-deb embeds build timestamps, so two builds of identical source differ. G9 — the payload's identity — is the meaningful check, and it passes. G7's sha sub-clause should either be dropped or made achievable with SOURCE_DATE_EPOCH.

8. Publication — did not happen

The R2 credentials in ~/.config/credentials were never read, never used, never echoed. No rclone or aws configuration file was created anywhere. Nothing was uploaded; no bucket setting was changed; iso.felhom.eu was not contacted. There is no public URL to report because there is no published object.

9. Teardown

demo-hp: VMs 500/501 qm destroy --purge; storage spike5 removed (storage.cfg back to 4, grep -c spike5 = 0); /mnt/nvme-1tb/images/ empty; usage 6.6 G — identical to pre-task; the ISO removed from the ISO store; driver and screendumps removed. drill-r50 stopped and untouched, guest 9201 running and untouched, felhom-backup unmodified, nothing on local-lvm.

demo-felhom: not contacted this session.

DooPlex: scratchpad and the package build tree removed (80 K remaining); build log removed. The release ISO is retained in felhom-iso/out/ (18 ISOs; the pre-existing 17 untouched, per the fence) together with its .sha256 and manifest — unpublished, and with no .rootpw.txt, which is itself G2's evidence. Repo tree clean and pushed.

Hub-side: nothing created. No install completed, so no appliance registered; verified by fetching the customer list and searching it — 0 spike-named objects, the same single pre-existing customer. R-131 gains no row.

10. R-dispositions

One new row is warranted (§6's defect), and it was grepped against the register first — no existing row covers /etc/felhom or the package's directory set (grep -rn 'etc/felhom' documentation/backlog/ returns nothing about package contents). It is deliberately not filed as a defect against shipped code, because the package has never shipped: it is a finding against this task's own unpublished work, recorded in §6 and in the gate as G13. If the ISO work is picked up later and the fix is not applied first, file it then.

Otherwise, no new rows. Each candidate was grepped against the register first:

• R-128 — FIXED here (§5).
• R-155 — RESOLVED here (§4): the guard is narrowed, not deleted.
• R-154 ([first-boot] is automated-only and nothing in the tree says so) — addressed in code rather than by a row: pkg/build-deb.sh's header and grub-release.cfg.tmpl both state it with the measurements. The register row can close when the docs land.
• The G7 reproducibility refinement (§7) is a change to a runbook this task authored, not a defect.

11. What did not happen, and why

• Part 5 — the TUI entry ran to completion and failed on observable 4 (§6). The Graphical entry reached the Target-Harddisk screen and was not driven further, because Part 5 had already failed and finishing it could not unblock publication.
• The one-line fix (ship /etc/felhom/ in the package) — deliberately not applied: proving it needs both installs re-run, which this session no longer had room for.
• Part 7, publication — gated on Part 5.
• Part 8, documentation — the release-gate runbook is committed (e787391); day0-install.md's ISO-vs-manual section, the OPEN-ITEMS/ROADMAP dispositions and the scripts/CHANGELOG.md entry are not written, since documenting a release that did not happen would be wrong.
• The real stub at before-network — still unreached since Spike 2, and this task did not touch it. Note it is now narrower than it was: on the .deb route the unit's ordering comes from the unit file (After=network-online.target …), not from [first-boot].ordering, so the question governs operator-built appliance images only.