felhom-controller/REPORT.md

# REPORT — controller v0.147.0 → v0.147.3: feedback slice 1 (2026-07-19)

**Baseline v0.146.0 → LIVE v0.147.3 on demo guest 9201.** Green at every version:
`go build ./... && go vet ./... && go test ./...` (23 packages) plus `template_id_gate`,
`emoji_gate`, `native_confirm_gate`, `offbox_rename_gate`, `app_row_dedup_gate`, `mojibake_gate`.

> `docker_run_volume_path_gate` fails on `internal/appexport/estimate.go:179`. **Pre-existing on
> HEAD and untouched by this release** — verified by stashing this work and re-running the gate.
> Not fixed here (out of scope, and it is someone's call whether that `-v :ro` du probe gets an
> allowlist entry or a rewrite).

## The problem

The systemic complaint, twice in one evening: **you press a button and nothing happens.** No
progress, no ETA, no named result. Three worst offenders fixed on the two patterns already in the
codebase — the deploy 3-step panel and the storage-init status poll. **No new framework**; that is
now ROADMAP **R-45**, because three targeted cards were worth shipping tonight and a framework was
not.

Three of the four versions below exist because the cards were watched against **real runs on the
demo box**. Each follow-up is a thing no unit test would have surfaced.

---

## 4a — a verification restore names its result

The completion flash said the app had been restored „ellenőrző mappába a meghajtón". *Which* folder,
on *which* drive, was invisible — so the customer could not go and look at the thing they had just
asked for. And nothing anywhere listed what these restores had accumulated, so copies piled up and
the only way to find them was SSH.

- The flash now carries the **full path**.
- The restore page gained **„Meglévő ellenőrző másolatok"** — app · size · date · path — each with a
  double-confirmed **„Másolat törlése"** (the house inline `felhomConfirm` idiom, never native
  `confirm()`).
- `backups/offsite-restore` was open-coded in three places; it now has one home
  (`offsiteRestoreRootFor`). A test pins the path in the flash to the path in the listing, so the
  customer can never be told about a directory the page cannot show or remove.

**The delete is the only one this release adds**, so it names a **stack, never a path**: the Manager
resolves that name inside a root it computed itself and refuses anything landing outside.
Red-proofed — neutralise the name guard and `stack: ""` resolves to the offsite-restore **root** and
`os.RemoveAll` takes every copy with it. Every refusal is asserted as a **non-effect** (the
neighbouring copy and the live data are still on disk afterwards).

Honest note: the `HasPrefix` containment check behind that name guard could **not** be red-proofed
independently — with `isSafeStackName` in front of it, no input the API accepts can reach it with an
escaping path. It is kept as defence-in-depth and labelled in the test file as unproven-by-test
rather than dressed up as a red-proof it does not have.

### Live (endpoint-exact, through the real handlers)

Real verification restore of `calibre-web`, then the guard matrix:

```
message: "A(z) calibre-web visszaállítva ellenőrző mappába:
          /mnt/felhom-drives/hdd_1/backups/offsite-restore/calibre-web
          (a meglévő adatok változatlanok)."
listing: calibre-web · 430.4 KB · …/offsite-restore/calibre-web · [Másolat törlése]

stack=../primary  -> refused; copy AND backups/primary both still present
missing confirm   -> refused; nothing changed
real delete       -> copy gone; backups/primary SURVIVES; page -> „Nincs ellenőrző másolat"
```

---

## 4b — Megosztás enable shows what it is waiting for

Enabling sharing ran `ReconcileSamba()` **synchronously inside the POST handler**. On a box whose
golden had not baked `felhom-samba` that is `compose up -d` pulling ~100MB from a private registry:
minutes of an apparently-hung form post, then „Beállítás mentve." whether or not anything came up.

Detached + polled now, with a card that distinguishes **„képfájl letöltése"** (image genuinely
absent — the multi-minute case) from **„indítás"** (already baked — seconds). The distinction is
decided *before* the work starts, because afterwards the image is always present and the card could
never truthfully say „letöltés".

- Success is **probed, not inferred** — `compose up -d` exits 0 on a crash-loop, so the terminal
  state is container liveness.
- `nil` from reconcile also covers "deliberately deployed nothing because there is no household
  password yet"; that now gets its own message instead of a card spinning forever.
- The **password** form starts the same job — with `UserSet` false reconcile deploys nothing, so on a
  fresh box *that*, not the enable toggle, is where the pull actually happens.

**Test scope, stated honestly:** the unit tests cover the single-flight slot, snapshot isolation and
the phase vocabulary. They do **not** drive `runSambaEnsureJob` end-to-end — the Server field is the
concrete `*stacks.Manager`, not an interface, and introducing one purely for this card was more churn
than the slice warranted. Pulling-vs-starting and the probed terminal state are covered by live
validation instead. That seam belongs to R-45.

Live: `/sharing/status` returns `{"ok":true,"data":{"phase":"running","running":true,"error":""}}`;
the page carries the card and the poll.

---

## 4c — „Távoli mentés most" streams real progress

restic was already reporting bytes and percentages; the runner seam used `CombinedOutput()` and threw
them away. The manual run now passes `--json`, scans stdout line-by-line, and the page shows total
bytes, percent and the app being pushed. **Manual only** — the nightly stays silent, pinned by a test
that fails if the scheduled path ever passes `--json` or publishes progress.

The poll also now **arms unconditionally**. It used to start only if the page already rendered
„Fut…", which loses a race the manual trigger always runs: the POST redirects and the page renders
before the detached goroutine writes `LastStatus=running`, so the poll never armed and the customer
watched a static page during the very run they had just started.

Red-proofed twice: break the parser -> the percent assertion fails; drop the wiring -> the `--json`
assertion fails.

### What three live runs actually taught (v0.147.1 -> .3)

**Run 1 — immich reported `0%` for 40+ seconds.** The parser was not broken. On an incremental run
where nothing changed restic transfers nothing: `bytes_done` is `omitempty`, so it is not even in the
JSON, and `percent_done` stays 0. Confirmed by capturing the real schema from
`backup --dry-run --json` on restic 0.14.0 in the controller image rather than guessing; those lines
are now quoted verbatim in the type's doc comment. **A byte-only bar is indistinguishable from a hang
in the common case** — shipping it would have traded "no feedback" for "feedback that says 0% and
looks stuck". -> **v0.147.1** parses and publishes `files_done`/`total_files`.

**Run 2 — bookstack showed clean byte progress (100%, 154.0 MB, 7/7), immich sat at `1 of 46 files,
0 bytes` for 42 seconds.** restic 0.14 only counts a file when it **completes**, so an app dominated
by one large archive (immich's ~430MB volume tar) freezes *both* counters. No percentage can move.
-> **v0.147.2** shows what restic *does* keep reporting: the file being processed and elapsed
seconds. „1 / 46 fájl (430.2 MB) · feldolgozás alatt: immich_upload.tar · 42 mp" is a different
message from „0%".

**Run 3 — the per-app legs finished in ~15s; the remaining 40 of a 57-second run was the shares leg
and `forget --prune`,** during which the card sat frozen on „calibre-web — 8 / 8 fájl". The same
silence, relocated to the end of the run. -> **v0.147.3** adds a run **phase**; the post-app stages
announce themselves and app-scoped counters clear when a phase starts.

Final live trace — the whole 57-second run is narrated, no frozen state:

```
t+6s   app=immich
t+9s   app=bookstack
t+12s  app=calibre-web
t+15s  phase=shares
t+18s ... t+54s  phase=retention
t+57s  done
```

---

## Also: golden/controller infra-image drift closed at the source

`infra.Images()` derives the list from the existing pins; `--print-infra-images` prints it; the golden
bake now asks the controller binary it is about to bake instead of carrying its own copy. That copy
had already drifted — `felhom-samba` was never added to it, so the golden baked 3 of 4, **which is
why enabling Megosztás pulled at runtime in the first place**. A test parses the const block out of
the source with `go/ast` and fails if a pin is added without reaching `Images()`; red-proofed.

Verified against the real published image on the live box — all four returned.

## Validation method

Live validation was **endpoint-exact** (the exact URLs the UI posts to, through the real handlers and
the real restic/samba paths), not browser click-through: the controller UI is password-gated and I do
not enter credentials into web forms. No server logic was skipped — only rendering. The rendered
markup was checked by fetching the pages themselves and asserting on the emitted HTML.

## Not done

- **Floor not raised** — Viktor decides floor timing.
- No golden rebuild, no manifest saves, nothing on Peti's arc.
- No SMB server-side changes — the `\\FELHOM` access issue stays client-side diagnosis first.
- ROADMAP: **R-45** (unified async-job feedback) and **R-46** (verification-copy browse + expiry)
  registered in `felhom.eu/documentation/backlog/ROADMAP.md`.