Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

32.9 KB
Raw Blame
import Darwin
import Foundation

/// GitHub repo that receives community compatibility reports (owner/name).
public let reportRepo = "gauthierpiarrette/highball-db"

/// Filesystem layout for everything Gin owns. Mirrors the spike layout under
/// `~/Library/Application Support/Gin`, overridable with `HIGHBALL_HOME` for tests.
public struct HighballPaths: Sendable {
    public let home: URL
    /// A location the user chose that is not there right now (its drive unplugged, #24): the app
    /// runs on the default home for the moment, says so, and never treats it as a first run.
    public let unavailableConfiguredHome: URL?

    /// `~/Library/Application Support/Highball`, the home unless one is chosen.
    public static var defaultHome: URL {
        FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
            .appending(path: "Highball", directoryHint: .isDirectory)
    }
    /// The pointer to a chosen location, at the fixed default home so the app and the CLI read the
    /// same one (UserDefaults is per bundle). `{"home": "/Volumes/Games/Highball"}`.
    public static var configFile: URL { defaultHome.appending(path: "config.json") }

    public init(home: URL? = nil) {
        let env = ProcessInfo.processInfo.environment["HIGHBALL_HOME"].map { URL(fileURLWithPath: $0, isDirectory: true) }
        let chosen = Self.configuredHome()
        let r = Self.resolve(explicit: home, env: env, configured: chosen,
                             reachable: chosen.map { FileManager.default.fileExists(atPath: $0.path) } ?? false,
                             defaultHome: Self.defaultHome)
        self.home = r.home; self.unavailableConfiguredHome = r.unavailable
    }

    /// Precedence, most explicit first: the caller's, `HIGHBALL_HOME`, the chosen location when its
    /// folder is there, else the default (with the chosen one reported as unavailable).
    public static func resolve(explicit: URL?, env: URL?, configured: URL?, reachable: Bool, defaultHome: URL) -> (home: URL, unavailable: URL?) {
        if let explicit { return (explicit, nil) }
        if let env { return (env, nil) }
        if let configured { return reachable ? (configured, nil) : (defaultHome, configured) }
        return (defaultHome, nil)
    }

    public static func configuredHome(from file: URL = configFile) -> URL? {
        guard let data = try? Data(contentsOf: file),
              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let path = obj["home"] as? String, !path.isEmpty else { return nil }
        return URL(fileURLWithPath: path, isDirectory: true)
    }

    /// Records a chosen location, or with nil goes back to the default.
    public static func setConfiguredHome(_ url: URL?, file: URL = configFile) throws {
        if let url {
            try FileManager.default.createDirectory(at: file.deletingLastPathComponent(), withIntermediateDirectories: true)
            let data = try JSONSerialization.data(withJSONObject: ["home": url.standardizedFileURL.path], options: [.prettyPrinted])
            try data.write(to: file, options: .atomic)
        } else {
            try? FileManager.default.removeItem(at: file)
        }
    }

    /// Why a folder cannot hold Highball's data, or nil when it can. The folder must exist and be
    /// writable, must not sit inside the default home (which would move the data into itself), and
    /// the volume must do the two things Wine needs: symbolic links, for an environment's drive
    /// letters, and an execute bit that survives, because the engine's own binaries run from here.
    ///
    /// Those last two are probed rather than inferred. The previous check read
    /// `volumeSupportsSymbolicLinks` and refused exFAT by name, but macOS reports exFAT as
    /// supporting symbolic links and does in fact create them, so the check never fired and the
    /// refusal the release notes promised never happened. Measured 2026-09-09 on an exFAT volume:
    /// the flag reads true, links are created, and a bottle moved there launches and runs. Asking
    /// the volume directly also catches what a format name never could.
    ///
    /// A network share is not refused. Prefixes there have locking and speed problems of their
    /// own, so `locationWarning` tells the picker; the folder can still be used.
    public static func locationProblem(_ url: URL, defaultHome: URL = defaultHome) -> String? {
        let fm = FileManager.default
        var isDir: ObjCBool = false
        guard fm.fileExists(atPath: url.path, isDirectory: &isDir), isDir.boolValue else { return "That folder does not exist." }
        guard fm.isWritableFile(atPath: url.path) else { return "Highball cannot write in that folder." }
        let target = url.standardizedFileURL.path + "/", base = defaultHome.standardizedFileURL.path + "/"
        if target.hasPrefix(base) || base.hasPrefix(target) { return "Pick a folder outside Highball's own data folder." }
        if let why = windowsPathProblem(url) { return why }
        if (try? url.resourceValues(forKeys: [.volumeIsReadOnlyKey]))?.volumeIsReadOnly == true {
            return "That volume is read only."
        }
        // FAT32 stops at one byte under 4 GiB per file, and game files pass that routinely. macOS
        // reports the real limit, so this asks rather than matching on a format name (measured
        // 2026-09-09: FAT32 4294967295, exFAT and APFS effectively unlimited).
        if let max = (try? url.resourceValues(forKeys: [.volumeMaximumFileSizeKey]))?.volumeMaximumFileSize,
           max < 4 << 30 {
            return "That drive cannot store a file larger than \(max >> 30) GB, and game files are often bigger. Format it as APFS, or pick another drive."
        }
        return volumeProblem(url)
    }

    /// Why Wine cannot reach a folder through its Windows paths, or nil. Windows drops a trailing
    /// period or space from every folder name and refuses <>:"|?* and control characters, and Wine
    /// does the same when it turns a Mac path into a Windows one. A home folder named "a." became
    /// Z:\Users\a, which does not exist, so the very first Windows setup failed with "could not load
    /// kernel32.dll" (exit 53) on every try and Repair repeated it (highball#547, #446). Reproduced
    /// 2026-10-29 with a folder named "u." on engine r28; the same tree without the period boots.
    public static func windowsPathProblem(_ url: URL) -> String? {
        for part in url.standardizedFileURL.pathComponents where part != "/" {
            let bad = part.hasSuffix(".") || part.hasSuffix(" ")
                || part.unicodeScalars.contains { "<>:\"|?*".unicodeScalars.contains($0) || $0.value < 0x20 }
            if bad {
                return "Wine can't use Highball's folder because the folder \"\(part)\" in its path has a name Windows can't use (it ends with a period or a space, or holds one of <>:\"|?*). In Highball's settings, under Environments, use Change… to keep Highball's data in a folder outside it, such as one in /Users/Shared."
            }
        }
        return nil
    }

    /// Why a usable folder is still a poor place for a prefix, or nil. Shown before the move,
    /// never as a hard stop.
    public static func locationWarning(_ url: URL) -> String? {
        guard isNetworkVolume(url) else { return nil }
        return "This folder is on a network share. Games can be slower there, and file locks sometimes get in the way. You can still use it."
    }

    /// Unknown paths fail closed as local, so a missing folder is not a scare.
    static func isNetworkVolume(_ url: URL) -> Bool {
        var st = statfs()
        guard statfs(url.path, &st) == 0 else { return false }
        return UInt32(st.f_flags) & UInt32(MNT_LOCAL) == 0
    }

    /// Makes and removes a scratch folder inside `url` to check what Wine actually needs from the
    /// volume. Leaves nothing behind, including when a check fails.
    static func volumeProblem(_ url: URL, uuid: String = UUID().uuidString) -> String? {
        let fm = FileManager.default
        let probe = url.appending(path: ".highball-probe-" + uuid.prefix(8))
        defer { try? fm.removeItem(at: probe) }
        do { try fm.createDirectory(at: probe, withIntermediateDirectories: true) }
        catch { return "Highball cannot write in that folder." }
        do { try fm.createSymbolicLink(atPath: probe.appending(path: "link").path, withDestinationPath: "target") }
        catch {
            return "That drive cannot hold a Windows environment: an environment's drive letters are symbolic links, and this volume does not support them. Format it as APFS, or pick another drive."
        }
        // Wine's C: is dosdevices/c: → drive_c. A share can allow `link` and still reject a colon.
        do {
            try fm.createDirectory(at: probe.appending(path: "drive_c"), withIntermediateDirectories: true)
            try fm.createSymbolicLink(atPath: probe.appending(path: "c:").path, withDestinationPath: "drive_c")
        } catch {
            return "That drive cannot hold a Windows environment: an environment's drive letters are files named c:, and this volume does not allow a colon in a name. Pick a folder on this Mac, an APFS disk, or a network share that keeps Unix file names."
        }
        let bin = probe.appending(path: "bin")
        guard fm.createFile(atPath: bin.path, contents: Data("#!/bin/sh\nexit 0\n".utf8),
                            attributes: [.posixPermissions: 0o755]) else {
            return "Highball cannot write in that folder."
        }
        let mode = ((try? fm.attributesOfItem(atPath: bin.path))?[.posixPermissions] as? NSNumber)?.uint16Value ?? 0
        guard mode & 0o100 != 0 else {
            return "That drive cannot hold a Windows environment: Highball runs its engine from here, and this volume does not keep the execute permission. Format it as APFS, or pick another drive."
        }
        return nil
    }

    public var downloads: URL { home.appending(path: "downloads", directoryHint: .isDirectory) }
    public var engines: URL { home.appending(path: "engines", directoryHint: .isDirectory) }
    public var bottles: URL { home.appending(path: "bottles", directoryHint: .isDirectory) }
    public var logs: URL { home.appending(path: "logs", directoryHint: .isDirectory) }
    public var manifests: URL { home.appending(path: "manifests", directoryHint: .isDirectory) }
    /// Staging for bottles on their way out. A sibling of `bottles/` rather than a child, so
    /// nothing that enumerates bottles ever sees a half-purged tree, and inside `home` rather
    /// than `~/.Trash` so the move is always same-filesystem — `rename(2)` cannot cross one,
    /// and Finder could not empty an undeletable prefix anyway.
    public var trash: URL { home.appending(path: ".trash", directoryHint: .isDirectory) }
    /// Copies of game saves Highball made before deleting something that held them, made on
    /// demand and never cleared by Highball.
    public var saveBackups: URL { home.appending(path: "save-backups", directoryHint: .isDirectory) }

    public func engine(_ id: String) -> URL { engines.appending(path: id, directoryHint: .isDirectory) }
    public func bottle(_ name: String) -> URL { bottles.appending(path: name, directoryHint: .isDirectory) }

    public func ensure() throws {
        for dir in [home, downloads, engines, bottles, logs, manifests, trash] {
            try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        }
        excludeFromSpotlight()
    }

    /// Keeps Spotlight out of the engines and environments. A game install is tens or hundreds of
    /// gigabytes of files nobody searches for, and indexing them costs real time: after a 75 GB
    /// install on 2026-09-09 mds_stores sat at 55% with the load average above 300, the machine was
    /// unusable for minutes, and a game launched into it looked like it had hung. The marker file
    /// is the documented way to say "never index this subtree" and costs nothing when Spotlight is
    /// already off.
    func excludeFromSpotlight() {
        let marker = home.appending(path: ".metadata_never_index")
        guard !FileManager.default.fileExists(atPath: marker.path) else { return }
        FileManager.default.createFile(atPath: marker.path, contents: nil)
    }

    /// Whether this home holds anything worth moving.
    public var hasData: Bool {
        let fm = FileManager.default
        return [engines, bottles].contains { (try? fm.contentsOfDirectory(atPath: $0.path))?.contains { !$0.hasPrefix(".") } == true }
    }
}

/// Builds a pre-filled GitHub bug-report URL: system info and a digest of the most relevant
/// log land in the issue form (field ids: what/chip/version/log in .github/ISSUE_TEMPLATE/bug.yml),
/// so every report arrives with the context that triage always needs.
public enum BugReport {
    /// Strings that prove a log recorded a real graphics-stack launch. Backend names only —
    /// never a game or exe name, so this keeps working for titles nobody has heard of.
    ///
    /// Picking the log by CONTENT rather than by filename is the whole point. A game that can
    /// only be started from a launcher's own UI (legacy CS:GO's CEG chooser) never gets a wine
    /// log of its own: Wine hands the entire process tree one pipe, so the game's DXVK output
    /// lands in the LAUNCHER's log. The previous picker skipped launcher logs by name and so
    /// attached the one file guaranteed not to mention the game — in issue #21 that was a
    /// wineboot log, and it cost four rounds of guessing.
    static let backendMarkers = [
        "info:  Game:",             // DXVK/d9vk banner: names the exe that created the device
        "DXVK-Kegworks",
        "DXVK:",
        "Found config file:",
        "Effective configuration:",
        "winemetal",                // DXMT
        "D3DMetal",
        "wined3d_adapter_create",
        "gl.renderer:",
        "gl.version:",
        "gl.vendor:",
        "OpenGL renderer",
    ]

    /// Kept in the digest for context, but deliberately NOT used to choose a log: every wine
    /// process emits `init_peb starting`, so treating it as a backend signal would make almost
    /// any log "informative" and collapse selection back to newest-wins.
    static let contextMarkers = ["init_peb starting"]

    static let errorMarkers = ["err:", "[mvk-error]", "Assertion Failed", "Backtrace:", "OpenGL error"]
    /// Wine shouts these on every single launch and they have never explained a failure. Left in
    /// the budget they crowd the real errors out: one issue #21 log carries 24 HID lines and 740
    /// identical font-handle lines before anything diagnostic.
    static let benignMarkers = [
        "handle_DeviceMatchingCallback",
        "kerberos_LsaApInitializePackage",
        "ntlm_check_version",
        "ntlm_LsaApInitializePackage",
        "process_run_key Error running cmd",
        "RoGetActivationFactory",
    ]
    static let maxErrorLines = 40
    static let tailLines = 40
    static let maxDigestCharacters = 8000
    /// How many of the newest logs to open. The directory accumulates hundreds of files.
    static let maxLogsExamined = 15
    /// How far before the newest log a log still counts as the same sitting.
    static let sameSessionWindow: TimeInterval = 2 * 3600
    /// GitHub answers a request URI over roughly 8 KB with 414, and percent-encoding a log can
    /// several-fold its length (every newline becomes %0A), so the ENCODED url is what must be
    /// budgeted — not the digest's character count. Someone not signed in to GitHub is sent to
    /// the login page with the whole link as its return address, and that page answers "Whoops,
    /// something went wrong!" once the address passes about 7 KB (a report link of about 5.8 KB),
    /// then drops the address altogether, report and all, past about 6.4 KB. Measured on
    /// 2026-10-01 after a player hit the error page.
    static let maxURLCharacters = 5000
    /// A single launch here has produced a 167 MB log, so never read one whole. The banner and
    /// the effective configuration are written when the game creates its device, early in its
    /// output; the runaway repetition that makes a log enormous always comes later. Kept modest
    /// because `url()` scans up to `maxLogsExamined` of these on the calling thread.
    static let maxHeadBytes = 1 << 20
    static let maxTailBytes = 256 << 10

    /// Wine infrastructure and launcher processes that are never the frozen game. Anything
    /// else running from a bottle's drive_c with an .exe suffix is a candidate.
    static let infraExes: Set<String> = [
        "steam.exe", "steamwebhelper.exe", "steamservice.exe", "steamerrorreporter.exe",
        "services.exe", "svchost.exe", "winedevice.exe", "plugplay.exe", "rpcss.exe",
        "explorer.exe", "wineboot.exe", "conhost.exe", "rundll32.exe", "reg.exe",
        "gameoverlayui.exe", "gameoverlayui64.exe", "x86launcher.exe", "cmd.exe",
        "epicgameslauncher.exe", "epicwebhelper.exe", "unrealcefsubprocess.exe",
    ]

    /// Parses `ps -Ao pid=,command=` output into candidate game processes: anything running
    /// out of a bottle's drive_c that isn't wine plumbing or a launcher. Pure for testability.
    public static func gameProcesses(fromPS ps: String) -> [(pid: Int32, exe: String)] {
        var out: [(Int32, String)] = []
        for line in ps.split(separator: "\n") {
            let trimmed = line.trimmingCharacters(in: .whitespaces)
            guard let sp = trimmed.firstIndex(of: " "), let pid = Int32(trimmed[..<sp]) else { continue }
            let command = String(trimmed[trimmed.index(after: sp)...])
            guard command.contains("/drive_c/") else { continue }
            // The executable path ends at ".exe"; what follows are the game's own arguments.
            guard let range = command.range(of: ".exe", options: [.caseInsensitive]) else { continue }
            let exePath = String(command[..<range.upperBound])
            let exe = (exePath as NSString).lastPathComponent.lowercased()
            guard !infraExes.contains(exe) else { continue }
            out.append((pid, exe))
        }
        return out
    }

    /// The issue #21 lesson, made permanent: a frozen game produces no crash, no exit and no
    /// fresh log lines, so a report filed DURING the freeze used to contain nothing at all —
    /// five diagnostic rounds to learn where one stack trace would have answered it. Now the
    /// report button samples any live game process (macOS `sample`, 5 s) into the logs
    /// directory, and the digest names the file so the user attaches it.
    static func sampleRunningGames(paths: HighballPaths) -> [String] {
        guard let ps = try? Shell.capture("/bin/ps", ["-Ao", "pid=,command="]) else { return [] }
        var written: [String] = []
        for (pid, exe) in gameProcesses(fromPS: ps).prefix(2) {
            let stamp = ISO8601DateFormatter().string(from: Date()).replacingOccurrences(of: ":", with: "")
            let file = paths.logs.appending(path: "\(stamp)-sample-\(exe).txt")
            if (try? Shell.run("/usr/bin/sample", [String(pid), "5", "-f", file.path])) != nil {
                written.append(file.lastPathComponent)
            }
        }
        return written
    }

    /// Where a launch can leave a log: Highball's own directory, plus the per-process files DXVK
    /// writes inside each bottle (DXVK_LOG_PATH, set in `Bottle.environment`). The DXVK files
    /// matter because they survive the one case Highball cannot otherwise observe — a game
    /// started by a launcher client that Highball did not spawn.
    static func logDirectories(_ paths: HighballPaths) -> [URL] {
        var dirs = [paths.logs]
        let bottles = (try? FileManager.default.contentsOfDirectory(at: paths.bottles, includingPropertiesForKeys: nil)) ?? []
        dirs += bottles.map { $0.appending(path: "drive_c/highball/logs") }
        return dirs.filter { FileManager.default.fileExists(atPath: $0.path) }
    }

    /// Head and tail of a log, bounded. A gap marker records what was skipped so nobody reads
    /// the result as complete.
    static func boundedText(of url: URL) -> String? {
        guard let handle = try? FileHandle(forReadingFrom: url) else { return nil }
        defer { try? handle.close() }
        let size = (try? handle.seekToEnd()) ?? 0
        try? handle.seek(toOffset: 0)
        guard size > UInt64(maxHeadBytes + maxTailBytes) else {
            return (try? handle.readToEnd()).map { String(decoding: $0, as: UTF8.self) }
        }
        let head = (try? handle.read(upToCount: maxHeadBytes)) ?? Data()
        try? handle.seek(toOffset: size - UInt64(maxTailBytes))
        let tail = (try? handle.readToEnd()) ?? Data()
        let skipped = size - UInt64(maxHeadBytes) - UInt64(maxTailBytes)
        return String(decoding: head, as: UTF8.self)
            + "\n… \(skipped) bytes not scanned …\n"
            + String(decoding: tail, as: UTF8.self)
    }

    /// Condenses a wine log to the lines triage actually reads: the launch header and exit
    /// footer, the first sighting of each graphics-backend marker (with the indented block that
    /// follows a configuration dump), the errors, and the tail. Runs of an identical line
    /// collapse to one `(xN)`.
    ///
    /// A blind `suffix(30)` — what this replaced — is structurally useless on a wine log: the
    /// end is always MoltenVK warning spam, while the block naming the backend sits thousands of
    /// lines earlier (line 6547 of 8185 in the issue #21 logs).
    public static func digest(_ text: String) -> String {
        let lines = text.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
        guard !lines.isEmpty else { return "" }
        var keep = Set<Int>()
        var note: [Int: String] = [:]
        // The "# …" launch header and the "# exit=" footer.
        for (i, line) in lines.enumerated() where line.hasPrefix("#") { keep.insert(i) }
        for marker in backendMarkers + contextMarkers {
            guard let i = lines.firstIndex(where: { $0.contains(marker) }) else { continue }
            keep.insert(i)
            // The indented report that follows a configuration dump.
            var j = i + 1
            while j < lines.count, lines[j].hasPrefix("info:    ") { keep.insert(j); j += 1 }
        }
        // Errors: benign startup noise dropped, the rest deduplicated across the whole log so a
        // failure repeated 740 times costs one line and still reports its true count.
        var firstIndex: [String: Int] = [:]
        var occurrences: [String: Int] = [:]
        var order: [String] = []
        var errorKey: [Int: String] = [:]
        for (i, line) in lines.enumerated()
        where errorMarkers.contains(where: line.contains) && !benignMarkers.contains(where: line.contains) {
            let key = normalizedError(line)
            errorKey[i] = key
            if firstIndex[key] == nil { firstIndex[key] = i; order.append(key) }
            occurrences[key, default: 0] += 1
        }
        for key in order.prefix(maxErrorLines) {
            guard let i = firstIndex[key] else { continue }
            keep.insert(i)
            if let n = occurrences[key], n > 1 { note[i] = "(x\(n))" }
        }
        // The tail: where a crash lands, and where a freeze simply stops. An error already
        // represented above is skipped here, so one failure can never appear twice carrying two
        // different counts.
        for i in max(0, lines.count - tailLines)..<lines.count {
            if let key = errorKey[i], firstIndex[key] != i { continue }
            keep.insert(i)
        }

        var out: [String] = []
        var previous = -1
        var repeats = 0
        func collapse() {
            if repeats > 1, !out.isEmpty { out[out.count - 1] += "  (x\(repeats))" }
            repeats = 0
        }
        for i in keep.sorted() {
            let rendered = note[i].map { "\(clip(lines[i]))  \($0)" } ?? clip(lines[i])
            if i == previous + 1, repeats > 0, rendered == out.last { repeats += 1; previous = i; continue }
            collapse()
            if previous >= 0, i > previous + 1 { out.append("… \(i - previous - 1) lines …") }
            out.append(rendered)
            repeats = 1
            previous = i
        }
        collapse()
        return redactHome(trim(out))
    }

    /// Longest single line kept. Bounds the digest and, not incidentally, stops a very long opaque
    /// value — a launcher URL carrying an auth token, which real Epic logs here do contain — from
    /// being pasted whole into a public GitHub issue.
    static let maxLineCharacters = 300
    static func clip(_ line: String) -> String {
        guard line.count > maxLineCharacters else { return line }
        return line.prefix(maxLineCharacters) + "… (+\(line.count - maxLineCharacters) chars)"
    }

    /// Joins the kept lines, and if they exceed the budget keeps BOTH ENDS: the head carries the
    /// launch header, the backend banner and the effective configuration; the tail carries how the
    /// run ended. A plain `suffix` would drop exactly the head — the content this function exists
    /// to preserve — and keep the MoltenVK spam, reinstating the failure it was written to fix.
    static func trim(_ lines: [String], budget: Int = maxDigestCharacters) -> String {
        let whole = lines.joined(separator: "\n")
        guard whole.count > budget else { return whole }
        let headBudget = budget * 2 / 3
        var head: [String] = [], used = 0
        for line in lines {
            if used + line.count + 1 > headBudget, !head.isEmpty { break }
            head.append(line); used += line.count + 1
        }
        var tail: [String] = [], tailUsed = 0
        for line in lines[head.count...].reversed() {
            if used + tailUsed + line.count + 1 > budget { break }
            tail.append(line); tailUsed += line.count + 1
        }
        let dropped = lines.count - head.count - tail.count
        guard dropped > 0 else { return whole }
        return (head + ["… \(dropped) digest lines dropped …"] + tail.reversed()).joined(separator: "\n")
    }

    /// Replaces the user's home directory with `~`. Wine command lines and DLL search paths are
    /// absolute, so they carry the account name into a public issue for no diagnostic gain.
    static func redactHome(_ text: String) -> String {
        let home = NSHomeDirectory()
        return home.count > 1 ? text.replacingOccurrences(of: home, with: "~") : text
    }

    /// An error line stripped of what varies between otherwise identical occurrences: Wine's
    /// per-thread id prefix and any hex addresses. Without this, the same failure on eight
    /// threads reads as eight different problems.
    static func normalizedError(_ line: String) -> String {
        var text = line
        if let colon = text.firstIndex(of: ":"), text.distance(from: text.startIndex, to: colon) == 4,
           text[text.startIndex..<colon].allSatisfy(\.isHexDigit) {
            text = String(text[text.index(after: colon)...])
        }
        return text.replacingOccurrences(of: "0x[0-9a-fA-F]+", with: "0x…", options: .regularExpression)
    }

    /// The log most likely to explain what went wrong: the newest one that actually recorded a
    /// graphics backend, falling back to the newest of all.
    static func mostInformativeLog(in directories: [URL]) -> (url: URL, text: String)? {
        let key: Set<URLResourceKey> = [.contentModificationDateKey]
        var logs: [URL] = []
        for dir in directories {
            let files = (try? FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: Array(key))) ?? []
            logs += files.filter { $0.pathExtension == "log" }
        }
        let modified: (URL) -> Date = {
            (try? $0.resourceValues(forKeys: key))?.contentModificationDate ?? .distantPast
        }
        // The app's own chores (a registry write, Steam's shutdown, winecfg) never show a game
        // failing, yet they are written after every launch setting change, so they were often the
        // newest file: three reports came with a keyboard-mapping registry write attached and
        // nothing else (highball#184, #135, #235). They are left out before the newest are taken,
        // so they cannot crowd the game's own log out either.
        let newestFirst = logs.filter { !isChore($0) }.sorted { modified($0) > modified($1) }.prefix(maxLogsExamined)
        // A wineboot log is the prefix booting, and it ends before the game starts, so it can
        // never show a game failing. It nonetheless matches a backend marker, because wineboot
        // creates a d3d adapter and Wine shouts `wined3d_adapter_create` while doing it — so the
        // marker test alone ranked it "informative". In issue #21 the reporter sent one twice,
        // both times chosen by this picker, and each round cost days. Repair runs wineboot, so it
        // is also the log most likely to be the newest one after someone follows fix instructions.
        let isPrefixBoot: (URL) -> Bool = { $0.lastPathComponent.hasSuffix("-wineboot.log") }
        // A log that recorded a backend wins over newer ones only from the same sitting. A Forza
        // Horizon 6 report came with a log from the evening before, written on another engine
        // revision, because the two newest logs (Steam launches on the new one) had no backend
        // line (highball#645).
        let sessionStart = newestFirst.first.map { modified($0).addingTimeInterval(-sameSessionWindow) } ?? .distantPast
        var fallback: (url: URL, text: String)?
        var bootFallback: (url: URL, text: String)?
        for url in newestFirst {
            guard let text = boundedText(of: url) else { continue }
            if isPrefixBoot(url) {
                if bootFallback == nil { bootFallback = (url, text) }
                continue
            }
            if backendMarkers.contains(where: text.contains), modified(url) >= sessionStart { return (url, text) }
            if fallback == nil { fallback = (url, text) }
        }
        // Only when it is genuinely the only thing on disk — a bottle that has never run anything.
        return fallback ?? bootFallback
    }

    /// A log of the app's own housekeeping, by the label in its name: `<stamp>-<bottle>-reg.log`,
    /// numbered `-reg-2.log` when two land in the same second. Pure, so it is tested by name.
    static func isChore(_ url: URL) -> Bool {
        var name = url.deletingPathExtension().lastPathComponent
        if let dash = name.lastIndex(of: "-"), Int(name[name.index(after: dash)...]) != nil { name = String(name[..<dash]) }
        return ["-reg", "-steam-shutdown", "-winecfg"].contains { name.hasSuffix($0) }
    }

    /// `samplingLiveGames: false` skips the live-process sample (tests; callers that must not
    /// block for the ~5 s a sample takes).
    public static func url(version: String, paths: HighballPaths = HighballPaths(), samplingLiveGames: Bool = true) -> URL {
        let chip = Machine.chip()
        let macos = Machine.macOSVersion()
        var logDigest = ""
        // A game frozen right now is the one moment its stack is capturable — grab it first.
        let samples = samplingLiveGames ? sampleRunningGames(paths: paths) : []
        if !samples.isEmpty {
            logDigest += "Live game sampled during this report — PLEASE ATTACH from ~/Library/Application Support/Highball/logs/:\n"
                + samples.map { "  \($0)" }.joined(separator: "\n") + "\n\n"
        }
        if let found = mostInformativeLog(in: logDirectories(paths)) {
            // Name the full file too: the digest is a summary, and triage may want the original.
            logDigest += "\(redactHome(found.url.path)):\n\(digest(found.text))"
        }
        func url(log: String) -> URL {
            var comps = URLComponents(string: "https://github.com/gauthierpiarrette/highball/issues/new")!
            comps.queryItems = [
                URLQueryItem(name: "template", value: "bug.yml"),
                URLQueryItem(name: "chip", value: "\(chip), macOS \(macos)"),
                URLQueryItem(name: "version", value: version),
                URLQueryItem(name: "log", value: log),
            ]
            return comps.url!
        }
        // Shrink from the middle until the encoded URL fits, as `trim` does: the head holds the launch
        // header and the configuration, the tail how the run ended. Cutting the tail here lost the
        // crash from reports whose digest was long (highball#618, cut 50 repeats before the end).
        var result = url(log: logDigest)
        while result.absoluteString.count > maxURLCharacters, logDigest.count > 400 {
            logDigest = shortened(logDigest)
            result = url(log: logDigest)
        }
        return result
    }

    /// `text` at about three quarters of its length, both ends kept. Always shorter, so the caller's
    /// loop ends: a text of a few long lines `trim` can't cut between loses its end instead.
    static func shortened(_ text: String) -> String {
        let budget = text.count * 3 / 4
        let cut = trim(text.components(separatedBy: "\n"), budget: budget)
        return cut.count < text.count ? cut : String(text.prefix(budget))
    }
}