felhom-agent/REPORT.md

REPORT — intermediary-mount re-architecture (agent half) (2026-06-15)

Type

Multi-commit build + live deploy + migration on the demo host (felhom-pve, guest 9201). Replaces the per-drive pct set -mpN guest bind (reboot-to-activate; bricks when a drive is absent at boot) with a single permanent parent bind /mnt/felhom-drives plus host-side drive hot-swaps underneath it. Pairs with controller v0.67.5 + the app-catalog repoint. Design: felhom.eu/documentation/audits/SPIKE-intermediary-mount-2026-06-15.md.

Shipped (agent), each built + Linux-gated (go vet/go test ./... green) + deployed to felhom-pve

• v0.33.0 — C1 net (transitional). Pre-start PVE hookscript (internal/guesthook) creates host-root placeholders for absent bind-mount sources so the guest always boots (fail-closed); decommission now pct set --deletes the dead mp (GuestBinder.DetachBind). Live-proven: reproduced the C1 brick (start exit 255) then the hook heal → clean boot.
• v0.34.0 — intermediary mechanism. EnsureSharedParent (self-bind + --make-shared + boot unit), AttachDrive/DetachDrive (host mount --bind <drive>/felhom-data under the parent — propagates into the running guest live, confined, fail-closed), ReassertGuestBinds rewritten as a host-side reconcile (no pct/reboot). /disks adds GuestPath + BoundUnderParent. Live-proven: the startup reconcile bound felhom-flash under the parent, propagating 3-hop into the controller container live.
• v0.35.0 — guest-reboot re-propagation (load-bearing). A guest's parent bind is NON-RECURSIVE, so a guest reboot leaves enrolled drives bound on the HOST but invisible in the fresh guest ns. AttachDrive now takes vmid, checks GuestSeesMount (/proc/<init-pid>/mountinfo), and FORCE re-binds to re-fire propagation; a 20s periodic reconcile self-heals guest reboots; BoundUnderParent reflects guest visibility. Live-proven: after a guest reboot the drive auto-re-propagated.
• v0.35.1 — host-boot ordering. The shared-parent oneshot now WantedBy=pve-guests.service (pulled in + Before-ordered) instead of the unreliable multi-user.target; EnsureSharedParent reinstalls on content change. Unit verified reinstalled + enabled + runs (the actual host-reboot ordering is not validated — the production demo host can't be rebooted).

Tests are non-hollow, each with a companion that fails the pre-fix/trivial impl (guesthook selector, decommission --delete, GuestAttach uses host-side AttachDrive not legacy pct, host-side reconcile, GuestPath/BoundUnderParent reporting). Sudoers extended (FELHOM_GUESTHOOK, FELHOM_INTERMEDIARY).

Live migration (guest 9201) + verification

felhom-flash (the drive with all 8 deployed apps) fully migrated to /mnt/felhom-drives/felhom-flash; the legacy per-drive mp2 deleted; a guest reboot self-converges with no manual intervention (agent re-propagates the drive, controller startup-recreates the apps onto it). End state: 25 containers healthy (komga's healthcheck is a pre-existing quirk), /mnt/felhom-flash gone from the guest, confinement intact (only appdata/backups/media/userdata cross in), data identical. felhom-usb (no deployed apps, stale decommissioned intent) left on its legacy bind — out of scope.

Known residuals (documented, not blocking)

• Host-reboot ordering: unit fix shipped (v0.35.1) but not validated via an actual host reboot.
• Guest-reboot app recreate is state-sampled (controller side): an app cleanly stopped at the exact sample instant may need one manual start (1/8 in one run). The deterministic fix is a guest-boot-id signal (future).