Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

70.4 KB
Raw Blame
import CoreGraphics
import Foundation
import Virtualization

// MARK: - Support Types

/// Base context for virtual machine directory and configuration
struct VMDirContext {
    let dir: VMDirectory
    var config: VMConfig
    let home: Home
    let storage: String?

    /// Optional override paths for disk and nvram files.
    /// When set, these take precedence over the default directory-based paths.
    /// This allows external tools (e.g. lumelet) to point lume at files
    /// stored outside the standard VM directory layout.
    var diskPathOverride: Path?
    var nvramPathOverride: Path?

    func saveConfig() throws {
        try dir.saveConfig(config)
    }

    var name: String { dir.name }
    var initialized: Bool { dir.initialized() }
    var diskPath: Path { diskPathOverride ?? dir.diskPath }
    var nvramPath: Path { nvramPathOverride ?? dir.nvramPath }

    func setDisk(_ size: UInt64) throws {
        try dir.setDisk(size)
    }

    func finalize(to name: String) throws {
        let vmDir = try home.getVMDirectory(name)
        try FileManager.default.moveItem(at: dir.dir.url, to: vmDir.dir.url)
    }
}

// MARK: - Base VM Class

/// Base class for virtual machine implementations
@MainActor
class VM {
    // MARK: - Properties

    var vmDirContext: VMDirContext
    var telemetryTransport: TelemetryTransport?

    @MainActor
    private var virtualizationService: VMVirtualizationService?
    internal let vncService: VNCService
    private var clipboardWatcher: ClipboardWatcher?
    private var displayPresenter: VMDisplayPresenter?
    private var displayContext: VMDisplayContext?
    private var nativeAttachRegistered = false
    private var activeSharedDirectories: [SharedDirectory] = []
    private var scopedSharedDirectoryURLs: [URL] = []
    private var clipboardTransferInProgress = false
    private var sessionCleanedUp = true
    /// The framework VM is being started or restored: a stop (or suspend)
    /// that arrives meanwhile waits for it, since stopping a VM mid-restore
    /// fails and would leave it running untracked once the restore ends.
    private var starting = false
    /// Policy of the session currently owned by this object. Cleanup needs it
    /// because a VNC-disabled session's marker is not owned by `vncService`.
    private var activeVNCPolicy: VNCPolicy = .enabled
    private var activeNoVNCSession: VNCSession?
    /// Host loopback ports carried to the guest over vsock (a run with
    /// `forwards`), and whether this run's VM has the socket device.
    private var vsockForwarder: VsockForwarder?
    private var activeSocketDevice = false
    internal let virtualizationServiceFactory:
        (VMVirtualizationServiceContext) throws -> VMVirtualizationService
    private let vncServiceFactory: (VMDirectory) -> VNCService
    private let displayPresenterFactory: @MainActor (DisplayMode, VNCService) -> VMDisplayPresenter
    /// Resolves the config-file run-lock owner during cross-process `stop`.
    // Lifecycle commands may run while the host is under VM boot I/O. Give
    // their one-shot lock lookup more time than list/get's latency-bound probe.
    private let runLockProbe: RunLockProbe = LsofRunLockProbe(timeout: 10)

    /// Default number of seconds a graceful `stop` waits for the owning process
    /// to exit before escalating to a forced power-off.
    nonisolated static let defaultStopTimeout: TimeInterval = 10

    /// Signal handlers that let an external `stop` (SIGTERM) or an interactive
    /// Ctrl-C (SIGINT) shut this run down cleanly. Installed only by the process
    /// that actually owns the running VM.
    private var shutdownSignalSources: [DispatchSourceSignal] = []

    // MARK: - Initialization

    init(
        vmDirContext: VMDirContext,
        virtualizationServiceFactory: @escaping (VMVirtualizationServiceContext) throws ->
            VMVirtualizationService = { try DarwinVirtualizationService(configuration: $0) },
        vncServiceFactory: @escaping (VMDirectory) -> VNCService = {
            DefaultVNCService(vmDirectory: $0)
        },
        displayPresenterFactory: @escaping @MainActor (DisplayMode, VNCService) -> VMDisplayPresenter =
            defaultDisplayPresenter
    ) {
        self.vmDirContext = vmDirContext
        self.virtualizationServiceFactory = virtualizationServiceFactory
        self.vncServiceFactory = vncServiceFactory
        self.displayPresenterFactory = displayPresenterFactory

        // Initialize VNC service
        self.vncService = vncServiceFactory(vmDirContext.dir)
    }

    // MARK: - Public Accessors

    /// The VM name
    var name: String { vmDirContext.name }

    /// The VM configuration
    var config: VMConfig { vmDirContext.config }

    /// Whether this process is running the guest: true from the moment `run`
    /// starts until the guest stops or the run fails.
    var isRunActive: Bool { !sessionCleanedUp }

    /// The network mode of the run in progress (the run's override, or the
    /// VM's configured mode), while it runs.
    private(set) var activeNetworkMode: NetworkMode?

    /// The guest's address: the gateway's DHCP lease in gateway mode,
    /// vmnet's leases (or the ARP table) otherwise.
    static func ipAddress(forMAC mac: String, networkMode: NetworkMode?) -> String? {
        if let control = networkMode?.gatewayControlSocket {
            return GatewayNetwork.leasedAddress(control: control, mac: mac)
        }
        return DHCPLeaseParser.getIPAddress(forMAC: mac)
    }

    // MARK: - VM State Management

    private var isRunning: Bool {
        // First check if we have a MAC address
        guard let macAddress = vmDirContext.config.macAddress else {
            Logger.info(
                "Cannot check if VM is running: macAddress is nil",
                metadata: ["name": vmDirContext.name])
            return false
        }

        // Behind a gateway the guest's address is not reachable from the
        // host: the run itself says whether it runs.
        if activeNetworkMode?.gatewayControlSocket != nil {
            return isRunActive
        }

        // Then check if we have an IP address
        guard let ipAddress = DHCPLeaseParser.getIPAddress(forMAC: macAddress) else {
            return false
        }

        // Then check if it's reachable
        return NetworkUtils.isReachable(ipAddress: ipAddress)
    }

    var details: VMDetails {
        let isRunning: Bool = self.isRunning
        let vncUrl = isRunning ? getVNCUrl() : nil

        // Safely get disk size with fallback
        let diskSizeValue: DiskSize
        do {
            diskSizeValue = try getDiskSize()
        } catch {
            Logger.error(
                "Failed to get disk size",
                metadata: ["name": vmDirContext.name, "error": "\(error)"])
            // Provide a fallback value to avoid crashing
            diskSizeValue = DiskSize(allocated: 0, total: vmDirContext.config.diskSize ?? 0)
        }

        // Safely access MAC address
        let macAddress = vmDirContext.config.macAddress
        let ipAddress: String? =
            isRunning && macAddress != nil
            ? VM.ipAddress(forMAC: macAddress!, networkMode: activeNetworkMode) : nil

        // Check if SSH is available (only if we have an IP)
        let sshAvailable: Bool? = ipAddress != nil ? NetworkUtils.isSSHAvailable(ipAddress: ipAddress!) : nil
        let vsockSession = isRunning ? vmDirContext.dir.loadVsockSession() : nil

        return VMDetails(
            name: vmDirContext.name,
            os: getOSType(),
            cpuCount: vmDirContext.config.cpuCount ?? 0,
            memorySize: vmDirContext.config.memorySize ?? 0,
            diskSize: diskSizeValue,
            display: vmDirContext.config.display.string,
            status: isRunning ? "running" : "stopped",
            vncUrl: vncUrl,
            ipAddress: ipAddress,
            sshAvailable: sshAvailable,
            locationName: vmDirContext.storage ?? "home",
            networkMode: vmDirContext.config.networkMode.description,
            machineIdentifier: vmDirContext.config.machineIdentifier?.base64EncodedString(),
            macAddress: macAddress,
            savedState: vmDirContext.dir.hasSavedState(),
            vsock: vsockSession.map { _ in true },
            forwards: vsockSession.flatMap { $0.agent ? $0.forwards : nil }
        )
    }

    // MARK: - VM Lifecycle Management

    static func shouldStartClipboardWatcher(
        displayMode: DisplayMode,
        osType: String,
        explicitlyRequested: Bool
    ) -> Bool {
        explicitlyRequested
            || (displayMode == .native && osType.caseInsensitiveCompare("macOS") == .orderedSame)
    }

    func run(
        displayMode: DisplayMode = .vnc, sharedDirectories: [SharedDirectory], mount: Path?,
        vncPort: Int = 0, vncPassword: String? = nil, recoveryMode: Bool = false,
        usbMassStoragePaths: [Path]? = nil, additionalDiskPaths: [Path]? = nil,
        networkMode: NetworkMode? = nil, clipboard: Bool = false,
        vncPolicy: VNCPolicy = .enabled, forwards: [UInt16] = []
    ) async throws {
        // Defense in depth: the CLI and the controller reject these combinations
        // first, but no caller may reach a VNC-dependent path with VNC disabled.
        if let option = VNCPolicy.conflictingOption(
            policy: vncPolicy,
            displayMode: displayMode,
            vncPort: vncPort,
            vncPassword: vncPassword
        ) {
            throw VMError.vncDisabledConflict(option)
        }

        guard let resizeGuard = try vmDirContext.dir.tryAcquireResizeGuard(exclusive: false) else {
            throw DiskResizeError.resizeInProgress(vmDirContext.name)
        }
        defer {
            flock(resizeGuard.fileDescriptor, LOCK_UN)
            try? resizeGuard.close()
        }
        Logger.info(
            "VM.run method called",
            metadata: [
                "name": vmDirContext.name,
                "displayMode": displayMode.rawValue,
                "vncPolicy": vncPolicy.rawValue,
                "recoveryMode": "\(recoveryMode)",
            ])

        guard vmDirContext.initialized else {
            Logger.error("VM not initialized", metadata: ["name": vmDirContext.name])
            throw VMError.notInitialized(vmDirContext.name)
        }

        guard let cpuCount = vmDirContext.config.cpuCount,
            let memorySize = vmDirContext.config.memorySize
        else {
            Logger.error("VM missing cpuCount or memorySize", metadata: ["name": vmDirContext.name])
            throw VMError.notInitialized(vmDirContext.name)
        }

        if vmDirContext.dir.hasResizeMarker() {
            Logger.error(
                "Refusing to run VM: a disk resize is in progress",
                metadata: ["name": vmDirContext.name])
            throw DiskResizeError.resizeInProgress(vmDirContext.name)
        }

        // Try to acquire lock on config file
        Logger.info(
            "Attempting to acquire lock on config file",
            metadata: [
                "path": vmDirContext.dir.configPath.path,
                "name": vmDirContext.name,
            ])
        let fileHandle = try FileHandle(forWritingTo: vmDirContext.dir.configPath.url)

        if flock(fileHandle.fileDescriptor, LOCK_EX | LOCK_NB) != 0 {
            try? fileHandle.close()
            Logger.error(
                "VM already running (failed to acquire lock)", metadata: ["name": vmDirContext.name]
            )

            throw VMError.alreadyRunning(vmDirContext.name)
        }
        Logger.info("Successfully acquired lock", metadata: ["name": vmDirContext.name])
        defer {
            flock(fileHandle.fileDescriptor, LOCK_UN)
            try? fileHandle.close()
        }
        guard let owner = RunOwner.current() else { throw VMError.unsafeOwner(vmDirContext.name) }
        try owner.save(vmDirContext.dir.runOwnerURL)
        defer { owner.remove(vmDirContext.dir.runOwnerURL) }
        sessionCleanedUp = false
        activeVNCPolicy = vncPolicy
        activeNoVNCSession = nil
        activeSharedDirectories = sharedDirectories

        Logger.info(
            "Running VM with configuration",
            metadata: [
                "name": vmDirContext.name,
                "cpuCount": "\(cpuCount)",
                "memorySize": "\(memorySize)",
                "diskSize": "\(vmDirContext.config.diskSize ?? 0)",
                "sharedDirectories": sharedDirectories.map { $0.string }.joined(separator: ", "),
                "recoveryMode": "\(recoveryMode)",
            ])

        // Create and configure the VM
        do {
            // Create a lume-config shared directory so the guest can discover
            // the VNC port/password at boot.  The directory is created empty now
            // and populated after the VNC server starts (VirtioFS exposes live
            // host directory contents, so the guest will see the file once written).
            let lumeConfigDir = FileManager.default.temporaryDirectory
                .appendingPathComponent("lume-config-\(vmDirContext.name)")
            // Remove stale vnc.env from a previous run so the guest doesn't
            // read outdated port/password before the new file is written. A
            // VNC-disabled run does the same removal so nothing left by an
            // earlier VNC-enabled run of this VM can leak into the guest.
            try? FileManager.default.removeItem(
                at: lumeConfigDir.appendingPathComponent("vnc.env"))
            var allSharedDirectories = sharedDirectories
            if vncPolicy.isEnabled {
                try? FileManager.default.createDirectory(
                    at: lumeConfigDir, withIntermediateDirectories: true)
                allSharedDirectories.append(
                    SharedDirectory(
                        hostPath: lumeConfigDir.path, tag: "lume-config", readOnly: true))
            }

            Logger.info(
                "Creating virtualization service context", metadata: ["name": vmDirContext.name])
            var config = try createVMVirtualizationServiceContext(
                cpuCount: cpuCount,
                memorySize: memorySize,
                display: vmDirContext.config.display.string,
                sharedDirectories: allSharedDirectories,
                mount: mount,
                recoveryMode: recoveryMode,
                usbMassStoragePaths: usbMassStoragePaths,
                additionalDiskPaths: additionalDiskPaths,
                networkMode: networkMode
            )
            activeNetworkMode = config.networkMode
            // A saved state restores only into the devices it was saved
            // with: one saved without the socket device resumes without
            // forwards (the client then uses the VM's address).
            activeSocketDevice = Self.usesSocketDevice(
                forwards: forwards,
                hasSavedState: !recoveryMode && vmDirContext.dir.hasSavedState(),
                savedStateHasVsock: vmDirContext.dir.savedStateHasVsock())
            config.socketDevice = activeSocketDevice
            vmDirContext.dir.clearVsockSession()
            Logger.info(
                "Successfully created virtualization service context",
                metadata: ["name": vmDirContext.name])

            Logger.info(
                "Initializing virtualization service", metadata: ["name": vmDirContext.name])
            virtualizationService = try virtualizationServiceFactory(config)
            Logger.info(
                "Successfully initialized virtualization service",
                metadata: ["name": vmDirContext.name])

            guard var service = virtualizationService else {
                Logger.error("Virtualization service is nil", metadata: ["name": vmDirContext.name])
                throw VMError.internalError("Virtualization service not initialized")
            }

            // A VM with a saved state (`suspend`, or a clone of a suspended
            // VM) resumes from it; that happens before the VNC server
            // attaches, since a state that cannot be restored leaves the
            // framework VM unusable and the VM boots on a fresh one.
            let resumedFromState = !recoveryMode && vmDirContext.dir.hasSavedState()
            if resumedFromState {
                starting = true
                defer { starting = false }
                service = try await restoreOrBoot(service: service, config: config)
            }

            let presenter = displayPresenterFactory(displayMode, vncService)
            displayPresenter = presenter

            // Parsed from the VNC URL for config distribution; both stay nil for
            // a VNC-disabled run so no credential is ever written or sent.
            var vncPortValue: Int?
            var vncPasswordValue: String?
            let vncInfo: String?

            if vncPolicy.isEnabled {
                // VNC remains active for automation and late remote attachment in every
                // display mode, including the in-process native viewer.
                Logger.info(
                    "Setting up VNC",
                    metadata: [
                        "name": vmDirContext.name,
                        "displayMode": displayMode.rawValue,
                        "port": "\(vncPort)",
                    ])
                let url = try await setupSession(
                    port: vncPort, password: vncPassword, sharedDirectories: sharedDirectories)
                vncInfo = url

                // URL format: vnc://:password@host:port — URLComponents needs http:// to parse correctly.
                if let components = URLComponents(
                    string: url.replacingOccurrences(of: "vnc://", with: "http://")),
                   let port = components.port {
                    vncPortValue = port
                    vncPasswordValue = components.password ?? ""
                    let envContent = "VNC_PORT=\(port)\nVNC_PASSWORD=\(vncPasswordValue!)\n"
                    try? envContent.write(
                        to: lumeConfigDir.appendingPathComponent("vnc.env"),
                        atomically: true, encoding: .utf8)
                    Logger.info("Wrote VNC config to shared directory", metadata: [
                        "port": "\(port)", "path": lumeConfigDir.path])
                }
                Logger.info(
                    "VNC setup successful", metadata: ["name": vmDirContext.name, "vncInfo": url])
            } else {
                vncInfo = nil
                // No listener, no credentials, no vnc.env. The session marker
                // still records the owning process so a detached `get`/`list`
                // in another process can prove this VM is running.
                saveNoVNCSessionData(sharedDirectories: sharedDirectories)
                Logger.info(
                    "VNC disabled for this run; no VNC server will be started",
                    metadata: [
                        "name": vmDirContext.name,
                        "displayMode": displayMode.rawValue,
                    ])
            }

            // Start the VM (unless it resumed from its saved state above).
            if !resumedFromState {
                // A state left from before a cold boot no longer matches the disk.
                vmDirContext.dir.discardSavedState()
                Logger.info(
                    "Starting VM via virtualization service", metadata: ["name": vmDirContext.name])
                starting = true
                defer { starting = false }
                try await service.start()
            }
            Logger.info("VM started successfully", metadata: ["name": vmDirContext.name])
            if activeSocketDevice {
                startVsockForwards(forwards, service: service)
            }
            if let telemetryTransport {
                TelemetryClient.shared.recordVMStarted(
                    transport: telemetryTransport,
                    guestOS: vmDirContext.config.os
                )
            }

            // macOS does not include a SPICE guest agent, so its native viewer uses
            // Lume's SSH bridge automatically. Keep --clipboard as an explicit opt-in
            // for other display modes and guest operating systems.
            if Self.shouldStartClipboardWatcher(
                displayMode: displayMode,
                osType: getOSType(),
                explicitlyRequested: clipboard
            ) {
                await startClipboardWatcherIfNeeded()
            }

            if displayMode == .vnc {
                await waitForVisibleFramebufferBeforeOpeningClient()
            }
            // Attach VZVirtualMachineView only once the guest has entered its live state.
            // Attaching a native view to a stopped VM can leave its display black.
            let context = VMDisplayContext(
                virtualMachine: service.displayVirtualMachine,
                vncURL: vncInfo,
                resolution: vmDirContext.config.display,
                vmName: vmDirContext.name,
                copyFromGuest: { [weak self] in
                    guard let self else { throw ClipboardSyncError.unavailable }
                    try await self.copyClipboardFromGuest()
                },
                pasteIntoGuest: { [weak self] in
                    guard let self else { throw ClipboardSyncError.unavailable }
                    try await self.pasteClipboardIntoGuest()
                },
                addSharedFolder: { [weak self] url, readOnly in
                    guard let self else {
                        throw VMError.internalError("The VM session is no longer available")
                    }
                    try await self.addSharedFolder(url, readOnly: readOnly)
                },
                copyFilesToGuestDesktop: { [weak self] urls in
                    guard let self else {
                        throw VMError.internalError("The VM session is no longer available")
                    }
                    try await self.copyFilesToGuestDesktop(urls)
                }
            )
            displayContext = context
            try await presenter.show(context: context)
            presenter.virtualMachineDidStart()

            if NativeApplicationLoop.isActive {
                do {
                    try NativeDisplayAttachService.register(
                        vmDirectory: vmDirContext.dir
                    ) { [weak self] in
                        await self?.showNativeDisplay()
                    }
                    nativeAttachRegistered = true
                } catch {
                    Logger.debug(
                        "Live native display attachment is unavailable",
                        metadata: [
                            "name": vmDirContext.name,
                            "error": error.localizedDescription,
                        ])
                }

                // The AppKit run loop swallows SIGINT, so install explicit
                // handlers that turn an external `stop` (SIGTERM) or an
                // interactive Ctrl-C (SIGINT) into a clean shutdown.
                installShutdownSignalHandlers()
            }

            // Write VNC config into VM via SSH (background task).
            // VirtioFS mounts are blocked by macOS TCC for LaunchAgent processes,
            // so we also write vnc.env directly to the guest's home directory.
            if let port = vncPortValue, let password = vncPasswordValue {
                let vmName = vmDirContext.name
                let storage = vmDirContext.storage
                Task.detached {
                    await VM.writeVNCConfigViaSSH(
                        vmName: vmName, storage: storage, port: port, password: password)
                }
            }

            try await service.waitForStop()
            Logger.info("VM lifecycle ended", metadata: ["name": vmDirContext.name])
            await cleanupSession()
        } catch {
            Logger.error(
                "Failed in VM.run",
                metadata: [
                    "name": vmDirContext.name,
                    "error": error.localizedDescription,
                    "errorType": "\(type(of: error))",
                ])

            // Presentation/startup failure and task cancellation must not leave a running guest.
            if let service = virtualizationService,
                service.state == .running || service.state == .paused
            {
                try? await service.stop()
            }
            await cleanupSession()
            throw error
        }
    }

    private func showNativeDisplay() async {
        guard let context = displayContext else {
            Logger.error(
                "Cannot attach native display without an active VM context",
                metadata: ["name": vmDirContext.name])
            return
        }

        do {
            if getOSType().caseInsensitiveCompare("macOS") == .orderedSame {
                await startClipboardWatcherIfNeeded()
            }

            if let nativePresenter = displayPresenter as? NativeVMDisplayPresenter {
                try await nativePresenter.show(context: context)
            } else {
                let nativePresenter = NativeVMDisplayPresenter()
                try await nativePresenter.show(context: context)
                displayPresenter?.hide()
                displayPresenter = nativePresenter
            }
            Logger.info(
                "Attached native display to running VM",
                metadata: ["name": vmDirContext.name])
        } catch {
            Logger.error(
                "Failed to attach native display",
                metadata: [
                    "name": vmDirContext.name,
                    "error": error.localizedDescription,
                ])
        }
    }

    private func startClipboardWatcherIfNeeded() async {
        guard clipboardWatcher == nil else { return }
        let watcher = ClipboardWatcher(
            vmName: vmDirContext.name,
            storage: vmDirContext.storage,
            macAddress: vmDirContext.config.macAddress
        )
        clipboardWatcher = watcher
        await watcher.start()
    }

    private func withManualClipboardTransfer<T: Sendable>(
        _ watcher: ClipboardWatcher,
        operation: () async throws -> T
    ) async throws -> T {
        guard !clipboardTransferInProgress else {
            throw ClipboardSyncError.transferInProgress
        }

        clipboardTransferInProgress = true
        defer { clipboardTransferInProgress = false }

        try await watcher.beginManualTransfer()
        do {
            let result = try await operation()
            await watcher.endManualTransfer()
            return result
        } catch {
            await watcher.endManualTransfer()
            throw error
        }
    }

    private func copyClipboardFromGuest() async throws {
        guard let clipboardWatcher else {
            throw ClipboardSyncError.unavailable
        }
        try await withManualClipboardTransfer(clipboardWatcher) {
            let baseline = try await clipboardWatcher.vmClipboardChangeCount()
            try Task.checkCancellation()
            for attempt in 0..<2 {
                try await sendGuestClipboardShortcut("c")
                try Task.checkCancellation()
                do {
                    try await clipboardWatcher.pullVMClipboardToHost(after: baseline)
                    try Task.checkCancellation()
                    return
                } catch ClipboardSyncError.guestCopyTimedOut where attempt == 0 {
                    Logger.debug(
                        "Guest copy did not update the pasteboard; retrying shortcut",
                        metadata: ["vm": vmDirContext.name]
                    )
                    try await Task.sleep(for: .milliseconds(150))
                }
            }
        }
    }

    private func pasteClipboardIntoGuest() async throws {
        guard let clipboardWatcher else {
            throw ClipboardSyncError.unavailable
        }
        try await withManualClipboardTransfer(clipboardWatcher) {
            try await clipboardWatcher.pushHostClipboardToVM()
            try Task.checkCancellation()
            // Give the guest pasteboard server a moment to publish the new value
            // before delivering Command-V to the foreground application.
            try await Task.sleep(for: .milliseconds(100))
            try await sendGuestClipboardShortcut("v")
        }
    }

    private func sendGuestClipboardShortcut(_ character: Character) async throws {
        try await vncService.connectInputClient()
        defer { vncService.disconnectInputClient() }
        try await vncService.sendCharWithModifiers(character, modifiers: .command)
    }

    private func addSharedFolder(_ url: URL, readOnly: Bool) async throws {
        var isDirectory: ObjCBool = false
        guard url.isFileURL,
              FileManager.default.fileExists(atPath: url.path, isDirectory: &isDirectory),
              isDirectory.boolValue else {
            throw VMError.internalError("Select an existing host directory")
        }
        guard let virtualizationService else {
            throw VMError.internalError("Virtualization service is not initialized")
        }

        let standardizedPath = url.standardizedFileURL.path
        let sharedDirectory = SharedDirectory(
            hostPath: standardizedPath,
            tag: VZVirtioFileSystemDeviceConfiguration.macOSGuestAutomountTag,
            readOnly: readOnly
        )
        let existing = activeSharedDirectories.filter {
            URL(fileURLWithPath: $0.hostPath).standardizedFileURL.path != standardizedPath
        }
        let updated = existing + [sharedDirectory]

        let gainedScopedAccess = url.startAccessingSecurityScopedResource()
        do {
            try await virtualizationService.updateSharedDirectories(updated)
        } catch {
            if gainedScopedAccess {
                url.stopAccessingSecurityScopedResource()
            }
            throw error
        }
        if gainedScopedAccess {
            scopedSharedDirectoryURLs.append(url)
        }
        activeSharedDirectories = updated
        if activeVNCPolicy.isEnabled {
            if let sessionURL = vncService.url {
                saveSessionData(url: sessionURL, sharedDirectories: updated)
            }
        } else if activeNoVNCSession != nil {
            saveNoVNCSessionData(sharedDirectories: updated)
        }
    }

    private func copyFilesToGuestDesktop(_ urls: [URL]) async throws {
        guard !urls.isEmpty else {
            throw VMError.internalError("Drop at least one file or folder")
        }
        for url in urls {
            guard url.isFileURL, FileManager.default.fileExists(atPath: url.path) else {
                throw VMError.internalError("A dropped item is no longer available")
            }
        }

        guard virtualizationService?.state == .running else {
            throw SSHError.vmNotRunning(vmDirContext.name)
        }
        guard let macAddress = vmDirContext.config.macAddress else {
            throw SSHError.noIPAddress(vmDirContext.name)
        }
        let ipAddress = await withCheckedContinuation { continuation in
            DispatchQueue.global(qos: .userInitiated).async {
                continuation.resume(
                    returning: DHCPLeaseParser.getIPAddress(forMAC: macAddress)
                )
            }
        }
        guard let ipAddress, !ipAddress.isEmpty else {
            throw SSHError.noIPAddress(vmDirContext.name)
        }

        let client = SystemSSHClient(
            host: ipAddress,
            port: 22,
            user: "lume",
            password: "lume"
        )
        try await client.copyToRemoteDesktop(urls)

        Logger.info(
            "Copied dropped items to VM Desktop",
            metadata: [
                "name": vmDirContext.name,
                "count": "\(urls.count)",
            ])
    }

    /// Installs SIGTERM/SIGINT handlers that request a clean VM shutdown. Only
    /// the process that owns the running VM calls this. Ignoring the default
    /// disposition first lets the dispatch source observe the signal instead of
    /// the process being terminated (or, for SIGINT under AppKit, ignored).
    @MainActor
    private func installShutdownSignalHandlers() {
        guard shutdownSignalSources.isEmpty else { return }
        for signalNumber in [SIGTERM, SIGINT] {
            signal(signalNumber, SIG_IGN)
            let source = DispatchSource.makeSignalSource(signal: signalNumber, queue: .main)
            source.setEventHandler { [weak self] in
                Task { @MainActor in
                    await self?.requestGracefulShutdown()
                }
            }
            source.resume()
            shutdownSignalSources.append(source)
        }
    }

    @MainActor
    private func removeShutdownSignalHandlers() {
        for source in shutdownSignalSources {
            source.cancel()
        }
        shutdownSignalSources.removeAll()
    }

    /// Stops the running VM in response to a shutdown signal. Returning from the
    /// framework's stop lets `run`'s lifecycle wait complete, which drives the
    /// normal session teardown and process exit.
    @MainActor
    private func requestGracefulShutdown() async {
        Logger.info(
            "Received shutdown signal; stopping VM", metadata: ["name": vmDirContext.name])
        guard let service = virtualizationService else { return }
        if service.state == .running || service.state == .paused {
            try? await service.stop()
        }
    }

    /// Resumes the VM from its saved state, or boots it when the state
    /// cannot be restored (say the configuration changed since it was saved;
    /// the disk is then as the VM left it at the save, like after a power
    /// loss). The state is consumed either way: once the guest runs, its disk
    /// diverges from the saved memory. Returns the service now running.
    private func restoreOrBoot(
        service: VMVirtualizationService, config: VMVirtualizationServiceContext
    ) async throws -> VMVirtualizationService {
        let state = vmDirContext.dir.statePath
        let started = Date()
        do {
            try await service.restoreMachineState(from: state.url)
            try await service.resume()
            vmDirContext.dir.discardSavedState()
            Logger.info(
                "VM resumed from its saved state",
                metadata: [
                    "name": vmDirContext.name,
                    "ms": "\(Int(Date().timeIntervalSince(started) * 1000))",
                ])
            return service
        } catch {
            Logger.error(
                "Could not restore the saved state; booting the VM instead",
                metadata: ["name": vmDirContext.name, "error": "\(error)"])
            vmDirContext.dir.discardSavedState()
            if service.state == .running || service.state == .paused {
                try? await service.stop()
            }
            let fresh = try virtualizationServiceFactory(config)
            virtualizationService = fresh
            try await fresh.start()
            return fresh
        }
    }

    /// Saves the running VM's state to its directory and stops it; the next
    /// run resumes from that state ([`restoreOrBoot`]). The state is written
    /// next to the disk under a temporary name first, so a failed save never
    /// leaves a partial state a run would try to restore. On failure the VM
    /// keeps running.
    @MainActor
    func suspend() async throws {
        await waitForStart()
        guard let service = virtualizationService,
            service.state == .running || service.state == .paused
        else {
            throw VMError.notRunning(vmDirContext.name)
        }
        let wasRunning = service.state == .running
        let state = vmDirContext.dir.statePath
        let partial = URL(fileURLWithPath: state.path + ".partial")
        try? FileManager.default.removeItem(at: partial)
        let started = Date()
        do {
            if wasRunning {
                try await service.pause()
            }
            try await service.saveMachineState(to: partial)
            try? FileManager.default.removeItem(at: state.url)
            try FileManager.default.moveItem(at: partial, to: state.url)
            vmDirContext.dir.markSavedStateVsock(activeSocketDevice)
        } catch {
            try? FileManager.default.removeItem(at: partial)
            if wasRunning, service.state == .paused {
                try? await service.resume()
            }
            Logger.error(
                "Failed to save the VM state",
                metadata: ["name": vmDirContext.name, "error": "\(error)"])
            throw error
        }
        Logger.info(
            "Saved the VM state",
            metadata: [
                "name": vmDirContext.name,
                "ms": "\(Int(Date().timeIntervalSince(started) * 1000))",
            ])
        try await service.stop()
        await cleanupSession()
    }

    /// Waits (bounded) while this process starts or restores the VM.
    @MainActor
    private func waitForStart() async {
        let deadline = Date().addingTimeInterval(120)
        while starting && Date() < deadline {
            try? await Task.sleep(nanoseconds: 100_000_000)
        }
    }

    private func cleanupSession() async {
        guard !sessionCleanedUp else { return }
        sessionCleanedUp = true

        removeShutdownSignalHandlers()

        // Detach native display before releasing the framework VM.
        if nativeAttachRegistered {
            NativeDisplayAttachService.unregister()
            nativeAttachRegistered = false
        }
        displayPresenter?.hide()
        displayPresenter = nil
        displayContext = nil
        await clipboardWatcher?.stop()
        clipboardWatcher = nil
        for url in scopedSharedDirectoryURLs {
            url.stopAccessingSecurityScopedResource()
        }
        scopedSharedDirectoryURLs.removeAll()
        activeSharedDirectories.removeAll()
        vncService.stop()
        vsockForwarder?.stop()
        vsockForwarder = nil
        vmDirContext.dir.clearVsockSession()
        if !activeVNCPolicy.isEnabled {
            // No VNC service owns this run's marker, so drop it here. Doing it
            // unconditionally also covers a failed start that never booted.
            vmDirContext.dir.clearSession()
            activeNoVNCSession = nil
        }
        virtualizationService = nil
    }

    @MainActor
    func stop() async throws {
        try await stop(force: false, timeout: VM.defaultStopTimeout)
    }

    /// Stops the VM.
    ///
    /// When this process owns the running VM, the framework stops it directly.
    /// Otherwise `stop` resolves the process holding the config-file run lock
    /// (typically a detached `lume run`) and signals it: by default it requests
    /// a graceful shutdown and waits up to `timeout` seconds before escalating to
    /// a forced power-off. `force` skips the graceful phase and powers the VM off
    /// immediately.
    @MainActor
    func stop(force: Bool, timeout: TimeInterval) async throws {
        guard vmDirContext.initialized else {
            throw VMError.notInitialized(vmDirContext.name)
        }

        Logger.info(
            "Attempting to stop VM",
            metadata: ["name": vmDirContext.name, "force": "\(force)"])

        // If we own the running VM in this process, stop it directly. The
        // framework's stop is an immediate power-off, so it serves both the
        // graceful and forced requests.
        await waitForStart()
        if let service = virtualizationService {
            do {
                Logger.info(
                    "Stopping VM via virtualization service", metadata: ["name": vmDirContext.name])
                try await service.stop()
                await cleanupSession()
                Logger.info(
                    "VM stopped successfully via virtualization service",
                    metadata: ["name": vmDirContext.name])

                // VM.run owns the lock and releases it as its lifecycle wait returns.
                return
            } catch let error {
                Logger.error(
                    "Failed to stop VM via virtualization service",
                    metadata: [
                        "name": vmDirContext.name,
                        "error": error.localizedDescription,
                    ])
                // Fall through to process termination
            }
        }

        Logger.info(
            "Resolving process holding the config-file run lock",
            metadata: [
                "path": vmDirContext.dir.configPath.path,
                "name": vmDirContext.name,
            ])
        let owner = RunOwner.load(vmDirContext.dir.runOwnerURL)
        if RunOwner.lockHeld(vmDirContext.dir.configPath.url) == false,
            owner?.matches != true {
            throw VMError.notRunning(vmDirContext.name)
        }
        guard let owner, verifiedOwner(owner) else {
            throw VMError.unsafeOwner(vmDirContext.name)
        }
        let pid = owner.pid

        Logger.info(
            "Found process \(pid) holding lock on config file",
            metadata: ["name": vmDirContext.name])

        // A `lume serve` may host other VMs too: a signal would end the server
        // and all of them. Ask it to stop this one.
        if let port = LumeServeProcess.apiPort(ofProcess: pid) {
            try await stopThroughServer(pid: pid, port: port, force: force, timeout: timeout)
            return
        }

        if force {
            Logger.info(
                "Force stop requested; powering off process \(pid) immediately",
                metadata: ["name": vmDirContext.name])
            try await forcePowerOff(owner: owner, graceful: false)
            return
        }

        // Graceful first: ask the owner to shut down. SIGTERM is honored by the
        // run process (its handler triggers a clean stop); even without a handler
        // its default disposition terminates the process, so unlike SIGINT — which
        // the AppKit run loop swallows — the VM never lingers.
        guard LumeServeProcess.apiPort(ofProcess: pid) == nil, verifiedOwner(owner) else {
            throw VMError.unsafeOwner(vmDirContext.name)
        }
        if kill(pid, SIGTERM) == 0 {
            Logger.info(
                "Sent SIGTERM to VM process \(pid) for graceful shutdown",
                metadata: ["name": vmDirContext.name])
        }

        if await waitForProcessExit(owner: owner, timeout: timeout) {
            Logger.info(
                "Process \(pid) exited after graceful shutdown",
                metadata: ["name": vmDirContext.name])
            finalizeCrossProcessStop()
            Logger.info(
                "VM stopped successfully via process termination",
                metadata: ["name": vmDirContext.name])
            return
        }

        Logger.info(
            "Graceful shutdown did not complete within \(Int(timeout))s; forcing power-off of process \(pid)",
            metadata: ["name": vmDirContext.name])
        try await forcePowerOff(owner: owner, graceful: true)
    }

    /// Stops this VM through the `lume serve` (process `pid`, API on `port`)
    /// that runs it, leaving the server and its other VMs running.
    @MainActor
    private func stopThroughServer(
        pid: pid_t, port: UInt16, force: Bool, timeout: TimeInterval
    ) async throws {
        Logger.info(
            "VM runs in lume serve; asking the server to stop it",
            metadata: ["name": vmDirContext.name, "pid": "\(pid)", "port": "\(port)"])
        let name =
            vmDirContext.name.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed)
            ?? vmDirContext.name
        guard let url = URL(string: "http://127.0.0.1:\(port)/lume/vms/\(name)/stop") else {
            throw VMError.internalError("Invalid lume serve URL for port \(port)")
        }
        var body: [String: Any] = ["force": force, "timeout": timeout]
        if let storage = vmDirContext.storage { body["storage"] = storage }
        var request = URLRequest(url: url, timeoutInterval: max(timeout, 0) + 30)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
        let data: Data
        let response: URLResponse
        do {
            (data, response) = try await URLSession.shared.data(for: request)
        } catch {
            // Never fall back to signalling the server: that is what ends
            // every VM it hosts.
            throw VMError.internalError(
                "VM '\(vmDirContext.name)' runs in lume serve (process \(pid)), which did not answer on port \(port): \(error.localizedDescription)"
            )
        }
        let status = (response as? HTTPURLResponse)?.statusCode ?? 0
        guard (200..<300).contains(status) else {
            let detail = String(decoding: data, as: UTF8.self)
            throw VMError.internalError(
                "lume serve (process \(pid)) could not stop VM '\(vmDirContext.name)' (HTTP \(status)): \(detail)"
            )
        }
        finalizeCrossProcessStop()
        Logger.info("VM stopped through lume serve", metadata: ["name": vmDirContext.name])
    }

    /// Polls until `pid` is no longer signalable or `timeout` elapses.
    /// Returns `true` if the process exited within the budget.
    @MainActor
    private func waitForProcessExit(owner: RunOwner, timeout: TimeInterval) async -> Bool {
        let deadline = Date().addingTimeInterval(max(timeout, 0))
        repeat {
            if !owner.matches { return true }
            try? await Task.sleep(nanoseconds: 500_000_000)
        } while Date() < deadline
        return !owner.matches
    }

    /// SIGKILLs `pid`, confirms it is gone, and releases this VM's local state.
    @MainActor
    private func forcePowerOff(owner: RunOwner, graceful: Bool) async throws {
        if graceful && (!owner.matches || RunOwner.load(vmDirContext.dir.runOwnerURL) == nil
            || RunOwner.lockHeld(vmDirContext.dir.configPath.url) == false) {
            finalizeCrossProcessStop()
            return
        }
        guard LumeServeProcess.apiPort(ofProcess: owner.pid) == nil, verifiedOwner(owner) else {
            throw VMError.unsafeOwner(vmDirContext.name)
        }
        let pid = owner.pid
        _ = kill(pid, SIGKILL)
        Logger.info("Sent SIGKILL to process \(pid)", metadata: ["name": vmDirContext.name])

        if await waitForProcessExit(owner: owner, timeout: 5) {
            finalizeCrossProcessStop()
            Logger.info("VM forcefully stopped", metadata: ["name": vmDirContext.name])
            return
        }

        // SIGKILL cannot be caught, so surviving it means the process is wedged
        // in the kernel. Release our side anyway so the run lock is not orphaned.
        finalizeCrossProcessStop()
        Logger.error(
            "Failed to stop VM - process \(pid) did not terminate",
            metadata: ["name": vmDirContext.name])
        throw VMError.internalError("Failed to stop VM process \(pid)")
    }

    /// Releases the resources a cross-process stop is responsible for cleaning up.
    @MainActor
    private func finalizeCrossProcessStop() {
        virtualizationService = nil
        vncService.stop()
    }

    private func verifiedOwner(_ owner: RunOwner) -> Bool {
        owner.verified(record: vmDirContext.dir.runOwnerURL,
            config: vmDirContext.dir.configPath.url, probe: runLockProbe)
    }

    // MARK: - Resource Management

    func updateVMConfig(vmConfig: VMConfig) throws {
        vmDirContext.config = vmConfig
        try vmDirContext.saveConfig()
    }

    private func getDiskSize() throws -> DiskSize {
        let resourceValues = try vmDirContext.diskPath.url.resourceValues(forKeys: [
            .totalFileAllocatedSizeKey,
            .totalFileSizeKey,
        ])

        guard let allocated = resourceValues.totalFileAllocatedSize,
            let total = resourceValues.totalFileSize
        else {
            throw VMConfigError.invalidDiskSize
        }

        return DiskSize(allocated: UInt64(allocated), total: UInt64(total))
    }

    func setCpuCount(_ newCpuCount: Int) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        vmDirContext.config.setCpuCount(newCpuCount)
        try vmDirContext.saveConfig()
    }

    func setMemorySize(_ newMemorySize: UInt64) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        vmDirContext.config.setMemorySize(newMemorySize)
        try vmDirContext.saveConfig()
    }

    /// Grow-only truncate of the raw image plus a config update. Used for
    /// initial provisioning and for the Linux plain-grow path. macOS user
    /// resizes go through `resizeDiskSafely` instead.
    func setDiskSize(_ newDiskSize: UInt64) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        try vmDirContext.setDisk(newDiskSize)  // throws on shrink / IO failure
        vmDirContext.config.setDiskSize(newDiskSize)
        try vmDirContext.saveConfig()
    }

    /// User-initiated disk resize entry point. For macOS guests this runs the
    /// recovery-preserving offline transaction (relocate recovery, rewrite GPT,
    /// grow the APFS container). For other guests it grows the image only;
    /// in-guest `growpart`/`resize2fs` is still required.
    func resizeDiskSafely(to newSize: UInt64, options: DiskResizeOptions) throws {
        guard !isRunning else {
            throw DiskResizeError.vmRunning(vmDirContext.name)
        }
        if vmDirContext.config.os.lowercased() == "macos" {
            let resizer = MacDiskResizer(
                vmDir: vmDirContext.dir,
                diskPath: vmDirContext.diskPath.url,
                vmName: vmDirContext.name)
            try resizer.resize(to: newSize, options: options)
            if !options.dryRun {
                vmDirContext.config.setDiskSize(newSize)  // keep in-memory config fresh
            }
        } else {
            if options.dryRun { return }
            try setDiskSize(newSize)
        }
    }

    func setDisplay(_ newDisplay: String) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        guard let display: VMDisplayResolution = VMDisplayResolution(string: newDisplay) else {
            throw VMError.invalidDisplayResolution(newDisplay)
        }
        vmDirContext.config.setDisplay(display)
        try vmDirContext.saveConfig()
    }

    func setHardwareModel(_ newHardwareModel: Data) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        vmDirContext.config.setHardwareModel(newHardwareModel)
        try vmDirContext.saveConfig()
    }

    func setMachineIdentifier(_ newMachineIdentifier: Data) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        vmDirContext.config.setMachineIdentifier(newMachineIdentifier)
        try vmDirContext.saveConfig()
    }

    /// Points this VM at its directory's new place after a rename (the
    /// directory was moved; a running guest keeps its open files).
    func relocate(to dir: VMDirectory) {
        var moved = VMDirContext(
            dir: dir, config: vmDirContext.config, home: vmDirContext.home,
            storage: vmDirContext.storage)
        moved.diskPathOverride = vmDirContext.diskPathOverride
        moved.nvramPathOverride = vmDirContext.nvramPathOverride
        vmDirContext = moved
        vncService.relocate(to: dir)
    }

    /// Gives a stopped VM whose saved state cannot be used a new MAC
    /// address and (macOS) machine identifier, dropping that state: used
    /// when another running VM already has the state's MAC address (two
    /// clones of one saved state), so this one boots as a machine of its
    /// own instead of colliding on the network. The usual `isRunning` check
    /// is skipped on purpose: it looks the MAC address up, and that address
    /// is the other VM's.
    func dropSavedStateForNewIdentity() throws {
        vmDirContext.dir.discardSavedState()
        vmDirContext.config.setMacAddress(VZMACAddress.randomLocallyAdministered().string)
        if getOSType().caseInsensitiveCompare("macOS") == .orderedSame {
            vmDirContext.config.setMachineIdentifier(
                DarwinVirtualizationService.generateMachineIdentifier())
        }
        try vmDirContext.saveConfig()
    }

    func setMacAddress(_ newMacAddress: String) throws {
        guard !isRunning else {
            throw VMError.alreadyRunning(vmDirContext.name)
        }
        vmDirContext.config.setMacAddress(newMacAddress)
        try vmDirContext.saveConfig()
    }

    // MARK: - VNC Management

    func getVNCUrl() -> String? {
        return vncService.url
    }

    /// Best-effort write of VNC config into the VM via SSH.
    /// Silently gives up if SSH is not available (e.g., SSH disabled on the VM).
    /// The guest can still read config from VirtioFS or use hardcoded defaults.
    /// Nonisolated: the SSH session blocks its thread for seconds, and on the
    /// main actor that stalls every `lume serve` request and VM start meanwhile.
    nonisolated static func writeVNCConfigViaSSH(
        vmName: String, storage: String?, port: Int, password: String
    ) async {
        let envContent = "VNC_PORT=\(port)\nVNC_PASSWORD=\(password)"
        let command = "echo '\(envContent)' > ~/.vnc.env"

        for _ in 1...6 {
            do {
                let details = try await MainActor.run {
                    let controller = LumeController()
                    return try controller.getDetails(name: vmName, storage: storage)
                }
                guard details.status == "running",
                      let ip = details.ipAddress, !ip.isEmpty,
                      details.sshAvailable == true else {
                    try? await Task.sleep(nanoseconds: 5_000_000_000)
                    continue
                }

                let client = SystemSSHClient(host: ip, port: 22, user: "lume", password: "lume")
                let result = try client.execute(command: command, timeout: 10)
                if result.exitCode == 0 {
                    Logger.info("Wrote VNC config to VM via SSH", metadata: [
                        "name": vmName, "port": "\(port)"])
                    return
                }
            } catch {
                // SSH not available — silently retry or give up
            }
            try? await Task.sleep(nanoseconds: 5_000_000_000)
        }
        // Silent give-up: SSH may be disabled on this VM, which is fine.
        // The guest can still discover VNC config via VirtioFS or defaults.
    }

    /// Sets up the VNC service and returns the VNC URL
    private func startVNCService(port: Int = 0, password: String? = nil) async throws -> String {
        guard let service = virtualizationService else {
            throw VMError.internalError("Virtualization service not initialized")
        }

        try await vncService.start(
            port: port,
            password: password,
            virtualMachine: service.displayVirtualMachine
        )

        guard let url = vncService.url else {
            throw VMError.vncNotConfigured
        }

        return url
    }

    /// Saves the session information including shared directories to disk
    private func saveSessionData(url: String, sharedDirectories: [SharedDirectory]) {
        do {
            let session = VNCSession(
                url: url, sharedDirectories: sharedDirectories.isEmpty ? nil : sharedDirectories)
            try vmDirContext.dir.saveSession(session)
            Logger.info(
                "Saved VNC session with shared directories",
                metadata: [
                    "count": "\(sharedDirectories.count)",
                    "dirs": "\(sharedDirectories.map { $0.hostPath }.joined(separator: ", "))",
                    "sessionsPath": "\(vmDirContext.dir.sessionsPath.path)",
                ])
        } catch {
            Logger.error("Failed to save VNC session", metadata: ["error": "\(error)"])
        }
    }

    /// Persists the session marker for a run started with `--vnc disabled`.
    ///
    /// There is no URL or port to record, so the marker carries this process's
    /// PID and start time. `get`/`list` in another process treat the VM as
    /// running only after proving that PID still holds the config-file run lock.
    private func saveNoVNCSessionData(sharedDirectories: [SharedDirectory]) {
        let session = VNCSession.vncDisabled(
            pid: activeNoVNCSession?.pid ?? getpid(),
            startedAt: activeNoVNCSession?.startedAt ?? Date().timeIntervalSince1970,
            sharedDirectories: sharedDirectories.isEmpty ? nil : sharedDirectories
        )
        do {
            try vmDirContext.dir.saveSession(session)
            activeNoVNCSession = session
            Logger.info(
                "Saved VNC-disabled session marker",
                metadata: [
                    "name": vmDirContext.name,
                    "pid": "\(session.pid ?? 0)",
                    "sessionsPath": vmDirContext.dir.sessionsPath.path,
                ])
        } catch {
            Logger.error(
                "Failed to save VNC-disabled session marker", metadata: ["error": "\(error)"])
        }
    }

    /// Main session setup method that handles VNC and persists session data
    private func setupSession(
        port: Int = 0, password: String? = nil, sharedDirectories: [SharedDirectory] = []
    ) async throws -> String {
        // Start the VNC service and get the URL
        let url = try await startVNCService(port: port, password: password)

        // Save the session data
        saveSessionData(url: url, sharedDirectories: sharedDirectories)

        return url
    }

    /// Avoid opening Screen Sharing on an all-black initial framebuffer.
    /// This only runs for the real VNC service (not mocks in tests).
    private func waitForVisibleFramebufferBeforeOpeningClient() async {
        guard vncService is DefaultVNCService else {
            return
        }

        do {
            try await vncService.connectInputClient()
            defer { vncService.disconnectInputClient() }

            let timeoutSeconds = 30
            for _ in 0..<timeoutSeconds {
                if let image = try? await vncService.captureFramebuffer(),
                    framebufferHasVisiblePixels(image)
                {
                    Logger.info(
                        "Detected visible VM framebuffer content before opening VNC client",
                        metadata: ["name": vmDirContext.name]
                    )
                    return
                }
                try? await Task.sleep(nanoseconds: 1_000_000_000)
            }

            Logger.info(
                "Timed out waiting for visible framebuffer content; opening VNC client anyway",
                metadata: ["name": vmDirContext.name, "timeout_seconds": "\(timeoutSeconds)"]
            )
        } catch {
            Logger.info(
                "Framebuffer readiness check failed; opening VNC client anyway",
                metadata: ["name": vmDirContext.name, "error": "\(error)"]
            )
        }
    }

    /// Fast heuristic: sample bytes from the framebuffer and treat any non-zero value as visible content.
    private func framebufferHasVisiblePixels(_ image: CGImage) -> Bool {
        guard let dataProvider = image.dataProvider,
            let data = dataProvider.data,
            let bytes = CFDataGetBytePtr(data)
        else {
            // If we can't inspect pixels, do not block client opening.
            return true
        }

        let count = CFDataGetLength(data)
        guard count > 0 else {
            return false
        }

        let stride = max(1, count / 4096)
        var index = 0
        while index < count {
            if bytes[index] != 0 {
                return true
            }
            index += stride
        }

        return false
    }

    // MARK: - Host port forwards over vsock

    /// Whether a run with `forwards` gets a virtio socket device: always on
    /// a cold boot; on a resume only when the state was saved with one.
    nonisolated static func usesSocketDevice(
        forwards: [UInt16], hasSavedState: Bool, savedStateHasVsock: Bool
    ) -> Bool {
        !forwards.isEmpty && (!hasSavedState || savedStateHasVsock)
    }

    /// Publishes `forwards` on host loopback ports through the guest agent
    /// and records them (`vsock.json`) for `get`. A failure leaves the VM
    /// reachable on its address only.
    private func startVsockForwards(_ forwards: [UInt16], service: VMVirtualizationService) {
        guard let connect = service.vsockConnector() else {
            Logger.error("The VM has no virtio socket device", metadata: ["name": vmDirContext.name])
            return
        }
        do {
            let forwarder = try VsockForwarder(guestPorts: forwards, connect: connect)
            let dir = vmDirContext.dir
            dir.saveVsockSession(forwarder.session(agent: false))
            let ready = forwarder.session(agent: true)
            let name = vmDirContext.name
            forwarder.start {
                dir.saveVsockSession(ready)
                Logger.info("The guest agent answers over vsock", metadata: ["name": name])
            }
            vsockForwarder = forwarder
            Logger.info(
                "Forwarding host loopback ports over vsock",
                metadata: [
                    "name": vmDirContext.name,
                    "forwards": forwarder.forwards.map { "\($0.value)->\($0.key)" }
                        .sorted().joined(separator: ","),
                ])
        } catch {
            Logger.error(
                "Could not forward ports over vsock",
                metadata: ["name": vmDirContext.name, "error": "\(error)"])
        }
    }

    // MARK: - Platform-specific Methods

    func getOSType() -> String {
        fatalError("Must be implemented by subclass")
    }

    func createVMVirtualizationServiceContext(
        cpuCount: Int,
        memorySize: UInt64,
        display: String,
        sharedDirectories: [SharedDirectory] = [],
        mount: Path? = nil,
        recoveryMode: Bool = false,
        usbMassStoragePaths: [Path]? = nil,
        additionalDiskPaths: [Path]? = nil,
        networkMode: NetworkMode? = nil
    ) throws -> VMVirtualizationServiceContext {
        // This is a diagnostic log to track actual file paths on disk for debugging
        try validateDiskState()

        // Use provided networkMode, falling back to config value
        let effectiveNetworkMode = networkMode ?? vmDirContext.config.networkMode

        return VMVirtualizationServiceContext(
            cpuCount: cpuCount,
            memorySize: memorySize,
            display: display,
            sharedDirectories: sharedDirectories,
            mount: mount,
            hardwareModel: vmDirContext.config.hardwareModel,
            machineIdentifier: vmDirContext.config.machineIdentifier,
            macAddress: vmDirContext.config.macAddress!,
            diskPath: vmDirContext.diskPath,
            nvramPath: vmDirContext.nvramPath,
            recoveryMode: recoveryMode,
            usbMassStoragePaths: usbMassStoragePaths,
            additionalDiskPaths: additionalDiskPaths,
            networkMode: effectiveNetworkMode
        )
    }

    /// Validates the disk state to help diagnose storage attachment issues
    private func validateDiskState() throws {
        // Check disk image state
        let diskPath = vmDirContext.diskPath.path
        let diskExists = FileManager.default.fileExists(atPath: diskPath)
        var diskSize: UInt64 = 0
        var diskPermissions = ""

        if diskExists {
            if let attrs = try? FileManager.default.attributesOfItem(atPath: diskPath) {
                diskSize = attrs[.size] as? UInt64 ?? 0
                let posixPerms = attrs[.posixPermissions] as? Int ?? 0
                diskPermissions = String(format: "%o", posixPerms)
            }
        }

        // Check disk container directory permissions
        let diskDir = (diskPath as NSString).deletingLastPathComponent
        let dirPerms =
            try? FileManager.default.attributesOfItem(atPath: diskDir)[.posixPermissions] as? Int
            ?? 0
        let dirPermsString = dirPerms != nil ? String(format: "%o", dirPerms!) : "unknown"

        // Log detailed diagnostics
        Logger.info(
            "Validating VM disk state",
            metadata: [
                "diskPath": diskPath,
                "diskExists": "\(diskExists)",
                "diskSize":
                    "\(ByteCountFormatter.string(fromByteCount: Int64(diskSize), countStyle: .file))",
                "diskPermissions": diskPermissions,
                "dirPermissions": dirPermsString,
                "locationName": vmDirContext.storage ?? "home",
            ])

        if !diskExists {
            Logger.error("VM disk image does not exist", metadata: ["diskPath": diskPath])
        } else if diskSize == 0 {
            Logger.error("VM disk image exists but has zero size", metadata: ["diskPath": diskPath])
        }
    }

    func setup(
        ipswPath: String,
        cpuCount: Int,
        memorySize: UInt64,
        diskSize: UInt64,
        display: String
    ) async throws {
        fatalError("Must be implemented by subclass")
    }

    // MARK: - Finalization

    /// Post-installation step to move the VM directory to the home directory
    func finalize(to name: String, home: Home, storage: String? = nil) throws {
        let vmDir = try home.getVMDirectory(name, storage: storage)
        try FileManager.default.moveItem(at: vmDirContext.dir.dir.url, to: vmDir.dir.url)
    }

    // Method to run VM with additional USB mass storage devices
    func runWithUSBStorage(
        noDisplay: Bool, sharedDirectories: [SharedDirectory], mount: Path?, vncPort: Int = 0,
        recoveryMode: Bool = false, usbImagePaths: [Path]
    ) async throws {
        guard vmDirContext.initialized else {
            throw VMError.notInitialized(vmDirContext.name)
        }

        guard let cpuCount = vmDirContext.config.cpuCount,
            let memorySize = vmDirContext.config.memorySize
        else {
            throw VMError.notInitialized(vmDirContext.name)
        }

        // Try to acquire lock on config file
        let fileHandle = try FileHandle(forWritingTo: vmDirContext.dir.configPath.url)
        guard flock(fileHandle.fileDescriptor, LOCK_EX | LOCK_NB) == 0 else {
            try? fileHandle.close()
            throw VMError.alreadyRunning(vmDirContext.name)
        }

        defer {
            flock(fileHandle.fileDescriptor, LOCK_UN)
            try? fileHandle.close()
        }
        guard let owner = RunOwner.current() else { throw VMError.unsafeOwner(vmDirContext.name) }
        try owner.save(vmDirContext.dir.runOwnerURL)
        defer { owner.remove(vmDirContext.dir.runOwnerURL) }

        Logger.info(
            "Running VM with USB storage devices",
            metadata: [
                "cpuCount": "\(cpuCount)",
                "memorySize": "\(memorySize)",
                "diskSize": "\(vmDirContext.config.diskSize ?? 0)",
                "usbImageCount": "\(usbImagePaths.count)",
                "recoveryMode": "\(recoveryMode)",
            ])

        // Create and configure the VM
        do {
            // Create lume-config shared directory for VNC discovery
            let lumeConfigDir = FileManager.default.temporaryDirectory
                .appendingPathComponent("lume-config-\(vmDirContext.name)")
            try? FileManager.default.createDirectory(at: lumeConfigDir, withIntermediateDirectories: true)
            try? FileManager.default.removeItem(
                at: lumeConfigDir.appendingPathComponent("vnc.env"))
            let lumeConfigSharedDir = SharedDirectory(
                hostPath: lumeConfigDir.path, tag: "lume-config", readOnly: true)
            var allSharedDirectories = sharedDirectories
            allSharedDirectories.append(lumeConfigSharedDir)

            let config = try createVMVirtualizationServiceContext(
                cpuCount: cpuCount,
                memorySize: memorySize,
                display: vmDirContext.config.display.string,
                sharedDirectories: allSharedDirectories,
                mount: mount,
                recoveryMode: recoveryMode,
                usbMassStoragePaths: usbImagePaths
            )
            virtualizationService = try virtualizationServiceFactory(config)

            let vncInfo = try await setupSession(
                port: vncPort, sharedDirectories: sharedDirectories)
            Logger.info("VNC info", metadata: ["vncInfo": vncInfo])

            // Write VNC config to shared directory for guest discovery
            var vncPortValue: Int?
            var vncPasswordValue: String?
            if let components = URLComponents(string: vncInfo.replacingOccurrences(of: "vnc://", with: "http://")),
               let port = components.port {
                vncPortValue = port
                vncPasswordValue = components.password ?? ""
                let envContent = "VNC_PORT=\(port)\nVNC_PASSWORD=\(vncPasswordValue!)\n"
                try? envContent.write(
                    to: lumeConfigDir.appendingPathComponent("vnc.env"),
                    atomically: true, encoding: .utf8)
            }

            // Start the VM
            guard let service = virtualizationService else {
                throw VMError.internalError("Virtualization service not initialized")
            }
            try await service.start()

            if !noDisplay {
                await waitForVisibleFramebufferBeforeOpeningClient()
                Logger.info("Starting VNC session", metadata: ["name": vmDirContext.name])
                try await vncService.openClient(url: vncInfo)
            }

            // Write VNC config into VM via SSH (background task)
            if let port = vncPortValue, let password = vncPasswordValue {
                let vmName = vmDirContext.name
                let storage = vmDirContext.storage
                Task.detached {
                    await VM.writeVNCConfigViaSSH(
                        vmName: vmName, storage: storage, port: port, password: password)
                }
            }

            while true {
                try await Task.sleep(nanoseconds: UInt64(1e9))
            }
        } catch {
            Logger.error(
                "Failed to create/start VM with USB storage",
                metadata: [
                    "error": "\(error)",
                    "errorType": "\(type(of: error))",
                ])
            virtualizationService = nil
            vncService.stop()
            throw error
        }
    }
}