v0.191.0 — warn before the wall comes down (R-167, R-158, R-174)

R-167: new internal/fillwatch warns the CUSTOMER before a filesystem fills.
It emits the PRE-EXISTING disk_warning/disk_critical pair, which was
allowlisted, copy'd, default-enabled and checkbox'd with no producer in any
repo — the sixth "built but never wired" instance here. Two threshold terms
(85% or 5 GiB free; critical 95%/2 GiB) because a percentage alone lies at
both ends of this fleet's size range. Edge-triggered on escalation only,
state persisted, hysteresis dead zone at 75%/7 GiB pinned by a test. A nil
usage read is never a warning and never clears one. Per filesystem, never
per app. Daily 03:30, before the nightly app-data legs.

R-158: new unitNotify seam fires per app when a Tier-1 recovery-unit capture
fails, loop continuing, carrying the target filesystem's used/free bytes.
Operator-tier (recovery_unit_capture_failed) — deliberately NOT backup_failed,
which is customer-enabled and would email the customer about a failure they
cannot act on. D-c overrides R-158's own proposal here.

R-174: the app-stop guard no longer starts apps onto MISSING drives — a
regression in v0.189.0 code, found by review and closed the same session.
SetStarter got the raw stack manager, whose StartStack has no drive gate,
and Recover runs at startup. R-171 one path over. bootDriveGate could not be
reused whole (its holder #2 is the guard's own marker, and holders #1/#2 read
vars assigned after Recover runs), so holder #3 is extracted into a shared
driveStartGate with a test pinning the delegation. ErrStartRefused splits a
refusal from a failure: both keep the marker, only Failed alarms, because
routing a deliberate hold into NotifyBackupFailed is the same false alarm.

Tests 1157 -> 1184. All red-proofs demonstrated failing and restored.

controller/internal/backup/appstop_drivegate_test.go

@@ -0,0 +1,229 @@
+package backup
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// R-174 — the app-stop guard's crash recovery must not start an app onto a MISSING drive.
+//
+// The defect these pin, found by review on 2026-08-02 in code shipped 2026-08-01 (v0.189.0):
+// `appStopGuard.SetStarter(stackMgr)` handed Recover the raw stack manager, whose `StartStack` has
+// no drive gate. Recover runs at STARTUP — exactly when an external drive may not have come back —
+// so a backup that stopped an app, followed by a power cut and a drive that did not remount, ended
+// with the app started onto a missing drive. R-171 one path over.
+//
+// THE SEAM UNDER TEST IS THE STARTER, not the gate: `internal/backup` must not import `stacks` or
+// `settings`, so the production gate lives in `cmd/controller`. What is pinned here is the contract
+// between them — that a starter returning ErrStartRefused produces a REFUSAL (marker kept, no alarm)
+// and not a FAILURE. The production wiring itself is pinned by TestMainWiresGatedAppStopStarter.
+
+// gatingStarter is a starter whose gate refuses a named set of apps, in the shape the production
+// `gatedAppStopStarter` uses: refuse BEFORE calling through, and wrap ErrStartRefused with a reason.
+type gatingStarter struct {
+	inner   *fakeStarter
+	refuse  map[string]string // app → reason
+	refused []string
+}
+
+func (s *gatingStarter) StartStack(name string) error {
+	if why, ok := s.refuse[name]; ok {
+		s.refused = append(s.refused, name)
+		return fmt.Errorf("%w: %s", ErrStartRefused, why)
+	}
+	return s.inner.StartStack(name)
+}
+
+func newGatedGuard(t *testing.T, dir string, refuse map[string]string) (*AppStopGuard, *gatingStarter) {
+	t.Helper()
+	s := &gatingStarter{inner: &fakeStarter{}, refuse: refuse}
+	g := NewAppStopGuard(filepath.Join(dir, "appstop-state.json"), log.New(io.Discard, "", 0))
+	g.SetStarter(s)
+	return g, s
+}
+
+// --- Scenario A — the guard does not start an app onto a missing drive ---------------------------
+
+func TestRecover_DriveAbsent_RefusesTheStartAndKEEPSTheMarker(t *testing.T) {
+	dir := t.TempDir()
+
+	// process 1: a volume dump stops immich, then the box loses power. No End(), no defer.
+	g1, _ := newGatedGuard(t, dir, nil)
+	if err := g1.Begin("volume-dump:immich", ReasonVolumeDump, []string{"immich"}); err != nil {
+		t.Fatalf("Begin: %v", err)
+	}
+	// <power cut> — and immich's drive does NOT come back.
+
+	// process 2: a fresh controller starts. The drive is absent.
+	g2, starter := newGatedGuard(t, dir, map[string]string{
+		"immich": "drive /mnt/felhom-drives/hdd_1 is not a live mountpoint",
+	})
+	res := g2.Recover()
+
+	if len(starter.inner.starts) != 0 {
+		t.Fatalf("started %v — the app was started onto a MISSING drive, which is the whole defect",
+			starter.inner.starts)
+	}
+	if res == nil {
+		t.Fatal("Recover returned nil — the refusal is invisible to the caller, so nothing can report it")
+	}
+	if len(res.Refused) != 1 || res.Refused[0] != "immich" {
+		t.Fatalf("refused=%v, want [immich]", res.Refused)
+	}
+	if len(res.Failed) != 0 {
+		t.Fatalf("failed=%v — a deliberate hold was recorded as a FAILURE. That bucket reaches "+
+			"NotifyBackupFailed, which is customer-enabled by default, so the customer would be "+
+			"emailed \"A biztonsági mentés sikertelen!\" about an app nothing is wrong with (R-171's "+
+			"false-alarm shape one path over)", res.Failed)
+	}
+	if !markerExists(t, dir) {
+		t.Fatal("the marker was CLEARED after a refused start — the operation is genuinely " +
+			"unfinished, and clearing it erases the only durable record that immich is owed a restart")
+	}
+	// The refusal must name the app AND the reason, or an operator cannot act on it.
+	if d := res.Detail(); !strings.Contains(d, "held_by_drive") || !strings.Contains(d, "immich") {
+		t.Fatalf("detail %q does not name the held app", d)
+	}
+	if msg := res.Message(); !strings.Contains(msg, "HELD") || !strings.Contains(msg, "drive") {
+		t.Fatalf("operator message %q does not say the app is held by an absent drive", msg)
+	}
+}
+
+// A refusal-only recovery MUST NOT alarm. This is the assertion that keeps the fix from being the
+// bug it fixes: the drive gate doing its job is not a backup failure.
+func TestRecover_RefusalOnly_IsNotAlarming(t *testing.T) {
+	dir := t.TempDir()
+	g1, _ := newGatedGuard(t, dir, nil)
+	if err := g1.Begin("volume-dump:immich", ReasonVolumeDump, []string{"immich"}); err != nil {
+		t.Fatal(err)
+	}
+	g2, _ := newGatedGuard(t, dir, map[string]string{"immich": "drive /mnt/felhom-drives/hdd_1 is not a live mountpoint"})
+	res := g2.Recover()
+
+	if res.Alarming() {
+		t.Fatal("a recovery that only REFUSED starts reports as alarming — main.go would push it " +
+			"through NotifyBackupFailed and email the customer about a working drive gate")
+	}
+}
+
+// A genuine failure alongside a refusal still alarms, and the two stay in different buckets.
+func TestRecover_FailureAlongsideRefusal_StillAlarmsAndKeepsThemApart(t *testing.T) {
+	dir := t.TempDir()
+	g1, _ := newGatedGuard(t, dir, nil)
+	if err := g1.Begin("volume-dump:batch", ReasonVolumeDump, []string{"immich", "nextcloud", "homebox"}); err != nil {
+		t.Fatal(err)
+	}
+
+	g2, starter := newGatedGuard(t, dir, map[string]string{"immich": "drive /mnt/felhom-drives/hdd_1 is not a live mountpoint"})
+	starter.inner.failWith = map[string]error{"nextcloud": errors.New("compose up: no such image")}
+	res := g2.Recover()
+
+	if len(res.Refused) != 1 || res.Refused[0] != "immich" {
+		t.Fatalf("refused=%v, want [immich]", res.Refused)
+	}
+	if len(res.Failed) != 1 || res.Failed[0] != "nextcloud" {
+		t.Fatalf("failed=%v, want [nextcloud]", res.Failed)
+	}
+	if len(res.Restarted) != 1 || res.Restarted[0] != "homebox" {
+		t.Fatalf("restarted=%v, want [homebox] — neither a refusal nor a failure may abort the loop",
+			res.Restarted)
+	}
+	if !res.Alarming() {
+		t.Fatal("a genuine restart FAILURE alongside a refusal no longer alarms — the refusal " +
+			"swallowed a real fault")
+	}
+	if !markerExists(t, dir) {
+		t.Fatal("the marker was cleared with work still owed")
+	}
+	// The message must not let the held app inflate the failure count.
+	msg := res.Message()
+	if !strings.Contains(msg, "1 of 2 app(s) could NOT be restarted") {
+		t.Fatalf("operator message %q miscounts: the held app must not be counted as a failure", msg)
+	}
+	if !strings.Contains(msg, "not counted as failures") {
+		t.Fatalf("operator message %q does not disclose the held app at all", msg)
+	}
+}
+
+// --- Scenario B — a live drive still recovers normally, byte-identical to before -----------------
+
+func TestRecover_DriveLive_RecoversExactlyAsBefore(t *testing.T) {
+	dir := t.TempDir()
+	g1, _ := newGatedGuard(t, dir, nil)
+	if err := g1.Begin("volume-dump:immich", ReasonVolumeDump, []string{"immich", "nextcloud"}); err != nil {
+		t.Fatal(err)
+	}
+
+	// Nothing refused — the gate says yes for both.
+	g2, starter := newGatedGuard(t, dir, nil)
+	res := g2.Recover()
+
+	if len(starter.inner.starts) != 2 {
+		t.Fatalf("started %v, want both apps — the new gate refused a LEGITIMATE recovery",
+			starter.inner.starts)
+	}
+	if len(res.Refused) != 0 || len(res.Failed) != 0 {
+		t.Fatalf("refused=%v failed=%v, want neither on a live drive", res.Refused, res.Failed)
+	}
+	if len(res.Restarted) != 2 {
+		t.Fatalf("restarted=%v, want both", res.Restarted)
+	}
+	if markerExists(t, dir) {
+		t.Fatal("the marker survived a fully successful recovery — the next boot would restart the apps again")
+	}
+	if !res.Alarming() {
+		t.Fatal("a successful recovery no longer reports to the operator — the interrupted operation " +
+			"itself is what §2.4 wants reported, and it went silent")
+	}
+}
+
+// The next startup, with the drive back, completes the recovery and clears the marker. This is what
+// makes "keep the marker" a recovery rather than a leak.
+func TestRecover_HeldAppIsRestartedOnceTheDriveReturns(t *testing.T) {
+	dir := t.TempDir()
+	g1, _ := newGatedGuard(t, dir, nil)
+	if err := g1.Begin("volume-dump:immich", ReasonVolumeDump, []string{"immich"}); err != nil {
+		t.Fatal(err)
+	}
+
+	// Boot 1 — drive absent: refused, marker kept.
+	g2, _ := newGatedGuard(t, dir, map[string]string{"immich": "drive /mnt/felhom-drives/hdd_1 is not a live mountpoint"})
+	if res := g2.Recover(); len(res.Refused) != 1 {
+		t.Fatalf("boot 1 refused=%v, want [immich]", res.Refused)
+	}
+	if !markerExists(t, dir) {
+		t.Fatal("boot 1 cleared the marker — boot 2 has nothing to act on and immich stays down forever")
+	}
+
+	// Boot 2 — the drive is back.
+	g3, starter := newGatedGuard(t, dir, nil)
+	res := g3.Recover()
+	if len(starter.inner.starts) != 1 || starter.inner.starts[0] != "immich" {
+		t.Fatalf("boot 2 started %v, want [immich] — the held app was never picked up again",
+			starter.inner.starts)
+	}
+	if len(res.Restarted) != 1 {
+		t.Fatalf("boot 2 restarted=%v, want [immich]", res.Restarted)
+	}
+	if markerExists(t, dir) {
+		t.Fatal("boot 2 kept the marker after a fully successful recovery")
+	}
+}
+
+// ErrStartRefused must be matched with errors.Is, i.e. it survives wrapping. A starter that returns
+// a bare string reason would land in Failed and alarm — the exact collapse this type prevents.
+func TestErrStartRefused_SurvivesWrapping(t *testing.T) {
+	err := fmt.Errorf("%w: drive /mnt/felhom-drives/hdd_1 is not a live mountpoint", ErrStartRefused)
+	if !errors.Is(err, ErrStartRefused) {
+		t.Fatal("a wrapped ErrStartRefused is no longer matched by errors.Is — every refusal would " +
+			"be recorded as a restart failure and alarm the customer")
+	}
+	if errors.Is(errors.New("compose up: no such image"), ErrStartRefused) {
+		t.Fatal("an ordinary restart failure matches ErrStartRefused — real faults would go silent")
+	}
+}

controller/internal/backup/appstop_marker.go

@@ -2,6 +2,7 @@ package backup
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log"
 	"os"
@@ -72,10 +73,27 @@ type AppStopMarker struct {
 
 // AppStopStarter is the one thing recovery needs: the ability to start a stack. StartStack must be
 // idempotent (it is — `compose up -d` on a running stack is a no-op).
+//
+// R-174: production MUST pass a GATED starter, never the raw stack manager. Recover runs at STARTUP —
+// exactly when an external drive may not have come back — and `Manager.StartStack` has no drive gate
+// of its own. See `gatedAppStopStarter` in cmd/controller/main.go.
 type AppStopStarter interface {
 	StartStack(name string) error
 }
 
+// ErrStartRefused is what a gated starter returns when a DELIBERATE HOLDER — today the drive gate —
+// says an app must not be started. Wrap it (`fmt.Errorf("%w: …", ErrStartRefused)`) so the reason
+// survives; Recover matches with errors.Is.
+//
+// IT IS NOT A FAILURE, AND THE DISTINCTION IS THE WHOLE POINT OF THE TYPE. A refusal means the
+// holder is doing its job and owns the restart; a failure means the restart was attempted and broke.
+// Collapsing the two would put a deliberately-held app into `Failed`, which main.go reports through
+// `NotifyBackupFailed` — a type that is customer-enabled by default (`settings.DefaultEnabledEvents`)
+// and carries the Hungarian "A biztonsági mentés sikertelen!". That is R-171's defect one path over:
+// a false alarm about an app the drive gate is deliberately holding. Both buckets keep the marker;
+// only `Failed` alarms.
+var ErrStartRefused = errors.New("start refused by a deliberate holder")
+
 // AppStopGuard owns one marker file. Construct with NewAppStopGuard; the zero value is inert (every
 // method is a no-op on a nil guard), so a caller that was never wired degrades to pre-v0.189.0
 // behaviour instead of panicking.
@@ -98,7 +116,21 @@ type AppStopRecovery struct {
 	OpID      string
 	StartedAt time.Time
 	Restarted []string // apps started again by this recovery
-	Failed    []string // apps that could NOT be restarted (the marker was kept for these)
+	Failed    []string // apps whose restart was ATTEMPTED and broke (the marker was kept for these)
+	// Refused are apps a deliberate holder said must not start — today, an absent data drive
+	// (R-174). The marker is kept for these too, but they are NOT a fault and MUST NOT alarm: the
+	// holder owns the restart. Separate from Failed for the reason recorded on ErrStartRefused.
+	Refused []string
+}
+
+// Alarming reports whether this recovery is worth paging an operator about. A recovery that only
+// REFUSED starts is the drive gate working as designed, and reporting it through the customer-enabled
+// `backup_failed` type would be the R-171 false alarm one path over.
+func (r *AppStopRecovery) Alarming() bool {
+	if r == nil {
+		return false
+	}
+	return len(r.Failed) > 0 || len(r.Restarted) > 0
 }
 
 // Message is the operator-facing headline for an interrupted operation.
@@ -107,11 +139,23 @@ func (r *AppStopRecovery) Message() string {
 		return ""
 	}
 	if len(r.Failed) > 0 {
-		return fmt.Sprintf("%s was interrupted by a controller restart and %d of %d app(s) could NOT be restarted",
+		m := fmt.Sprintf("%s was interrupted by a controller restart and %d of %d app(s) could NOT be restarted",
 			r.Reason.humanReason(), len(r.Failed), len(r.Restarted)+len(r.Failed))
+		if len(r.Refused) > 0 {
+			m += fmt.Sprintf(" (a further %d are held by an absent drive and are not counted as failures)", len(r.Refused))
+		}
+		return m
 	}
-	return fmt.Sprintf("%s was interrupted by a controller restart — %d app(s) were left stopped and have been restarted",
+	if len(r.Refused) > 0 && len(r.Restarted) == 0 {
+		return fmt.Sprintf("%s was interrupted by a controller restart — %d app(s) are left stopped and HELD: their data drive is not available, so the drive gate restarts them when it returns",
+			r.Reason.humanReason(), len(r.Refused))
+	}
+	m := fmt.Sprintf("%s was interrupted by a controller restart — %d app(s) were left stopped and have been restarted",
 		r.Reason.humanReason(), len(r.Restarted))
+	if len(r.Refused) > 0 {
+		m += fmt.Sprintf("; %d more are held by an absent drive", len(r.Refused))
+	}
+	return m
 }
 
 // Detail is the machine-readable tail. App/stack NAMES only — never env values (§9.5).
@@ -124,6 +168,9 @@ func (r *AppStopRecovery) Detail() string {
 	if len(r.Failed) > 0 {
 		d += fmt.Sprintf(" restart_failed=%v", r.Failed)
 	}
+	if len(r.Refused) > 0 {
+		d += fmt.Sprintf(" held_by_drive=%v", r.Refused)
+	}
 	return d
 }
 
@@ -210,6 +257,15 @@ func (g *AppStopGuard) Recover() *AppStopRecovery {
 	res := &AppStopRecovery{Reason: m.Reason, OpID: m.OpID, StartedAt: m.StartedAt}
 	for _, name := range m.Stacks {
 		if err := g.starter.StartStack(name); err != nil {
+			// R-174: a REFUSAL is not a failure. The starter's gate has said this app must not be
+			// started (an absent data drive), so the app is left down deliberately and the holder
+			// owns the restart. Logged at WARN with the reason, and kept out of Failed so it never
+			// reaches the customer-enabled backup_failed alarm — see ErrStartRefused.
+			if errors.Is(err, ErrStartRefused) {
+				g.logger.Printf("[WARN] [appstop] crash recovery: NOT restarting %s — %v; the marker is KEPT and the holder owns the restart", name, err)
+				res.Refused = append(res.Refused, name)
+				continue
+			}
 			g.logger.Printf("[ERROR] [appstop] crash recovery: restart %s failed: %v", name, err)
 			res.Failed = append(res.Failed, name)
 			continue
@@ -218,13 +274,23 @@ func (g *AppStopGuard) Recover() *AppStopRecovery {
 		res.Restarted = append(res.Restarted, name)
 	}
 	sort.Strings(res.Failed)
+	sort.Strings(res.Refused)
 	sort.Strings(res.Restarted)
 
+	// The marker is kept for BOTH unfinished outcomes, for the same reason and with different
+	// urgency: a failed restart is retried next startup, and a refused one is genuinely unfinished
+	// until its drive returns. Clearing it in either case would erase the only durable record that
+	// an app is owed a restart.
 	if len(res.Failed) > 0 {
 		g.logger.Printf("[ERROR] [appstop] crash recovery: %d app(s) could not be restarted — KEEPING the marker so the next startup retries; the dead-app alarm owns them meanwhile: %v",
 			len(res.Failed), res.Failed)
 		return res
 	}
+	if len(res.Refused) > 0 {
+		g.logger.Printf("[WARN] [appstop] crash recovery: %d app(s) were deliberately NOT restarted (drive absent) — KEEPING the marker; this is the gate working, not a fault: %v",
+			len(res.Refused), res.Refused)
+		return res
+	}
 	g.End()
 	return res
 }

controller/internal/backup/backup.go

@@ -32,6 +32,27 @@ type Manager struct {
 	// tier2Notify, if set, is called after each Tier 2 copy (success: err==nil) for notifications.
 	tier2Notify func(stackName, destLabel string, dur time.Duration, err error)
 
+	// unitNotify (R-158 / R-167), if set, is called ONCE PER APP whose Tier-1 recovery-unit capture
+	// FAILED, and the capture loop continues to the next app. Wired in cmd/controller/main.go.
+	//
+	// WHY IT EXISTS. `/backups/apps` is the page a person opens to ask whether ONE app is backed up,
+	// and until now it was the one page that never said: a per-app capture failure was a `[WARN]`
+	// line and went no further. The manager had three notify seams and none for the unit capture —
+	// the FIFTH instance in this project of a mechanism built and left disconnected.
+	//
+	// IT CARRIES THE SPACE FIGURES DELIBERATELY. The overwhelmingly likely cause is a full
+	// filesystem, and an operator who has the used/free bytes at the moment of failure can act
+	// without logging in. It is the same pair of numbers the customer-facing fill warning reports,
+	// which is why the two ship together.
+	//
+	// OPERATOR-TIER. Routed to a hub event type that is in `notify.operatorOnlyEvents` — a customer
+	// can take no action on a capture failure. Deliberately NOT `backup_failed`, which is
+	// customer-enabled by default and would email them in Hungarian about it (D-c).
+	//
+	// NO CONTROLLER-SIDE COOLDOWN — the hub owns cooldown, per the offboxEnlargeBlockedNotify
+	// precedent.
+	unitNotify func(stackName string, err error, usage *UnitSpace)
+
 	// appStop (R-166) is the crash marker for operations that stop an app, work on its data, and
 	// start it again. Written BEFORE the stop and cleared AFTER the restart, so a SIGKILL or a power
 	// cut in that window leaves a durable record that Recover honours at the next startup. Built in

controller/internal/backup/recovery_unit.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"gitea.dooplex.hu/admin/felhom-controller/internal/system"
 	"gopkg.in/yaml.v3"
 )
 
@@ -196,8 +197,54 @@ func (m *Manager) CaptureRecoveryUnit(stackName string) error {
 	return nil
 }
 
+// UnitSpace is the target filesystem's occupancy at the moment a capture failed — the numbers that
+// answer "why" without an operator logging in. Nil when the filesystem could not be read at all
+// (system.GetDiskUsage returns nil on error), which is reported as unknown rather than as full.
+type UnitSpace struct {
+	Path        string
+	UsedGB      float64
+	AvailGB     float64
+	TotalGB     float64
+	UsedPercent float64
+}
+
+// String renders the space figures for an operator, or says plainly that they are unknown. An absent
+// reading must never render as zeros — "0 GB free" and "we could not look" are opposite diagnoses.
+func (u *UnitSpace) String() string {
+	if u == nil {
+		return "target filesystem usage unavailable"
+	}
+	return fmt.Sprintf("%s: %.1f/%.1f GB used (%.0f%%), %.1f GB free",
+		u.Path, u.UsedGB, u.TotalGB, u.UsedPercent, u.AvailGB)
+}
+
+// SetUnitNotify wires the per-app recovery-unit capture failure alert (R-158 / R-167). INIT-ONLY —
+// call once at startup, in main.go, alongside SetOffboxNotify. Nil-safe: an unwired seam is silently
+// the pre-v0.191.0 behaviour, which is a `[WARN]` line and nothing else.
+func (m *Manager) SetUnitNotify(fn func(stackName string, err error, usage *UnitSpace)) {
+	m.unitNotify = fn
+}
+
+// unitTargetSpace reads the occupancy of the filesystem a unit for `stackName` would be written to.
+// Nil on an unreadable path — never a fabricated zero (§8.4: an unreadable filesystem is not a full
+// one, and the drive gate already owns the absent-drive case).
+func (m *Manager) unitTargetSpace(stackName string) *UnitSpace {
+	path := m.GetAppDrivePath(stackName)
+	if path == "" {
+		return nil
+	}
+	di := system.GetDiskUsage(path)
+	if di == nil {
+		return nil
+	}
+	return &UnitSpace{
+		Path: path, UsedGB: di.UsedGB, AvailGB: di.AvailGB,
+		TotalGB: di.TotalGB, UsedPercent: di.UsedPercent,
+	}
+}
+
 // captureAllRecoveryUnits refreshes the recovery unit for every deployed stack. Best-effort:
-// a per-app failure is logged and does not abort the others.
+// a per-app failure is logged, NOTIFIED (R-158), and does not abort the others.
 func (m *Manager) captureAllRecoveryUnits() {
 	if m.stackProvider == nil {
 		return
@@ -209,6 +256,12 @@ func (m *Manager) captureAllRecoveryUnits() {
 		}
 		if err := m.CaptureRecoveryUnit(stack.Name); err != nil {
 			m.logger.Printf("[WARN] [backup] Recovery unit capture failed for %s: %v", stack.Name, err)
+			// R-158: per app, and the loop CONTINUES — one app's failure must not silence the
+			// others, and it must not abort their captures either. The space figures are read at
+			// the moment of failure, because the point is to answer "why" (usually: no room).
+			if m.unitNotify != nil {
+				m.unitNotify(stack.Name, err, m.unitTargetSpace(stack.Name))
+			}
 		}
 	}
 }

controller/internal/backup/recovery_unit_notify_test.go

@@ -0,0 +1,182 @@
+package backup
+
+import (
+	"io"
+	"log"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/appbackup"
+)
+
+// R-158 / R-167 (D-c, operator half) — a per-app Tier-1 recovery-unit capture failure must reach a
+// hub channel.
+//
+// THE GAP THESE CLOSE. `captureAllRecoveryUnits` logged `[WARN] Recovery unit capture failed for %s`
+// and stopped there. The manager carried three notify seams — tier2Notify, offboxNotify,
+// offboxEnlargeBlockedNotify — and none for the unit capture, so the one page a person opens to ask
+// whether ONE app is backed up (`/backups/apps`) was the one page that never said. Fifth instance in
+// this project of a mechanism built and left disconnected.
+
+// unitFailProvider lists a fixed set of stacks and refuses GetStackRecoveryInfo for the named ones,
+// which is the earliest real failure inside CaptureRecoveryUnit ("stack %q not found").
+type unitFailProvider struct {
+	stacks []string
+	fail   map[string]bool
+	dir    string
+}
+
+func (p *unitFailProvider) GetStackComposePath(string) (string, bool) { return "", false }
+func (p *unitFailProvider) ListDeployedStacks() []StackSummary {
+	out := make([]StackSummary, 0, len(p.stacks))
+	for _, s := range p.stacks {
+		out = append(out, StackSummary{Name: s})
+	}
+	return out
+}
+func (p *unitFailProvider) GetStackHDDMounts(string) []string { return nil }
+func (p *unitFailProvider) GetStackHDDPath(string) string     { return "" }
+func (p *unitFailProvider) GetImportRoot() string             { return "" }
+func (p *unitFailProvider) GetDockerVolumes(string) []string  { return nil }
+func (p *unitFailProvider) StopStack(string) error            { return nil }
+func (p *unitFailProvider) StartStack(string) error           { return nil }
+func (p *unitFailProvider) RefreshAndIsRunning(string) bool   { return true }
+func (p *unitFailProvider) GetStackRecoveryInfo(name string) (RecoveryInfo, bool) {
+	if p.fail[name] {
+		return RecoveryInfo{}, false
+	}
+	return RecoveryInfo{StackDir: filepath.Join(p.dir, "stacks", name)}, true
+}
+func (p *unitFailProvider) RecoverStackSecrets(string, []string) map[string]string { return nil }
+func (p *unitFailProvider) RecreateStackDefinitionFromUnit(string, string, map[string]string) error {
+	return nil
+}
+func (p *unitFailProvider) StartStackServices(string, []string) error { return nil }
+func (p *unitFailProvider) GetStackClassifiedBinds(string) ([]appbackup.ClassifiedBind, bool) {
+	return nil, false
+}
+
+var _ appbackup.StackDataProvider = (*unitFailProvider)(nil)
+
+type unitEvent struct {
+	app   string
+	err   string
+	usage *UnitSpace
+}
+
+func newUnitNotifyManager(t *testing.T, stacks []string, fail map[string]bool) (*Manager, *[]unitEvent) {
+	t.Helper()
+	dir := t.TempDir()
+	m := &Manager{
+		logger:         log.New(io.Discard, "", 0),
+		systemDataPath: dir,
+		stackProvider:  &unitFailProvider{stacks: stacks, fail: fail, dir: dir},
+	}
+	var got []unitEvent
+	m.SetUnitNotify(func(name string, err error, usage *UnitSpace) {
+		got = append(got, unitEvent{app: name, err: err.Error(), usage: usage})
+	})
+	return m, &got
+}
+
+// --- Scenario C — a local unit capture failure reaches the operator ------------------------------
+
+func TestCaptureAll_FailureNotifiesOnceWithTheSpaceFigures(t *testing.T) {
+	m, got := newUnitNotifyManager(t, []string{"immich"}, map[string]bool{"immich": true})
+
+	m.captureAllRecoveryUnits()
+
+	if len(*got) != 1 {
+		t.Fatalf("got %d unit-failure events, want exactly 1 — a per-app Tier-1 capture failure "+
+			"reached no hub channel, which is the R-158 gap un-fixed", len(*got))
+	}
+	e := (*got)[0]
+	if e.app != "immich" {
+		t.Fatalf("event names app %q, want immich — an operator cannot act on an unnamed app", e.app)
+	}
+	if e.err == "" {
+		t.Fatal("the event carries no error — the operator is told a capture failed but not why")
+	}
+	// The space figures are the point: the overwhelmingly likely cause is a full filesystem, and
+	// these answer "why" without an operator logging in.
+	if e.usage == nil {
+		t.Fatal("the event carries no space figures for a readable target filesystem — this is the " +
+			"pair of numbers that makes the alert actionable, and the same pair the customer fill " +
+			"warning reports (which is why the two ship together)")
+	}
+	if e.usage.Path == "" || e.usage.TotalGB <= 0 {
+		t.Fatalf("space figures are not populated: %+v", e.usage)
+	}
+}
+
+// --- Scenario D — one failing app does not silence the others ------------------------------------
+
+func TestCaptureAll_OneFailureDoesNotAbortOrDuplicate(t *testing.T) {
+	m, got := newUnitNotifyManager(t,
+		[]string{"homebox", "immich", "nextcloud"},
+		map[string]bool{"immich": true})
+
+	m.captureAllRecoveryUnits()
+
+	if len(*got) != 1 {
+		t.Fatalf("got %d events, want exactly 1 — either the loop ABORTED on the middle app "+
+			"(and its siblings were never captured), or one failure produced several events: %+v",
+			len(*got), *got)
+	}
+	if (*got)[0].app != "immich" {
+		t.Fatalf("event names %q, want immich", (*got)[0].app)
+	}
+
+	// The siblings must have been ATTEMPTED after the failure — a positive observable, not the
+	// absence of an event. The provider records nothing, so assert via the failure set instead:
+	// flip the LAST app to failing and require both events.
+	m2, got2 := newUnitNotifyManager(t,
+		[]string{"homebox", "immich", "nextcloud"},
+		map[string]bool{"immich": true, "nextcloud": true})
+	m2.captureAllRecoveryUnits()
+	if len(*got2) != 2 {
+		t.Fatalf("got %d events, want 2 — the app AFTER the first failure was never reached, so the "+
+			"loop is aborting rather than continuing: %+v", len(*got2), *got2)
+	}
+	if (*got2)[0].app != "immich" || (*got2)[1].app != "nextcloud" {
+		t.Fatalf("events %+v, want immich then nextcloud in loop order", *got2)
+	}
+}
+
+// A successful capture must be SILENT. An alert that fires on success is an alert an operator learns
+// to ignore.
+func TestCaptureAll_SuccessIsSilent(t *testing.T) {
+	m, got := newUnitNotifyManager(t, []string{"homebox"}, nil)
+	m.captureAllRecoveryUnits()
+	if len(*got) != 0 {
+		t.Fatalf("a successful capture fired %d event(s): %+v", len(*got), *got)
+	}
+}
+
+// The seam must be nil-safe: an unwired notify is the pre-v0.191.0 behaviour (a WARN line), never a
+// panic that takes the whole nightly backup down with it.
+func TestCaptureAll_UnwiredNotifyDoesNotPanic(t *testing.T) {
+	dir := t.TempDir()
+	m := &Manager{
+		logger:         log.New(io.Discard, "", 0),
+		systemDataPath: dir,
+		stackProvider:  &unitFailProvider{stacks: []string{"immich"}, fail: map[string]bool{"immich": true}, dir: dir},
+	}
+	m.captureAllRecoveryUnits() // no SetUnitNotify — must not panic
+}
+
+// §8.4 in the failure direction: an unreadable target filesystem is reported as UNKNOWN, never as
+// zeros. "0 GB free" and "we could not look" are opposite diagnoses, and rendering the second as the
+// first is the presence-is-not-success trap pointing the other way.
+func TestUnitSpace_NilRendersAsUnavailableNotZero(t *testing.T) {
+	var u *UnitSpace
+	s := u.String()
+	if !strings.Contains(s, "unavailable") {
+		t.Fatalf("nil UnitSpace renders as %q — it must say the reading is unavailable", s)
+	}
+	if strings.Contains(s, "0.0") {
+		t.Fatalf("nil UnitSpace renders zeros (%q) — an operator would read \"the disk is full\" "+
+			"from a filesystem nobody could read", s)
+	}
+}