After a power cut: remove the dead half-written backup (R-1006); a backup task from before the boot is not in flight (R-1008)

internal/backup/r685_space_test.go

@@ -81,3 +81,28 @@ func TestR685_FailsOpen(t *testing.T) {
 		}
 	}
 }
+
+// TestR1006_LeftoverCleanupRunsBeforeThePreflight — the night of 2026-10-14: a 12.2 GB half-written archive from a power
+// cut held the space, so every later backup was skipped. The cleanup step runs BEFORE the preflight reads the free space:
+// here it „removes" the leftover (free 4 → 16 GiB) and the backup then fits and runs.
+//
+// RED-PROOF: drop the r.beforeBackup call from backup() (or move it after spaceFits) → the backup is skipped → fails.
+func TestR1006_LeftoverCleanupRunsBeforeThePreflight(t *testing.T) {
+	api := spaceAPI(4*gib, 8182759056, "dir")
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	var got []string
+	r.SetBeforeBackup(func(_ context.Context, storage string, vmid int) {
+		got = append(got, storage)
+		if vmid != 9201 {
+			t.Errorf("cleanup asked for vmid %d", vmid)
+		}
+		api.storages[0].Avail = 16 * gib
+	})
+	_, _ = r.Backup(context.Background(), 9201)
+	if len(got) != 1 || got[0] != "local" {
+		t.Fatalf("the cleanup must run once for this target, got %v", got)
+	}
+	if len(api.vzdumps) != 1 {
+		t.Fatalf("after the cleanup freed the space the backup must run, vzdumps=%d", len(api.vzdumps))
+	}
+}

internal/backup/runner.go

@@ -58,8 +58,11 @@ type BackupRunner struct {
 	// tier cannot have that accident — its keep_last defaults to 0 (never prune), so any value
 	// there is a deliberate act.
 	allowPBSPrune bool
-	logger        *slog.Logger
-	now           func() time.Time
+	// beforeBackup runs just before the space preflight (R-1006): it removes a dead half-written vzdump of this guest on
+	// this target, so a leftover from a power cut cannot hold the space this backup needs. nil = nothing.
+	beforeBackup func(ctx context.Context, storage string, vmid int)
+	logger       *slog.Logger
+	now          func() time.Time
 	// rejected remembers the volids already announced by warnRejectedArchiveOnce, so an incomplete
 	// archive is reported ONCE rather than on every 5-minute due-check. Bounded in practice: one
 	// entry per aborted upload, and a process restart clears it. Guarded by rejectedMu because the
@@ -102,6 +105,11 @@ func NewBackupRunnerFull(api BackupAPI, target string, mode proxmox.BackupMode,
 		now: func() time.Time { return time.Now().UTC() }}
 }
 
+// SetBeforeBackup sets the step run just before the space preflight (R-1006: the dead-leftover cleanup).
+func (r *BackupRunner) SetBeforeBackup(fn func(ctx context.Context, storage string, vmid int)) {
+	r.beforeBackup = fn
+}
+
 // localPruneSpec returns the `--prune-backups` spec to apply to THIS backup, or "" to skip pruning. It
 // applies the configured retention ONLY when the target is a non-PBS storage — PBS offsite retention is a
 // separate lifecycle and must never be pruned by the per-run flag (§9). Fail-safe: if the target's type
@@ -183,6 +191,9 @@ func (r *BackupRunner) backup(ctx context.Context, vmid int, onSnapshot func())
 	// R-685 (v0.134.0): will the new archive FIT on a local target? Asked before anything runs, so a
 	// target that cannot hold it is a named SKIP with the numbers, not a nightly "No space left on
 	// device" that only the vzdump log explains (demo-hp, every night from 2026-09-23 — R-684).
+	if r.beforeBackup != nil {
+		r.beforeBackup(ctx, r.target, vmid)
+	}
 	if ok, why := r.spaceFits(ctx, vmid); !ok {
 		rec.Error = BackupSkipNoSpacePrefix + why
 		rec.DurationSeconds = time.Since(start).Seconds()

internal/capability/manifest.go

@@ -117,6 +117,7 @@ var manifest = []Capability{
 	{"guest-reboot", "enroll activate-binds reboot", "/usr/sbin/pct", []string{"reboot", "9201"}, false, ""},
 	{"guest-shutdown", "household power-off: guest shutdown (R-998)", "/usr/sbin/pct", []string{"shutdown", "9201", "--timeout", "120"}, false, ""},
 	{"host-poweroff", "household power-off: host power-off (R-998)", "/usr/bin/systemctl", []string{"poweroff"}, false, ""},
+	{"vzdump-partial-clean", "dead half-written vzdump removal (R-1006)", "/usr/local/sbin/felhom-vzdump-partial-clean", []string{"local", "9201", "vzdump-lxc-9201-2026_10_14-04_42_18.tar.dat"}, false, ""},
 
 	// ---- LAN split-horizon resolver (dnsmasq) ----
 	{"dnsmasq-install", "dnsmasq package install", "/usr/bin/apt-get", []string{"install", "-y", "-q", "dnsmasq"}, false, ""},

internal/capability/r861_injection_test.go

@@ -63,6 +63,15 @@ var r861Injections = []string{
 	"/usr/bin/systemctl reboot",
 	"/usr/bin/systemctl halt",
 	"/usr/bin/systemctl kexec",
+	// R-1006: the partial-cleanup helper takes exactly one storage, one vmid, one half-written name.
+	"/usr/local/sbin/felhom-vzdump-partial-clean local 9201 vzdump-lxc-9201-2026_10_14-04_42_18.tar.zst",
+	"/usr/local/sbin/felhom-vzdump-partial-clean local 9201 vzdump-lxc-9201-2026_10_14-04_42_18.log",
+	"/usr/local/sbin/felhom-vzdump-partial-clean local 9201 ../../etc/vzdump-lxc-9201-2026_10_14-04_42_18.tar.dat",
+	"/usr/local/sbin/felhom-vzdump-partial-clean local 9201 vzdump-lxc-9201-2026_10_14-04_42_18.tar.dat /etc/shadow",
+	"/usr/local/sbin/felhom-vzdump-partial-clean local 9201 vzdump-lxc-9201-2026_10_14-04_42_18.tar.dat;id",
+	"/usr/local/sbin/felhom-vzdump-partial-clean local;id 9201 vzdump-lxc-9201-2026_10_14-04_42_18.tar.dat",
+	"/usr/local/sbin/felhom-vzdump-partial-clean local 9201",
+	"/usr/local/sbin/felhom-vzdump-partial-clean --help",
 }
 
 func TestSudoersRefusesTheR861Injections(t *testing.T) {

internal/localapi/controllersupervisor_test.go

@@ -19,10 +19,10 @@ import (
 // again", and each guard is pinned by the case where acting would be wrong.
 
 type supExec struct {
-	mu        sync.Mutex
-	status    map[int]string // docker .State.Status per vmid; "" = container absent
-	inspectErr error         // non-nil = pct exec itself failed (unknown)
-	restarts  map[int]int
+	mu         sync.Mutex
+	status     map[int]string // docker .State.Status per vmid; "" = container absent
+	inspectErr error          // non-nil = pct exec itself failed (unknown)
+	restarts   map[int]int
 	// onRestart, when set, is the status the container reaches after a restart (a crash-looper
 	// stays "exited").
 	onRestart string
@@ -249,7 +249,6 @@ func TestControllerSupervisorStanza_WireShape(t *testing.T) {
 	}
 }
 
-
 // ---- R-539 (operator ruling 3 of 2026-09-16): the SLOW crash loop ----------------------------------
 
 // supKillOnce kills the controller and lets the supervisor restart it (two confirming sweeps), then

internal/localapi/guestbind.go

@@ -1,13 +1,13 @@
 package localapi
 
 import (
-	"time"
 	"context"
 	"fmt"
 	"log/slog"
 	"strconv"
 	"strings"
 	"sync"
+	"time"
 
 	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
 )

internal/localapi/server.go

@@ -313,10 +313,11 @@ type Server struct {
 	// offsite repository password. OPTIONAL — nil (no hub client configured) makes
 	// POST /escrow/recover-offsite-password answer 503 rather than pretending.
 	escrowRecovery EscrowRecoverer
-	intent         IntentRecorder      // slice 10 P3 (optional)
-	guestBinds     *GuestBindStore     // F9 startup bind re-assert record (optional)
-	formatJobs     *FormatJobStore     // F20-BUG3 detached-format job record (optional)
-	staleLock      StaleLockController // F2-b startup stale-lock recovery (optional)
+	intent         IntentRecorder                      // slice 10 P3 (optional)
+	guestBinds     *GuestBindStore                     // F9 startup bind re-assert record (optional)
+	formatJobs     *FormatJobStore                     // F20-BUG3 detached-format job record (optional)
+	staleLock      StaleLockController                 // F2-b startup stale-lock recovery (optional)
+	partialSweep   func(ctx context.Context, vmid int) // R-1006 start-up sweep of dead vzdump leftovers (optional)
 	// guestPower (F-REBOOT) is per-guest start-attempt state for the guest-power watchdog.
 	// Guarded by guestPowerMu in guestpower.go; in-memory on purpose (see guestPowerState).
 	guestPower map[int]guestPowerState

internal/localapi/stalelock.go

@@ -5,7 +5,9 @@ import (
 	"fmt"
 	"log/slog"
 	"strconv"
+	"sync"
 
+	"gitea.dooplex.hu/admin/felhom-agent/internal/poweroff"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
 )
 
@@ -142,6 +144,11 @@ type staleLockController struct {
 	runner proxmox.Runner
 	pool   string       // ownership registry: only members of this PVE pool are ever scanned (A1)
 	logger *slog.Logger // the one success-path scan-summary line; nil = silent
+	// bootTime is the host's boot time (unix seconds) and whether it could be read (R-1008). nil = the
+	// kernel's btime (poweroff.ProcBtime — the one reader of /proc/stat btime this agent shares).
+	bootTime func() (int64, bool)
+	deadMu   sync.Mutex
+	deadSeen map[string]bool // UPIDs of dead tasks already logged (once per task)
 }
 
 // staleLockAPI is the subset of *proxmox.Client the controller uses (kept narrow for clarity/testing).
@@ -209,19 +216,81 @@ func (c *staleLockController) Lock(ctx context.Context, vmid int) (string, bool,
 	return cfg.Lock(), cfg.OnBoot(), nil
 }
 
+// BackupRunning is THE answer to „is a vzdump in flight for vmid" for all four callers (startup stale-lock
+// recovery, the guest-power watchdog, the household power-off guard, the controller supervisor): every one of
+// them reaches this method through the StaleLockController interface. R-1008: Proxmox keeps a task in
+// `tasks?source=active` after a power cut — nobody is left to end it (measured on demo-hp 2026-10-14: still
+// listed RUNNING after the boot) — so a task that STARTED BEFORE THIS BOOT is dead, not in flight.
 func (c *staleLockController) BackupRunning(ctx context.Context, vmid int) (bool, error) {
 	tasks, err := c.px.ListRunningTasks(ctx)
 	if err != nil {
 		return false, err
 	}
+	bt := c.bootTime
+	if bt == nil {
+		bt = procBootTime
+	}
+	boot, ok := bt()
+	running, dead := vzdumpInFlight(tasks, vmid, boot, ok)
+	for _, t := range dead {
+		c.logDeadOnce(t, vmid, boot)
+	}
+	return running, nil
+}
+
+// vzdumpInFlight decides, from the node's active-task list, whether a vzdump for vmid is in flight. A matching
+// task is in flight when it started at or after the host's boot; one that started before the boot is dead
+// (returned in dead, for the log). FAIL SAFE on doubt — the old answer: an unreadable boot time, or a task whose
+// start time is unknown, counts as in flight. Pure; pinned by stalelock_inflight_test.go.
+func vzdumpInFlight(tasks []proxmox.TaskStatus, vmid int, boot int64, bootOK bool) (bool, []proxmox.TaskStatus) {
 	id := strconv.Itoa(vmid)
+	var dead []proxmox.TaskStatus
 	for _, t := range tasks {
 		// A single-guest vzdump task carries the vmid in its ID field.
-		if t.Type == "vzdump" && t.ID == id {
+		if t.Type != "vzdump" || t.ID != id {
+			continue
+		}
+		if !bootOK || boot <= 0 {
 			return true, nil
 		}
+		start := taskStart(t)
+		if start <= 0 || start >= boot {
+			return true, nil
+		}
+		dead = append(dead, t)
 	}
-	return false, nil
+	return false, dead
+}
+
+// taskStart is the task's start time: the list's starttime field, else the one encoded in its UPID; 0 = unknown.
+func taskStart(t proxmox.TaskStatus) int64 {
+	if t.StartTime > 0 {
+		return t.StartTime
+	}
+	if u, err := proxmox.ParseUPID(t.UPID); err == nil {
+		return int64(u.StartTime)
+	}
+	return 0
+}
+
+// procBootTime reads the kernel's boot time through poweroff.ProcBtime (no second /proc/stat parser).
+func procBootTime() (int64, bool) {
+	b, err := strconv.ParseInt(poweroff.ProcBtime(), 10, 64)
+	return b, err == nil && b > 0
+}
+
+func (c *staleLockController) logDeadOnce(t proxmox.TaskStatus, vmid int, boot int64) {
+	c.deadMu.Lock()
+	defer c.deadMu.Unlock()
+	if c.deadSeen == nil {
+		c.deadSeen = map[string]bool{}
+	}
+	if c.deadSeen[t.UPID] || c.logger == nil {
+		return
+	}
+	c.deadSeen[t.UPID] = true
+	c.logger.Warn("backup-in-flight: a vzdump task from before this boot is listed as active — it is dead, not running",
+		"vmid", vmid, "upid", t.UPID, "task_start", taskStart(t), "host_boot", boot)
 }
 
 func (c *staleLockController) HasVzdumpSnapshot(ctx context.Context, vmid int) (bool, error) {

internal/localapi/stalelock_inflight_test.go

@@ -0,0 +1,195 @@
+package localapi
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-1008: after a power cut Proxmox keeps the dead vzdump task in `tasks?source=active` (measured on demo-hp
+// 2026-10-14: still RUNNING after the boot, started 136 s before it). A task that started before this boot is
+// dead, not in flight. These tests pin the helper (vzdumpInFlight), the production controller, and three of the
+// four callers end to end; the fourth (the controller supervisor) by the structural pin at the bottom.
+
+const testBoot = int64(1791967481) // the C3 boot (power-cut-fixes-2026-10-14)
+
+func vz(vmid string, start int64) proxmox.TaskStatus {
+	return proxmox.TaskStatus{UPID: "UPID:demo-hp:001E6EEC:00000001:6ACF4071:vzdump:" + vmid + ":felhom-agent@pve!agent:",
+		Type: "vzdump", ID: vmid, Status: "RUNNING", StartTime: start}
+}
+
+// RED-PROOF: make vzdumpInFlight return true for every matching task (drop the `start >= boot` test) → this fails.
+func TestVzdumpInFlight_PreBootTaskIsDead(t *testing.T) {
+	running, dead := vzdumpInFlight([]proxmox.TaskStatus{vz("9201", testBoot-136)}, 9201, testBoot, true)
+	if running || len(dead) != 1 {
+		t.Fatalf("a task from before the boot must be dead: running=%v dead=%d", running, len(dead))
+	}
+}
+
+func TestVzdumpInFlight_PostBootTaskRuns(t *testing.T) {
+	for _, start := range []int64{testBoot, testBoot + 600} {
+		if running, _ := vzdumpInFlight([]proxmox.TaskStatus{vz("9201", start)}, 9201, testBoot, true); !running {
+			t.Fatalf("a task started at %d (boot %d) must be in flight", start, testBoot)
+		}
+	}
+}
+
+// RED-PROOF: drop the `!bootOK` early return → a pre-boot task with an unreadable boot is called dead → fails.
+func TestVzdumpInFlight_UnreadableBootFailsSafe(t *testing.T) {
+	// the boot value is a real one on purpose: only bootOK=false may make this „running"
+	if running, _ := vzdumpInFlight([]proxmox.TaskStatus{vz("9201", testBoot-136)}, 9201, testBoot, false); !running {
+		t.Fatal("an unreadable boot time must count as running (fail safe)")
+	}
+}
+
+// RED-PROOF: make taskStart ignore the UPID → StartTime 0 counts as unknown → running; the first case fails.
+func TestVzdumpInFlight_StartFromUPIDThenUnknownFailsSafe(t *testing.T) {
+	tk := vz("9201", 0) // no starttime in the list: the UPID's 6ACF4071 = 1791967345 (before the boot)
+	if running, dead := vzdumpInFlight([]proxmox.TaskStatus{tk}, 9201, testBoot, true); running || len(dead) != 1 {
+		t.Fatalf("the UPID's start time must be used: running=%v", running)
+	}
+	tk.UPID = "garbage"
+	if running, _ := vzdumpInFlight([]proxmox.TaskStatus{tk}, 9201, testBoot, true); !running {
+		t.Fatal("an unknown start time must count as running (fail safe)")
+	}
+}
+
+func TestVzdumpInFlight_OtherGuestOrTypeIgnored(t *testing.T) {
+	tasks := []proxmox.TaskStatus{vz("9202", testBoot+5), {Type: "vzsnapshot", ID: "9201", StartTime: testBoot + 5}}
+	if running, dead := vzdumpInFlight(tasks, 9201, testBoot, true); running || len(dead) != 0 {
+		t.Fatalf("other guests' and other types' tasks are not 9201's backup: running=%v dead=%d", running, len(dead))
+	}
+}
+
+func inflightCtrl(api *fakeStaleLockAPI, runner *recordingRunner, logger *slog.Logger) *staleLockController {
+	c := NewStaleLockController(api, runner, "felhom", logger).(*staleLockController)
+	c.bootTime = func() (int64, bool) { return testBoot, true }
+	return c
+}
+
+// The production controller answers through the helper, and logs a dead task ONCE.
+// RED-PROOF: make BackupRunning ignore bootTime (the pre-R-1008 body) → returns true → fails.
+func TestStaleLockController_BackupRunningIgnoresDeadTask(t *testing.T) {
+	var buf bytes.Buffer
+	api := &fakeStaleLockAPI{tasks: []proxmox.TaskStatus{vz("9201", testBoot-136)}}
+	c := inflightCtrl(api, &recordingRunner{}, slog.New(slog.NewTextHandler(&buf, nil)))
+	for i := 0; i < 3; i++ {
+		if running, err := c.BackupRunning(context.Background(), 9201); err != nil || running {
+			t.Fatalf("dead pre-boot task reported running=%v err=%v", running, err)
+		}
+	}
+	if n := strings.Count(buf.String(), "backup-in-flight: a vzdump task from before this boot"); n != 1 {
+		t.Fatalf("the dead task must be logged exactly once, got %d", n)
+	}
+	api.tasks = []proxmox.TaskStatus{vz("9201", testBoot+30)}
+	if running, _ := c.BackupRunning(context.Background(), 9201); !running {
+		t.Fatal("a post-boot task must be running")
+	}
+}
+
+func poolOf(vmids ...int) proxmox.PoolInfo {
+	var p proxmox.PoolInfo
+	raw := `{"members":[`
+	for i, v := range vmids {
+		if i > 0 {
+			raw += ","
+		}
+		raw += `{"vmid":` + itoaT(v) + `,"type":"lxc"}`
+	}
+	raw += `]}`
+	_ = json.Unmarshal([]byte(raw), &p)
+	return p
+}
+
+// Caller 1 — the startup stale-lock recovery clears the lock a power cut left (the night of 2026-10-14 it said
+// „genuinely in-flight — leaving the lock").
+func TestCaller_StartupStaleLockClearsAfterPowerCut(t *testing.T) {
+	for _, tc := range []struct {
+		start   int64
+		cleared bool
+	}{{testBoot - 136, true}, {testBoot + 30, false}} {
+		api := &fakeStaleLockAPI{tasks: []proxmox.TaskStatus{vz("9201", tc.start)},
+			cfg: map[int]proxmox.GuestConfig{9201: staleCfg("backup", true)}}
+		runner := &recordingRunner{}
+		s := &Server{staleLock: inflightCtrl(api, runner, nil), logger: slog.New(slog.NewTextHandler(discardW{}, nil))}
+		s.recoverOneStaleLock(context.Background(), proxmox.Guest{VMID: 9201, Status: "running"})
+		if runner.unlocked("9201") != tc.cleared {
+			t.Fatalf("task start %d: unlocked=%v, want %v", tc.start, runner.unlocked("9201"), tc.cleared)
+		}
+	}
+}
+
+// Caller 2 — the guest-power watchdog starts a stopped guest despite a dead pre-boot vzdump task.
+func TestCaller_GuestPowerStartsGuestAfterPowerCut(t *testing.T) {
+	for _, tc := range []struct {
+		start   int64
+		started bool
+	}{{testBoot - 136, true}, {testBoot + 30, false}} {
+		api := &fakeStaleLockAPI{lxc: []proxmox.Guest{{VMID: 9201, Status: "stopped"}}, pool: poolOf(9201),
+			tasks: []proxmox.TaskStatus{vz("9201", tc.start)}, cfg: map[int]proxmox.GuestConfig{9201: staleCfg("", true)}}
+		s := gpServer(t, inflightCtrl(api, &recordingRunner{}, nil), nil)
+		s.GuestPowerTick(context.Background())
+		if (len(api.started) == 1) != tc.started {
+			t.Fatalf("task start %d: started=%v, want %v", tc.start, api.started, tc.started)
+		}
+	}
+}
+
+// Caller 3 — the household power-off guard does not refuse „backup running" for a dead task.
+func TestCaller_PowerOffJobBlockerIgnoresDeadTask(t *testing.T) {
+	for _, tc := range []struct {
+		start int64
+		want  string
+	}{{testBoot - 136, ""}, {testBoot + 30, PowerOffBackup}} {
+		rig := newPowerRig(t, 0)
+		rig.srv.staleLock = inflightCtrl(&fakeStaleLockAPI{tasks: []proxmox.TaskStatus{vz("9201", tc.start)}}, &recordingRunner{}, nil)
+		if code, _ := rig.srv.jobBlocker(context.Background(), 9201); code != tc.want {
+			t.Fatalf("task start %d: jobBlocker=%q, want %q", tc.start, code, tc.want)
+		}
+	}
+}
+
+// Caller 4 (the supervisor), the R-1006 cleanup (VzdumpInFlight) and the rest — structural pin: every non-test BackupRunning call in this package goes through
+// s.staleLock (whose one production implementation is staleLockController, which uses vzdumpInFlight), and no
+// other production type implements BackupRunning. If someone adds a second path, this fails.
+func TestBackupRunning_AllCallersUseTheOneHelper(t *testing.T) {
+	files, _ := filepath.Glob("*.go")
+	call := regexp.MustCompile(`([A-Za-z_.]+)\.BackupRunning\(`)
+	impl := regexp.MustCompile(`func \([a-z]+ \*?([A-Za-z]+)\) BackupRunning\(`)
+	callers := 0
+	for _, f := range files {
+		if strings.HasSuffix(f, "_test.go") {
+			continue
+		}
+		b, err := os.ReadFile(f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, m := range call.FindAllStringSubmatch(string(b), -1) {
+			if m[1] != "s.staleLock" {
+				t.Errorf("%s: BackupRunning called on %q, not s.staleLock", f, m[1])
+			}
+			callers++
+		}
+		for _, m := range impl.FindAllStringSubmatch(string(b), -1) {
+			if m[1] != "staleLockController" {
+				t.Errorf("%s: a second production BackupRunning on %s", f, m[1])
+			}
+		}
+	}
+	if callers != 5 {
+		t.Errorf("expected the five known callers (stale-lock, guest-power, power-off, supervisor, the R-1006 cleanup), found %d", callers)
+	}
+	b, _ := os.ReadFile("stalelock.go")
+	if !strings.Contains(string(b), "vzdumpInFlight(tasks, vmid, boot, ok)") {
+		t.Error("staleLockController.BackupRunning no longer answers through vzdumpInFlight")
+	}
+}

internal/localapi/vzpartial_sweep.go

@@ -0,0 +1,33 @@
+package localapi
+
+import "context"
+
+// R-1006: the half-written vzdump cleanup's two needs from the Server, and its start-up sweep. The cleaner itself is
+// internal/vzpartial; the root helper is configs/felhom-vzdump-partial-clean.
+
+// VzdumpInFlight is the one in-flight answer (staleLockController.BackupRunning, R-1008) for the cleanup. No stale-lock
+// controller wired → true: fail safe, nothing is removed.
+func (s *Server) VzdumpInFlight(ctx context.Context, vmid int) (bool, error) {
+	if s.staleLock == nil {
+		return true, nil
+	}
+	return s.staleLock.BackupRunning(ctx, vmid)
+}
+
+// SetPartialSweep sets the start-up sweep: called with every owned guest (the felhom pool, ownership proven).
+func (s *Server) SetPartialSweep(fn func(ctx context.Context, vmid int)) { s.partialSweep = fn }
+
+// SweepVzdumpPartials runs the sweep once for every owned guest. No-op when unwired.
+func (s *Server) SweepVzdumpPartials(ctx context.Context) {
+	if s.partialSweep == nil || s.staleLock == nil {
+		return
+	}
+	guests, err := s.staleLock.Guests(ctx)
+	if err != nil {
+		s.logger.Warn("vzdump-partial: guest list unavailable — skipping the start-up sweep", "err", err)
+		return
+	}
+	for _, g := range guests {
+		s.partialSweep(ctx, g.VMID)
+	}
+}

internal/vzpartial/vzpartial.go

@@ -0,0 +1,208 @@
+// Package vzpartial removes a dead, half-written vzdump backup of a guest from a local dir storage (R-1006).
+//
+// A power cut during the night's whole-guest backup leaves `vzdump-lxc-<vmid>-<date>.tar.dat` and its `.tmp/` directory
+// on the target (demo-hp 2026-10-14: 12.2 GB on the host root). Nothing removes them: Proxmox does not list them as
+// backups, every later backup is skipped „not enough space", and a host root that fills up breaks LVM's own metadata
+// writes (audits/power-cut-fixes-2026-10-14 C4). This package finds such a leftover and asks the root helper
+// /usr/local/sbin/felhom-vzdump-partial-clean to remove it; the helper re-checks every rule as root.
+//
+// Rules here (the helper repeats them, and adds the open-file check the agent cannot do):
+//   - only a `dir` storage; only names of the exact vzdump pattern for that vmid (NamePattern) — never a finished
+//     archive, a log, another guest;
+//   - only when no vzdump for that vmid is in flight (the R-1008 answer: a task from before the boot is not in flight);
+//   - only when dead: last modified before this boot, or untouched for QuietFor.
+//
+// Any doubt leaves the entry and logs why. Pinned by vzpartial_test.go.
+package vzpartial
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// Helper is the root helper's installed path (configs/felhom-vzdump-partial-clean, delivered by the config bundle).
+const Helper = "/usr/local/sbin/felhom-vzdump-partial-clean"
+
+// QuietFor is how long an entry written in THIS boot must be untouched before it counts as dead (the helper's QUIET_S).
+const QuietFor = 120 * time.Second
+
+// NamePattern matches the half-written entries of one guest: the archive being written (.tar.dat / .vma.dat) and the
+// temporary directory (.tmp). The timestamp is vzdump's own (host local time).
+func NamePattern(vmid int) *regexp.Regexp {
+	return regexp.MustCompile(`^vzdump-(lxc|qemu)-` + strconv.Itoa(vmid) +
+		`-[0-9]{4}_[0-9]{2}_[0-9]{2}-[0-9]{2}_[0-9]{2}_[0-9]{2}\.(tar\.dat|vma\.dat|tmp)$`)
+}
+
+// Entry is one leftover found in the dump directory.
+type Entry struct {
+	Name    string
+	Dir     bool
+	ModTime time.Time
+	Size    int64
+}
+
+// Candidates lists the entries of dumpDir that match vmid's half-written pattern. A missing directory is no error.
+func Candidates(dumpDir string, vmid int) ([]Entry, error) {
+	ents, err := os.ReadDir(dumpDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	re := NamePattern(vmid)
+	var out []Entry
+	for _, e := range ents {
+		if !re.MatchString(e.Name()) || e.Type()&os.ModeSymlink != 0 {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if strings.HasSuffix(e.Name(), ".tmp") != info.IsDir() {
+			continue // a .tmp that is not a directory, or an archive name that is one: not vzdump's
+		}
+		mt := info.ModTime()
+		if info.IsDir() {
+			mt = newestUnder(filepath.Join(dumpDir, e.Name()), mt)
+		}
+		out = append(out, Entry{Name: e.Name(), Dir: info.IsDir(), ModTime: mt, Size: info.Size()})
+	}
+	return out, nil
+}
+
+func newestUnder(dir string, mt time.Time) time.Time {
+	_ = filepath.WalkDir(dir, func(_ string, d os.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if i, e := d.Info(); e == nil && i.ModTime().After(mt) {
+			mt = i.ModTime()
+		}
+		return nil
+	})
+	return mt
+}
+
+// Dead decides whether an entry is dead: written before this boot, or untouched for QuietFor. bootOK=false (the boot
+// time could not be read) leaves only the quiet rule.
+func Dead(e Entry, boot time.Time, bootOK bool, now time.Time) (bool, string) {
+	if bootOK && e.ModTime.Before(boot) {
+		return true, "written before this boot"
+	}
+	if age := now.Sub(e.ModTime); age >= QuietFor {
+		return true, "untouched for " + age.Round(time.Second).String()
+	}
+	return false, "modified " + now.Sub(e.ModTime).Round(time.Second).String() + " ago — may still be written"
+}
+
+// StorageAPI is the one Proxmox read the cleaner needs (the storage's type and path).
+type StorageAPI interface {
+	ListStorage(ctx context.Context) ([]proxmox.Storage, error)
+}
+
+// Cleaner removes dead leftovers. All fields but Logger and Now are required; a nil Cleaner is a no-op.
+type Cleaner struct {
+	API      StorageAPI
+	Runner   proxmox.Runner // the fenced sudo runner
+	InFlight func(ctx context.Context, vmid int) (bool, error)
+	Boot     func() (int64, bool)
+	Logger   *slog.Logger
+	Now      func() time.Time
+	// dumpDir maps a storage path to its dump directory (tests); nil = <path>/dump.
+	dumpDir func(path string) string
+}
+
+// Result is one removal or one entry left in place.
+type Result struct {
+	Entry   Entry
+	Removed bool
+	Why     string
+}
+
+// Clean removes the dead leftovers of vmid on storage. It never returns an error for „nothing to do"; every entry it
+// finds is logged with what was done and why.
+func (c *Cleaner) Clean(ctx context.Context, storage string, vmid int) []Result {
+	if c == nil || c.API == nil || c.Runner == nil || c.InFlight == nil || c.Boot == nil {
+		return nil
+	}
+	log := c.Logger
+	if log == nil {
+		log = slog.Default()
+	}
+	now := time.Now
+	if c.Now != nil {
+		now = c.Now
+	}
+	stores, err := c.API.ListStorage(ctx)
+	if err != nil {
+		log.Warn("vzdump-partial: storage list unreadable — not looking for leftovers", "storage", storage, "err", err)
+		return nil
+	}
+	var st *proxmox.Storage
+	for i := range stores {
+		if stores[i].Storage == storage {
+			st = &stores[i]
+			break
+		}
+	}
+	if st == nil || st.Type != "dir" || st.Path == "" {
+		return nil // PBS, LVM, NFS …: vzdump does not leave a .tar.dat there that this agent may remove
+	}
+	dump := filepath.Join(st.Path, "dump")
+	if c.dumpDir != nil {
+		dump = c.dumpDir(st.Path)
+	}
+	ents, err := Candidates(dump, vmid)
+	if err != nil {
+		log.Warn("vzdump-partial: dump directory unreadable", "dir", dump, "err", err)
+		return nil
+	}
+	if len(ents) == 0 {
+		return nil
+	}
+	var out []Result
+	inFlight, err := c.InFlight(ctx, vmid)
+	if err != nil || inFlight {
+		why := "a backup of this guest is in flight"
+		if err != nil {
+			why = "cannot tell whether a backup is in flight: " + err.Error()
+		}
+		for _, e := range ents {
+			log.Info("vzdump-partial: leaving a half-written backup", "storage", storage, "vmid", vmid, "name", e.Name, "why", why)
+			out = append(out, Result{Entry: e, Why: why})
+		}
+		return out
+	}
+	b, bootOK := c.Boot()
+	boot := time.Unix(b, 0)
+	for _, e := range ents {
+		dead, why := Dead(e, boot, bootOK, now())
+		if !dead {
+			log.Info("vzdump-partial: leaving a half-written backup", "storage", storage, "vmid", vmid, "name", e.Name, "why", why)
+			out = append(out, Result{Entry: e, Why: why})
+			continue
+		}
+		stdout, stderr, err := c.Runner.Run(ctx, Helper, storage, strconv.Itoa(vmid), e.Name)
+		if err != nil {
+			why = fmt.Sprintf("the root helper refused: %s", strings.TrimSpace(string(stderr)))
+			log.Warn("vzdump-partial: leaving a half-written backup", "storage", storage, "vmid", vmid, "name", e.Name, "why", why, "err", err)
+			out = append(out, Result{Entry: e, Why: why})
+			continue
+		}
+		log.Warn("vzdump-partial: removed a dead half-written backup", "storage", storage, "vmid", vmid, "name", e.Name,
+			"bytes", e.Size, "why", why, "helper", strings.TrimSpace(string(stdout)))
+		out = append(out, Result{Entry: e, Removed: true, Why: why})
+	}
+	return out
+}

internal/vzpartial/vzpartial_test.go

@@ -0,0 +1,206 @@
+package vzpartial
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+const vmid = 9201
+const name = "vzdump-lxc-9201-2026_10_14-10_42_25"
+
+var boot = time.Unix(1791967481, 0)
+
+type fakeAPI struct{ stores []proxmox.Storage }
+
+func (f fakeAPI) ListStorage(context.Context) ([]proxmox.Storage, error) { return f.stores, nil }
+
+type fakeRunner struct {
+	calls [][]string
+	err   error
+}
+
+func (r *fakeRunner) Run(_ context.Context, n string, a ...string) ([]byte, []byte, error) {
+	r.calls = append(r.calls, append([]string{n}, a...))
+	if r.err != nil {
+		return nil, []byte("REFUSED: in use"), r.err
+	}
+	return []byte("removed"), nil, nil
+}
+func (r *fakeRunner) RunStdin(ctx context.Context, _ io.Reader, n string, a ...string) ([]byte, []byte, error) {
+	return r.Run(ctx, n, a...)
+}
+
+type rig struct {
+	dump   string
+	runner *fakeRunner
+	c      *Cleaner
+}
+
+func newRig(t *testing.T, storeType string, inFlight bool, inErr error) *rig {
+	t.Helper()
+	root := t.TempDir()
+	dump := filepath.Join(root, "dump")
+	if err := os.MkdirAll(dump, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	r := &rig{dump: dump, runner: &fakeRunner{}}
+	r.c = &Cleaner{
+		API:      fakeAPI{stores: []proxmox.Storage{{Storage: "local", Type: storeType, Path: root}}},
+		Runner:   r.runner,
+		InFlight: func(context.Context, int) (bool, error) { return inFlight, inErr },
+		Boot:     func() (int64, bool) { return boot.Unix(), true },
+		Now:      func() time.Time { return boot.Add(5 * time.Minute) },
+	}
+	return r
+}
+
+func (r *rig) put(t *testing.T, n string, dir bool, mt time.Time) {
+	t.Helper()
+	p := filepath.Join(r.dump, n)
+	if dir {
+		if err := os.MkdirAll(filepath.Join(p, "etc"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		_ = os.Chtimes(filepath.Join(p, "etc"), mt, mt)
+	} else if err := os.WriteFile(p, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_ = os.Chtimes(p, mt, mt)
+}
+
+func (r *rig) asked() []string {
+	var out []string
+	for _, c := range r.runner.calls {
+		if len(c) == 4 && c[0] == Helper && c[1] == "local" && c[2] == "9201" {
+			out = append(out, c[3])
+		}
+	}
+	return out
+}
+
+// RED-PROOF: remove the `bootOK && e.ModTime.Before(boot)` rule in Dead → a pre-boot entry modified 1 min before the
+// boot is still „untouched for 6m" — so the test uses a 1-min-old-at-boot entry AND a Now 30 s after the boot.
+func TestClean_RemovesDeadPartialAndTmp(t *testing.T) {
+	r := newRig(t, "dir", false, nil)
+	r.c.Now = func() time.Time { return boot.Add(30 * time.Second) }
+	r.put(t, name+".tar.dat", false, boot.Add(-time.Minute))
+	r.put(t, name+".tmp", true, boot.Add(-time.Minute))
+	res := r.c.Clean(context.Background(), "local", vmid)
+	if got := r.asked(); len(got) != 2 {
+		t.Fatalf("both dead entries must go to the helper, got %v", got)
+	}
+	for _, x := range res {
+		if !x.Removed || x.Why != "written before this boot" {
+			t.Fatalf("%+v", x)
+		}
+	}
+}
+
+func TestClean_RemovesQuietPartialOfThisBoot(t *testing.T) {
+	r := newRig(t, "dir", false, nil)
+	r.put(t, name+".tar.dat", false, boot.Add(time.Minute)) // 4 min before Now
+	r.c.Clean(context.Background(), "local", vmid)
+	if len(r.asked()) != 1 {
+		t.Fatal("a partial untouched for QuietFor must be removed")
+	}
+}
+
+// Each keep has its positive control (the dead pre-boot partial in the same rig IS asked for).
+func TestClean_Keeps(t *testing.T) {
+	cases := map[string]func(t *testing.T) (*rig, string){
+		// RED-PROOF: drop the InFlight check in Clean → the in-flight partial is asked for → fails.
+		"in flight": func(t *testing.T) (*rig, string) { return newRig(t, "dir", true, nil), name + ".tar.dat" },
+		"in-flight unknown": func(t *testing.T) (*rig, string) {
+			return newRig(t, "dir", false, errors.New("api down")), name + ".tar.dat"
+		},
+		// RED-PROOF: drop the `st.Type != "dir"` test → an lvmthin target is cleaned → fails.
+		"not a dir storage": func(t *testing.T) (*rig, string) { return newRig(t, "lvmthin", false, nil), name + ".tar.dat" },
+	}
+	for what, mk := range cases {
+		r, n := mk(t)
+		r.put(t, n, false, boot.Add(-time.Hour))
+		r.c.Clean(context.Background(), "local", vmid)
+		if len(r.asked()) != 0 {
+			t.Fatalf("%s: must keep, helper asked for %v", what, r.asked())
+		}
+		ctl := newRig(t, "dir", false, nil)
+		ctl.put(t, n, false, boot.Add(-time.Hour))
+		ctl.c.Clean(context.Background(), "local", vmid)
+		if len(ctl.asked()) != 1 {
+			t.Fatalf("%s: positive control not removed", what)
+		}
+	}
+}
+
+// RED-PROOF: weaken NamePattern to `vzdump-.*` → the finished archive / log / other guest's partial are asked for.
+func TestClean_OnlyThisGuestsHalfWrittenNames(t *testing.T) {
+	r := newRig(t, "dir", false, nil)
+	old := boot.Add(-time.Hour)
+	for _, n := range []string{name + ".tar.zst", name + ".log", name + ".tar.zst.notes", "vzdump-lxc-9202-2026_10_14-10_42_25.tar.dat",
+		"vzdump-lxc-92011-2026_10_14-10_42_25.tar.dat", name + ".tar.dat.bak", name + ".tar.da", "x" + name + ".tar.dat"} {
+		r.put(t, n, false, old)
+	}
+	r.put(t, name+".tar.dat", false, old) // the positive control in the same directory
+	r.c.Clean(context.Background(), "local", vmid)
+	if got := r.asked(); len(got) != 1 || got[0] != name+".tar.dat" {
+		t.Fatalf("only %s.tar.dat may be asked for, got %v", name, got)
+	}
+}
+
+func TestClean_KeepsRecentAndWrongKindAndSymlink(t *testing.T) {
+	r := newRig(t, "dir", false, nil)
+	r.put(t, name+".tar.dat", false, boot.Add(4*time.Minute))                            // 1 min before Now: may still be written
+	r.put(t, "vzdump-lxc-9201-2026_10_14-11_00_00.tmp", false, boot.Add(-time.Hour))     // a FILE named .tmp
+	r.put(t, "vzdump-lxc-9201-2026_10_14-13_00_00.tar.dat", false, boot.Add(-time.Hour)) // positive control
+	r.c.Clean(context.Background(), "local", vmid)
+	if got := r.asked(); len(got) != 1 || got[0] != "vzdump-lxc-9201-2026_10_14-13_00_00.tar.dat" {
+		t.Fatalf("only the positive control may be asked for, got %v", got)
+	}
+}
+
+// RED-PROOF: drop the ModeSymlink skip in Candidates → the symlink (quiet: Now is an hour ahead) is asked for → fails.
+func TestClean_KeepsSymlink(t *testing.T) {
+	r := newRig(t, "dir", false, nil)
+	r.c.Now = func() time.Time { return time.Now().Add(time.Hour) }
+	target := filepath.Join(r.dump, "elsewhere")
+	_ = os.WriteFile(target, []byte("x"), 0o644)
+	_ = os.Symlink(target, filepath.Join(r.dump, "vzdump-lxc-9201-2026_10_14-12_00_00.tar.dat"))
+	r.put(t, "vzdump-lxc-9201-2026_10_14-13_00_00.tar.dat", false, boot.Add(-time.Hour)) // positive control
+	r.c.Clean(context.Background(), "local", vmid)
+	if got := r.asked(); len(got) != 1 || got[0] != "vzdump-lxc-9201-2026_10_14-13_00_00.tar.dat" {
+		t.Fatalf("only the positive control may be asked for, got %v", got)
+	}
+}
+
+func TestClean_HelperRefusalIsNotARemoval(t *testing.T) {
+	r := newRig(t, "dir", false, nil)
+	r.runner.err = errors.New("exit status 1")
+	r.put(t, name+".tar.dat", false, boot.Add(-time.Hour))
+	res := r.c.Clean(context.Background(), "local", vmid)
+	if len(res) != 1 || res[0].Removed {
+		t.Fatalf("a refused helper call must not count as removed: %+v", res)
+	}
+}
+
+// The root helper's own tests (configs/test_felhom_vzdump_partial_clean.py) run with the Go suite.
+func TestRootHelperPythonSuite(t *testing.T) {
+	py, err := exec.LookPath("python3")
+	if err != nil {
+		t.Skip("python3 not found")
+	}
+	_, file, _, _ := runtime.Caller(0)
+	script := filepath.Join(filepath.Dir(file), "..", "..", "configs", "test_felhom_vzdump_partial_clean.py")
+	out, err := exec.Command(py, script).CombinedOutput()
+	if err != nil {
+		t.Fatalf("helper suite failed: %v\n%s", err, out)
+	}
+}