# REPORT — slice 10: external user-data drive passthrough (P1 spike + P2)

**Agent v0.25.0** (+ controller v0.48.0, golden rebaked). P1 spike PASSED (gate); P2 BUILT + validated
live on guest 9201. P3 (self-heal) + P4 (dual-role) are the next phases.

## PHASE 1 — SPIKE (GATE PASSED), four proofs on 9201
- **1A host→guest bind:** `pct set 9201 -mp0 /mnt/felhom-usb,mp=/mnt/felhom-usb` — **bind form** (host
  path), never `storage:size`. Propagation `shared:49` host↔guest automatic.
- **1B write — chown, not idmap:** idmap not clean (mixed host ownership 1000+0, container-wide,
  restart, subuid). Decision (refined with Viktor): chown only a fresh **`<drive>/felhom-data`**
  namespace to `100000:100000`; the customer's existing data is never touched. Guest-root r+w confirmed.
- **1C guest→controller-container:** `-v /mnt:/mnt:rslave` + `/mnt` rshared in the guest → newly-mounted
  drives propagate into the running container (proven). The de-priv `/mnt` gap, reopened scoped.
- **1D app-container:** busybox bind read+write; bytes land on `/dev/sdb1`.

## PHASE 2 — passthrough (Model A: the felhom-data namespace is the in-guest mount)
- **P2A agent — `POST /disks/guest-attach`** (`internal/localapi`, `GuestBinder`): self-scoped; creates
  `<drive>/felhom-data`, chowns it to the guest base (not -R), and `pct set <vmid> -mpN
  <drive>/felhom-data,mp=/mnt/<name>` (RW bind). Idempotent; lowest free `mpN`; `where` validated. Only
  Felhom's namespace crosses into the guest — the customer's other on-drive data never does. Tests:
  `TestGuestAttach_*` (slot select, idempotency, bad-path, not-configured).
- **P2B golden — `configs/build-golden.sh`:** controller `docker run` gains `-v /mnt:/mnt:rslave`; the
  bootstrap makes `/mnt` rshared first. Scoped to `/mnt` (only felhom-data-namespace mounts).
- **P2C controller (v0.48.0):** `agentapi.GuestAttach`; `runStorageInit`/`runStorageAttach`/
  `handleStorageRegister` call `attachIntoGuest` after register (best-effort; P3 heals a miss).

## Live validation (9201)
After `guest-attach` + a guest restart to activate mp0:
- mp0 = `/mnt/felhom-usb SOURCE /dev/sdb1[/felhom-data]` (Model A; the `[/felhom-data]` suffix the
  controller's mount strip already handles).
- Controller container mountinfo has `/felhom-data /mnt/felhom-usb … /dev/sdb1`.
- An app (busybox bind) writes `proof.txt` → present on the **host** `/mnt/felhom-usb/felhom-data/...`,
  `df` device `/dev/sdb1` (NOT the rootfs).
- Banner cleared: **`[PASS] Storage paths: 1 connected, 0 disconnected`**.
- `go test ./...` green (both repos).

## KNOWN LIMITATION — live activation (decision needed before P3)
`pct set` does **not** hot-apply a mountpoint to a *running* guest when the guest's `/mnt` is rshared
(the P2B rbind shadows the live hotplug; the spike's live hot-apply worked only because `/mnt` wasn't
yet shared). So a drive enrolled into a **running** guest activates on the **next guest restart** — the
end-state is correct, but live enroll isn't seamless. This is a genuine hotplug-vs-propagation fork
(like the chown/idmap + Model A decisions) to settle before P3: options are (a) enroll triggers a guest
reboot; (b) drop the guest `/mnt` rbind and have enroll do `pct set` (live hotplug works) + a
lightweight controller-container restart to capture it; (c) let P3 self-heal reconcile drive activation.
Fresh guests from the rebaked golden are unaffected (mp mounts activate at first boot, before the
controller starts).

## Not done (next phases)
P3 self-heal watchdog reconcile (4-state new/enrolled/ejected/decommissioned) + safety rails; P4
dual-role + backup-aware wipe warning. Cross-drive backup ENGINE remains out of scope.