# REPORT — R-55 boot-gate stop-honesty (TASK-E Part 2), 2026-07-21

**Versions: v0.157.0 (R-55) + v0.157.1 (.gitignore anchor). Baseline `83f20c8` (v0.156.0), clean tree.
v0.157.0 is BUILT, PUSHED and DEPLOYED to guest 9201.**

## Scope correction — this part was specified against the wrong repo

TASK-E placed R-55 in `felhom-agent` (Parts 1–2 → felhom-agent) and separately forbade controller
changes ("felhom-controller untouched", "no controller changes at all"), with a supervised-lite leg
described as an *agent binary* deploy to felhom-pve.

**R-55 is not in the agent.** It is `felhom-controller/controller/internal/web/intermediary.go` —
the in-guest boot bind gate. The agent's only related code is host-side `ReassertGuestBinds`, which
re-adds `pct set -mpN` binds and never touches apps. The GO ruling and the scope fence therefore
contradicted each other; the fence was evidently written believing the gate lived in the agent.

**Raised as a STOP rather than resolved unilaterally**, because it changes which repo ships and which
artifact deploys. **Operator ruling 2026-07-21: implement in the controller AND deploy to 9201.** Done.

## The defect

`shouldRecreateOnBoot` keyed on `Deployed && HDD_PATH && drive-present`. `Deployed` is a
deploy-lifecycle flag that stays true across a Stop, so the gate could not tell "the guest went down
under this app" from "the customer switched this off" — and resurrected both. Proven live by STOP-1's
R-52 leg, which was designed to prove the opposite: immich, stopped from the UI seconds earlier, came
back running after `pct reboot 9201`.

The operator's rationale for ruling this GO is worth keeping attached to the fix: an unconditional
recreate can **drown the node** when apps were deliberately stopped to free resources for others. This
is not only about honesty; it is about not fighting the customer's own capacity management.

## Spike-lite: a truthful source already existed — nothing was invented

The task required stopping rather than inventing state if no honest running-at-shutdown signal existed.
It does exist, and R-52 already trusts it:

- `AppConfig` carries **no** run-state. `Deployed` is lifecycle, not intent.
- `Stack.Containers` comes from `docker ps -a` (so `Exited` containers **count**), and docker's own
  on-disk container records survive a reboot.
- A UI Stop is `compose down`, which **removes** the containers. Nothing else leaves a deployed app at
  zero containers.

That is exactly `bootrecon.isBootOrphan`'s `existing-Exited vs absent` distinction. The gate now
additionally requires `len(Stack.Containers) > 0`.

**What deliberately did NOT change: container STATE is still not a filter.** That half of the original
design is load-bearing — a `State != stopped` filter misses an app docker has not auto-restarted yet,
or one stuck `Exited` on a create-time bind failure with `RestartCount=0`, which is the bug the boot-id
path exists to fix. `state` and `hasContainers` are different questions ("is it up right now" vs "does
docker still have records of it") and only the second survives a reboot as a statement of intent.
`TestShouldRecreateOnBoot` now pins both axes at once; they pull in opposite directions, which is the
entire difficulty of this gate.

**Ordering trap, found and handled:** the evidence is sampled into the `bootStack` snapshot **before**
any recreate runs, because `recreate` itself calls `StopStack` (`compose down`) and destroys it.

**No regression to the drive-absent gate:** apps it stopped are also at zero containers, so this path
now skips them — correctly. They are recorded in `StoragePath.StoppedStacks` and restarted by
`ReconcileDriveGates`' `Return` branch on the same `driveGateLoop` tick. Checked, not assumed.

**Honoured Stops are observable.** `leftStopped` is counted and logged separately from `skipped`, at
INFO. Conflating them would fire a WARN about a missing drive bind for an app behaving exactly as
asked — and a silent correct path is how an inert seam hides.

**No new privileged verb**, as required: `StopStack`/`StartStack` are plain `docker compose` execs in
the controller's own container, and the boot path's only agent calls are read-only (`agent.Disks`).
The agent sudoers/wrapper set is untouched — nothing in it relates to app start/stop.

### Red-proof — RUN

Dropped `hasContainers` from the predicate:

```
--- FAIL: TestShouldRecreateOnBoot
    R-55 customer-stopped drive app (zero containers): shouldRecreateOnBoot = true, want false
    R-55 gate-stopped app (zero containers; Return branch owns it): shouldRecreateOnBoot = true, want false
--- FAIL: TestRecreateDriveBackedApps_HonoursCustomerStop
    recreated=[romm immich], want exactly [romm] — a customer-stopped app must never be restarted
```

`recreated=[romm immich]` is the live defect by name. Fix restored → green; `git diff` clean.

## Gates and deploy verification

`go build ./... && go vet ./... && go test ./...` — **green**, whole module.

```
gitea.dooplex.hu/admin/felhom-controller:0.157.0 | Up (healthy)
```

**Not an inert seam** — the new code is verified present in the *running* binary, not just the image:
`grep -a -c "stopped them on purpose" /usr/local/bin/felhom-controller` → `1` inside the live
container. This check exists because three inert-seam defects shipped fully-green in three days.

### The live reboot leg is NOT done, and that is a deliberate stop

Proving R-55 end to end needs a drive-backed app stopped from the UI followed by `pct reboot 9201`.
9201 has two drive-backed apps (calibre-web, immich) on `hdd_1`, so the fixture is available — but the
demo box is **at a remote site until ~2026-08-02**, and rebooting it unprompted is not a call CC
should make (the 2026-07-20 dhclient incident cost 1h15m from a smaller action). **One operator-present
STOP away.** Until then R-55 is *shipped and wired*, not *proven live*; the capability-map row says so
in those words.

## v0.157.1 — `.gitignore` anchor (TASK-E Part 5)

`controller/.gitignore` carried a bare `controller`, which git matches against **directories** too, so
it also matched `cmd/controller/`. Two opposite failure modes, both manufacturing inert seams:
ripgrep silently skipped `cmd/controller/main.go` (a search for a setter's caller returns nothing and
reads as "unused"), and new files there needed `git add -f` or were never committed.

Anchored to `/controller` + `/controller.exe`. Verified **both** directions: `git check-ignore` no
longer matches `cmd/controller/main.go` and `rg` now finds it; a built binary at the module root is
still ignored. `git ls-files` confirms nothing had been hiding untracked behind the old rule.

## Observations

- `TestShouldRecreateOnBoot`'s old comment argued explicitly that a state filter would be a
  regression — correct, and still true. The comment is now expanded to say why `hasContainers` is a
  *different* axis, so the next reader does not "fix" it back.
- The gate calling `StopStack` before `StartStack` on every recreate is what erases the container
  evidence, and is also why R-52's boot-orphan sweep only ever sees non-drive-backed apps. R-52's
  practical scope on a real box remains narrower than its brief assumed; unchanged by this fix.