v0.190.0 — the boot settle window, both gates on intent, and R-171

R-171 (a regression v0.189.0 introduced, CONFIRMED on hardware before any fix
was written). Replacing isBootOrphan's container-count term with recorded intent
made a drive-gate-stopped app read as a boot orphan: the gate stops apps with
`compose down` (zero containers) and never touches desired_state, because it is
not the customer. Observed on 9201 with the drive held unmounted — the sweep
found and started it, burned both attempts, and handed it to the dead-app alarm.
The write hazard did not materialise (the unbound mountpoint is host-root-owned
and the guest is unprivileged) but that protection is accidental and untested.
New consumer-side seam bootrecon.StartGate, fail-safe (cannot determine ⇒ do not
start), wired in main.go. The rule is not new: the API's startGatedByMissingDrive
already refuses this; the sweep bypassed it.

R-157 mechanism A. The sweep looked once at T+5s, deriving candidates from a
fleet docker was still restoring — three of six hard resets. Now a settle-then-
sweep window: sample every 5s, settled after 3 identical samples, sweep ONCE at
the end; ends on settled or a 50s budget, and the log says which. The budget is
50s because settle+budget+one retry must stay under the 90s dead-app grace — a
test rejected 60s at 95s. A window that overruns emits a LATE RECOVERY warn
rather than the grace being widened to hide it.

Widening the window made two more holders reachable, so the one gate covers all
three: an absent drive, a quiesce, and an in-flight app-data operation — reusing
quiesce.SuppressedStacks() and a new read-only AppStopGuard.HeldStacks().

R-170. shouldRecreateOnBoot now reads desired_state with the identical three-way
table; absent keeps the old hasContainers behaviour exactly. Its comment argued
for the container count and was rewritten. presentStable is untouched. The two
gates' agreement is pinned from both sides against one fixture table.

27/27 packages green; 6 red-proofs observed FAIL then restored.

controller/internal/web/intermediary.go

@@ -11,6 +11,7 @@ import (
 
 	"gitea.dooplex.hu/admin/felhom-controller/internal/agentapi"
 	"gitea.dooplex.hu/admin/felhom-controller/internal/settings"
+	"gitea.dooplex.hu/admin/felhom-controller/internal/stacks"
 )
 
 // bootBindWait / bootBindPoll bound the readiness gate in processGuestBootChange. On a guest reboot
@@ -106,31 +107,54 @@ func agentWhere(registeredPath string) string {
 // container-uptime sample and a `State != stopped` filter MISS exactly that case. Do not reintroduce
 // a state filter here.
 //
-// R-55: it DOES filter on whether the app still HAS containers, which is a different question and the
-// one that tells the truth about intent. This is R-52's `existing-Exited vs absent` distinction
-// (bootrecon.isBootOrphan), translated to this gate:
+// ── R-170: intent replaced the container count (v0.190.0) ────────────────────────────────────────
 //
-//   - containers EXIST but are down  → the guest went down under the app; docker's own records survive
-//     the reboot, so this is a boot orphan → recreate.
-//   - ZERO containers                → a UI Stop is `compose down`, which REMOVES the containers.
-//     Nothing else in the controller leaves a deployed app at zero containers. → the customer stopped
-//     this on purpose → LEAVE IT ALONE.
+// The question this gate has to answer is "did the customer want this app running?", and until
+// v0.190.0 it answered by counting containers, exactly as bootrecon.isBootOrphan did:
 //
-// `deployed` cannot answer this: it is a deploy-lifecycle flag and stays true across a Stop. Before
-// R-55 the gate had no other signal and therefore silently undid a customer's Stop on every guest
-// reboot — including when apps were stopped deliberately to free resources for others, which is
-// precisely when resurrecting them is most harmful.
+//	ZERO containers → a UI Stop is `compose down`, which REMOVES them → the customer stopped it.
+//
+// R-55 added that term for a real defect and it was the right fix FOR THE SIGNAL AVAILABLE THEN:
+// before it, the gate silently undid a customer's Stop on every guest reboot — including apps
+// stopped deliberately to free resources for others, which is precisely when resurrecting them is
+// most harmful. `deployed` could not answer it: it is a deploy-lifecycle flag and stays true across
+// a Stop.
+//
+// But the count has at least three causes and cannot separate them — a deliberate Stop, a power cut
+// mid-compose, an interrupted backup — so R-166 replaced it in `bootrecon` with the customer's
+// RECORDED intent (`desired_state` in app.yaml). This gate was left on the old signal for one
+// release, which left the two boot gates disagreeing about the same question. They now agree:
+//
+//	stopped  → NEVER recreate. The customer said so; no observation overrides it.
+//	running  → recreate, whatever the container count. This is the case the count could not see.
+//	absent   → fall back to `hasContainers`, i.e. EXACTLY the pre-v0.190.0 behaviour.
+//
+// The absent branch is not a leftover. Every app.yaml written before v0.189.0 lacks the field, so
+// absent is what an upgraded box reads for every app nobody has pressed a button on since; treating
+// it as `running` would recreate — and therefore start — apps their owners had deliberately stopped,
+// fleet-wide, on the first reboot after the upgrade.
 //
 // The evidence is read from the snapshot taken BEFORE any recreate runs, because `recreate` itself
-// calls StopStack (`compose down`) and so destroys it.
+// calls StopStack (`compose down`) and so destroys it (R-55).
 //
-// NOTE on the drive-absent gate: apps it stopped are also at zero containers, so they are skipped
-// here too. That is correct — they are recorded in StoragePath.StoppedStacks and restarted by
-// ReconcileDriveGates' `Return` branch, which runs on the same loop tick. Their recovery is that
-// path's job, not this one's.
-func shouldRecreateOnBoot(deployed bool, hdd string, presentStable map[string]bool, hasContainers bool) bool {
-	return deployed && hdd != "" && strings.HasPrefix(hdd, StableParentDir+"/") &&
-		presentStable[hdd] && hasContainers
+// NOTE on the drive-absent gate: `presentStable[hdd]` is still required and is still load-bearing.
+// An app whose drive is absent is never recreated here no matter what its intent says — it is
+// recorded in StoragePath.StoppedStacks and restarted by ReconcileDriveGates' `Return` branch, which
+// runs on the same loop tick. That term is what keeps this gate safe; it is the term the BOOT SWEEP
+// was missing until R-171 (audits/DIAG-bootrecon-drive-absent-2026-08-02.md), and it must not be
+// dropped in sympathy with the count.
+func shouldRecreateOnBoot(deployed bool, hdd string, presentStable map[string]bool, hasContainers bool, desired string) bool {
+	if !deployed || hdd == "" || !strings.HasPrefix(hdd, StableParentDir+"/") || !presentStable[hdd] {
+		return false
+	}
+	switch desired {
+	case stacks.DesiredStateStopped:
+		return false
+	case stacks.DesiredStateRunning:
+		return true
+	default:
+		return hasContainers // absent/legacy — byte-identical to the pre-v0.190.0 rule
+	}
 }
 
 // defaultPromotionTarget decides M1 (never leave zero default). If the path being decommissioned is NOT
@@ -423,6 +447,9 @@ func (s *Server) processGuestBootChange() {
 		bootStacks = append(bootStacks, bootStack{
 			name: st.Name, deployed: cfg.Deployed, hdd: cfg.Env["HDD_PATH"], state: string(st.State),
 			hasContainers: len(st.Containers) > 0,
+			// R-170: read intent from the app.yaml just loaded, not from st.AppConfig — cfg is the
+			// fresh on-disk read this loop already performs, so the two cannot disagree.
+			desired: cfg.DesiredState,
 		})
 	}
 	recreate := func(bs bootStack) {
@@ -443,7 +470,7 @@ func (s *Server) processGuestBootChange() {
 	if leftStopped > 0 {
 		// INFO, not WARN: this is the gate working as intended (R-55). Make the honoured path
 		// observable — a silent correct path is how an inert seam hides.
-		s.logger.Printf("[INFO] [gate] boot %s: %d drive-backed app(s) left stopped — zero containers means the customer stopped them on purpose", resp.GuestBootID, leftStopped)
+		s.logger.Printf("[INFO] [gate] boot %s: %d drive-backed app(s) left stopped on purpose (recorded Stop, or a legacy app.yaml at zero containers)", resp.GuestBootID, leftStopped)
 	}
 	if serr := s.settings.SetLastGuestBootID(resp.GuestBootID); serr != nil {
 		s.logger.Printf("[WARN] [gate] persist boot-id: %v", serr)
@@ -458,8 +485,13 @@ type bootStack struct {
 	state    string
 	// hasContainers is len(Stack.Containers) > 0, from `docker ps -a` — so Exited containers COUNT.
 	// R-55's running-at-shutdown signal: a UI Stop is `compose down` and leaves zero. MUST be sampled
-	// before any recreate runs, since recreate's StopStack erases it.
+	// before any recreate runs, since recreate's StopStack erases it. Since R-170 it is only consulted
+	// for apps with NO recorded intent (legacy app.yaml), but it is still sampled for all of them —
+	// the legacy branch needs it and the snapshot has exactly one chance to take it.
 	hasContainers bool
+	// desired is the customer's recorded intent (stacks.DesiredState*), "" when the app.yaml predates
+	// v0.189.0. R-170: this is what the gate decides on now, with hasContainers as the legacy fallback.
+	desired string
 }
 
 // recreateDriveBackedApps recreates every deployed drive-backed app whose drive bind is live, then
@@ -474,11 +506,14 @@ type bootStack struct {
 // intended behaviour.
 func recreateDriveBackedApps(stacks []bootStack, presentStable map[string]bool, recreate func(bootStack), syncFB func()) (recreated, skipped, leftStopped int) {
 	for _, bs := range stacks {
-		if !shouldRecreateOnBoot(bs.deployed, bs.hdd, presentStable, bs.hasContainers) {
+		if !shouldRecreateOnBoot(bs.deployed, bs.hdd, presentStable, bs.hasContainers, bs.desired) {
 			if bs.deployed && strings.HasPrefix(bs.hdd, StableParentDir+"/") {
 				switch {
-				case presentStable[bs.hdd] && !bs.hasContainers:
-					leftStopped++ // drive IS live; the app is at zero containers → stopped on purpose
+				case presentStable[bs.hdd]:
+					// The drive IS live and we still declined: the customer's recorded Stop, or a legacy
+					// app.yaml at zero containers. Both are "left stopped on purpose", which is what this
+					// counter has always meant — only the signal behind it changed (R-170).
+					leftStopped++
 				default:
 					skipped++ // a deployed drive-backed app whose bind never went live → gate's job
 				}

controller/internal/web/intermediary_test.go

@@ -6,6 +6,8 @@ import (
 
 	"gitea.dooplex.hu/admin/felhom-controller/internal/agentapi"
 	"gitea.dooplex.hu/admin/felhom-controller/internal/settings"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/stacks"
 )
 
 func TestAgentWhere(t *testing.T) {
@@ -65,7 +67,7 @@ func TestShouldRecreateOnBoot(t *testing.T) {
 		{"no HDD_PATH (SSD-resident)", true, "", true, false},
 	}
 	for _, c := range cases {
-		if got := shouldRecreateOnBoot(c.deployed, c.hdd, present, c.hasContainers); got != c.want {
+		if got := shouldRecreateOnBoot(c.deployed, c.hdd, present, c.hasContainers, stacks.DesiredStateUnknown); got != c.want {
 			t.Errorf("%s: shouldRecreateOnBoot = %v, want %v", c.name, got, c.want)
 		}
 	}
@@ -158,7 +160,7 @@ func TestPollLiveBinds_WaitsForLateBind(t *testing.T) {
 	if nowT < goLive { // proves it WAITED through the rebind window (a single sample would return at t=0)
 		t.Fatalf("poll returned at t=%s before the bind went live at %s — it did not wait (regression)", nowT, goLive)
 	}
-	if !shouldRecreateOnBoot(true, flash, live, true) {
+	if !shouldRecreateOnBoot(true, flash, live, true, stacks.DesiredStateUnknown) {
 		t.Fatalf("with the live bind present, the drive-backed app MUST be recreated")
 	}
 }
@@ -170,7 +172,7 @@ func TestSingleEarlySample_MissesLateBind_Companion(t *testing.T) {
 	flash := "/mnt/felhom-drives/felhom-flash"
 	bindLiveAtBoot := func(string) bool { return false } // not yet live at the boot instant
 	oldPresent := map[string]bool{flash: bindLiveAtBoot(flash)}
-	if shouldRecreateOnBoot(true, flash, oldPresent, true) {
+	if shouldRecreateOnBoot(true, flash, oldPresent, true, stacks.DesiredStateUnknown) {
 		t.Fatalf("companion: a single early sample reads the not-yet-live bind as absent and must MISS it")
 	}
 }
@@ -192,7 +194,7 @@ func TestPollLiveBinds_TimeoutLeavesAbsent(t *testing.T) {
 	if nowT < bootBindWait {
 		t.Fatalf("poll must run to the deadline for an absent drive, t=%s", nowT)
 	}
-	if shouldRecreateOnBoot(true, usb, live, true) {
+	if shouldRecreateOnBoot(true, usb, live, true, stacks.DesiredStateUnknown) {
 		t.Fatalf("an absent drive's app must NOT be recreated here (the gate owns drive-absent)")
 	}
 }

controller/internal/web/recreate_intent_test.go

@@ -0,0 +1,147 @@
+package web
+
+import (
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/stacks"
+)
+
+// R-170 — the drive-backed boot recreate gate reads the customer's recorded intent instead of
+// counting containers, so the two boot gates stop disagreeing about the same question.
+
+const rgDrive = "/mnt/felhom-drives/hdd_1"
+
+func rgPresent() map[string]bool { return map[string]bool{rgDrive: true} }
+
+// --- Group D / Scenario E — the three-way table, every row ----------------------------------------
+
+func TestShouldRecreateOnBoot_IntentTable(t *testing.T) {
+	// RED-PROOF: restore the old `&& hasContainers` ending (i.e. ignore `desired` entirely) and the
+	// `running/no containers` row fails — that row is the whole point of R-170, and it is the shape a
+	// power cut mid-compose leaves behind on a drive-backed app.
+	// Demonstrated in REPORT.md §4.
+	cases := []struct {
+		name          string
+		desired       string
+		hasContainers bool
+		want          bool
+	}{
+		{"stopped + no containers", stacks.DesiredStateStopped, false, false},
+		{"stopped + containers present", stacks.DesiredStateStopped, true, false},
+		{"running + no containers", stacks.DesiredStateRunning, false, true},
+		{"running + containers present", stacks.DesiredStateRunning, true, true},
+		{"legacy + no containers", stacks.DesiredStateUnknown, false, false},
+		{"legacy + containers present", stacks.DesiredStateUnknown, true, true},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := shouldRecreateOnBoot(true, rgDrive, rgPresent(), c.hasContainers, c.desired)
+			if got != c.want {
+				t.Fatalf("shouldRecreateOnBoot(desired=%q hasContainers=%v) = %v, want %v",
+					c.desired, c.hasContainers, got, c.want)
+			}
+		})
+	}
+}
+
+func TestShouldRecreateOnBoot_StoppedIsNeverRecreated_WhateverElseIsTrue(t *testing.T) {
+	// The safety property R-55 added this gate's filter for, restated on the new signal: a customer's
+	// Stop must survive a guest reboot. It must hold across every other axis.
+	for _, hasContainers := range []bool{true, false} {
+		if shouldRecreateOnBoot(true, rgDrive, rgPresent(), hasContainers, stacks.DesiredStateStopped) {
+			t.Fatalf("a recorded Stop was recreated (hasContainers=%v) — this silently undoes the "+
+				"customer's decision on every guest reboot, which is the defect R-55 existed to fix",
+				hasContainers)
+		}
+	}
+}
+
+func TestShouldRecreateOnBoot_DriveAbsentStillWinsOverIntent(t *testing.T) {
+	// The `presentStable` term is load-bearing and must NOT have been dropped in sympathy with the
+	// container count. An app whose drive is absent is never recreated here, whatever its intent —
+	// the drive gate's Return branch owns it. This is the exact term the BOOT SWEEP was missing
+	// (R-171), so removing it here would reproduce that hazard in the other gate.
+	absent := map[string]bool{rgDrive: false}
+	for _, desired := range []string{stacks.DesiredStateRunning, stacks.DesiredStateStopped, stacks.DesiredStateUnknown} {
+		if shouldRecreateOnBoot(true, rgDrive, absent, true, desired) {
+			t.Fatalf("an app whose drive is ABSENT was recreated (desired=%q) — the drive-presence "+
+				"term is load-bearing and must outrank intent", desired)
+		}
+	}
+}
+
+func TestShouldRecreateOnBoot_OtherGuardsSurviveTheRewrite(t *testing.T) {
+	// deployed / stable-parent-prefix / HDD_PATH were terms before R-170 and must still be, at the
+	// strongest intent available — the rewrite reordered the terms and a reorder is how a guard
+	// silently disappears.
+	if shouldRecreateOnBoot(false, rgDrive, rgPresent(), true, stacks.DesiredStateRunning) {
+		t.Fatal("a NOT-deployed app was recreated")
+	}
+	if shouldRecreateOnBoot(true, "", rgPresent(), true, stacks.DesiredStateRunning) {
+		t.Fatal("an app with no HDD_PATH (SSD-resident) was recreated by the DRIVE gate")
+	}
+	sys := "/mnt/sys_drive/felhom-data"
+	if shouldRecreateOnBoot(true, sys, map[string]bool{sys: true}, true, stacks.DesiredStateRunning) {
+		t.Fatal("a non-stable-parent (system) path was recreated by the drive gate")
+	}
+}
+
+// --- Scenario F — the two boot gates agree --------------------------------------------------------
+
+func TestShouldRecreateOnBoot_AgreesWithBootrecon(t *testing.T) {
+	// The sibling of bootrecon's TestBothBootGatesAgreeOnIntent, over the SAME fixture table. The two
+	// gates cannot be called from one package without an import cycle, so the agreement is pinned
+	// from both sides against an identical table. If this table changes, change the other.
+	//
+	// Both answer: "did the customer want this app running?" On a live drive, this gate's verdict
+	// must equal that answer exactly.
+	cases := []struct {
+		desired       string
+		hasContainers bool
+		wantWanted    bool
+	}{
+		{stacks.DesiredStateStopped, false, false},
+		{stacks.DesiredStateStopped, true, false},
+		{stacks.DesiredStateRunning, false, true},
+		{stacks.DesiredStateRunning, true, true},
+		{stacks.DesiredStateUnknown, false, false},
+		{stacks.DesiredStateUnknown, true, true},
+	}
+	for _, c := range cases {
+		got := shouldRecreateOnBoot(true, rgDrive, rgPresent(), c.hasContainers, c.desired)
+		if got != c.wantWanted {
+			t.Fatalf("gate disagreement: shouldRecreateOnBoot(desired=%q containers=%v) = %v, but "+
+				"bootrecon.isBootOrphan answers %v for the same facts. Two boot gates answering the "+
+				"same question differently is how R-157 mechanism B survived a year",
+				c.desired, c.hasContainers, got, c.wantWanted)
+		}
+	}
+}
+
+// --- the counter that reports the honoured path ---------------------------------------------------
+
+func TestRecreateDriveBackedApps_RecordedStopCountsAsLeftStopped(t *testing.T) {
+	// `leftStopped` has always meant "deliberately not touched", and it is reported at INFO as the
+	// gate working as intended. After R-170 a recorded Stop must land in that bucket — NOT in
+	// `skipped`, which is the "bind never went live" failure and fires a WARN.
+	apps := []bootStack{
+		{name: "stopped-app", deployed: true, hdd: rgDrive, hasContainers: false, desired: stacks.DesiredStateStopped},
+		{name: "legacy-stopped", deployed: true, hdd: rgDrive, hasContainers: false, desired: stacks.DesiredStateUnknown},
+		{name: "wanted-running", deployed: true, hdd: rgDrive, hasContainers: false, desired: stacks.DesiredStateRunning},
+	}
+	var recreated []string
+	n, skipped, leftStopped := recreateDriveBackedApps(apps, rgPresent(),
+		func(bs bootStack) { recreated = append(recreated, bs.name) }, func() {})
+
+	if n != 1 || len(recreated) != 1 || recreated[0] != "wanted-running" {
+		t.Fatalf("recreated=%v (n=%d), want exactly [wanted-running] — the zero-container app the "+
+			"customer wants RUNNING is the R-170 case", recreated, n)
+	}
+	if leftStopped != 2 {
+		t.Fatalf("leftStopped=%d, want 2 (the recorded Stop and the legacy zero-container app)", leftStopped)
+	}
+	if skipped != 0 {
+		t.Fatalf("skipped=%d, want 0 — the drive is live, so nothing was skipped for a missing bind; "+
+			"counting a deliberate Stop as skipped would fire a WARN for healthy behaviour", skipped)
+	}
+}