# 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 --delete`s 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).