felhom-controller/REPORT.md

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).