# REPORT — intermediary-mount re-architecture (controller half) → v0.67.5 (2026-06-15)

## Type
Controller half of the intermediary-mount re-architecture (pairs with agent v0.35.1 + catalog repoint).
Built + Linux-gated (`go vet`/`go test ./...` green) + deployed to demo guest 9201, which was then
migrated live. Drives are now visible in-guest ONLY at the STABLE path `/mnt/felhom-drives/<name>` (the
host swaps the backing drive underneath it — no per-drive `pct` mp, no guest reboot for attach/detach).
Design: `felhom.eu/documentation/audits/SPIKE-intermediary-mount-2026-06-15.md`.

## What changed (internal/web/intermediary.go + storage_handlers.go + api/router.go + settings.go)
- **HDD_PATH repoint.** The registered storage path + every app's HDD_PATH + FileBrowser source are now
  the stable `/mnt/felhom-drives/<name>`; the AGENT still operates on the raw `/mnt/<name>` (mapped via
  `agentWhere()` at the assign/attach/eject/decommission call sites). Enroll binds-under-the-parent
  BEFORE register (the controller only sees the drive at the stable path post-attach). New
  `settings.RepointStoragePath`; `agentapi.DiskInfo` gains `GuestPath`/`BoundUnderParent`.
- **Drive-absent GATE** (`planDriveGates` pure core + `driveGateLoop` 30s, replacing the retired
  watchdog). An ABSENT external drive (only `/mnt/felhom-drives/<name>` paths — never SSD/system) stops +
  blocks its apps (`StoppedStacks` = gate-stopped set); a RETURNED drive re-attaches + auto-restarts
  them. `present` keys on `BoundUnderParent` (guest-usable), not host-mount. Start-gate in `actionStack`
  refuses to start an app whose drive is absent.
- **Guest-reboot convergence** (`recreateBootStaleApps`, one-time at startup after a bounded stack-scan
  wait): docker auto-starts app containers on a guest reboot possibly before the agent re-propagates the
  drive, so they bind the empty stable dir; the controller (which restarts with the guest) recreates
  present drive-backed apps that are boot-stale/exited/restarting onto the populated path.
- **H1 endpoints routed** (were 404): `POST /api/storage/{disconnect,reconnect,restart-apps}` → host-side
  eject/reconnect (no guest reboot).

Version path v0.67.0 → .5 (`.1` gate-only-externals, `.2` BoundUnderParent, `.3`/`.4`/`.5` startup
recreate hardening). Non-hollow tests + companions: `TestPlanDriveGates` (5 states incl. SSD-never-gated),
`TestAgentWhere`, `TestRunStorageInit_Success` (agent gets RAW, registry gets STABLE).

## Live migration (guest 9201) + verification
8 deployed apps (all on felhom-flash) repointed (app.yaml HDD_PATH rewrite + controller-driven
down/up recreate, which decrypts the `ENC:` secrets) + registry repointed + FileBrowser re-synced + the
legacy `mp2` deleted. **A guest reboot self-converges**: the startup recreate logged + rebound the
drive-backed apps onto `/mnt/felhom-drives/felhom-flash` with no manual intervention. End state: **25
containers healthy** (komga healthcheck pre-existing quirk), confinement + data integrity verified.

## Known residuals (documented)
- Startup recreate is state-sampled; an app cleanly stopped at the exact sample instant may need one
  manual start (1/8 once). Deterministic fix = a guest-boot-id signal from the agent (future).
- felhom-usb left on its legacy bind (no deployed apps + stale `decommissioned` intent).