fix(vm-guard): decide on the unsent backlog (vfs/queue), not the cache size

27.10.2026 12:24 the guard paused the first full backup at 116 GiB and never
resumed it: it read diskCache.bytesUsed, the whole cache on disk, which keeps
uploaded bands for reading until --vfs-cache-max-size and does not fall when
the upload catches up. At 12:37 the real backlog was 30 GiB (966 bands in
vfs/queue) with the cache still at 116.

The reading now also carries the sum of vfs/queue sizes; pause and resume use
it, and a missing queue answer counts as unknown (do nothing), never as zero.
vm-status shows both numbers. Regression test with the 27.10 values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: mbeczynski

mac-app/Sources/CloudMachineCore/L10nPolish+VM.swift

@@ -154,8 +154,8 @@ extension L10nPolish {
       "nieznany",
     "Unpacking the image failed: %@":
       "Rozpakowanie obrazu nie powiodło się: %@",
-    "Upload buffer:    %@ GiB, queued %@, uploading %@":
-      "Bufor wysyłki:    %@ GiB, w kolejce %@, wysyłane %@",
+    "Still to upload:  %@ GiB in %@ bands, uploading %@ (cache on disk %@ GiB)":
+      "Do wysłania:      %@ GiB w %@ pasmach, wysyłane %@ (cache na dysku %@ GiB)",
     "Upload buffer:    no answer from rclone (rc %@)":
       "Bufor wysyłki:    brak odpowiedzi rclone (rc %@)",
     "When Time Machine has created its empty image, stop the backup (tmutil stopbackup) and run: cloudmachine-agent vm-prepare-bundle":

mac-app/Sources/CloudMachineCore/VMGuard.swift

@@ -4,7 +4,8 @@ import Foundation
 /// than rclone uploads to Google Drive (750 GB a day at most), and the buffer
 /// is the machine's 200 GB disk. One `step()` per launchd run (every 60 s).
 ///
-/// Pause when the buffer holds more than `highGiB` or the disk has less than
+/// Pause when more than `highGiB` is still to upload (`unsentBytes` - not the
+/// cache size, see `VMLayout.BufferStats`) or the disk has less than
 /// `minFreeGiB` free. Resume below `lowGiB` - and ONLY if this guard paused
 /// the backup (the marker file); a backup the person stopped stays stopped.
 /// No answer from the machine or from tmutil means: do nothing.
@@ -42,8 +43,10 @@ public struct VMGuard: Sendable {
     reading: VMLayout.Reading?, backupRunning: Bool?, pausedByGuard: Bool,
     thresholds: Thresholds
   ) -> Action {
-    guard let reading else { return .nothing }
-    let usedGiB = reading.buffer.bytesUsed / gib
+    // No queue = unknown backlog: the cache size would stand in for it, and
+    // it is exactly the number that kept the backup paused on 27.10.
+    guard let reading, let unsent = reading.buffer.unsentBytes else { return .nothing }
+    let usedGiB = unsent / gib
     let freeGiB = reading.freeBytes / gib
     if usedGiB > Int64(thresholds.highGiB) || freeGiB < Int64(thresholds.minFreeGiB) {
       return backupRunning == true ? .pause : .nothing
@@ -109,14 +112,14 @@ public struct VMGuard: Sendable {
     let paused = probes.markerExists()
     let action = Self.decide(
       reading: reading, backupRunning: running, pausedByGuard: paused, thresholds: thresholds)
-    let used = reading.buffer.bytesUsed / Self.gib
+    let used = (reading.buffer.unsentBytes ?? -1) / Self.gib
     let free = reading.freeBytes / Self.gib
     let queued = reading.buffer.uploadsQueued
     switch action {
     case .pause:
       if await probes.tmutil("stopbackup") {
         probes.setMarker(true)
-        probes.log("VM guard: PAUSE - buffer \(used) GiB, queue \(queued), free \(free) GiB")
+        probes.log("VM guard: PAUSE - unsent \(used) GiB, queue \(queued), free \(free) GiB")
       } else {
         probes.log("VM guard: tmutil stopbackup FAILED - buffer \(used) GiB, free \(free) GiB")
       }
@@ -126,7 +129,7 @@ public struct VMGuard: Sendable {
       // for good with nobody left to resume it.
       if await probes.tmutil("startbackup") {
         probes.setMarker(false)
-        probes.log("VM guard: RESUME - buffer \(used) GiB, free \(free) GiB")
+        probes.log("VM guard: RESUME - unsent \(used) GiB, free \(free) GiB")
       } else {
         probes.log("VM guard: tmutil startbackup FAILED - will try again on the next run")
       }

mac-app/Sources/CloudMachineCore/VMLayout.swift

@@ -165,11 +165,38 @@ public enum VMLayout {
     return nil
   }
 
-  /// What rclone's `vfs/stats` says about the upload buffer.
+  /// What rclone says about the upload buffer.
+  ///
+  /// `bytesUsed` is the whole cache on disk, uploaded bands included: rclone
+  /// keeps them for reading until the cache reaches `--vfs-cache-max-size`.
+  /// It does NOT fall when the upload catches up - on 27.10.2026 it stayed at
+  /// 116 GiB for 13 minutes while the real backlog was 30 GiB, and a guard
+  /// deciding on it never resumed the backup. Decisions use `unsentBytes`,
+  /// the sum of `vfs/queue`.
   public struct BufferStats: Equatable, Sendable {
     public var bytesUsed: Int64
     public var uploadsQueued: Int
     public var uploadsInProgress: Int
+    /// Bytes still to upload; `nil` = `vfs/queue` did not answer.
+    public var unsentBytes: Int64?
+
+    public init(
+      bytesUsed: Int64, uploadsQueued: Int, uploadsInProgress: Int, unsentBytes: Int64? = nil
+    ) {
+      self.bytesUsed = bytesUsed
+      self.uploadsQueued = uploadsQueued
+      self.uploadsInProgress = uploadsInProgress
+      self.unsentBytes = unsentBytes
+    }
+  }
+
+  /// Sum of the item sizes in `vfs/queue`; `nil` when it is not that JSON.
+  static func unsentBytes(vfsQueueJSON: String) -> Int64? {
+    guard let data = vfsQueueJSON.data(using: .utf8),
+      let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+      let queue = object["queue"] as? [[String: Any]]
+    else { return nil }
+    return queue.reduce(Int64(0)) { $0 + ((($1["size"] as? NSNumber)?.int64Value) ?? 0) }
   }
 
   static func bufferStats(vfsStatsJSON: String) -> BufferStats? {
@@ -191,23 +218,29 @@ public enum VMLayout {
     public var freeBytes: Int64
   }
 
-  /// The script prints `vfs/stats` JSON on one line, then `CMFREE <bytes>`.
+  /// The script prints `vfs/stats` JSON on one line, `CMQUEUE <vfs/queue JSON>`
+  /// on the next, then `CMFREE <bytes>`.
   static let readingScript =
     "curl -s -m 20 -X POST http://\(Guest.rcAddress)/vfs/stats | tr -d '\\n'; echo; "
+    + "printf 'CMQUEUE '; curl -s -m 20 -X POST http://\(Guest.rcAddress)/vfs/queue | tr -d '\\n'; echo; "
     + "echo CMFREE $(df -B1 --output=avail \(Guest.cacheDir) | tail -1 | tr -dc 0-9)"
 
   /// `nil` unless BOTH parts are there: half an answer is no answer.
   static func reading(scriptOutput: String) -> Reading? {
     var stats: BufferStats?
     var free: Int64?
+    var unsent: Int64?
     for line in scriptOutput.split(separator: "\n") {
-      if line.hasPrefix("CMFREE ") {
+      if line.hasPrefix("CMQUEUE ") {
+        unsent = unsentBytes(vfsQueueJSON: String(line.dropFirst("CMQUEUE ".count)))
+      } else if line.hasPrefix("CMFREE ") {
         free = Int64(line.dropFirst("CMFREE ".count).trimmingCharacters(in: .whitespaces))
       } else if line.hasPrefix("{") {
         stats = bufferStats(vfsStatsJSON: String(line))
       }
     }
-    guard let stats, let free else { return nil }
+    guard var stats, let free else { return nil }
+    stats.unsentBytes = unsent
     return Reading(buffer: stats, freeBytes: free)
   }
 

mac-app/Sources/CloudMachineCore/VMStatus.swift

@@ -100,9 +100,10 @@ public enum VMStatus {
     if let reading = report.reading {
       out.append(
         L10n.tr(
-          "Upload buffer:    %@ GiB, queued %@, uploading %@",
-          "\(reading.buffer.bytesUsed / VMGuard.gib)", "\(reading.buffer.uploadsQueued)",
-          "\(reading.buffer.uploadsInProgress)"))
+          "Still to upload:  %@ GiB in %@ bands, uploading %@ (cache on disk %@ GiB)",
+          reading.buffer.unsentBytes.map { "\($0 / VMGuard.gib)" } ?? "?",
+          "\(reading.buffer.uploadsQueued)", "\(reading.buffer.uploadsInProgress)",
+          "\(reading.buffer.bytesUsed / VMGuard.gib)"))
       out.append(L10n.tr("Free in machine:  %@ GiB", "\(reading.freeBytes / VMGuard.gib)"))
     } else {
       out.append(

mac-app/Tests/CloudMachineAppTests/VMGuardDecisionTests.swift

@@ -13,12 +13,43 @@ final class VMGuardDecisionTests: XCTestCase {
   private let thresholds = VMGuard.Thresholds()
   private let gib: Int64 = 1 << 30
 
-  private func reading(usedGiB: Int64, freeGiB: Int64 = 150, queued: Int = 3) -> VMLayout.Reading {
+  /// `usedGiB` is what is still to upload; the cache on disk is bigger on
+  /// purpose (116 GiB, as on 27.10) so no rule can lean on it by accident.
+  private func reading(
+    usedGiB: Int64, freeGiB: Int64 = 150, queued: Int = 3, cacheGiB: Int64 = 116
+  ) -> VMLayout.Reading {
     VMLayout.Reading(
-      buffer: .init(bytesUsed: usedGiB * gib, uploadsQueued: queued, uploadsInProgress: 1),
+      buffer: .init(
+        bytesUsed: cacheGiB * gib, uploadsQueued: queued, uploadsInProgress: 1,
+        unsentBytes: usedGiB * gib),
       freeBytes: freeGiB * gib)
   }
 
+  /// 27.10.2026 12:24-12:37: paused at 116 GiB of cache, then the backlog fell
+  /// to 30 GiB while the cache stayed at 116 - the guard deciding on the
+  /// cache never resumed. The backlog is what counts.
+  func testResumesOnTheBacklogWhileTheCacheStaysFull() {
+    XCTAssertEqual(
+      VMGuard.decide(
+        reading: reading(usedGiB: 30, cacheGiB: 116), backupRunning: false, pausedByGuard: true,
+        thresholds: thresholds), .resume)
+    XCTAssertEqual(
+      VMGuard.decide(
+        reading: reading(usedGiB: 30, cacheGiB: 116), backupRunning: true, pausedByGuard: false,
+        thresholds: thresholds), .nothing, "a full cache alone must not pause")
+  }
+
+  func testUnknownBacklogDoesNothing() {
+    var r = reading(usedGiB: 0)
+    r.buffer.unsentBytes = nil
+    for paused in [false, true] {
+      XCTAssertEqual(
+        VMGuard.decide(
+          reading: r, backupRunning: true, pausedByGuard: paused, thresholds: thresholds),
+        .nothing)
+    }
+  }
+
   // MARK: - The decision
 
   func testDefaultsAreTheOnesTheFirstBackupRanWith() {

mac-app/Tests/CloudMachineAppTests/VMLayoutTests.swift

@@ -200,4 +200,16 @@ final class VMLayoutTests: XCTestCase {
     XCTAssertFalse(VMStatus.targets(urls: urls, address: "192.168.64.11"))
     XCTAssertFalse(VMStatus.targets(urls: [], address: "192.168.64.10"))
   }
+
+  func testReadingCarriesTheUnsentBacklogFromVfsQueue() {
+    let stats = #"{"diskCache":{"bytesUsed":124554051584,"uploadsQueued":2,"uploadsInProgress":1}}"#
+    let queue = #"{"queue":[{"name":"bands/a","size":33554432},{"name":"bands/b","size":1048576}]}"#
+    let r = VMLayout.reading(scriptOutput: "\(stats)\nCMQUEUE \(queue)\nCMFREE 1\n")
+    XCTAssertEqual(r?.buffer.unsentBytes, 33_554_432 + 1_048_576)
+    XCTAssertEqual(r?.buffer.bytesUsed, 124_554_051_584)
+    let noQueue = VMLayout.reading(scriptOutput: "\(stats)\nCMQUEUE \nCMFREE 1\n")
+    XCTAssertNotNil(noQueue, "stats and free space still make a reading")
+    XCTAssertNil(noQueue?.buffer.unsentBytes, "an empty queue answer is unknown, not zero")
+    XCTAssertEqual(VMLayout.unsentBytes(vfsQueueJSON: #"{"queue":[]}"#), 0)
+  }
 }