Merge nucleic/mellow-dewy-falcon-rjhr into main

Sources/RunnerHost/Doctor.swift

@@ -525,19 +525,39 @@ public enum Doctor {
 
     /// The macOS 15+ Local Network permission note.
     ///
-    /// Reports `.pass` when the host carries a subnet allowlist, because that
-    /// bypasses the prompt entirely. Otherwise it stays informational: we
-    /// cannot see the grant itself, since Local Network privacy is a Network
-    /// Extension packet filter rather than a TCC entry, so there is no
-    /// database to query and `tccutil` does not apply (Apple, TN3179).
+    /// Reports `.pass` when the host carries a subnet allowlist that actually
+    /// covers where guests turn up, because that bypasses the prompt entirely.
+    /// An allowlist that names some *other* subnet is worse than none, since it
+    /// looks configured while blocking every guest, so it warns rather than
+    /// passing. Without one this stays informational: we cannot see the grant
+    /// itself, since Local Network privacy is a Network Extension packet filter
+    /// rather than a TCC entry, so there is no database to query and `tccutil`
+    /// does not apply (Apple, TN3179).
     public static func localNetworkNote() -> DoctorCheck {
         let name = "local network access"
         let allowed = localNetworkAllowlist()
         if !allowed.isEmpty {
+            if allowed.contains(where: coversVMNetRange) {
+                return DoctorCheck(
+                    name: name,
+                    result: .pass,
+                    detail: "subnet allowlist set: \(allowed.joined(separator: ", "))"
+                )
+            }
             return DoctorCheck(
                 name: name,
-                result: .pass,
-                detail: "subnet allowlist set: \(allowed.joined(separator: ", "))"
+                result: .warn,
+                detail: "subnet allowlist set but does not cover the guest range: "
+                    + allowed.joined(separator: ", "),
+                remediation: """
+                    Virtualization.framework's NAT does not stay on 192.168.64.0/24 — it moves \
+                    to the next free /24 (192.168.65.x, .66.x, …) when one is taken, so \
+                    an allowlist pinned to a single /24 stops working the day the subnet shifts \
+                    and every guest connection then fails with "No route to host". Widen it to \
+                    cover the whole span: sudo defaults write com.apple.network.local-network \
+                    AllowedEthernetLocalNetworkAddresses -array "192.168.64.0/18" (same for \
+                    AllowedWiFiLocalNetworkAddresses), then reboot. See docs/setup.md §2.6.
+                    """
             )
         }
 
@@ -554,11 +574,51 @@ public enum Doctor {
                 Terminal in the GUI session. On an unattended CI host prefer the subnet \
                 allowlist, which needs no prompt and survives rebuilds: sudo defaults write \
                 com.apple.network.local-network AllowedEthernetLocalNetworkAddresses -array \
-                "192.168.64.0/24" (then reboot). See docs/setup.md §2.6.
+                "192.168.64.0/18" (then reboot). See docs/setup.md §2.6.
                 """
         )
     }
 
+    /// The span of addresses a vmnet NAT link can plausibly use.
+    ///
+    /// `192.168.64.0/24` is only the *first* choice: the subnet is picked at
+    /// runtime and steps to the next free /24 when that one is already in use,
+    /// which is why a host that worked yesterday can hand out `192.168.65.x`
+    /// today. Everything from 192.168.64.0 to 192.168.127.255 — a /18 — is
+    /// treated as guest territory so the allowlist survives that drift.
+    static let vmNetFirstAddress: UInt32 = 0xC0A8_4000  // 192.168.64.0
+    static let vmNetLastAddress: UInt32 = 0xC0A8_7FFF  // 192.168.127.255
+
+    /// Whether one allowlist entry covers the whole guest range.
+    ///
+    /// Deliberately all-or-nothing: partial cover is the failure mode being
+    /// warned about, so an entry that contains today's subnet but not
+    /// tomorrow's is not treated as good enough.
+    static func coversVMNetRange(_ entry: String) -> Bool {
+        let parts = entry.split(separator: "/", maxSplits: 1)
+        guard let base = ipv4Value(String(parts[0])) else { return false }
+        let prefix = parts.count == 2 ? Int(parts[1]) : 32
+        guard let prefix, (0...32).contains(prefix) else { return false }
+
+        let mask: UInt32 = prefix == 0 ? 0 : ~UInt32(0) << (32 - prefix)
+        let network = base & mask
+        let broadcast = network | ~mask
+        return network <= vmNetFirstAddress && broadcast >= vmNetLastAddress
+    }
+
+    /// Packs dotted-quad IPv4 into a comparable integer; nil for anything else
+    /// (an IPv6 entry, a hostname, a typo).
+    static func ipv4Value(_ text: String) -> UInt32? {
+        let octets = text.split(separator: ".", omittingEmptySubsequences: false)
+        guard octets.count == 4 else { return nil }
+        var value: UInt32 = 0
+        for octet in octets {
+            guard let number = UInt32(octet), number <= 255 else { return nil }
+            value = value << 8 | number
+        }
+        return value
+    }
+
     /// Subnets pre-authorized for local network access on this host, if any.
     ///
     /// Best effort and never fatal: an unreadable or absent preferences file