# REPORT — controller v0.75.0: gate userdata MkdirAll on a live mountpoint

## Baseline → target
`felhom-controller` `main` v0.74.0 → **v0.75.0**. Controller-only; agent/hub untouched.

## Problem
Two `MkdirAll`-into-`<drive>/userdata` sites fired without checking the drive was mounted (campaign-#2
findings #2/#3): the deploy belt (`ensureUserdataMounts`) and the FileBrowser sync. During a
drive-absent window they logged `mkdir …/userdata: permission denied` + caused transient `Created`
container flapping — and worse, writing into an unmounted mountpoint lands app data on the guest
**rootfs**, shadowed when the drive returns (data-integrity + rootfs-fill hazard).

## Change (commit `0b2605c`)
- `internal/stacks/manager.go` — `ensureUserdataMounts` skips when the `HDD_PATH` drive root is an
  **external** path (`!= sysDataPath`) that is **not a live mountpoint**; the app is held by
  `planDriveGates`. New injectable `Manager.isMountPoint` seam (defaults to `system.IsMountPoint`).
  The system/local path is never gated.
- `internal/web/handlers.go` — the FileBrowser sync loop skips (and doesn't mount) a path under
  `StableParentDir` that isn't a live mountpoint, via the new pure `skipFileBrowserPath` helper.
- `EnsureUserdataDir`/`EnsureUserdataSkeleton`/`planDriveGates` unchanged (gated the callers).

## Tests (green; red-proofed)
`go build ./... && go vet ./... && go test ./...` all green.
- T1 `TestEnsureUserdataMounts_SkipsAbsentExternalDrive` — belt skips when external drive absent.
  Red-proof: removing the gate → dir created → FAIL (shown, reverted).
- T2 `TestEnsureUserdataMounts_EnsuresWhenMounted` — belt ensures when drive mounted.
- T3 `TestEnsureUserdataMounts_SystemPathNeverSkipped` — system/local path never gated (must-not-over-gate).
- T4 `TestSkipFileBrowserPath` — only an absent external path is skipped; mounted + system paths kept.
  Red-proof: gate→false → absent `usb` not skipped → FAIL (shown, reverted).

## Deploy
Built+pushed `gitea.dooplex.hu/admin/felhom-controller:0.75.0` on 192.168.0.180 (digest
`sha256:f735676e…`; **build-server `git pull` done first** — the v0.74.0 stale-source gotcha),
deployed to guest 9201 via the bootstrap path. `docker inspect`: `image=:0.75.0 running healthy`.

## LIVE acceptance — campaign-#2 C6 re-run, now clean
Disconnected felhom-flash (8 apps) and observed the drive-absent window:

| Check | campaign #2 (pre-fix) | **v0.75.0 (fixed)** |
|---|---|---|
| `mkdir …/userdata: permission denied` | many | **0** |
| "could not ensure userdata skeleton" | present | **0** |
| rootfs shadow dir at unmounted mountpoint | created | **none** — `/mnt/felhom-drives/felhom-flash/userdata` does not exist (bare mountpoint) |
| apps during absent window | transient `Created` flapping | held cleanly (down) |
| reconnect | recovered | **recovered: flash remounted /dev/sdc1, 8 apps restarted → 25 running / 0 unhealthy** |

The integrity hazard (app data shadowed onto the rootfs) is closed: the now-unmounted mountpoint is
empty, no `userdata/...` was written to the rootfs.

## Not touched / design note (see CONTEXT.md)
The **boot-time** `mkdir … permission denied` (daemon boot-restore) is a different cause — **docker**
auto-starts drive-backed containers (`restart: unless-stopped`) before the agent mounts the drives, so
docker (not the belt) tries to create the bind source; `planDriveGates` recovers them after mount
convergence. This task ships only the runtime gate; the boot-ordering decision is documented, not
implemented.