felhom-controller/REPORT.md

REPORT — app lifecycle states + R-55 live leg (TASK-F Parts 1 & 3), 2026-07-21

Versions: v0.158.0 (lifecycle) + v0.158.1 (a defect I shipped in 0.158.0 and caught live — read §4). Baseline a96226a (v0.157.0), clean tree. Deployed to guest 9201 and live-verified.

1. What shipped — app lifecycle

.felhom.yml gains an optional top-level lifecycle:. Absent/empty ≡ available, so all existing templates are untouched.

state	offered for new installs	shown to someone already running it
available	yes	nothing
hidden	no	nothing — "we stopped offering this" is not their problem
abandoned	no	„Nem karbantartott" badge + a permanent notice on the app page

A deployed instance keeps full function in every state. That is the whole design: the earlier retired/ directory move un-offered the app but would ALSO have made the orphan detector see the template as gone for anyone running it — flagging a working install Elavult and offering a Törlés button. Withdrawing an app must never take a working app away from a customer.

Three design points worth carrying past this feature:

• The deploy gate is server-side and fail-CLOSED, before any mutation, with the ruled message „Ez az alkalmazás jelenleg nem telepíthető." Hiding a button is not a gate — a stale link, a bookmarked deploy form and a direct POST must all be refused. A second check in stacks.DeployStack covers callers that do not route through the API.
• Unknown values fail OPEN (→ available + one WARN) — deliberately the opposite posture. A typo, or a state from a catalog newer than this controller, must never silently pull a working app out of every customer's list. Both paths read the same EffectiveLifecycle, so they cannot disagree.
• Lifecycle never reaches orphan detection. getCatalogTemplateSlugs keys on directory + compose presence only. Red-proofed.

Badge plumbing is generic (MetaBadge + the meta_badge partial + a lifecycleBadge funcmap entry) so R-56's difficulty labels need only a sibling funcmap function — no new markup or CSS.

2. Live validation — endpoint-level, on 9201

The catalog change arrived through the normal git-sync, not a hand-copy:

$ grep -m1 '^lifecycle:' /opt/docker/stacks/plant-it/.felhom.yml
lifecycle: abandoned

check	result
plant-it on the Alkalmazások page	0 occurrences (control app bookstack: 10)
direct POST /api/stacks/plant-it/deploy	HTTP 409 {"ok":false,"error":"Ez az alkalmazás jelenleg nem telepíthető."}
/apps/plant-it	200, carries the notice, no Telepítés button
/apps/bookstack (control)	200, no badge, unaffected

Method: the exact endpoints the UI calls, authenticated as the customer (no browser on DooPlex).

3. Red-proofs — all five run

#	pre-fix shape restored	observed failure
1	remove the API deploy gate	wiring test: "deployStack never calls Meta.CanInstall() — the lifecycle gate is INERT"
2	drop st.Deployed || from the catalog filter	"plant-it-run" must be listed, "oldapp-run" must be listed — a customer's running app vanishes from their own page
3	remove the badge line from stacks.html	"a deployed abandoned app must carry the Nem karbantartott badge"
4	make orphan detection lifecycle-aware	catalog set = map[bookstack:true] — both withdrawn apps read as orphans
5	restore the pointer receivers (§4)	can't evaluate field IsAbandoned in type interface {} on every lifecycle value

The wiring test walks the AST, not strings.Contains, because a commented-out call still contains the string; it also asserts the gate precedes DeployStack, since a gate that fires after the mutation is not fail-closed.

4. A defect I shipped in v0.158.0 and caught within the hour

/apps/<slug> returned HTTP 500 for EVERY app, not only withdrawn ones.

EffectiveLifecycle / CanInstall / IsAbandoned were declared with pointer receivers. appDetailHandler passes data["Meta"] = found.Meta — a stacks.Metadata VALUE inside a map[string]interface{} — and html/template cannot call a pointer-receiver method on a non-addressable value:

executing "app_info" at <.Meta.IsAbandoned>: can't evaluate field IsAbandoned in type interface {}

Fixed in v0.158.1 with value receivers and the reason recorded at the declaration so it is not "tidied" back.

Why every gate missed it, which is the transferable part. It compiles. go vet is silent. All of v0.158.0's tests passed — because none of them rendered app_info. The catalog-page tests exercised the funcmap route (lifecycleBadge .Meta), which takes a value and works with either receiver. A template method call is only ever checked when that template actually runs, so a render test is not optional coverage for template-facing methods — it is the only coverage.

TestAppInfoRendersForEveryLifecycle now renders the real template through the production tree with the handler's exact data shape — "Meta" as a value in a map[string]interface{}, deliberately not a pointer, because a pointer would hide the bug the test exists to catch.

I found this while live-validating, not from the suite. That is the honest sequence.

5. Part 3 — R-55 live leg, PROVEN

Operator-present, 2026-07-21. Fixture on 9201 (guest clock = UTC, host = CEST):

time (UTC)	event
14:28:52	immich STOPPED through the real UI endpoint POST /api/stacks/immich/stop → compose down
—	pre-state verified: immich 0 containers, calibre-web 1 running (drive-backed), bookstack 2 running (not drive-backed)
14:29:14	pct reboot 9201
14:29:28	[gate] boot 1784525102-11906045: waiting (≤2m0s) for live drive bind(s) [/mnt/felhom-drives/hdd_1]
14:29:28	[gate] … live bind confirmed — recreating drive-backed app calibre-web (state=stopped) onto /mnt/felhom-drives/hdd_1
14:29:29	[gate] … 1 drive-backed app(s) left stopped — zero containers means the customer stopped them on purpose
14:29:32	[bootrecon] Boot reconciliation: no boot-orphaned apps (nothing to start)

End state: immich 0 containers / stopped, calibre-web 1 running, bookstack 2 running. Zero alerts (the only app_start_failed|deadapp grep hit was the scheduler registering its job). Reboot → steady state in ~15 seconds.

immich is absent from the recreate list. Hours earlier, the identical fixture brought it back RUNNING — that is the defect R-55 fixed, and this is the same experiment with the opposite result. The left stopped INFO line fired in production for the first time, so the honoured path is observable rather than silent.

6. Gates

go build ./... && go vet ./... && go test ./... — green (both versions). All five template gates pass (template_id, emoji, mojibake, app_row_dedup, native_confirm).

7. Observations

1. I pushed a commit that does not build. A git stash/stash pop used to compare reuse_refs_check.py output silently discarded the staged index, so the first lifecycle commit landed only the new test files. Fixed by a follow-up commit rather than a force-push (rewriting pushed history is worse than one bad commit in the log). Lesson: never git stash mid-staging.
2. REUSE.md cross-repo citation drift is pre-existing and improved: 8 broken paths → 5. I fixed the three that were plain prefix errors; the rest cite abbreviated paths the checker resolves against the repo root.
3. The hidden state currently has no user in the catalog. It is implemented and tested, but only abandoned is exercised end to end.