Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.
Swift apple-silicond3dmetaldxmtdxvkfexgame-porting-toolkitgamingmac-gamingmacosmetalmoltenvksteamswiftuivkd3d-protonwhisky-alternativewindows-gameswinewine-wrapper
testing: process-environment invariant, canary titles, launcher nightly, beta cadence
Gauthier Piarrettec0cf6ee59f23
diff --git a/Scripts/env-invariant-smoke.sh b/Scripts/env-invariant-smoke.shnew file mode 100755index 0000000..49e5f1d--- /dev/null+++ b/Scripts/env-invariant-smoke.sh@@ -0,0 +1,26 @@+#!/bin/zsh+# Environment invariant: a program launched from a bottle must run with the stack the bottle+# would launch it with (renderer overlay, sync mode, custom variables), and so must the Windows+# services that outlive it. Every launch bug of 2026-09-18 broke this invariant while the launch+# log's header claimed the right stack: services booted under a setup-time environment, an+# installer's agent respawning the client without the overlay, a sync mode adopted silently.+# `highball bottle ps --expect` reads the live process environments and fails on a mismatch.+#+# Cold-starts the Steam client in the Gaming environment (Steam's own pin forces sync off, so+# the check compares against what that launch asked for), then asserts. Needs no sign-in and+# no screen. Exit 0 on pass, 1 on a mismatch, 2 when the environment or engine is missing.+set -u+HB=${HB:-.build/debug/highball}+B=${1:-Gaming}+OUT=private/env-invariant; mkdir -p "$OUT"+$HB bottle list 2>/dev/null | grep -q "^$B\b" || { echo "env-invariant: no environment named $B"; exit 2; }+$HB bottle kill "$B" >/dev/null 2>&1; sleep 3+# Steam's pin (sync none for its browser) is the launch whose stack the client must carry.+($HB run "$B" "Steam" > "$OUT/steam.log" 2>&1 &)+for i in $(seq 1 30); do sleep 2; pgrep -f 'Steam.steam\.exe' >/dev/null && break; done+sleep 20+$HB bottle ps "$B" --expect > "$OUT/ps.txt" 2>&1; rc=$?+cat "$OUT/ps.txt"+$HB bottle kill "$B" >/dev/null 2>&1+if [ $rc -eq 0 ]; then echo "ENV INVARIANT PASSED for $B"; else echo "ENV INVARIANT FAILED for $B: see $OUT/ps.txt"; fi+exit $rcdiff --git a/Scripts/game-smoke.sh b/Scripts/game-smoke.shindex aa44afe..70ccec1 100755--- a/Scripts/game-smoke.sh+++ b/Scripts/game-smoke.sh@@ -35,6 +35,11 @@ GAMES=("230410|dxmt|Warframe|warframe|""3314060|dxvk|Sims|sims|""319510|dxvk|Five Nights|fnaf|"+ # Canary set (2026-09-18): one title per graphics path, all installed here as demos or+ # verified rows, so a renderer or engine change cannot slip through on a path nobody ran.+ "3916150|d3dmetal|Caretaker|caretaker|"+ "1773210|d3dmetal|HumanitZ|humanitz|"+ "3527290|dxvk|PEAK|peak|")only=("$@")results=(); passed=truediff --git a/Scripts/gate.sh b/Scripts/gate.shindex 290672b..8c19744 100755--- a/Scripts/gate.sh+++ b/Scripts/gate.sh@@ -45,6 +45,9 @@ run firstrun Scripts/firstrun-smoke.sh --screenrun launch-window Scripts/launch-window-smoke.shecho "gate: advisory checks"run game Scripts/game-smoke.sh+# Advisory until its false-fail rate is zero, like every new check: the process-environment+# invariant behind the 2026-09-18 launcher fixes (see Scripts/env-invariant-smoke.sh).+run env-invariant Scripts/env-invariant-smoke.sh[ $WITH_RENDER = 1 ] && run render Scripts/render-smoke.shpassed=truediff --git a/Scripts/install-nightly.sh b/Scripts/install-nightly.shnew file mode 100755index 0000000..6e533f6--- /dev/null+++ b/Scripts/install-nightly.sh@@ -0,0 +1,30 @@+#!/bin/zsh+# Installs (or with --remove, removes) the launchd agent that runs the launcher nightly at+# 03:30 on this Mac, with the display kept awake for the run. Logs land in private/nightly/.+# The loop is deliberately light (one session per launcher, sign-in window only), see+# Scripts/launcher-nightly.sh. Usage: Scripts/install-nightly.sh [--remove]+set -eu+LABEL=com.highball.launcher-nightly+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"+REPO="$(cd "$(dirname "$0")/.." && pwd)"+if [ "${1:-}" = --remove ]; then launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || true; rm -f "$PLIST"; echo "removed $LABEL"; exit 0; fi+mkdir -p "$HOME/Library/LaunchAgents" "$REPO/private/nightly"+cat > "$PLIST" <<PL+<?xml version="1.0" encoding="UTF-8"?>+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">+<plist version="1.0"><dict>+ <key>Label</key><string>$LABEL</string>+ <key>ProgramArguments</key><array>+ <string>/usr/bin/caffeinate</string><string>-dis</string>+ <string>/bin/zsh</string><string>-lc</string>+ <string>cd "$REPO" && swift build >/dev/null 2>&1; Scripts/launcher-nightly.sh</string>+ </array>+ <key>StartCalendarInterval</key><dict><key>Hour</key><integer>3</integer><key>Minute</key><integer>30</integer></dict>+ <key>StandardOutPath</key><string>$REPO/private/nightly/launcher-nightly.log</string>+ <key>StandardErrorPath</key><string>$REPO/private/nightly/launcher-nightly.err</string>+ <key>RunAtLoad</key><false/>+</dict></plist>+PL+launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || true+launchctl bootstrap "gui/$(id -u)" "$PLIST"+echo "installed $LABEL (03:30 daily): $PLIST"diff --git a/Scripts/launcher-nightly.sh b/Scripts/launcher-nightly.shnew file mode 100755index 0000000..7af5d3b--- /dev/null+++ b/Scripts/launcher-nightly.sh@@ -0,0 +1,68 @@+#!/bin/zsh+# Launcher nightly: every launcher recipe, installed into a fresh environment on the engine the+# recipe asks for, launched once up to its sign-in window, measured, then deleted. One session+# per launcher per run, never further than the sign-in window: Rockstar and Ubisoft flagged this+# machine's address after repeated scripted starts (2026-09), so the loop is deliberately light.+#+# Per launcher it records: whether the recipe applied (blocked recipes are expected-fail and+# recorded as such), the installer's exit, crash lines in the launch log, whether a window with+# the launcher's title appeared, how much of it drew (only when the screen is unlocked; a locked+# session records "locked", never a verdict), and the process-environment invariant+# (`highball bottle ps --expect`). Writes private/launcher-nightly/latest.json and one line per+# launcher on stdout. Usage: Scripts/launcher-nightly.sh [--only <id>...]+set -u+HB=${HB:-.build/debug/highball}+DB=${DB:-../highball-db/recipes/launchers}+OUT=private/launcher-nightly; mkdir -p "$OUT"+only=(); [ "${1:-}" = "--only" ] && { shift; only=("$@"); }+locked=$(ioreg -n Root -d1 2>/dev/null | grep -q 'CGSSessionScreenIsLocked"=Yes' && echo true || echo false)+winlist=Scripts/winlist; [ -x "$winlist" ] || winlist=""+results=()+for f in "$DB"/*.json; do+ id=$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['id'])" "$f")+ if [ ${#only[@]} -gt 0 ] && ! printf '%s\n' "${only[@]}" | grep -qx "$id"; then continue; fi+ read -r engine pinname winre blocked <<< "$(python3 - "$f" <<'PY'+import json,sys+r=json.load(open(sys.argv[1]))+pin=[s for s in r['steps'] if s['type']=='pin']+name=pin[0]['pin']['name'] if pin else ''+print((r.get('engine') or 'default').replace(' ','_'), name.replace(' ','_'), r.get('windowTitle', name.split()[0] if name else 'x').replace(' ','_'), 'yes' if r.get('blocked') else 'no')+PY+)"+ pinname=${pinname//_/ }; winre=${winre//_/ }+ b="nightly-$id"; t0=$(date +%s)+ $HB bottle delete "$b" >/dev/null 2>&1+ if [ "$blocked" = yes ]; then+ echo "[$id] blocked by its recipe (expected)"; results+=("{\"id\":\"$id\",\"result\":\"blocked\"}"); continue+ fi+ engarg=(); [ "$engine" != default ] && engarg=(--engine "$engine")+ if ! $HB bottle create "$b" "${engarg[@]}" --recipe "$f" > "$OUT/$id-install.log" 2>&1; then+ echo "[$id] install FAILED (see $OUT/$id-install.log)"; results+=("{\"id\":\"$id\",\"result\":\"install-failed\"}"); $HB bottle delete "$b" >/dev/null 2>&1; continue+ fi+ # Steam's first start is a chain of relaunches (exit 9 mid-download, exit 42 after the+ # update, then the client), fifteen minutes or more under WoW64 and Rosetta; the others+ # show their sign-in window within a minute or two.+ wait_s=90; [ "$id" = steam ] && wait_s=900+ ($HB run "$b" "$pinname" > "$OUT/$id-launch.log" 2>&1 &)+ sleep "$wait_s"+ crash=$(grep -cE 'int3|Unhandled exception|page fault' "$OUT/$id-launch.log")+ win="none"; lit="n/a"+ if [ -n "$winlist" ]; then+ row=$($winlist 2>/dev/null | grep -i "owner=wine" | grep -i "$winre" | head -1); [ -n "$row" ] && win="yes"+ if [ "$win" = yes ] && [ "$locked" = false ]; then+ wid=$(echo "$row" | sed -n 's/^id=\([0-9]*\).*/\1/p')+ screencapture -l "$wid" -o -x "$OUT/$id.png" 2>/dev/null && lit=$(python3 -c "+from PIL import Image; im=Image.open('$OUT/$id.png').convert('RGBA'); px=list(im.getdata()); n=len(px)+print('%.2f'%(sum(1 for q in px if q[3]>200 and (q[0]+q[1]+q[2])>90)/n))" 2>/dev/null || echo "n/a")+ elif [ "$locked" = true ]; then lit="locked"; fi+ fi+ # An empty process list is a failure, not a pass: the launcher exited or never started, and+ # an invariant over nothing proves nothing.+ $HB bottle ps "$b" --expect > "$OUT/$id-ps.txt" 2>&1 && env_ok=true || env_ok=false+ if ! grep -q " program " "$OUT/$id-ps.txt"; then env_ok=false; win="none"; echo "[$id] no program running 90 s after launch (see $OUT/$id-launch.log)"; fi+ $HB bottle kill "$b" >/dev/null 2>&1; $HB bottle delete "$b" >/dev/null 2>&1+ echo "[$id] installed, crash lines $crash, window $win, lit $lit, env invariant $env_ok ($(( $(date +%s) - t0 ))s)"+ results+=("{\"id\":\"$id\",\"result\":\"ran\",\"crashLines\":$crash,\"window\":\"$win\",\"lit\":\"$lit\",\"envInvariant\":$env_ok}")+done+printf '{"date":"%s","epoch":%s,"locked":%s,"results":[%s]}\n' "$(date +%Y-%m-%d)" "$(date +%s)" "$locked" "$(IFS=,; echo "${results[*]}")" > "$OUT/latest.json"+echo "launcher nightly: $OUT/latest.json"diff --git a/Scripts/release.sh b/Scripts/release.shindex dd8f5b6..65ca127 100755--- a/Scripts/release.sh+++ b/Scripts/release.sh@@ -55,6 +55,24 @@ VERSION="${1:?usage: release.sh [--beta|--hotfix] <version> <summary> [notes.md]SUMMARY="${2:?summary required}"NOTES_FILE="${3:-}"export HB_CHANNEL="$CHANNEL"+# Beta cadence (2026-09-18): three betas in one day is churn for testers and for the owner. A+# beta waits two days after the previous one unless it fixes a regression (say "regression" in+# the summary) or HB_CADENCE_OK=1 says so.+if [ "$CHANNEL" = beta ]; then+ HB_SUMMARY="${2:-}" python3 - <<'PY' || { echo "set HB_CADENCE_OK=1 to cut it anyway, or put 'regression' in the summary if it fixes one" >&2; exit 1; }+import os, re, sys, time+from email.utils import parsedate_to_datetime+if os.environ.get('HB_CADENCE_OK') == '1' or 'regression' in os.environ.get('HB_SUMMARY', '').lower(): sys.exit(0)+s = open('appcast.xml').read()+last = None+for item in re.findall(r'<item>.*?</item>', s, re.S):+ if '<sparkle:channel>beta</sparkle:channel>' in item:+ m = re.search(r'<pubDate>(.*?)</pubDate>', item)+ if m: last = max(last or 0, parsedate_to_datetime(m.group(1)).timestamp())+if last and time.time() - last < 2 * 86400:+ print(f"release cadence: the previous beta was {(time.time() - last) / 3600:.1f} hours ago; betas wait two days unless they fix a regression.", file=sys.stderr); sys.exit(1)+PY+fi# The tag below marks HEAD as the source of this build, so the tree must be clean.git diff-index --quiet HEAD -- || { echo "tracked files modified; commit before releasing" >&2; exit 1; }diff --git a/Sources/HighballKit/Bottle.swift b/Sources/HighballKit/Bottle.swiftindex b622d2b..151bd31 100644--- a/Sources/HighballKit/Bottle.swift+++ b/Sources/HighballKit/Bottle.swift@@ -585,6 +585,21 @@ public struct Bottle: Sendable {return .active(multiplier: multiplier)}+ /// The pin a running program belongs to, by folder: a program whose Windows path lies under+ /// a pinned program's folder (Steam's steamwebhelper.exe under Program Files (x86)\Steam) is+ /// launched by that pin or by something the pin started, so it carries the pin's+ /// environment, not the environment's defaults (the Steam pin forces sync off for its+ /// browser). Pure; `argv0` is the Windows path as the process reports it.+ public static func pin(owning argv0: String, in pins: [Pin]) -> Pin? {+ let norm = { (p: String) -> String in p.replacingOccurrences(of: "\\", with: "/").lowercased() }+ let program = norm(argv0)+ // Longest folder wins when pins nest.+ return pins.filter { pin in+ let folder = norm(pin.path).split(separator: "/").dropLast().joined(separator: "/")+ return !folder.isEmpty && program.contains("/" + folder + "/")+ }.max { a, b in a.path.count < b.path.count }+ }+public func environment(engine: InstalledEngine, renderer: Renderer? = nil, extra: [String: String] = [:]) throws -> [String: String] {let effective = try effectiveRenderer(requested: renderer, engine: engine).renderervar env = engine.baseEnvironment()diff --git a/Sources/HighballKit/ProcessTable.swift b/Sources/HighballKit/ProcessTable.swiftindex caf08f5..bf290c7 100644--- a/Sources/HighballKit/ProcessTable.swift+++ b/Sources/HighballKit/ProcessTable.swift@@ -145,6 +145,17 @@ public enum ProcessTable {}}+ /// Whether a prefix process is Wine's own plumbing (or the server) rather than a program:+ /// plumbing works in `drive_c/windows`, the server in its `/tmp` server directory. The+ /// rule `bottle ps` prints and the environment invariant asserts against. Pure.+ public static func isPlumbing(executable exe: String, workingDirectory cwd: String, prefix: String) -> Bool {+ let root = prefix.hasSuffix("/") ? prefix : prefix + "/"+ let windows = root + "drive_c/windows"+ if cwd == windows || cwd.hasPrefix(windows + "/") { return true }+ let name = exe.replacingOccurrences(of: "\\", with: "/").split(separator: "/").last.map(String.init) ?? exe+ return name == "wineserver" || name.hasSuffix("/wineserver")+ }+public static func isIdle(prefix: URL) -> Bool {let root = canonical(prefix.path)let server = serverDirectory(forPrefix: prefix).map { canonical($0.path) }diff --git a/Sources/highball/main.swift b/Sources/highball/main.swiftindex fb0e6df..5e38bd3 100644--- a/Sources/highball/main.swift+++ b/Sources/highball/main.swift@@ -77,7 +77,7 @@ struct Engine: AsyncParsableCommand {// MARK: - highball bottlestruct Bottle: AsyncParsableCommand {- static let configuration = CommandConfiguration(abstract: "Manage bottles (Wine prefixes).", subcommands: [List.self, Create.self, Delete.self, Set.self, Kill.self, Duplicate.self, Repair.self])+ static let configuration = CommandConfiguration(abstract: "Manage bottles (Wine prefixes).", subcommands: [List.self, Create.self, Delete.self, Set.self, Kill.self, Duplicate.self, Repair.self, Ps.self])struct List: AsyncParsableCommand {func run() async throws {@@ -218,6 +218,59 @@ struct Bottle: AsyncParsableCommand {}}+ /// What is really running in a bottle, and with which stack. Every launch bug of 2026-09-18+ /// (services booted under a setup-time environment, an installer's agent spawning the client+ /// without the renderer overlay, a sync mode adopted silently) was invisible in the launch+ /// log and obvious in the process environment. This prints that, and with --expect it fails+ /// when a program runs with a different stack than the bottle would launch it with, which+ /// is what the smokes assert after a fresh install and first Play.+ struct Ps: AsyncParsableCommand {+ static let configuration = CommandConfiguration(abstract: "List the bottle's processes with the renderer, sync mode and custom variables each one actually got. --expect fails (exit 1) when a program's stack differs from the bottle's launch environment.")+ @Argument var name: String+ @Flag(name: .long, help: "Fail when any program (not Wine's plumbing) runs with a stack that differs from what the bottle would launch it with.") var expect = false+ func run() async throws {+ let b = try BottleStore().get(name)+ let eng = try EngineStore().engine(b.settings.engineID)+ let wanted = try b.environment(engine: eng)+ let wantedRenderer = SteamRestart.rendererName(ofLive: wanted)+ let custom = Array(b.settings.environment.keys).sorted()+ let root = b.url.resolvingSymlinksInPath().path+ var mismatches = 0+ let rows = ProcessTable.processes(ofPrefix: b.url).compactMap { pid -> (pid_t, String, String, String, String, String, String?)? in+ guard let info = ProcessTable.commandLineAndEnvironment(of: pid) else { return nil }+ let argv0 = info.arguments.first ?? "?"+ let exe = argv0.replacingOccurrences(of: "\\", with: "/").split(separator: "/").last.map(String.init) ?? argv0+ let cwd = ProcessTable.workingDirectory(of: pid).map { URL(fileURLWithPath: $0).resolvingSymlinksInPath().path } ?? ""+ let kind = ProcessTable.isPlumbing(executable: argv0, workingDirectory: cwd, prefix: root) ? "plumbing" : "program"+ let env = info.environment+ let renderer = env["WINEDLLPATH_PREPEND"] == nil && env["WINEPREFIX"] == nil ? "?" : SteamRestart.rendererName(ofLive: env)+ let sync = SyncMode(environment: env).rawValue+ let vars = custom.map { "\($0)=\(env[$0] ?? "-")" }.joined(separator: " ")+ var why: String? = nil+ if kind == "program", env["WINEPREFIX"] != nil {+ // A program under a pinned program's folder is judged against that pin's+ // environment (renderer and variables), which is what launched it.+ var expected = wanted, expectedRenderer = wantedRenderer+ if let pin = HighballKit.Bottle.pin(owning: argv0, in: b.settings.pins),+ let e = try? b.environment(engine: eng, renderer: pin.renderer, extra: pin.environment) {+ expected = e; expectedRenderer = SteamRestart.rendererName(ofLive: e)+ }+ why = SteamRestart.reason(live: env, wanted: expected, wantedRenderer: expectedRenderer, custom: custom)+ if why != nil { mismatches += 1 }+ }+ return (pid, kind, exe, renderer, sync, vars, why)+ }+ if rows.isEmpty { print("no processes in \(name)"); return }+ for r in rows {+ print("\(r.0)\t\(r.1)\t\(r.2)\trenderer=\(r.3)\tsync=\(r.4)\(r.5.isEmpty ? "" : "\t" + r.5)\(r.6.map { "\tMISMATCH: " + $0 } ?? "")")+ }+ if expect && mismatches > 0 {+ print("\(mismatches) program\(mismatches == 1 ? "" : "s") run with a different stack than \(name) would launch them with")+ throw ExitCode(1)+ }+ }+ }+struct Kill: AsyncParsableCommand {@Argument var name: Stringfunc run() async throws {diff --git a/Tests/HighballKitTests/ProcessTableIdleTests.swift b/Tests/HighballKitTests/ProcessTableIdleTests.swiftindex bbaead0..fb4dd27 100644--- a/Tests/HighballKitTests/ProcessTableIdleTests.swift+++ b/Tests/HighballKitTests/ProcessTableIdleTests.swift@@ -38,3 +38,45 @@ final class ProcessTableIdleTests: XCTestCase {XCTAssertFalse(ProcessTable.isIdle(workingDirectories: [server], prefix: prefix, serverDirectory: nil))}}++final class ProcessTablePlumbingTests: XCTestCase {+ private let prefix = "/Users/me/Library/Application Support/Highball/bottles/games"++ func testWindowsSystemProcessesArePlumbing() {+ XCTAssertTrue(ProcessTable.isPlumbing(executable: "C:\\windows\\system32\\services.exe", workingDirectory: prefix + "/drive_c/windows", prefix: prefix))+ XCTAssertTrue(ProcessTable.isPlumbing(executable: "C:\\windows\\system32\\explorer.exe", workingDirectory: prefix + "/drive_c/windows/system32", prefix: prefix))+ }++ func testTheServerIsPlumbingWhereverItWorks() {+ XCTAssertTrue(ProcessTable.isPlumbing(executable: "/e/engine/bin/wineserver", workingDirectory: "/private/tmp/.wine-501/server-1-2", prefix: prefix))+ }++ func testAWindowsServiceCountsAsPlumbingByItsWorkingDirectory() {+ // Rockstar's service is started by services.exe in drive_c/windows (measured 2026-09-18).+ XCTAssertTrue(ProcessTable.isPlumbing(executable: "C:\\Program Files\\Rockstar Games\\Launcher\\RockstarService.exe", workingDirectory: prefix + "/drive_c/windows", prefix: prefix))+ }++ func testAProgramInItsOwnFolderIsNotPlumbing() {+ XCTAssertFalse(ProcessTable.isPlumbing(executable: "C:\\Program Files (x86)\\Steam\\steam.exe", workingDirectory: prefix + "/drive_c/Program Files (x86)/Steam", prefix: prefix))+ XCTAssertFalse(ProcessTable.isPlumbing(executable: "C:/ProgramData/Battle.net/Agent/Agent.exe", workingDirectory: prefix + "/drive_c/ProgramData/Battle.net/Agent", prefix: prefix))+ }+}++final class PinOwnershipTests: XCTestCase {+ private let steam = Pin(name: "Steam", path: "Program Files (x86)/Steam/steam.exe", arguments: [], environment: ["WINEMSYNC": "0", "WINEESYNC": "0"], renderer: nil)+ private let rockstar = Pin(name: "Rockstar Launcher", path: "Program Files/Rockstar Games/Launcher/Launcher.exe", arguments: [], environment: [:], renderer: .dxvk)++ func testAHelperUnderThePinnedFolderBelongsToThePin() {+ XCTAssertEqual(Bottle.pin(owning: "C:\\Program Files (x86)\\Steam\\bin\\cef\\cef.win7x64\\steamwebhelper.exe", in: [steam, rockstar])?.name, "Steam")+ XCTAssertEqual(Bottle.pin(owning: "C:\\Program Files (x86)\\Steam\\steam.exe", in: [steam, rockstar])?.name, "Steam")+ }++ func testAProgramElsewhereBelongsToNoPin() {+ XCTAssertNil(Bottle.pin(owning: "C:\\Program Files\\Rockstar Games\\Social Club\\SocialClubHelper.exe", in: [steam]))+ XCTAssertNil(Bottle.pin(owning: "C:\\windows\\system32\\services.exe", in: [steam, rockstar]))+ }++ func testForwardSlashesAndCaseDoNotMatter() {+ XCTAssertEqual(Bottle.pin(owning: "c:/program files/rockstar games/launcher/RockstarService.exe", in: [steam, rockstar])?.name, "Rockstar Launcher")+ }+}