felhom.eu/documentation/backlog/DIAGNOSIS-f9-storage-registration-gap-2026-06-14.md

DIAGNOSIS — post-F9 storage-registration gap (read-only; no system changes made)

Date: 2026-06-14. Scope: why the HDD (felhom-usb) is attached + written-to by RomM yet badged "Nem regisztrált" and absent from the deploy dropdown. Method: live SSH (read-only) + controller source. No state changed — no registration, deploy, restart, or edits. Diagnosis only; fix to be specced next.

TL;DR

F9 attached the HDD at the agent/guest layer (the pct set -mpN bind). The controller's storage registry (settings.json → storage_paths) is a separate layer that F9 never touched. The controller registers a drive only through its own enroll flows (runStorageInit / runStorageAttach / handleStorageRegister), each of which calls registerStoragePath. In the F9 session the drive was attached by calling the agent's /disks/guest-attach directly (and RomM got HDD_PATH=/mnt/felhom-usb via a manual deploy value) — both bypass the controller's registry. Auto-discovery can't backfill it (it's a one-time seed that only scans deployed-app HDD_PATHs, never the agent's attached-drive list). Result: attached + in use, but unregistered → not selectable for a new app. F9 is NOT closed.

Q1 — Real storage topology (what each path maps to)

Name (UI)	Host path	Device	Size / free	What it is
Tárhely (felhom-data) ★ (registered)	/mnt/sys_drive/felhom-data	/dev/mapper/pve-vm--9201--disk--0	32 G / ~29 G	the internal OS-disk volume (rootfs disk-0). The "28.7 GB szabad" in the dropdown = this.
felhom-usb (NOT registered)	/mnt/felhom-usb	/dev/sdb1	916 G / 870 G	the HDD, guest-attached (mp1), 2.1 MB used

Evidence: pct config 9201 → mp1: /mnt/felhom-usb/felhom-data,mp=/mnt/felhom-usb; guest df → /mnt/sys_drive on …disk--0 (32 G, 29 G avail) vs /mnt/felhom-usb on /dev/sdb1 (916 G, 870 G avail). The registry (settings.json) lists only {"path":"/mnt/sys_drive/felhom-data","label":"Tárhely (felhom-data)","is_default":true,"added_at":"2026-06-13T22:22:50Z"}. Confirmed: the "28.7 GB" option is the internal volume, not the HDD.

Q2 — Where RomM's data is + how it got an HDD path

• RomM's app.yaml (/opt/docker/stacks/romm/app.yaml): env.HDD_PATH: /mnt/felhom-usb, deployed: true, locked_fields: [HDD_PATH]. Its data dirs live under /mnt/felhom-usb/felhom-data/appdata/romm/… (the HDD).
• How it got set: the HDD_PATH deploy field was filled with /mnt/felhom-usb when RomM was (re)deployed onto the HDD during the F9 P3/restore test. The deploy path validates os.Stat(HDD_PATH) exists (stacks/deploy.go path-field check) — it does, because F9 had bound /mnt/felhom-usb into the guest — but the deploy does NOT register the path in storage_paths. So RomM references the HDD path directly, entirely independent of the registry. That's how "RomM uses the HDD" coexists with "HDD unregistered."

Q3 — Why felhom-usb is "Nem regisztrált"

The registry (settings.json storage_paths) contains only /mnt/sys_drive/felhom-data; /mnt/felhom-usb is absent. Nothing registered it, at any layer:

• F9's attach is agent-layer only. ReassertGuestBinds / handleDiskGuestAttach → guestbind.go AttachBind do pct set -mpN (the bind). They never call the controller's registerStoragePath. In the F9 session the drive was attached by calling the agent /disks/guest-attach directly, bypassing the controller enroll flow.
• Deploy doesn't register. Setting HDD_PATH on RomM only validates existence (above), no registry write.
• Auto-discovery can't backfill it — two reasons in settings.AutoDiscoverStoragePaths (internal/settings/settings.go:584):
  1. One-time seed: if len(s.StoragePaths) > 0 { return // already configured } (≈:592). The registry already holds sys_drive (seeded 2026-06-13), so discovery is now permanently inert on every restart.
  2. Wrong source even if it ran: it's fed by discoverHDDPaths(StacksDir) (cmd/controller/main.go:1337, called once at startup, main.go:126), which scans deployed apps' HDD_PATH — never the agent's /disks attached-drive list. A drive attached out-of-band (or whose app was deployed after startup) is invisible.

So: registration is decoupled from attach; auto-discovery is a one-shot startup seed of app HDD_PATHs; the agent-layer F9 bind and the manual deploy both bypass registration → the HDD stays unregistered.

Q4 — Why the deploy dropdown excludes the HDD

The deploy dropdown is populated from s.settings.GetSchedulableStoragePaths() (internal/web/handlers.go:323), i.e. registered paths only. /mnt/felhom-usb is not in the registry → not schedulable → absent. So a new app (Calibre) can only be pointed at sys_drive (the 31 G internal volume). The "Nem regisztrált" badge is the storage page (storageWizardPageHandler) merging the agent /disks (attached, guest_attached=true) against GetStoragePaths() (registry) and flagging the difference (storage_handlers.go Registered field; settings.html window.__registeredPaths).

Q5 — Intended registration-vs-attach behavior (per the code)

The controller's design intends register + attach as one operator-driven enroll operation, NOT an automatic side-effect of an agent bind:

• runStorageInit (format a blank/new drive) and runStorageAttach (mount an existing-fs drive — the "Csatolás" button) both do: assign (host mount) → registerStoragePath → attachIntoGuest→agent.GuestAttach (internal/web/storage_handlers.go:83-158). The comment is explicit: "the StoragePath registration is the durable intent, so a transient attach failure is logged (not fatal) — P3 self-heal completes it."
• For an already-mounted, unregistered drive (exactly felhom-usb's state), there is a dedicated action: POST /api/storage/register → handleStorageRegister (storage_handlers.go:442, the "Regisztrálás" button), commented: "the natural primary action for a mounted-but-unregistered data drive (e.g. felhom-usb): the customer's intent is to USE the existing data, not wipe it… registering a host-only mount otherwise leaves it guest-invisible (the exact gap that produced the 'nem elérhető' banner)." It registers + attaches into the guest.

So per the code, registration is meant to come through these controller flows. There is no reconciliation that auto-registers a drive the agent attached out-of-band — which is precisely the F9 case (the agent's re-assert / a direct guest-attach binds the drive without ever invoking the controller's register step).

Q6 — The "felhom-data" naming collision

Deliberate convention, but genuinely confusing. felhom-data is BOTH:

1. the path tail of the internal volume's registered path (/mnt/sys_drive/felhom-data), surfaced as the label Tárhely (felhom-data), and
2. the per-drive Felhom namespace subdirectory created on EVERY user-data drive by the agent's AttachBind (guestbind.go:29 felhomDataNS = "felhom-data", "matches appbackup.FelhomDataDir") — hence /mnt/felhom-usb/felhom-data/…. So felhom-data denotes both a specific volume and the generic namespace. Risk: the label Tárhely (felhom-data) reads as generic but is specifically the OS-disk volume; meanwhile the HDD also has a felhom-data dir. A clearer label (e.g. "Belső SSD" for the internal volume vs the drive's own name for the HDD) would remove the ambiguity.

Recommended fix direction (to spec next — NOT implemented here)

1. Auto-register on attach (primary). REJECTED (2026-06-14) — contradicts the new→enrolled manual-enrollment model; manual enroll is by design. A drive becomes usable through the explicit enroll/"Regisztrálás" flow (recommendation #2), not by auto-registering whatever the agent attached out-of-band. (The "make discovery additive, not return-if-any-path-exists" sub-point WAS adopted — shipped in controller v0.64.0, A1 — but only as additive pickup of paths referenced by deployed apps, NOT as auto-register-on-attach.) Make a drive the agent has attached into the guest become a registered storage path automatically, so F9's attach is usable end-to-end. Options: (a) the controller's startup/periodic storage reconcile consults the agent /disks and registers any guest_attached=true user-data drive missing from the registry (extend beyond the app-HDD_PATH scan); and/or (b) the enroll/re-assert path that binds a drive also performs registerStoragePath. Also remove the one-time-seed gate (or make discovery additive, not "return if any path exists") so it can pick up drives added after the first run.
2. Keep handleStorageRegister as the explicit fallback ("Regisztrálás" button) for the mounted-but-unregistered case, and make the "Nem regisztrált" badge clearly actionable. For the immediate demo state, this button (POST /api/storage/register {where:/mnt/felhom-usb}) would register felhom-usb + make it selectable — no fix needed to recover now.
3. Clarify the felhom-data label (Q6) to disambiguate the internal volume from the per-drive namespace. Recommended: both auto-register-on-attach AND the clearer manual path — auto so the normal flow "just works", manual for out-of-band/edge cases.

Verdict on F9 — NOT closed

F9 made the HDD present + writable inside the guest (agent layer), but did not make it usable for new apps through the UI (controller registry layer). The deploy dropdown is gated on the registry; the registry is unaware of the agent-attached drive. F9 should remain open (or spawn an F9b) until: attach ⇒ auto-registered ⇒ a NEW app (e.g. Calibre) can be deployed to the HDD through the normal deploy UI with its data landing on /dev/sdb1 persistently. Today that round-trip fails at the dropdown.