From 7745bed0e7981dec23d4981b1c43c15d9769cfed Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 15:39:05 -0600
Subject: [PATCH 01/14] replace setup bundles with complete runtime installer

---
 AGENTS.md                                   |  21 ++-
 app/package.json                            |   4 +
 app/src-rust/src/installer.rs               | 142 +++++++++++++++-----
 app/src-rust/src/setup.rs                   |  15 ++-
 app/src/renderer/components/SetupWizard.vue |   2 +-
 5 files changed, 141 insertions(+), 43 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 64450c225..6d366d4d4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,8 +1,27 @@
 # AGENTS.md
-**Updated:** 2026-07-08
+**Updated:** 2026-07-31
 
 Guide for AI agents working on the MetalSharp repository.
 
+## 0.60.0 Preview Release Work
+
+Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
+`~/Documents/obsidian/Avery'sVault/0.60.0 Official Preview Release Plan.md`.
+
+- Phase 1 replaces first-run split-bundle installation with
+  `scripts/install-metalsharp-wine-runtime.sh` from release
+  `v0.60.0-dependency-bundles`.
+- The canonical complete-runtime SHA-256 is
+  `93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee`.
+- Runtime completion is gated by `.metalsharp-runtime-install` plus Wine,
+  wineserver, fonts/NLS, DXVK i386, vkd3d-proton D3D12, OpenGL-Metal, and
+  MoltenVK payloads. Do not restore the old six-archive setup gate.
+- The runtime installs transactionally at `~/.metalsharp/runtime`; prefixes,
+  Steam, bottles, saves, and shader caches remain outside that directory.
+- Phase 1 keeps Rosetta installation until macOS 28 and keeps GPTK/Homebrew as
+  a separate route. The complete runtime launch adapters explicitly disable
+  FEX TSO, vector TSO, and memcpy/set TSO.
+
 ## What This Project Is
 
 MetalSharp is a macOS app that runs Windows Steam games and Windows programs via Wine + Metal translation. It's an Electron app with a Rust HTTP backend, a C++ native D3D/Metal engine, per-game engine routing, runtime bottles, installer profiles, and Linux `.deb` packaging.
diff --git a/app/package.json b/app/package.json
index b9ac53668..09698ab4b 100644
--- a/app/package.json
+++ b/app/package.json
@@ -136,6 +136,10 @@
           "*.toml"
         ]
       },
+      {
+        "from": "../scripts/install-metalsharp-wine-runtime.sh",
+        "to": "scripts/install-metalsharp-wine-runtime.sh"
+      },
       {
         "from": "bundles/metalsharp-electron.tar.zst",
         "to": "bundles/metalsharp-electron.tar.zst"
diff --git a/app/src-rust/src/installer.rs b/app/src-rust/src/installer.rs
index aecfd305d..565b27811 100644
--- a/app/src-rust/src/installer.rs
+++ b/app/src-rust/src/installer.rs
@@ -31,6 +31,8 @@ const ASSETS_BUNDLE: &str = "metalsharp-assets";
 const FNALIBS_BUNDLE: &str = "fnalibs";
 const SCRIPTS_TOOLS_BUNDLE: &str = "metalsharp-scripts-tools";
 const STEAM_BUNDLE: &str = "metalsharp-steam";
+const COMPLETE_RUNTIME_INSTALLER: &str = "install-metalsharp-wine-runtime.sh";
+const COMPLETE_RUNTIME_ARCHIVE_SHA256: &str = "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee";
 const METALSHARP_NTDLL_HOOK_DLL: &str = "metalsharp_ntdll_hook.dll";
 const DXMT_REQUIRED_PE: &[&str] = &[
     "d3d10core.dll",
@@ -319,21 +321,80 @@ fn install_steps() -> Vec<InstallStep> {
         ("System Tools", Box::new(|_| install_xcode_cli())),
         ("Rosetta 2", Box::new(|_| install_rosetta())),
         ("Extract Tools (zstd)", Box::new(|_| ensure_zstd())),
-        ("Runtime Bundle Downloads", Box::new(ensure_runtime_bundle_assets)),
-        ("Runtime Assets", Box::new(install_metalsharp_bundle)),
-        ("Host Runtime ABI", Box::new(install_host_runtime)),
-        ("Support Assets", Box::new(install_split_assets_bundle)),
-        ("Scripts and Tools", Box::new(install_scripts_tools_bundle)),
-        ("DXMT Graphics Runtimes", Box::new(|home| ensure_graphics_runtimes_ready(home))),
-        ("Goldberg Steam Emulator", Box::new(install_goldberg)),
-        ("Steam Bridge Shim", Box::new(install_steam_bridge)),
-        ("Pipeline Rules", Box::new(install_mtsp_rules)),
-        ("Mono Configs", Box::new(install_mono_configs)),
-        ("Runtime Support", Box::new(|_| install_mono_arm64())),
-        ("FNA Shim Precompile", Box::new(|_| crate::mtsp::launcher::precompile_all_fna_shims().map(|_| true))),
+        ("Complete Multi-Architecture Runtime", Box::new(install_complete_runtime)),
     ]
 }
 
+fn complete_runtime_root(home: &Path) -> PathBuf {
+    crate::platform::metalsharp_home_dir_for(home).join("runtime")
+}
+
+fn complete_runtime_marker(root: &Path) -> PathBuf {
+    root.join(".metalsharp-runtime-install")
+}
+
+pub fn complete_runtime_current_for_home(home: &Path) -> bool {
+    let root = complete_runtime_root(home);
+    let marker = match fs::read_to_string(complete_runtime_marker(&root)) {
+        Ok(marker) => marker,
+        Err(_) => return false,
+    };
+
+    marker.lines().any(|line| line == format!("archive_sha256={COMPLETE_RUNTIME_ARCHIVE_SHA256}"))
+        && file_nonempty(&root.join("wine/bin/metalsharp-wine"))
+        && file_nonempty(&root.join("wine/build-ec/wine"))
+        && file_nonempty(&root.join("wine/build-ec/server/wineserver"))
+        && file_nonempty(&root.join("wine/wine-11.12/nls/locale.nls"))
+        && file_nonempty(&root.join("wine/wine-11.12/fonts/tahoma.ttf"))
+        && file_nonempty(&root.join("graphics/dxvk/i386/d3d9.dll"))
+        && file_nonempty(&root.join("graphics/vkd3d-proton/x86_64/d3d12.dll"))
+        && file_nonempty(&root.join("graphics/opengl-metal/metalsharp-opengl.dylib"))
+        && file_nonempty(&root.join("graphics/moltenvk/libMoltenVK.dylib"))
+}
+
+fn find_complete_runtime_installer() -> Option<PathBuf> {
+    let mut candidates = Vec::new();
+    if let Some(resources) = crate::platform::app_resources_dir() {
+        candidates.push(resources.join("scripts").join(COMPLETE_RUNTIME_INSTALLER));
+    }
+    candidates
+        .push(PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..").join("scripts").join(COMPLETE_RUNTIME_INSTALLER));
+    candidates.push(PathBuf::from("scripts").join(COMPLETE_RUNTIME_INSTALLER));
+    candidates.push(PathBuf::from("../scripts").join(COMPLETE_RUNTIME_INSTALLER));
+    candidates.into_iter().find(|path| file_nonempty(path))
+}
+
+fn install_complete_runtime(home: &PathBuf) -> Result<bool, String> {
+    if complete_runtime_current_for_home(home) {
+        return Ok(false);
+    }
+
+    let installer = find_complete_runtime_installer().ok_or_else(|| {
+        format!("{} is missing from the MetalSharp application resources", COMPLETE_RUNTIME_INSTALLER)
+    })?;
+    let target = complete_runtime_root(home);
+    let output = Command::new("/bin/bash")
+        .arg(&installer)
+        .args(["--target"])
+        .arg(&target)
+        .args(["--replace", "--discard-backup"])
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .output()
+        .map_err(|e| format!("start complete runtime installer: {e}"))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let detail = stderr.lines().rev().find(|line| !line.trim().is_empty()).unwrap_or("unknown installer error");
+        return Err(format!("complete runtime installer failed: {detail}"));
+    }
+    if !complete_runtime_current_for_home(home) {
+        return Err("complete runtime installer exited successfully, but the runtime verification gate failed".into());
+    }
+
+    Ok(true)
+}
+
 fn runtime_bundle_assets_for_host() -> &'static [&'static str] {
     MAC_RUNTIME_BUNDLE_ASSETS
 }
@@ -2540,21 +2601,6 @@ mod tests {
         let _ = fs::remove_dir_all(home);
     }
 
-    #[test]
-    fn runtime_bundle_preflight_knows_beta7_assets() {
-        let mac_assets = MAC_RUNTIME_BUNDLE_ASSETS;
-        for expected in [
-            "metalsharp-runtime.tar.zst",
-            "metalsharp-graphics-dll.tar.zst",
-            "metalsharp-assets.tar.zst",
-            "fnalibs.tar.zst",
-            "metalsharp-scripts-tools.tar.zst",
-            "metalsharp-steam.tar.zst",
-        ] {
-            assert!(mac_assets.contains(&expected), "missing mac bundle asset {}", expected);
-        }
-    }
-
     #[test]
     fn install_order_runs_xcode_cli_before_rosetta() {
         let names: Vec<&str> = install_steps().into_iter().map(|(name, _)| name).collect();
@@ -2566,18 +2612,46 @@ mod tests {
     }
 
     #[test]
-    fn install_steps_use_split_graphics_runtime_and_do_not_install_eac_toggle_or_gptk() {
+    fn install_steps_use_only_prerequisites_and_complete_runtime() {
         let names: Vec<&str> = install_steps().into_iter().map(|(name, _)| name).collect();
 
-        assert!(names.contains(&"DXMT Graphics Runtimes"));
-        assert!(!names.contains(&"Offline EAC Mode"));
-        assert!(
-            names.iter().all(|name| !name.to_ascii_lowercase().contains("gptk")),
-            "first-time setup must not install GPTK; D3DMetal bottles own Homebrew GPTK setup: {:?}",
-            names
+        assert_eq!(
+            names,
+            vec!["System Tools", "Rosetta 2", "Extract Tools (zstd)", "Complete Multi-Architecture Runtime"]
         );
     }
 
+    #[test]
+    fn complete_runtime_gate_requires_matching_marker_and_all_surfaces() {
+        let home = test_home("complete-runtime-gate");
+        let root = complete_runtime_root(&home);
+        for rel in [
+            "wine/bin/metalsharp-wine",
+            "wine/build-ec/wine",
+            "wine/build-ec/server/wineserver",
+            "wine/wine-11.12/nls/locale.nls",
+            "wine/wine-11.12/fonts/tahoma.ttf",
+            "graphics/dxvk/i386/d3d9.dll",
+            "graphics/vkd3d-proton/x86_64/d3d12.dll",
+            "graphics/opengl-metal/metalsharp-opengl.dylib",
+            "graphics/moltenvk/libMoltenVK.dylib",
+        ] {
+            let path = root.join(rel);
+            fs::create_dir_all(path.parent().expect("fixture parent")).expect("create fixture parent");
+            fs::write(path, b"fixture").expect("write fixture");
+        }
+        fs::write(
+            complete_runtime_marker(&root),
+            format!("archive_sha256={COMPLETE_RUNTIME_ARCHIVE_SHA256}\nno_tso=1\n"),
+        )
+        .expect("write marker");
+
+        assert!(complete_runtime_current_for_home(&home));
+        fs::remove_file(root.join("graphics/vkd3d-proton/x86_64/d3d12.dll")).expect("remove gate fixture");
+        assert!(!complete_runtime_current_for_home(&home));
+        let _ = fs::remove_dir_all(home);
+    }
+
     #[test]
     fn graphics_bundle_layout_matches_release_manifest() {
         let manifest = include_str!("../../../tools/bundles/asset-manifest.tsv");
diff --git a/app/src-rust/src/setup.rs b/app/src-rust/src/setup.rs
index 751940060..1cf2b5218 100644
--- a/app/src-rust/src/setup.rs
+++ b/app/src-rust/src/setup.rs
@@ -23,12 +23,13 @@ const DEFAULT_AGILITY_PACKAGE_VERSION: &str = "1.619.3";
 pub fn state() -> Value {
     let home = dirs::home_dir().unwrap_or_default();
     let config_path = crate::platform::metalsharp_home_dir_for(&home).join("setup.json");
+    let complete_runtime_current = crate::installer::complete_runtime_current_for_home(&home);
     let dxmt_runtime = crate::installer::dxmt_runtime_status();
     let dxmt_current = dxmt_runtime.get("current").and_then(|v| v.as_bool()).unwrap_or(false);
     let dxmt_m12_current = dxmt_runtime.get("m12Current").and_then(|v| v.as_bool()).unwrap_or(false);
     let wine_dir = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
     let metalsharp_runtime_lib_ready = crate::installer::metalsharp_runtime_lib_ready(&wine_dir);
-    let runtime_current = dxmt_current && dxmt_m12_current && metalsharp_runtime_lib_ready;
+    let runtime_current = complete_runtime_current;
 
     if config_path.exists() {
         if let Ok(contents) = std::fs::read_to_string(&config_path) {
@@ -42,6 +43,7 @@ pub fn state() -> Value {
                     "deviceName": cfg.get("deviceName").and_then(|v| v.as_str()).unwrap_or(""),
                     "steamApiKeySet": cfg.get("steamApiKeySet").and_then(|v| v.as_bool()).unwrap_or(false),
                     "runtimeMigrationRequired": saved_completed && !runtime_current,
+                    "completeRuntimeCurrent": complete_runtime_current,
                     "dxmtRuntime": dxmt_runtime,
                     "metalsharpRuntimeLibReady": metalsharp_runtime_lib_ready,
                 });
@@ -57,6 +59,7 @@ pub fn state() -> Value {
         "deviceName": "",
         "steamApiKeySet": false,
         "runtimeMigrationRequired": false,
+        "completeRuntimeCurrent": complete_runtime_current,
         "dxmtRuntime": dxmt_runtime,
         "metalsharpRuntimeLibReady": metalsharp_runtime_lib_ready,
     })
@@ -127,8 +130,7 @@ pub fn dependencies() -> Value {
         || check_path(&PathBuf::from("/Applications/Steam.app/Contents/MacOS/steam_osx"));
     let homebrew = check_command("brew");
     let moltenvk = check_path(&PathBuf::from("/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json"));
-    let metalsharp_wine = check_path(&crate::platform::metalsharp_home_dir_for(&home).join("runtime/wine/bin/wine"))
-        || check_path(&crate::platform::metalsharp_home_dir_for(&home).join("runtime/wine/bin/metalsharp-wine"));
+    let metalsharp_wine = crate::installer::complete_runtime_current_for_home(&home);
     let host_runtime = host_runtime_installed(&home);
     let dxmt_status = crate::installer::dxmt_runtime_status();
     let dxmt_runtime = dxmt_status
@@ -144,8 +146,7 @@ pub fn dependencies() -> Value {
         .and_then(|v| v.as_bool())
         .unwrap_or(false);
 
-    let all_ok =
-        homebrew && rosetta && xcode_cli && metalsharp_wine && host_runtime && dxmt_runtime && dxmt_m12_runtime;
+    let all_ok = homebrew && rosetta && xcode_cli && metalsharp_wine;
 
     json!({
         "ok": true,
@@ -178,8 +179,8 @@ pub fn dependencies() -> Value {
             },
             {
                 "id": "metalsharp_wine",
-                "name": "MetalSharp Wine",
-                "desc": "From-source Wine 11.5 with DXMT Metal D3D11, gnutls TLS, MoltenVK. Runs Windows Steam and launches games with native Metal rendering.",
+                "name": "MetalSharp Complete Wine Runtime",
+                "desc": "Verified Wine 11.12 multi-architecture runtime with ARM64, ARM64EC, x86_64 and i386/WoW64 execution plus the complete Metal and Vulkan graphics stack.",
                 "installed": metalsharp_wine,
                 "required": true,
                 "installCmd": "metalsharp-setup-wine",
diff --git a/app/src/renderer/components/SetupWizard.vue b/app/src/renderer/components/SetupWizard.vue
index f14a7e73a..423d39f65 100644
--- a/app/src/renderer/components/SetupWizard.vue
+++ b/app/src/renderer/components/SetupWizard.vue
@@ -307,7 +307,7 @@ async function installVcppX86() {
       <div v-if="step === 2" class="setup-body">
         <div class="setup-section-header">
           <h1>Install Runtime</h1>
-          <p>Install the MetalSharp-owned Wine runtime, DXMT graphics runtimes, Steam support files, Mono/FNA support, scripts, and bottle rules. GPTK is not installed during first-time setup.</p>
+          <p>Download, verify, and install the complete MetalSharp Wine 11.12 runtime for ARM64, ARM64EC, x86_64, and i386/WoW64. The installer includes the Metal/Vulkan graphics stacks, fonts, TLS, media, Java, Mono, SDL, and runtime providers. GPTK remains a separate Homebrew-owned route.</p>
         </div>
 
         <button

From d2bdc60cdcc65add664114a62962f141fa05aa6f Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 15:51:54 -0600
Subject: [PATCH 02/14] integrate all-architecture Steam installer handoffs

---
 AGENTS.md                                   |  11 +
 app/src-rust/src/installer.rs               |  10 +
 app/src-rust/src/main.rs                    |   4 +
 app/src-rust/src/steam.rs                   | 511 ++++++++++++++++----
 app/src/renderer/components/SetupWizard.vue |  16 +-
 scripts/install-metalsharp-wine-runtime.sh  |   5 +
 6 files changed, 467 insertions(+), 90 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6d366d4d4..8b8b5eb9d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,17 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
 - Phase 1 keeps Rosetta installation until macOS 28 and keeps GPTK/Homebrew as
   a separate route. The complete runtime launch adapters explicitly disable
   FEX TSO, vector TSO, and memcpy/set TSO.
+- Phase 2 creates `~/.metalsharp/prefix-steam` as a single all-architecture
+  prefix. Before wineboot it stages ARM64 WoW64 providers, every i386 Wine
+  builtin, and the accepted ARM64/ARM64EC CPU providers; after wineboot it
+  restages/verifies providers and requires both system32 and syswow64 gates.
+- Steam installation enables the ntdll host notification only for installer
+  processes. `POST /steam/handoff` accepts exactly two serialized callbacks:
+  cycle 1 shuts down only the Steam prefix and relaunches its updater; cycle 2
+  shuts it down, deploys and verifies the CEF wrapper, and writes
+  `.metalsharp-steam-install-complete`. Steam is not reported installed before
+  that marker exists. All install and handoff launches keep every FEX TSO mode
+  disabled.
 
 ## What This Project Is
 
diff --git a/app/src-rust/src/installer.rs b/app/src-rust/src/installer.rs
index 565b27811..15f5aecad 100644
--- a/app/src-rust/src/installer.rs
+++ b/app/src-rust/src/installer.rs
@@ -350,6 +350,11 @@ pub fn complete_runtime_current_for_home(home: &Path) -> bool {
         && file_nonempty(&root.join("graphics/vkd3d-proton/x86_64/d3d12.dll"))
         && file_nonempty(&root.join("graphics/opengl-metal/metalsharp-opengl.dylib"))
         && file_nonempty(&root.join("graphics/moltenvk/libMoltenVK.dylib"))
+        && file_nonempty(&root.join("providers/xtajit64-arm64ec-known-good.dll"))
+        && file_nonempty(&root.join("providers/xtajit-arm64-known-good.dll"))
+        && file_nonempty(&root.join("scripts/stage-runtime-providers.sh"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/wow64/aarch64-windows/wow64.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/wow64win/aarch64-windows/wow64win.dll"))
 }
 
 fn find_complete_runtime_installer() -> Option<PathBuf> {
@@ -2635,6 +2640,11 @@ mod tests {
             "graphics/vkd3d-proton/x86_64/d3d12.dll",
             "graphics/opengl-metal/metalsharp-opengl.dylib",
             "graphics/moltenvk/libMoltenVK.dylib",
+            "providers/xtajit64-arm64ec-known-good.dll",
+            "providers/xtajit-arm64-known-good.dll",
+            "scripts/stage-runtime-providers.sh",
+            "wine/build-ec/dlls/wow64/aarch64-windows/wow64.dll",
+            "wine/build-ec/dlls/wow64win/aarch64-windows/wow64win.dll",
         ] {
             let path = root.join(rel);
             fs::create_dir_all(path.parent().expect("fixture parent")).expect("create fixture parent");
diff --git a/app/src-rust/src/main.rs b/app/src-rust/src/main.rs
index 60cd77c0f..eaadf97ff 100644
--- a/app/src-rust/src/main.rs
+++ b/app/src-rust/src/main.rs
@@ -419,6 +419,10 @@ fn route(req: &mut tiny_http::Request) -> RouteResponse {
                 resp(500, json!({"ok": false, "error": e.to_string()}))
             },
         },
+        (Method::Post, "/steam/handoff") => {
+            let (status, body) = steam::accept_install_handoff();
+            resp(status, body)
+        },
         (Method::Post, "/steam/launch") => {
             app_log("Launching Wine Steam...");
             match steam::launch_wine_steam() {
diff --git a/app/src-rust/src/steam.rs b/app/src-rust/src/steam.rs
index 833cb7ae6..6a14d7240 100644
--- a/app/src-rust/src/steam.rs
+++ b/app/src-rust/src/steam.rs
@@ -2,15 +2,55 @@ use serde_json::{json, Value};
 use std::path::{Component, Path, PathBuf};
 use std::process::Command;
 use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Mutex, OnceLock};
 
 static STEAM_INSTALLING: AtomicBool = AtomicBool::new(false);
+static STEAM_INSTALL_HANDOFF: OnceLock<Mutex<SteamInstallHandoffState>> = OnceLock::new();
+const STEAM_INSTALL_HANDOFF_LIMIT: u8 = 2;
+const STEAM_INSTALL_MARKER: &str = ".metalsharp-steam-install-complete";
+const XTAJIT64_SHA256: &str = "7b9f55ceabe971ffa1f514570bb54ed7b5640959e4440e7f8a013e9af13ab7e6";
+const XTAJIT_SHA256: &str = "7d2ac83d2c0935e04d033d609c42d8307294225dcb4cb16b88af849e95c694ab";
 const STEAMWEBHELPER_WRAPPER_MAX_BYTES: u64 = 100_000;
 const STEAMWEBHELPER_WRAPPER_SHA256: &str = "f46a1e8c39c850ba22861f63559f13b4f68557acf04a92e6d1b899769b2ea1f9";
 const STEAM_D3D12_GUARD_APPS: &[&str] = &["Steam.exe", "steamwebhelper.exe", "steamwebhelper_real.exe"];
 const STEAM_D3D12_GUARD_DLLS: &[&str] = &["d3d12", "d3d12core", "d3d12SDKLayers", "dxcore"];
 
+#[derive(Clone, Debug, Default)]
+struct SteamInstallHandoffState {
+    accepted: u8,
+    active: bool,
+    complete: bool,
+    last_child_pid: Option<u32>,
+    last_error: Option<String>,
+}
+
+fn install_handoff_state() -> &'static Mutex<SteamInstallHandoffState> {
+    STEAM_INSTALL_HANDOFF.get_or_init(|| Mutex::new(SteamInstallHandoffState::default()))
+}
+
+fn reset_install_handoff_state() {
+    if let Ok(mut state) = install_handoff_state().lock() {
+        *state = SteamInstallHandoffState::default();
+    }
+}
+
+fn install_handoff_json(state: &SteamInstallHandoffState) -> Value {
+    json!({
+        "accepted": state.accepted,
+        "remaining": STEAM_INSTALL_HANDOFF_LIMIT.saturating_sub(state.accepted),
+        "active": state.active,
+        "complete": state.complete,
+        "last_child_pid": state.last_child_pid,
+        "last_error": state.last_error,
+    })
+}
+
+fn runtime_root() -> PathBuf {
+    crate::platform::metalsharp_home_dir().join("runtime")
+}
+
 fn ms_wine() -> PathBuf {
-    let ms_root = crate::platform::metalsharp_home_dir().join("runtime").join("wine");
+    let ms_root = runtime_root().join("wine");
     crate::platform::runtime_wine_binary(&ms_root)
 }
 
@@ -60,7 +100,9 @@ pub fn status() -> Value {
 
     let wine_steam_dir = steam_prefix().join("drive_c").join("Program Files (x86)").join("Steam");
     let wine_steam_exe = wine_steam_dir.join("Steam.exe");
-    let windows_installed = wine_steam_exe.exists();
+    let windows_installed = wine_steam_exe.exists()
+        && wine_steam_dir.join("steamui.dll").exists()
+        && wine_steam_dir.join(STEAM_INSTALL_MARKER).exists();
     let windows_path = if windows_installed { Some(wine_steam_dir.to_string_lossy().to_string()) } else { None };
 
     let login_state = detect_login_state();
@@ -77,6 +119,10 @@ pub fn status() -> Value {
     let running = is_wine_steam_running();
     let ms_available = ms_wine().exists();
     let installing = is_installing_steam();
+    let handoff = install_handoff_state()
+        .lock()
+        .map(|state| install_handoff_json(&state))
+        .unwrap_or_else(|_| json!({"last_error": "Steam install handoff state is unavailable"}));
 
     json!({
         "installed": windows_installed,
@@ -88,7 +134,8 @@ pub fn status() -> Value {
         "mac_running": mac_running,
         "running": running,
         "metalsharp_wine_available": ms_available,
-        "installing": installing
+        "installing": installing,
+        "install_handoff": handoff
     })
 }
 
@@ -937,6 +984,18 @@ fn steamwebhelper_wrapper_valid(path: &Path) -> bool {
     file_sha256(path).as_deref() == Some(STEAMWEBHELPER_WRAPPER_SHA256)
 }
 
+fn steamwebhelper_wrapper_deployed(steam_dir: &Path) -> bool {
+    let cef_dirs = cef_subdirs(steam_dir);
+    !cef_dirs.is_empty()
+        && cef_dirs.iter().any(|cef_dir| {
+            let wrapper = cef_dir.join("steamwebhelper.exe");
+            let real = cef_dir.join("steamwebhelper_real.exe");
+            steamwebhelper_wrapper_valid(&wrapper)
+                && std::fs::metadata(real).map(|metadata| metadata.len()).unwrap_or(0)
+                    > STEAMWEBHELPER_WRAPPER_MAX_BYTES
+        })
+}
+
 fn file_sha256(path: &Path) -> Option<String> {
     for (program, args) in [("shasum", vec!["-a", "256"]), ("sha256sum", Vec::new())] {
         let Ok(output) = Command::new(program).args(args).arg(path).output() else {
@@ -1451,10 +1510,266 @@ fn parse_vdf_value(line: &str, key: &str) -> Option<String> {
     Some(rest.trim_matches('"').to_string())
 }
 
+fn steam_installer_valid(path: &Path) -> bool {
+    if std::fs::metadata(path).map(|metadata| metadata.len()).unwrap_or(0) < 1_000_000 {
+        return false;
+    }
+    let mut header = [0u8; 2];
+    std::fs::File::open(path).and_then(|mut file| std::io::Read::read_exact(&mut file, &mut header)).is_ok()
+        && header == *b"MZ"
+}
+
+fn copy_file_required(source: &Path, destination: &Path, label: &str) -> Result<(), Box<dyn std::error::Error>> {
+    if !source.is_file() {
+        return Err(format!("missing {label}: {}", source.display()).into());
+    }
+    if let Some(parent) = destination.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    std::fs::copy(source, destination)?;
+    Ok(())
+}
+
+fn stage_i386_builtins(build: &Path, prefix: &Path) -> Result<usize, Box<dyn std::error::Error>> {
+    let dll_root = build.join("dlls");
+    let syswow64 = prefix.join("drive_c/windows/syswow64");
+    std::fs::create_dir_all(&syswow64)?;
+    let mut staged = 0usize;
+
+    for component in std::fs::read_dir(&dll_root)? {
+        let component = component?;
+        let lane = component.path().join("i386-windows");
+        if !lane.is_dir() {
+            continue;
+        }
+        for entry in std::fs::read_dir(lane)? {
+            let entry = entry?;
+            let path = entry.path();
+            if path.extension().and_then(|ext| ext.to_str()).is_some_and(|ext| ext.eq_ignore_ascii_case("dll")) {
+                std::fs::copy(&path, syswow64.join(entry.file_name()))?;
+                staged += 1;
+            }
+        }
+    }
+
+    if staged == 0 {
+        return Err("complete runtime contains no i386 Wine builtins to stage into the Steam prefix".into());
+    }
+    Ok(staged)
+}
+
+fn run_runtime_provider_stage(prefix: &Path, verify_only: bool) -> Result<(), Box<dyn std::error::Error>> {
+    let root = runtime_root();
+    let script = root.join("scripts/stage-runtime-providers.sh");
+    let xtajit64 = root.join("providers/xtajit64-arm64ec-known-good.dll");
+    let xtajit = root.join("providers/xtajit-arm64-known-good.dll");
+    if !script.is_file() {
+        return Err(format!("runtime provider staging script is missing: {}", script.display()).into());
+    }
+
+    let status = Command::new("/bin/bash")
+        .arg(&script)
+        .arg(if verify_only { "--verify-prefix" } else { "--prefix" })
+        .arg(prefix)
+        .env("WINEBUILDDIR", root.join("wine/build-ec"))
+        .env("VKMT_XTAJIT64_SOURCE", &xtajit64)
+        .env("VKMT_XTAJIT_SOURCE", &xtajit)
+        .env("VKMT_XTAJIT64_SHA256", XTAJIT64_SHA256)
+        .env("VKMT_XTAJIT_SHA256", XTAJIT_SHA256)
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::piped())
+        .output()?;
+    if !status.status.success() {
+        return Err(format!(
+            "runtime provider {} failed: {}",
+            if verify_only { "verification" } else { "staging" },
+            String::from_utf8_lossy(&status.stderr).lines().last().unwrap_or("unknown error")
+        )
+        .into());
+    }
+    Ok(())
+}
+
+fn steam_prefix_all_arch_ready(prefix: &Path) -> bool {
+    [
+        "system.reg",
+        "user.reg",
+        "drive_c/windows/system32/kernel32.dll",
+        "drive_c/windows/system32/ntdll.dll",
+        "drive_c/windows/system32/wow64.dll",
+        "drive_c/windows/system32/wow64win.dll",
+        "drive_c/windows/system32/xtajit64.dll",
+        "drive_c/windows/system32/xtajit.dll",
+        "drive_c/windows/syswow64/kernel32.dll",
+        "drive_c/windows/syswow64/ntdll.dll",
+        ".vkmt/gstreamer-runtime.sha256",
+    ]
+    .iter()
+    .all(|relative| prefix.join(relative).is_file())
+}
+
+fn prepare_steam_prefix(prefix: &Path) -> Result<(), Box<dyn std::error::Error>> {
+    let root = runtime_root();
+    let build = root.join("wine/build-ec");
+    let wine = ms_wine();
+    let system32 = prefix.join("drive_c/windows/system32");
+    std::fs::create_dir_all(&system32)?;
+    std::fs::create_dir_all(prefix.join("drive_c/windows/syswow64"))?;
+
+    copy_file_required(
+        &build.join("dlls/wow64/aarch64-windows/wow64.dll"),
+        &system32.join("wow64.dll"),
+        "ARM64 WoW64 provider",
+    )?;
+    copy_file_required(
+        &build.join("dlls/wow64win/aarch64-windows/wow64win.dll"),
+        &system32.join("wow64win.dll"),
+        "ARM64 WoW64 windowing provider",
+    )?;
+    stage_i386_builtins(&build, prefix)?;
+    run_runtime_provider_stage(prefix, false)?;
+
+    let wineboot = build.join("programs/wineboot/aarch64-windows/wineboot.exe");
+    let status = Command::new(&wine)
+        .arg(&wineboot)
+        .arg("--init")
+        .env("WINEPREFIX", prefix)
+        .env("WINEBUILDDIR", &build)
+        .env("WINEBOOTSTRAPMODE", "1")
+        .env("WINE_NO_EXPLORER", "1")
+        .env("WINEDEBUG", "-all")
+        .env("WINEDEBUGGER", "none")
+        .env("FEX_TSOENABLED", "0")
+        .env("FEX_VECTORTSOENABLED", "0")
+        .env("FEX_MEMCPYSETTSOENABLED", "0")
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()?;
+    if !status.success() {
+        return Err(format!("all-architecture wineboot failed with {status}").into());
+    }
+
+    let wineserver = crate::platform::runtime_wineserver(&root.join("wine"));
+    let wait_status = Command::new(wineserver).arg("-w").env("WINEPREFIX", prefix).status()?;
+    if !wait_status.success() {
+        return Err(format!("wineserver -w failed after Steam prefix initialization with {wait_status}").into());
+    }
+
+    run_runtime_provider_stage(prefix, false)?;
+    run_runtime_provider_stage(prefix, true)?;
+    if !steam_prefix_all_arch_ready(prefix) {
+        return Err("Steam prefix was initialized but the ARM64/ARM64EC/x86_64/i386 acceptance gate failed".into());
+    }
+    Ok(())
+}
+
+fn stop_steam_install_prefix() -> Result<(), Box<dyn std::error::Error>> {
+    let prefix = steam_prefix();
+    let wineserver = crate::platform::runtime_wineserver(&runtime_root().join("wine"));
+    for argument in ["-k", "-w"] {
+        let status = Command::new(&wineserver).arg(argument).env("WINEPREFIX", &prefix).status()?;
+        if !status.success() {
+            return Err(format!("Steam install wineserver {argument} failed with {status}").into());
+        }
+    }
+    Ok(())
+}
+
+fn spawn_steam_install_bootstrap() -> Result<u32, Box<dyn std::error::Error>> {
+    let prefix = steam_prefix();
+    let steam_dir = prefix.join("drive_c/Program Files (x86)/Steam");
+    let steam = steam_dir.join("Steam.exe");
+    if !steam.is_file() {
+        return Err(format!("Steam handoff executable is missing: {}", steam.display()).into());
+    }
+
+    let log_dir = crate::platform::metalsharp_home_dir().join("logs");
+    std::fs::create_dir_all(&log_dir)?;
+    let output =
+        std::fs::OpenOptions::new().create(true).append(true).open(log_dir.join("steam-install-handoff.log"))?;
+    let errors = output.try_clone()?;
+    let child = Command::new(ms_wine())
+        .arg(&steam)
+        .current_dir(&steam_dir)
+        .env("WINEPREFIX", &prefix)
+        .env("WINEBUILDDIR", runtime_root().join("wine/build-ec"))
+        .env("WINEBOOTSTRAPMODE", "1")
+        .env("VKMT_STEAM_HANDOFF_NOTIFY", "1")
+        .env("VKMT_STEAM_BOOTSTRAP_WAKE_RECOVERY", "0")
+        .env("FEX_TSOENABLED", "0")
+        .env("FEX_VECTORTSOENABLED", "0")
+        .env("FEX_MEMCPYSETTSOENABLED", "0")
+        .env("WINEDEBUG", "-all")
+        .env("WINEDEBUGGER", "none")
+        .env("MS_FWD_COMPAT_GL_CTX", "1")
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::from(output))
+        .stderr(std::process::Stdio::from(errors))
+        .spawn()?;
+    Ok(child.id())
+}
+
+fn run_install_handoff_cycle(cycle: u8) -> Result<Option<u32>, Box<dyn std::error::Error>> {
+    std::thread::sleep(std::time::Duration::from_millis(350));
+    stop_steam_install_prefix()?;
+    if cycle < STEAM_INSTALL_HANDOFF_LIMIT {
+        return spawn_steam_install_bootstrap().map(Some);
+    }
+
+    let steam_dir = steam_prefix().join("drive_c/Program Files (x86)/Steam");
+    deploy_steamwebhelper_wrapper(&steam_dir);
+    if !steamwebhelper_wrapper_deployed(&steam_dir) {
+        return Err("Steam updated successfully, but the verified steamwebhelper wrapper was not deployed".into());
+    }
+    std::fs::write(steam_dir.join(STEAM_INSTALL_MARKER), "handoffs=2\nwrapper_deployed=1\nno_tso=1\n")?;
+    Ok(None)
+}
+
+pub fn accept_install_handoff() -> (u16, Value) {
+    let mut state = match install_handoff_state().lock() {
+        Ok(state) => state,
+        Err(_) => return (500, json!({"ok": false, "error": "Steam install handoff state is unavailable"})),
+    };
+    if !STEAM_INSTALLING.load(Ordering::SeqCst) {
+        return (409, json!({"ok": false, "accepted": false, "reason": "no-install-active"}));
+    }
+    if state.active {
+        return (409, json!({"ok": false, "accepted": false, "reason": "handoff-active"}));
+    }
+    if state.accepted >= STEAM_INSTALL_HANDOFF_LIMIT {
+        return (429, json!({"ok": false, "accepted": false, "reason": "handoff-limit"}));
+    }
+
+    state.accepted += 1;
+    state.active = true;
+    let cycle = state.accepted;
+    drop(state);
+
+    std::thread::spawn(move || {
+        let outcome = run_install_handoff_cycle(cycle);
+        if let Ok(mut state) = install_handoff_state().lock() {
+            state.active = false;
+            match outcome {
+                Ok(pid) => {
+                    state.last_child_pid = pid;
+                    state.complete = cycle == STEAM_INSTALL_HANDOFF_LIMIT;
+                    state.last_error = None;
+                },
+                Err(error) => state.last_error = Some(error.to_string()),
+            }
+        }
+    });
+
+    (202, json!({"ok": true, "accepted": true, "cycle": cycle, "limit": STEAM_INSTALL_HANDOFF_LIMIT}))
+}
+
 pub fn install_steam() -> Result<String, Box<dyn std::error::Error>> {
     let steam_dir = steam_prefix().join("drive_c").join("Program Files (x86)").join("Steam");
 
-    if steam_dir.join("steamui.dll").exists() && steam_exe_path().exists() {
+    if steam_dir.join(STEAM_INSTALL_MARKER).exists()
+        && steam_dir.join("steamui.dll").exists()
+        && steam_exe_path().exists()
+    {
         return Ok("Steam already installed".into());
     }
 
@@ -1465,9 +1780,16 @@ pub fn install_steam() -> Result<String, Box<dyn std::error::Error>> {
     if STEAM_INSTALLING.compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst).is_err() {
         return Ok("Steam installation already in progress".into());
     }
+    reset_install_handoff_state();
 
     std::thread::spawn(move || {
-        let _ = run_install_steam();
+        if let Err(error) = run_install_steam() {
+            if let Ok(mut state) = install_handoff_state().lock() {
+                state.active = false;
+                state.complete = false;
+                state.last_error = Some(error.to_string());
+            }
+        }
         STEAM_INSTALLING.store(false, Ordering::SeqCst);
     });
 
@@ -1481,136 +1803,97 @@ fn run_install_steam() -> Result<String, Box<dyn std::error::Error>> {
 
     let steam_dir = steam_prefix().join("drive_c").join("Program Files (x86)").join("Steam");
 
+    let _ = stop_steam_install_prefix();
     let _ = std::fs::remove_dir_all(steam_prefix());
 
     let installer = metalsharp_dir.join("SteamSetup.exe");
     let _ = std::fs::remove_file(&installer);
 
     let url = "https://steamcdn-a.akamaihd.net/client/installer/SteamSetup.exe";
-    let output = Command::new("curl").args(["-sL", "-o", &installer.to_string_lossy(), url]).status()?;
-    if !output.success() {
+    let output = Command::new("/usr/bin/curl")
+        .args(["--fail", "--location", "--silent", "--show-error", "--retry", "4", "--output"])
+        .arg(&installer)
+        .arg(url)
+        .status()?;
+    if !output.success() || !steam_installer_valid(&installer) {
+        let _ = std::fs::remove_file(&installer);
         if let Some(bundled) = find_bundled_steam_asset("SteamSetup.exe") {
             let _ = std::fs::copy(&bundled, &installer);
         }
     }
-    if !installer.exists() {
-        return Err("Failed to download Steam installer".into());
+    if !steam_installer_valid(&installer) {
+        return Err("Failed to download a valid Steam installer".into());
     }
 
     let wine = ms_wine();
-    if !wine.exists() {
+    if !wine.exists() || !crate::installer::complete_runtime_current_for_home(&home) {
         return Err("MetalSharp Wine not found".into());
     }
 
     let prefix = steam_prefix();
     std::fs::create_dir_all(&prefix)?;
-
-    let prefix_str = prefix.to_string_lossy().to_string();
-
-    let ms_root = crate::platform::metalsharp_home_dir().join("runtime").join("wine");
-
-    let mut wineboot_cmd = Command::new(&wine);
-    wineboot_cmd
-        .env("WINEPREFIX", &prefix_str)
-        .env("WINEDEBUG", "-all")
-        .env("WINEDEBUGGER", "/usr/bin/true")
-        .env("WINEDLLOVERRIDES", "winedbg=d")
-        .arg("wineboot")
-        .arg("--init")
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null());
-    crate::platform::set_runtime_library_env(&mut wineboot_cmd, &ms_root);
-    let wineboot_result = wineboot_cmd.status();
-
-    if wineboot_result.is_err() {
-        return Err("wineboot --init failed — MetalSharp Wine may not be properly installed".into());
-    }
-
-    let windows_dir = prefix.join("drive_c").join("windows").join("system32");
-    let mut wineboot_ok = false;
-    for _ in 0..30 {
-        if windows_dir.exists() {
-            wineboot_ok = true;
-            break;
-        }
-        std::thread::sleep(std::time::Duration::from_secs(2));
-    }
-    if !wineboot_ok {
-        return Err("wineboot --init timed out — Wine prefix was not created within 60 seconds".into());
-    }
+    prepare_steam_prefix(&prefix)?;
 
     let seed_log = prefix.join("drive_c").join("metalsharp-post-wineboot.log");
     let _ = crate::bottles::seed_post_wineboot_config(&prefix, &seed_log);
 
     let mut install_cmd = Command::new(&wine);
     install_cmd
-        .env("WINEPREFIX", &prefix_str)
+        .env("WINEPREFIX", &prefix)
+        .env("WINEBUILDDIR", runtime_root().join("wine/build-ec"))
+        .env("WINEBOOTSTRAPMODE", "1")
+        .env("VKMT_STEAM_HANDOFF_NOTIFY", "1")
+        .env("VKMT_STEAM_BOOTSTRAP_WAKE_RECOVERY", "0")
+        .env("FEX_TSOENABLED", "0")
+        .env("FEX_VECTORTSOENABLED", "0")
+        .env("FEX_MEMCPYSETTSOENABLED", "0")
         .env("WINEDEBUG", "-all")
-        .env("WINEDEBUGGER", "/usr/bin/true")
+        .env("WINEDEBUGGER", "none")
         .env("WINEDLLOVERRIDES", "winedbg=d")
         .arg(&installer)
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null());
-    crate::platform::set_runtime_library_env(&mut install_cmd, &ms_root);
 
     let mut install_child = install_cmd.spawn()?;
     let install_pid = install_child.id();
 
     let steam_exe = steam_dir.join("Steam.exe");
     let steam_ui_dll = steam_dir.join("steamui.dll");
-    let mut install_crashed = false;
-    for _ in 0..70 {
-        // Check if the installer process is still running before waiting.
+    let mut installer_exited = false;
+    for _ in 0..2700 {
         match install_child.try_wait() {
             Ok(Some(status)) => {
-                if !status.success() {
+                if !status.success() && !steam_exe.exists() {
                     eprintln!("steam: installer exited early with status {:?}", status.code());
-                    install_crashed = true;
+                    return Err(format!("Steam installer exited before installing Steam (pid {install_pid})").into());
                 }
-                break;
+                installer_exited = true;
             },
-            Ok(None) => {}, // Still running
+            Ok(None) => {},
             Err(e) => {
                 eprintln!("steam: failed to check installer status: {}", e);
-                break;
             },
         }
-        if steam_exe.exists() && steam_ui_dll.exists() {
-            break;
-        }
-        std::thread::sleep(std::time::Duration::from_secs(1));
-    }
 
-    // If installer crashed, wait briefly for any remaining file I/O to settle
-    // before checking if Steam was partially installed anyway.
-    if install_crashed {
-        std::thread::sleep(std::time::Duration::from_secs(3));
-        if steam_exe.exists() && steam_ui_dll.exists() {
-            eprintln!("steam: installer crashed but Steam files are present — continuing");
-        } else {
-            // Kill any remaining Wine processes from the failed install
-            let _ = Command::new("pkill")
-                .args(["-f", &format!("WINEPREFIX={}", prefix_str)])
-                .stdout(std::process::Stdio::null())
-                .stderr(std::process::Stdio::null())
-                .status();
-            return Err(format!("Steam installer crashed (pid {}). Check Wine setup and retry.", install_pid).into());
+        let state = install_handoff_state()
+            .lock()
+            .map(|state| state.clone())
+            .map_err(|_| "Steam install handoff state is unavailable")?;
+        if let Some(error) = state.last_error {
+            return Err(format!("Steam updater handoff failed: {error}").into());
         }
-    }
-
-    if steam_exe.exists() && steam_ui_dll.exists() {
-        deploy_steamwebhelper_wrapper(&steam_dir);
-    }
-
-    for _ in 0..30 {
-        if !cef_subdirs(&steam_dir).is_empty() {
-            deploy_steamwebhelper_wrapper(&steam_dir);
-            break;
+        if state.complete
+            && steam_exe.exists()
+            && steam_ui_dll.exists()
+            && steam_dir.join(STEAM_INSTALL_MARKER).exists()
+        {
+            return Ok("Steam install completed after two updater handoffs".into());
         }
-        std::thread::sleep(std::time::Duration::from_secs(2));
+        std::thread::sleep(std::time::Duration::from_secs(1));
     }
 
-    Ok("Steam install thread complete".into())
+    let exited = if installer_exited { " after the installer process exited" } else { "" };
+    Err(format!("Steam installation timed out before both updater handoffs completed{exited}").into())
 }
 
 pub fn watch_steamapps() -> Vec<u32> {
@@ -1643,6 +1926,10 @@ pub fn watch_steamapps() -> Vec<u32> {
 mod tests {
     use super::*;
 
+    fn test_prefix(name: &str) -> PathBuf {
+        std::env::temp_dir().join(format!("metalsharp-steam-{name}-{}", std::process::id()))
+    }
+
     #[test]
     fn stop_wine_steam_targets_report_has_required_shape() {
         // Phase 7: the stop-targets report must expose the targeted and
@@ -1735,4 +2022,56 @@ mod tests {
         assert_eq!(fields.get(1).copied(), Some("steam"));
         assert_eq!(STEAMWEBHELPER_WRAPPER_SHA256.len(), 64);
     }
+
+    #[test]
+    fn all_arch_prefix_gate_requires_native_wow64_and_i386_surfaces() {
+        let prefix = test_prefix("all-arch-gate");
+        let _ = std::fs::remove_dir_all(&prefix);
+        for relative in [
+            "system.reg",
+            "user.reg",
+            "drive_c/windows/system32/kernel32.dll",
+            "drive_c/windows/system32/ntdll.dll",
+            "drive_c/windows/system32/wow64.dll",
+            "drive_c/windows/system32/wow64win.dll",
+            "drive_c/windows/system32/xtajit64.dll",
+            "drive_c/windows/system32/xtajit.dll",
+            "drive_c/windows/syswow64/kernel32.dll",
+            "drive_c/windows/syswow64/ntdll.dll",
+            ".vkmt/gstreamer-runtime.sha256",
+        ] {
+            let path = prefix.join(relative);
+            std::fs::create_dir_all(path.parent().expect("fixture parent")).expect("create fixture parent");
+            std::fs::write(path, b"fixture").expect("write fixture");
+        }
+
+        assert!(steam_prefix_all_arch_ready(&prefix));
+        std::fs::remove_file(prefix.join("drive_c/windows/syswow64/ntdll.dll")).expect("remove i386 fixture");
+        assert!(!steam_prefix_all_arch_ready(&prefix));
+        let _ = std::fs::remove_dir_all(prefix);
+    }
+
+    #[test]
+    fn handoff_endpoint_rejects_callbacks_without_active_install() {
+        STEAM_INSTALLING.store(false, Ordering::SeqCst);
+        reset_install_handoff_state();
+        let (status, response) = accept_install_handoff();
+
+        assert_eq!(status, 409);
+        assert_eq!(response.get("reason").and_then(Value::as_str), Some("no-install-active"));
+    }
+
+    #[test]
+    fn steam_installer_gate_requires_large_pe_payload() {
+        let fixture = test_prefix("installer-gate.exe");
+        let mut payload = vec![0u8; 1_000_001];
+        payload[..2].copy_from_slice(b"MZ");
+        std::fs::write(&fixture, &payload).expect("write installer fixture");
+        assert!(steam_installer_valid(&fixture));
+
+        payload[..2].copy_from_slice(b"NO");
+        std::fs::write(&fixture, &payload).expect("replace installer fixture");
+        assert!(!steam_installer_valid(&fixture));
+        let _ = std::fs::remove_file(fixture);
+    }
 }
diff --git a/app/src/renderer/components/SetupWizard.vue b/app/src/renderer/components/SetupWizard.vue
index 423d39f65..5cacd6310 100644
--- a/app/src/renderer/components/SetupWizard.vue
+++ b/app/src/renderer/components/SetupWizard.vue
@@ -132,7 +132,7 @@ async function startInstall() {
 
 async function checkSteam() {
   const s = await api<{ installed: boolean; running: boolean }>("GET", "/steam/status");
-  if (s?.installed || s?.running) {
+  if (s?.installed) {
     steamInstalled.value = true;
   }
   installingSteam.value = true;
@@ -147,8 +147,16 @@ async function installSteam() {
     return;
   }
   const poll = setInterval(async () => {
-    const s = await api<{ installed: boolean; running: boolean }>("GET", "/steam/status");
-    if (s?.installed || s?.running) {
+    const s = await api<{
+      installed: boolean;
+      installing: boolean;
+      install_handoff?: { accepted?: number; last_error?: string | null };
+    }>("GET", "/steam/status");
+    if (s?.install_handoff?.last_error) {
+      clearInterval(poll);
+      steamInstalling.value = false;
+      toast.show(s.install_handoff.last_error, "error");
+    } else if (s?.installed) {
       clearInterval(poll);
       steamInstalled.value = true;
       steamInstalling.value = false;
@@ -157,7 +165,7 @@ async function installSteam() {
   setTimeout(() => {
     clearInterval(poll);
     steamInstalling.value = false;
-  }, 300000);
+  }, 2700000);
 }
 
 async function finish() {
diff --git a/scripts/install-metalsharp-wine-runtime.sh b/scripts/install-metalsharp-wine-runtime.sh
index fa4ea459d..7bd9f77e1 100755
--- a/scripts/install-metalsharp-wine-runtime.sh
+++ b/scripts/install-metalsharp-wine-runtime.sh
@@ -222,6 +222,11 @@ validate_archive_layout() {
     "$PACKAGE_ROOT/graphics/vkd3d-proton/x86_64/d3d12.dll" \
     "$PACKAGE_ROOT/graphics/opengl-metal/metalsharp-opengl.dylib" \
     "$PACKAGE_ROOT/graphics/moltenvk/libMoltenVK.dylib" \
+    "$PACKAGE_ROOT/providers/xtajit64-arm64ec-known-good.dll" \
+    "$PACKAGE_ROOT/providers/xtajit-arm64-known-good.dll" \
+    "$PACKAGE_ROOT/scripts/stage-runtime-providers.sh" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/wow64/aarch64-windows/wow64.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/wow64win/aarch64-windows/wow64win.dll" \
     "$PACKAGE_ROOT/dependencies" \
     "$PACKAGE_ROOT/providers" \
     "$PACKAGE_ROOT/source/LICENSE-METALSHARP-POLYFORM-NONCOMMERCIAL.md" \

From 15d3af6af0b5261bb616a9c4b840719aaeb407e6 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 15:58:05 -0600
Subject: [PATCH 03/14] verify Homebrew for the D3DMetal route

---
 AGENTS.md                                   |  9 ++++
 app/src-rust/src/d3dmetal_gptk.rs           | 11 +++--
 app/src-rust/src/setup.rs                   | 20 ++++++++-
 app/src/main/index.ts                       | 50 ++++++++++++++++-----
 app/src/renderer/api-types.ts               | 11 ++++-
 app/src/renderer/components/SetupWizard.vue |  7 ++-
 6 files changed, 88 insertions(+), 20 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 8b8b5eb9d..0269612f3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,15 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   `.metalsharp-steam-install-complete`. Steam is not reported installed before
   that marker exists. All install and handoff launches keep every FEX TSO mode
   disabled.
+- Phase 3 makes a functioning Homebrew installation a hard setup gate. Both
+  Electron and the Rust backend require `brew --version` to succeed; file
+  presence alone is not acceptance. The Terminal installer downloads the
+  official Homebrew installer with curl, validates it with `bash -n`, runs it,
+  then verifies the installed brew before reporting success.
+- GPTK/D3DMetal remains separate from the complete MetalSharp Wine runtime and
+  is owned by Homebrew. Saving a D3DMetal bottle invokes the existing
+  `gcenx/wine/game-porting-toolkit` tap/trust/cask route; do not stage a private
+  GPTK copy into the main runtime.
 
 ## What This Project Is
 
diff --git a/app/src-rust/src/d3dmetal_gptk.rs b/app/src-rust/src/d3dmetal_gptk.rs
index 506f30ce2..74c7d3668 100644
--- a/app/src-rust/src/d3dmetal_gptk.rs
+++ b/app/src-rust/src/d3dmetal_gptk.rs
@@ -1547,7 +1547,9 @@ fn gptk_dyld_path() -> String {
 
 fn find_brew() -> Result<PathBuf, String> {
     for path in [PathBuf::from("/opt/homebrew/bin/brew"), PathBuf::from("/usr/local/bin/brew")] {
-        if path.is_file() {
+        if path.is_file()
+            && Command::new(&path).arg("--version").output().map(|output| output.status.success()).unwrap_or(false)
+        {
             return Ok(path);
         }
     }
@@ -1555,10 +1557,13 @@ fn find_brew() -> Result<PathBuf, String> {
     if output.status.success() {
         let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
         if !path.is_empty() {
-            return Ok(PathBuf::from(path));
+            let path = PathBuf::from(path);
+            if Command::new(&path).arg("--version").output().map(|result| result.status.success()).unwrap_or(false) {
+                return Ok(path);
+            }
         }
     }
-    Err("Homebrew not found".to_string())
+    Err("Homebrew was not found or failed its brew --version verification".to_string())
 }
 
 fn command_text(output: &std::process::Output) -> String {
diff --git a/app/src-rust/src/setup.rs b/app/src-rust/src/setup.rs
index 1cf2b5218..bf735a304 100644
--- a/app/src-rust/src/setup.rs
+++ b/app/src-rust/src/setup.rs
@@ -128,7 +128,7 @@ pub fn dependencies() -> Value {
     let xcode_cli = check_command("clang") || check_command("xcodebuild");
     let steam = check_path(&home.join("Library/Application Support/Steam/Steam.app/Contents/MacOS/steam_osx"))
         || check_path(&PathBuf::from("/Applications/Steam.app/Contents/MacOS/steam_osx"));
-    let homebrew = check_command("brew");
+    let homebrew = homebrew_ready();
     let moltenvk = check_path(&PathBuf::from("/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json"));
     let metalsharp_wine = crate::installer::complete_runtime_current_for_home(&home);
     let host_runtime = host_runtime_installed(&home);
@@ -156,7 +156,7 @@ pub fn dependencies() -> Value {
             {
                 "id": "homebrew",
                 "name": "Homebrew",
-                "desc": "Package manager — required to install other dependencies",
+                "desc": "Required package manager and owner of the separate GPTK/D3DMetal runtime",
                 "installed": homebrew,
                 "required": true,
                 "installCmd": "/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"",
@@ -1966,6 +1966,22 @@ fn check_command(cmd: &str) -> bool {
     mac_cmd("which").arg(cmd).output().map(|o| o.status.success()).unwrap_or(false)
 }
 
+fn homebrew_ready() -> bool {
+    ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"]
+        .iter()
+        .any(|brew| Command::new(brew).arg("--version").output().map(|o| o.status.success()).unwrap_or(false))
+        || mac_cmd("which")
+            .arg("brew")
+            .output()
+            .ok()
+            .filter(|o| o.status.success())
+            .and_then(|o| String::from_utf8(o.stdout).ok())
+            .map(|brew| {
+                Command::new(brew.trim()).arg("--version").output().map(|o| o.status.success()).unwrap_or(false)
+            })
+            .unwrap_or(false)
+}
+
 fn check_path(path: &PathBuf) -> bool {
     path.exists()
 }
diff --git a/app/src/main/index.ts b/app/src/main/index.ts
index 10a566218..c08e2b9d2 100644
--- a/app/src/main/index.ts
+++ b/app/src/main/index.ts
@@ -29,7 +29,12 @@ function ensureShellPath() {
   return shellPath;
 }
 
-function findHomebrew(): string | null {
+type HomebrewInstallation = {
+  path: string;
+  version: string;
+};
+
+function findHomebrew(): HomebrewInstallation | null {
   const prefix = process.env.HOMEBREW_PREFIX?.trim();
   const candidates = [
     prefix ? path.join(prefix, "bin", "brew") : "",
@@ -44,11 +49,14 @@ function findHomebrew(): string | null {
   for (const candidate of new Set(candidates.filter(Boolean))) {
     try {
       fs.accessSync(candidate, fs.constants.X_OK);
-      execFileSync(candidate, ["--version"], {
+      const version = execFileSync(candidate, ["--version"], {
         env: { ...process.env, PATH: ensureShellPath() },
-        stdio: "ignore",
-      });
-      return candidate;
+        encoding: "utf8",
+        timeout: 10000,
+      })
+        .split("\n")[0]
+        .trim();
+      if (version) return { path: candidate, version };
     } catch {
       // continue to next candidate
     }
@@ -1025,17 +1033,35 @@ function registerIpc() {
       return { ok: false, error: "Homebrew setup is only available on macOS." };
     }
 
-    const brewPath = findHomebrew();
-    if (brewPath) {
-      return { ok: true, installed: true, path: brewPath, message: "Homebrew is already installed" };
+    const homebrew = findHomebrew();
+    if (homebrew) {
+      return { ok: true, installed: true, ...homebrew, message: "Homebrew is already installed and verified" };
     }
 
     return new Promise((resolve) => {
       const commandPath = path.join(app.getPath("temp"), `metalsharp-homebrew-${process.pid}-${Date.now()}.command`);
       const command = [
         "#!/bin/bash",
-        `trap 'rm -f "${commandPath.replace(/'/g, "'\\\\''")}"' EXIT`,
-        '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+        "set -euo pipefail",
+        `COMMAND_PATH='${commandPath.replace(/'/g, "'\\\\''")}'`,
+        'INSTALL_SCRIPT="$(/usr/bin/mktemp -t metalsharp-homebrew-install)"',
+        "cleanup() { /bin/rm -f \"$COMMAND_PATH\" \"$INSTALL_SCRIPT\"; }",
+        "trap cleanup EXIT",
+        'echo "MetalSharp: downloading the official Homebrew installer..."',
+        '/usr/bin/curl --fail --show-error --silent --location https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh --output "$INSTALL_SCRIPT"',
+        '/bin/bash -n "$INSTALL_SCRIPT"',
+        '/bin/bash "$INSTALL_SCRIPT"',
+        'BREW="${HOMEBREW_PREFIX:-}/bin/brew"',
+        'if [[ ! -x "$BREW" ]]; then',
+        '  for CANDIDATE in /opt/homebrew/bin/brew /usr/local/bin/brew; do',
+        '    if [[ -x "$CANDIDATE" ]]; then BREW="$CANDIDATE"; break; fi',
+        "  done",
+        "fi",
+        'if [[ ! -x "$BREW" ]]; then echo "MetalSharp: Homebrew installed but brew could not be found." >&2; exit 1; fi',
+        '"$BREW" --version',
+        'echo "MetalSharp: Homebrew installation verified. Return to MetalSharp and click Continue."',
+        'printf "\\nPress Return to close this window..."',
+        "read -r _",
         "",
       ].join("\n");
 
@@ -1066,8 +1092,8 @@ function registerIpc() {
   });
 
   ipcMain.handle("app:homebrew-status", () => {
-    const brewPath = process.platform === "darwin" ? findHomebrew() : null;
-    return { installed: brewPath !== null, path: brewPath ?? undefined };
+    const homebrew = process.platform === "darwin" ? findHomebrew() : null;
+    return { installed: homebrew !== null, ...homebrew };
   });
 
   ipcMain.handle("app:open-in-finder", async (_e, inputPath: string) => {
diff --git a/app/src/renderer/api-types.ts b/app/src/renderer/api-types.ts
index acaf5eeac..90b80c411 100644
--- a/app/src/renderer/api-types.ts
+++ b/app/src/renderer/api-types.ts
@@ -209,8 +209,15 @@ type MetalsharpAPI = {
   }>;
   ejectDmg: () => Promise<void>;
   installDeps: (command: string) => Promise<{ ok: boolean; error?: string }>;
-  installHomebrew: () => Promise<{ ok: boolean; installed?: boolean; path?: string; message?: string; error?: string }>;
-  homebrewStatus: () => Promise<{ installed: boolean; path?: string }>;
+  installHomebrew: () => Promise<{
+    ok: boolean;
+    installed?: boolean;
+    path?: string;
+    version?: string;
+    message?: string;
+    error?: string;
+  }>;
+  homebrewStatus: () => Promise<{ installed: boolean; path?: string; version?: string }>;
   openInFinder: (path: string) => Promise<void>;
   openLogsFolder: () => Promise<{ ok: boolean; path?: string; error?: string }>;
   openMetalsharpFolder: () => Promise<{ ok: boolean; path?: string; error?: string }>;
diff --git a/app/src/renderer/components/SetupWizard.vue b/app/src/renderer/components/SetupWizard.vue
index 5cacd6310..ec0febf28 100644
--- a/app/src/renderer/components/SetupWizard.vue
+++ b/app/src/renderer/components/SetupWizard.vue
@@ -24,6 +24,7 @@ const installingSteam = ref(false);
 const brewChecking = ref(true);
 const brewInstalled = ref(false);
 const brewInstalling = ref(false);
+const brewVersion = ref("");
 
 const steps = ["Welcome", "Homebrew", "Runtime", "VC++", "Done"];
 
@@ -37,12 +38,14 @@ async function checkBrew() {
   const localStatus = await getAPI().homebrewStatus();
   if (localStatus?.installed) {
     brewInstalled.value = true;
+    brewVersion.value = localStatus.version ?? "Homebrew verified";
     brewChecking.value = false;
     return;
   }
   const deps = await api<{ dependencies: { id: string; installed: boolean }[] }>("GET", "/setup/dependencies");
   const brewDep = deps?.dependencies?.find((d) => d.id === "homebrew");
   brewInstalled.value = brewDep?.installed ?? false;
+  brewVersion.value = brewInstalled.value ? "Homebrew verified" : "";
   brewChecking.value = false;
 }
 
@@ -56,6 +59,7 @@ async function installHomebrew() {
   }
   if (result.installed) {
     brewInstalled.value = true;
+    brewVersion.value = result.version ?? "Homebrew verified";
     brewInstalling.value = false;
     toast.show("Homebrew is already installed", "success");
     return;
@@ -293,7 +297,7 @@ async function installVcppX86() {
       <div v-if="step === 1" class="setup-body">
         <div class="setup-section-header">
           <h1>Install Homebrew</h1>
-          <p>MetalSharp uses Homebrew for setup tools such as zstd and Rosetta checks. GPTK/D3DMetal is optional and is only installed later when you save a game as a D3DMetal bottle.</p>
+          <p>Homebrew is required by MetalSharp. It supplies setup tools such as zstd and is the trusted owner of the separate GPTK/D3DMetal runtime. GPTK itself is installed through Homebrew only when you save a game as a D3DMetal bottle.</p>
         </div>
 
         <div class="setup-brew-step">
@@ -302,6 +306,7 @@ async function installVcppX86() {
             2. Follow the prompts in Terminal to install Homebrew<br />
             3. When finished, click <strong>Continue</strong>
           </p>
+          <p v-if="brewInstalled" class="setup-brew-verified">✓ {{ brewVersion }}</p>
           <div class="setup-actions">
             <button class="btn btn-secondary" @click="step = 0">Back</button>
             <button class="btn btn-primary" :disabled="brewInstalling" @click="installHomebrew">

From db13ab7fb2e248fa626ee2e1d6db0cbdc19b0233 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 16:08:49 -0600
Subject: [PATCH 04/14] route redistributables through complete Wine runtime

---
 AGENTS.md                                   |  10 ++
 app/src-rust/src/bottles.rs                 | 161 ++++++++++++++------
 app/src-rust/src/main.rs                    |  24 ++-
 app/src-rust/src/steam.rs                   |   2 +-
 app/src/renderer/components/SetupWizard.vue |   6 +-
 5 files changed, 148 insertions(+), 55 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0269612f3..b592625fb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,6 +41,16 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   is owned by Homebrew. Saving a D3DMetal bottle invokes the existing
   `gcenx/wine/game-porting-toolkit` tap/trust/cask route; do not stage a private
   GPTK copy into the main runtime.
+- Phase 4 runs the interactive VC++ 2015-2022 x64 and x86 installers only
+  through `runtime/wine/bin/metalsharp-wine` and only after both the canonical
+  complete-runtime gate and the Steam all-architecture prefix gate pass. Both
+  installer commands pin `WINEBUILDDIR`, the Steam prefix, and all FEX TSO
+  modes off; they may wait up to 45 minutes for user interaction.
+- Redistributables download from Microsoft's current aka.ms endpoints using
+  `/usr/bin/curl`, require a valid PE bootstrap and architecture-appropriate
+  payload size, and verify x64 DLLs in `system32` or x86 DLLs in `syswow64`.
+  Microsoft's x64 redistributable intentionally uses an i386 PE bootstrap, so
+  do not misclassify its bootstrap machine as the installed payload target.
 
 ## What This Project Is
 
diff --git a/app/src-rust/src/bottles.rs b/app/src-rust/src/bottles.rs
index e72955b82..7560d020a 100644
--- a/app/src-rust/src/bottles.rs
+++ b/app/src-rust/src/bottles.rs
@@ -3,7 +3,7 @@ use serde_json::{json, Value};
 use std::collections::{hash_map::DefaultHasher, HashMap, HashSet};
 use std::fs::{self, OpenOptions};
 use std::hash::{Hash, Hasher};
-use std::io::Write;
+use std::io::{Read, Seek, SeekFrom, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Child, Command, Stdio};
 use std::sync::Mutex;
@@ -18,18 +18,43 @@ const VCPP_X64_URL: &str = "https://aka.ms/vs/17/release/vc_redist.x64.exe";
 const VCPP_X86_URL: &str = "https://aka.ms/vs/17/release/vc_redist.x86.exe";
 const VCPP_X64_FILENAME: &str = "vc_redist.x64.exe";
 const VCPP_X86_FILENAME: &str = "vc_redist.x86.exe";
-const VCPP_MIN_SIZE: u64 = 1_000_000;
+const VCPP_X64_MIN_SIZE: u64 = 15_000_000;
+const VCPP_X86_MIN_SIZE: u64 = 5_000_000;
 
 fn vcpp_cached_dir() -> Option<PathBuf> {
     Some(crate::platform::metalsharp_home_dir().join("runtime").join("redist").join("vcredist"))
 }
 
-fn vcpp_downloaded(path: &Path) -> bool {
-    path.is_file() && fs::metadata(path).map(|m| m.len() > VCPP_MIN_SIZE).unwrap_or(false)
+fn vcpp_downloaded(path: &Path, arch: &str) -> bool {
+    let minimum_size = match arch {
+        // Microsoft's x64 redistributable currently uses an i386 PE bootstrap
+        // around the larger x64 payload. Size and PE validity distinguish it
+        // from the smaller x86 package; the bootstrap machine does not.
+        "x64" => VCPP_X64_MIN_SIZE,
+        "x86" => VCPP_X86_MIN_SIZE,
+        _ => return false,
+    };
+    if !path.is_file() || !fs::metadata(path).map(|m| m.len() > minimum_size).unwrap_or(false) {
+        return false;
+    }
+    let mut file = match fs::File::open(path) {
+        Ok(file) => file,
+        Err(_) => return false,
+    };
+    let mut dos = [0u8; 64];
+    if file.read_exact(&mut dos).is_err() || &dos[..2] != b"MZ" {
+        return false;
+    }
+    let pe_offset = u32::from_le_bytes([dos[0x3c], dos[0x3d], dos[0x3e], dos[0x3f]]) as u64;
+    let mut pe = [0u8; 6];
+    file.seek(SeekFrom::Start(pe_offset)).is_ok()
+        && file.read_exact(&mut pe).is_ok()
+        && &pe[..4] == b"PE\0\0"
+        && matches!(u16::from_le_bytes([pe[4], pe[5]]), 0x014c | 0x8664)
 }
 
-fn vcpp_download(url: &str, dest: &Path) -> Result<(), String> {
-    if vcpp_downloaded(dest) {
+fn vcpp_download(url: &str, dest: &Path, arch: &str) -> Result<(), String> {
+    if vcpp_downloaded(dest, arch) {
         return Ok(());
     }
     let tmp = dest.with_extension("download");
@@ -37,7 +62,7 @@ fn vcpp_download(url: &str, dest: &Path) -> Result<(), String> {
     if let Some(parent) = dest.parent() {
         let _ = fs::create_dir_all(parent);
     }
-    let output = Command::new("curl")
+    let output = Command::new("/usr/bin/curl")
         .args(["--fail", "--location", "--silent", "--show-error", "--retry", "3", "-o"])
         .arg(&tmp)
         .arg(url)
@@ -47,9 +72,9 @@ fn vcpp_download(url: &str, dest: &Path) -> Result<(), String> {
         let _ = fs::remove_file(&tmp);
         return Err(format!("curl download failed for {}", url));
     }
-    if !vcpp_downloaded(&tmp) {
+    if !vcpp_downloaded(&tmp, arch) {
         let _ = fs::remove_file(&tmp);
-        return Err(format!("downloaded file too small or missing: {}", dest.display()));
+        return Err(format!("downloaded {} redistributable is not a valid PE bootstrap: {}", arch, dest.display()));
     }
     let _ = fs::rename(&tmp, dest);
     Ok(())
@@ -59,7 +84,7 @@ fn vcpp_both_cached() -> Option<(PathBuf, PathBuf)> {
     let dir = vcpp_cached_dir()?;
     let x64 = dir.join(VCPP_X64_FILENAME);
     let x86 = dir.join(VCPP_X86_FILENAME);
-    if vcpp_downloaded(&x64) && vcpp_downloaded(&x86) {
+    if vcpp_downloaded(&x64, "x64") && vcpp_downloaded(&x86, "x86") {
         Some((x64, x86))
     } else {
         None
@@ -71,13 +96,13 @@ fn vcpp_ensure_downloaded() -> Result<(PathBuf, PathBuf), String> {
     let _ = fs::create_dir_all(&dir);
     let x64 = dir.join(VCPP_X64_FILENAME);
     let x86 = dir.join(VCPP_X86_FILENAME);
-    if !vcpp_downloaded(&x64) {
+    if !vcpp_downloaded(&x64, "x64") {
         eprintln!("vcredist: downloading VC++ 2015-2022 x64 from Microsoft ...");
-        vcpp_download(VCPP_X64_URL, &x64)?;
+        vcpp_download(VCPP_X64_URL, &x64, "x64")?;
     }
-    if !vcpp_downloaded(&x86) {
+    if !vcpp_downloaded(&x86, "x86") {
         eprintln!("vcredist: downloading VC++ 2015-2022 x86 from Microsoft ...");
-        vcpp_download(VCPP_X86_URL, &x86)?;
+        vcpp_download(VCPP_X86_URL, &x86, "x86")?;
     }
     Ok((x64, x86))
 }
@@ -105,33 +130,25 @@ fn vcpp_install_into_prefix(prefix: &Path) -> Result<(), String> {
     }
     let prefix_str = prefix.to_string_lossy().to_string();
     eprintln!("vcredist: installing VC++ 2015-2022 x64 into {} ...", prefix.display());
-    let x64_status = Command::new(&wine)
-        .arg(&x64)
-        .arg("/install")
-        .env("WINEPREFIX", &prefix_str)
-        .env("WINEDEBUG", "-all")
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null())
-        .status()
-        .map_err(|e| format!("wine x64 failed: {}", e))?;
+    let mut x64_command = Command::new(&wine);
+    x64_command.arg(&x64).arg("/install").stdout(Stdio::null()).stderr(Stdio::null());
+    configure_metalsharp_vcpp_env(&mut x64_command, &ms_root, &prefix_str);
+    let x64_status = x64_command.status().map_err(|e| format!("wine x64 failed: {}", e))?;
     if !x64_status.success() {
         return Err("VC++ x64 installer failed".into());
     }
-    let _ = Command::new(ms_root.join("bin").join("wineserver")).env("WINEPREFIX", &prefix_str).arg("-w").status();
+    let _ =
+        Command::new(crate::platform::runtime_wineserver(&ms_root)).env("WINEPREFIX", &prefix_str).arg("-w").status();
     eprintln!("vcredist: installing VC++ 2015-2022 x86 into {} ...", prefix.display());
-    let x86_status = Command::new(&wine)
-        .arg(&x86)
-        .arg("/install")
-        .env("WINEPREFIX", &prefix_str)
-        .env("WINEDEBUG", "-all")
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null())
-        .status()
-        .map_err(|e| format!("wine x86 failed: {}", e))?;
+    let mut x86_command = Command::new(&wine);
+    x86_command.arg(&x86).arg("/install").stdout(Stdio::null()).stderr(Stdio::null());
+    configure_metalsharp_vcpp_env(&mut x86_command, &ms_root, &prefix_str);
+    let x86_status = x86_command.status().map_err(|e| format!("wine x86 failed: {}", e))?;
     if !x86_status.success() {
         return Err("VC++ x86 installer failed".into());
     }
-    let _ = Command::new(ms_root.join("bin").join("wineserver")).env("WINEPREFIX", &prefix_str).arg("-w").status();
+    let _ =
+        Command::new(crate::platform::runtime_wineserver(&ms_root)).env("WINEPREFIX", &prefix_str).arg("-w").status();
     if vcpp_prefix_has_runtime(prefix) {
         eprintln!("vcredist: VC++ 2015-2022 verified in {}", prefix.display());
         Ok(())
@@ -171,22 +188,11 @@ fn run_interactive_vcpp_installer(prefix: &Path, installer: &Path, arch: &str) -
     }
     let prefix_str = prefix.to_string_lossy().to_string();
     eprintln!("vcredist: launching interactive VC++ 2015-2022 {} installer into {} ...", arch, prefix.display());
-    let mut cmd = Command::new(&wine);
-    cmd.arg("start")
-        .arg("/wait")
-        .arg("/unix")
-        .arg(installer)
-        .args(vcpp_setup_install_args())
-        .env("WINEPREFIX", &prefix_str)
-        .env("WINEARCH", "win64")
-        .env("WINEDEBUG", "-all")
-        .stdin(Stdio::inherit())
-        .stdout(Stdio::inherit())
-        .stderr(Stdio::inherit());
+    let mut cmd = vcpp_installer_command(&wine, &ms_root, &prefix_str, installer);
+    cmd.stdin(Stdio::inherit()).stdout(Stdio::inherit()).stderr(Stdio::inherit());
     if let Some(parent) = installer.parent() {
         cmd.current_dir(parent);
     }
-    crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
     let status = cmd.status().map_err(|e| format!("wine {} failed: {}", arch, e))?;
     if vcpp_installer_status_ok(status.code()) {
         Ok(())
@@ -195,6 +201,25 @@ fn run_interactive_vcpp_installer(prefix: &Path, installer: &Path, arch: &str) -
     }
 }
 
+fn vcpp_installer_command(wine: &Path, ms_root: &Path, prefix: &str, installer: &Path) -> Command {
+    let mut cmd = Command::new(wine);
+    cmd.arg("start").arg("/wait").arg("/unix").arg(installer).args(vcpp_setup_install_args());
+    configure_metalsharp_vcpp_env(&mut cmd, ms_root, prefix);
+    cmd
+}
+
+fn configure_metalsharp_vcpp_env(cmd: &mut Command, ms_root: &Path, prefix: &str) {
+    cmd.env("WINEPREFIX", prefix)
+        .env("WINEARCH", "win64")
+        .env("WINEBUILDDIR", ms_root.join("build-ec"))
+        .env("FEX_TSOENABLED", "0")
+        .env("FEX_VECTORTSOENABLED", "0")
+        .env("FEX_MEMCPYSETTSOENABLED", "0")
+        .env("WINEDEBUG", "-all")
+        .env("WINEDEBUGGER", "none");
+    crate::platform::set_runtime_library_env(cmd, ms_root);
+}
+
 fn vcpp_setup_install_args() -> [&'static str; 1] {
     ["/install"]
 }
@@ -7383,6 +7408,48 @@ mod tests {
         assert_eq!(vcpp_setup_install_args(), ["/install"]);
     }
 
+    #[test]
+    fn setup_vcpp_download_gate_accepts_microsoft_x86_bootstrap_for_x64_payload() {
+        let dir = test_dir("vcpp-pe-gate");
+        fs::create_dir_all(&dir).expect("create fixture dir");
+        let installer = dir.join("vc_redist.exe");
+        let mut x64 = vec![0u8; (VCPP_X64_MIN_SIZE + 1) as usize];
+        x64[..0x200].copy_from_slice(&test_pe(0x014c, 0x10b));
+        fs::write(&installer, x64).expect("write x64 fixture");
+        assert!(vcpp_downloaded(&installer, "x64"));
+
+        let mut x86 = vec![0u8; (VCPP_X86_MIN_SIZE + 1) as usize];
+        x86[..0x200].copy_from_slice(&test_pe(0x014c, 0x10b));
+        fs::write(&installer, x86).expect("write x86 fixture");
+        assert!(vcpp_downloaded(&installer, "x86"));
+        assert!(!vcpp_downloaded(&installer, "x64"));
+        let _ = fs::remove_dir_all(dir);
+    }
+
+    #[test]
+    fn setup_vcpp_command_uses_complete_runtime_without_tso() {
+        let wine = PathBuf::from("/runtime/wine/bin/metalsharp-wine");
+        let root = PathBuf::from("/runtime/wine");
+        let installer = PathBuf::from("/runtime/redist/vc_redist.x86.exe");
+        let cmd = vcpp_installer_command(&wine, &root, "/prefix-steam", &installer);
+        assert_eq!(cmd.get_program(), wine.as_os_str());
+        assert_eq!(
+            cmd.get_args().map(|arg| arg.to_string_lossy().to_string()).collect::<Vec<_>>(),
+            vec!["start", "/wait", "/unix", "/runtime/redist/vc_redist.x86.exe", "/install"]
+        );
+        let env = cmd
+            .get_envs()
+            .filter_map(|(key, value)| {
+                value.map(|value| (key.to_string_lossy().to_string(), value.to_string_lossy().to_string()))
+            })
+            .collect::<HashMap<_, _>>();
+        assert_eq!(env.get("WINEPREFIX").map(String::as_str), Some("/prefix-steam"));
+        assert_eq!(env.get("WINEBUILDDIR").map(String::as_str), Some("/runtime/wine/build-ec"));
+        assert_eq!(env.get("FEX_TSOENABLED").map(String::as_str), Some("0"));
+        assert_eq!(env.get("FEX_VECTORTSOENABLED").map(String::as_str), Some("0"));
+        assert_eq!(env.get("FEX_MEMCPYSETTSOENABLED").map(String::as_str), Some("0"));
+    }
+
     #[test]
     fn setup_vcpp_accepts_reboot_required_status() {
         assert!(vcpp_installer_status_ok(Some(0)));
diff --git a/app/src-rust/src/main.rs b/app/src-rust/src/main.rs
index eaadf97ff..541edf3af 100644
--- a/app/src-rust/src/main.rs
+++ b/app/src-rust/src/main.rs
@@ -254,8 +254,16 @@ fn route(req: &mut tiny_http::Request) -> RouteResponse {
         (Method::Post, "/setup/install-vcpp-x64") => {
             let home = dirs::home_dir().unwrap_or_default();
             let prefix = crate::platform::metalsharp_home_dir_for(&home).join("prefix-steam");
-            if !prefix.join("drive_c/windows/system32").exists() {
-                resp(400, json!({"ok": false, "error": "Wine prefix not ready — install runtime and Steam first"}))
+            if !crate::installer::complete_runtime_current_for_home(&home) {
+                resp(
+                    400,
+                    json!({"ok": false, "error": "Complete MetalSharp Wine runtime not ready — install or repair the runtime first"}),
+                )
+            } else if !steam::steam_prefix_all_arch_ready(&prefix) {
+                resp(
+                    400,
+                    json!({"ok": false, "error": "All-architecture Steam prefix not ready — complete Steam installation first"}),
+                )
             } else {
                 match bottles::vcpp_ensure_and_install_x64(&prefix) {
                     Ok(()) => resp(200, json!({"ok": true})),
@@ -266,8 +274,16 @@ fn route(req: &mut tiny_http::Request) -> RouteResponse {
         (Method::Post, "/setup/install-vcpp-x86") => {
             let home = dirs::home_dir().unwrap_or_default();
             let prefix = crate::platform::metalsharp_home_dir_for(&home).join("prefix-steam");
-            if !prefix.join("drive_c/windows/system32").exists() {
-                resp(400, json!({"ok": false, "error": "Wine prefix not ready — install runtime and Steam first"}))
+            if !crate::installer::complete_runtime_current_for_home(&home) {
+                resp(
+                    400,
+                    json!({"ok": false, "error": "Complete MetalSharp Wine runtime not ready — install or repair the runtime first"}),
+                )
+            } else if !steam::steam_prefix_all_arch_ready(&prefix) {
+                resp(
+                    400,
+                    json!({"ok": false, "error": "All-architecture Steam prefix not ready — complete Steam installation first"}),
+                )
             } else {
                 match bottles::vcpp_ensure_and_install_x86(&prefix) {
                     Ok(()) => resp(200, json!({"ok": true})),
diff --git a/app/src-rust/src/steam.rs b/app/src-rust/src/steam.rs
index 6a14d7240..92d87effa 100644
--- a/app/src-rust/src/steam.rs
+++ b/app/src-rust/src/steam.rs
@@ -1590,7 +1590,7 @@ fn run_runtime_provider_stage(prefix: &Path, verify_only: bool) -> Result<(), Bo
     Ok(())
 }
 
-fn steam_prefix_all_arch_ready(prefix: &Path) -> bool {
+pub(crate) fn steam_prefix_all_arch_ready(prefix: &Path) -> bool {
     [
         "system.reg",
         "user.reg",
diff --git a/app/src/renderer/components/SetupWizard.vue b/app/src/renderer/components/SetupWizard.vue
index ec0febf28..aece087c1 100644
--- a/app/src/renderer/components/SetupWizard.vue
+++ b/app/src/renderer/components/SetupWizard.vue
@@ -211,7 +211,7 @@ async function goToDoneStep() {
 async function installVcppX64() {
   vcppX64Installing.value = true;
   try {
-    const result = await api<{ ok: boolean; error?: string }>("POST", "/setup/install-vcpp-x64");
+    const result = await api<{ ok: boolean; error?: string }>("POST", "/setup/install-vcpp-x64", undefined, 2700000);
     if (result?.ok) {
       vcppX64Done.value = true;
       toast.show("VC++ 2015-2022 x64 installed", "success");
@@ -227,7 +227,7 @@ async function installVcppX64() {
 async function installVcppX86() {
   vcppX86Installing.value = true;
   try {
-    const result = await api<{ ok: boolean; error?: string }>("POST", "/setup/install-vcpp-x86");
+    const result = await api<{ ok: boolean; error?: string }>("POST", "/setup/install-vcpp-x86", undefined, 2700000);
     if (result?.ok) {
       vcppX86Done.value = true;
       toast.show("VC++ 2015-2022 x86 installed", "success");
@@ -362,7 +362,7 @@ async function installVcppX86() {
       <div v-if="step === 3" class="setup-body">
         <div class="setup-section-header">
           <h1>VC++ 2015-2022 Runtimes</h1>
-          <p>Many Windows games depend on the Microsoft Visual C++ Redistributable. Install both x64 and x86 into the standard MetalSharp Wine prefix so Steam games can find the runtime DLLs they need at launch.</p>
+          <p>Many Windows games depend on the Microsoft Visual C++ Redistributable. Install both x64 and x86 through the complete MetalSharp Wine runtime into its accepted all-architecture Steam prefix.</p>
         </div>
 
         <div class="setup-vcpp-section">

From 032b1340e7034aa745a5b4cfe7669e78e220ec70 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 16:14:06 -0600
Subject: [PATCH 05/14] confine Steam wrapper to MetalSharp runtime

---
 AGENTS.md                 |  10 ++++
 app/src-rust/src/steam.rs | 115 ++++++++++++++++++++++++++++++--------
 2 files changed, 102 insertions(+), 23 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b592625fb..e2895d88d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,6 +51,16 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   payload size, and verify x64 DLLs in `system32` or x86 DLLs in `syswow64`.
   Microsoft's x64 redistributable intentionally uses an i386 PE bootstrap, so
   do not misclassify its bootstrap machine as the installed payload target.
+- Phase 5 does not change the Launch Steam endpoint, UI button, executable, or
+  flags. Its wrapper maintenance now prefers the canonical complete-runtime
+  asset at `runtime/integration/steam-webhelper/steamwebhelper.exe`, whose
+  accepted SHA-256 is
+  `f46a1e8c39c850ba22861f63559f13b4f68557acf04a92e6d1b899769b2ea1f9`.
+- Steam updates are repaired before launch only when the wrapper/real-helper
+  pair fails its hash-and-size contract. Wrapper deployment is refused unless
+  the target is exactly the MetalSharp Steam prefix or a MetalSharp-managed
+  bottle prefix; never deploy into CrossOver, another Wine installation, or an
+  arbitrary path.
 
 ## What This Project Is
 
diff --git a/app/src-rust/src/steam.rs b/app/src-rust/src/steam.rs
index 92d87effa..ff5bca331 100644
--- a/app/src-rust/src/steam.rs
+++ b/app/src-rust/src/steam.rs
@@ -298,17 +298,7 @@ fn cef_subdirs(steam_dir: &Path) -> Vec<PathBuf> {
 
 fn ensure_steam_launch_ready(steam_dir: &PathBuf) {
     for cef_dir in cef_subdirs(steam_dir) {
-        let wrapper = cef_dir.join("steamwebhelper.exe");
-        let real = cef_dir.join("steamwebhelper_real.exe");
-
-        let wrapper_size = std::fs::metadata(&wrapper).map(|m| m.len()).unwrap_or(0);
-        let real_size = std::fs::metadata(&real).map(|m| m.len()).unwrap_or(0);
-
-        let wrapper_missing = wrapper_size == 0;
-        let wrapper_overwritten = wrapper_size > STEAMWEBHELPER_WRAPPER_MAX_BYTES;
-        let real_missing_or_bad = real_size > 0 && real_size < STEAMWEBHELPER_WRAPPER_MAX_BYTES;
-
-        if wrapper_missing || wrapper_overwritten || real_missing_or_bad {
+        if !steamwebhelper_pair_ready(&cef_dir) {
             deploy_steamwebhelper_wrapper(steam_dir);
             return;
         }
@@ -775,6 +765,12 @@ pub fn get_wine_steam_installed_games() -> Vec<u32> {
 }
 
 pub fn deploy_steamwebhelper_wrapper(steam_dir: &PathBuf) {
+    let metalsharp_home = crate::platform::metalsharp_home_dir();
+    if !managed_steam_dir(&metalsharp_home, steam_dir) {
+        eprintln!("steam: refusing to deploy CEF wrapper outside MetalSharp prefixes: {}", steam_dir.display());
+        return;
+    }
+
     let wrapper = match find_bundled_steamwebhelper_wrapper() {
         Some(wrapper) => wrapper,
         None => match download_steamwebhelper_wrapper_fallback() {
@@ -796,16 +792,19 @@ pub fn deploy_steamwebhelper_wrapper(steam_dir: &PathBuf) {
 
         let original_size = std::fs::metadata(&original).map(|m| m.len()).unwrap_or(0);
         let real_size = std::fs::metadata(&real).map(|m| m.len()).unwrap_or(0);
+        let original_is_wrapper = steamwebhelper_wrapper_valid(&original);
+        let original_is_real = original_size > STEAMWEBHELPER_WRAPPER_MAX_BYTES;
+        let real_is_real = real_size > STEAMWEBHELPER_WRAPPER_MAX_BYTES;
 
-        if original_size > 0 && original_size <= STEAMWEBHELPER_WRAPPER_MAX_BYTES {
+        if original_is_wrapper && real_is_real {
             if !wrapper_marker.exists() {
                 let _ = std::fs::write(&wrapper_marker, "deployed");
             }
             continue;
         }
 
-        if real_size < STEAMWEBHELPER_WRAPPER_MAX_BYTES {
-            if original_size > STEAMWEBHELPER_WRAPPER_MAX_BYTES {
+        if !real_is_real {
+            if original_is_real {
                 let _ = std::fs::remove_file(&real);
                 let _ = std::fs::rename(&original, &real);
             } else {
@@ -815,16 +814,48 @@ pub fn deploy_steamwebhelper_wrapper(steam_dir: &PathBuf) {
             let _ = std::fs::remove_file(&original);
         }
 
-        if std::fs::copy(&wrapper, &original).is_ok() {
+        if std::fs::copy(&wrapper, &original).is_ok() && steamwebhelper_wrapper_valid(&original) {
             let _ = std::fs::write(&wrapper_marker, "deployed");
         }
     }
 }
 
 fn find_bundled_steamwebhelper_wrapper() -> Option<PathBuf> {
+    let runtime_wrapper = runtime_steamwebhelper_wrapper(&runtime_root());
+    if steamwebhelper_wrapper_valid(&runtime_wrapper) {
+        return Some(runtime_wrapper);
+    }
     find_bundled_steam_asset("steamwebhelper.exe").filter(|path| steamwebhelper_wrapper_valid(path))
 }
 
+fn runtime_steamwebhelper_wrapper(runtime: &Path) -> PathBuf {
+    runtime.join("integration").join("steam-webhelper").join("steamwebhelper.exe")
+}
+
+fn managed_steam_dir(metalsharp_home: &Path, steam_dir: &Path) -> bool {
+    if let (Ok(home_real), Ok(steam_real)) = (metalsharp_home.canonicalize(), steam_dir.canonicalize()) {
+        if !steam_real.starts_with(home_real) {
+            return false;
+        }
+    }
+
+    let primary = metalsharp_home.join("prefix-steam/drive_c/Program Files (x86)/Steam");
+    if steam_dir == primary {
+        return true;
+    }
+
+    let Ok(relative) = steam_dir.strip_prefix(metalsharp_home.join("bottles")) else {
+        return false;
+    };
+    let components = relative.components().collect::<Vec<_>>();
+    components.len() == 5
+        && matches!(components[0], Component::Normal(_))
+        && components[1] == Component::Normal(std::ffi::OsStr::new("prefix"))
+        && components[2] == Component::Normal(std::ffi::OsStr::new("drive_c"))
+        && components[3] == Component::Normal(std::ffi::OsStr::new("Program Files (x86)"))
+        && components[4] == Component::Normal(std::ffi::OsStr::new("Steam"))
+}
+
 fn find_bundled_steam_asset(filename: &str) -> Option<PathBuf> {
     let home = dirs::home_dir()?;
     let cache_dir = crate::platform::metalsharp_home_dir_for(&home).join("cache").join("steam");
@@ -986,14 +1017,13 @@ fn steamwebhelper_wrapper_valid(path: &Path) -> bool {
 
 fn steamwebhelper_wrapper_deployed(steam_dir: &Path) -> bool {
     let cef_dirs = cef_subdirs(steam_dir);
-    !cef_dirs.is_empty()
-        && cef_dirs.iter().any(|cef_dir| {
-            let wrapper = cef_dir.join("steamwebhelper.exe");
-            let real = cef_dir.join("steamwebhelper_real.exe");
-            steamwebhelper_wrapper_valid(&wrapper)
-                && std::fs::metadata(real).map(|metadata| metadata.len()).unwrap_or(0)
-                    > STEAMWEBHELPER_WRAPPER_MAX_BYTES
-        })
+    !cef_dirs.is_empty() && cef_dirs.iter().any(|cef_dir| steamwebhelper_pair_ready(cef_dir))
+}
+
+fn steamwebhelper_pair_ready(cef_dir: &Path) -> bool {
+    steamwebhelper_wrapper_valid(&cef_dir.join("steamwebhelper.exe"))
+        && std::fs::metadata(cef_dir.join("steamwebhelper_real.exe")).map(|metadata| metadata.len()).unwrap_or(0)
+            > STEAMWEBHELPER_WRAPPER_MAX_BYTES
 }
 
 fn file_sha256(path: &Path) -> Option<String> {
@@ -2023,6 +2053,45 @@ mod tests {
         assert_eq!(STEAMWEBHELPER_WRAPPER_SHA256.len(), 64);
     }
 
+    #[test]
+    fn steam_wrapper_prefers_complete_runtime_integration_path() {
+        let runtime = PathBuf::from("/metalsharp/runtime");
+        assert_eq!(
+            runtime_steamwebhelper_wrapper(&runtime),
+            runtime.join("integration/steam-webhelper/steamwebhelper.exe")
+        );
+    }
+
+    #[test]
+    fn wrapper_deployment_is_confined_to_metalsharp_prefixes() {
+        let home = PathBuf::from("/Users/test/.metalsharp");
+        assert!(managed_steam_dir(&home, &home.join("prefix-steam/drive_c/Program Files (x86)/Steam")));
+        assert!(managed_steam_dir(&home, &home.join("bottles/steam_123/prefix/drive_c/Program Files (x86)/Steam")));
+        assert!(!managed_steam_dir(
+            &home,
+            Path::new("/Applications/CrossOver.app/Contents/SharedSupport/CrossOver/Bottles/Steam/drive_c/Program Files (x86)/Steam")
+        ));
+        assert!(!managed_steam_dir(
+            &home,
+            &home.join("bottles/steam_123/not-prefix/drive_c/Program Files (x86)/Steam")
+        ));
+    }
+
+    #[test]
+    fn steam_update_or_corrupt_small_wrapper_requires_redeployment() {
+        let cef = test_prefix("wrapper-update-repair");
+        let _ = std::fs::remove_dir_all(&cef);
+        std::fs::create_dir_all(&cef).expect("create CEF fixture");
+        std::fs::write(cef.join("steamwebhelper_real.exe"), vec![0u8; 100_001]).expect("write real helper");
+
+        std::fs::write(cef.join("steamwebhelper.exe"), b"not-the-pinned-wrapper").expect("write corrupt wrapper");
+        assert!(!steamwebhelper_pair_ready(&cef));
+
+        std::fs::write(cef.join("steamwebhelper.exe"), vec![0u8; 100_001]).expect("simulate Steam overwrite");
+        assert!(!steamwebhelper_pair_ready(&cef));
+        let _ = std::fs::remove_dir_all(cef);
+    }
+
     #[test]
     fn all_arch_prefix_gate_requires_native_wow64_and_i386_surfaces() {
         let prefix = test_prefix("all-arch-gate");

From 82398f477563599518a76743a937b28f20f80d35 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 17:02:15 -0600
Subject: [PATCH 06/14] route bottles through complete graphics runtime

---
 AGENTS.md                                     |  42 +-
 README.md                                     |   6 +-
 app/src-rust/src/bottles.rs                   | 213 +++---
 app/src-rust/src/d3d12_runtime_doctor.rs      |  41 +-
 app/src-rust/src/d3dmetal_gptk.rs             |   2 +-
 app/src-rust/src/diagnostics.rs               |   8 +-
 app/src-rust/src/installer.rs                 |  60 +-
 app/src-rust/src/migrate.rs                   | 109 ++-
 app/src-rust/src/mtsp/default_rules.rs        |   7 +-
 app/src-rust/src/mtsp/engine.rs               | 307 ++++-----
 app/src-rust/src/mtsp/launcher.rs             | 629 ++++++------------
 app/src-rust/src/mtsp/recipe.rs               |  89 ++-
 app/src-rust/src/mtsp/rules.rs                |   2 +-
 app/src-rust/src/mtsp/shader_cache.rs         |  16 +-
 app/src-rust/src/setup.rs                     |  56 +-
 app/src/renderer/components/GameCard.vue      |  12 +-
 app/src/renderer/views/SettingsView.vue       |   2 +-
 app/src/renderer/views/SharpView.vue          |  12 +-
 configs/mtsp-roadmap.md                       |   4 +-
 configs/mtsp-rules.toml                       |  48 +-
 docs/README.md                                |   4 +-
 docs/architecture/dxmt-vulkan-architecture.md | 115 ++--
 docs/architecture/launch-architecture.md      |  20 +-
 docs/architecture/m10-pipeline-map.md         |  14 +-
 docs/architecture/m12-pipeline-map.md         | 205 ++----
 docs/architecture/m9-pipeline-map.md          |   4 +-
 docs/compatibility/GAMES-SUPPORTED.md         |   2 +-
 docs/guides/gptk-guide.md                     |   4 +-
 docs/guides/install-from-source.md            |   4 +-
 .../runtime-bundles-and-steam-routing.md      |  22 +-
 docs/runtime/wine-architecture.md             |   9 +-
 scripts/install-metalsharp-wine-runtime.sh    |  22 +
 32 files changed, 961 insertions(+), 1129 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e2895d88d..7d7182392 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -61,6 +61,31 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   the target is exactly the MetalSharp Steam prefix or a MetalSharp-managed
   bottle prefix; never deploy into CrossOver, another Wine installation, or an
   arbitrary path.
+- Phase 6 makes M12 a vkd3d-proton route, not a DXMT route. Its only PE
+  owners are `lib/vkd3d-proton/x86_64/{d3d12.dll,d3d12core.dll}` and
+  `lib/dxvk/x86_64/dxgi.dll`; the host handoff is Wine Vulkan to the bundled
+  ARM64 MoltenVK library. Never restore winemetal, `dxgi_dxmt`, or
+  `lib/dxmt_m12` to M12.
+- M12 bottle save migrates old component ids to `m12_vkd3d_d3d12`,
+  `m12_vkd3d_d3d12core`, `m12_dxvk_dxgi`, `m12_winevulkan`, and
+  `m12_moltenvk`. Save, prepare, Play, dry-run, runtime doctor, migration, and
+  the complete-runtime gate all validate the same ownership boundaries.
+- M9/M10/M10(32)/M11/M11(32) consume the complete runtime directly, not the
+  retired split-graphics manifest gate. M10/M11 use DXMT's
+  `aarch64-windows` PE lane; M10(32)/M11(32) use its `i386-windows` PE lane;
+  both cross into the native ARM64 `aarch64-unix/winemetal.so`. M9 uses the
+  Wine build's x86_64/i386 D3D9 lanes. D3DMetal remains a separate
+  Homebrew-owned GPTK prefix and must not borrow M12 runtime DLLs.
+- The M12 launch environment contains vkd3d-proton/DXVK cache paths and no
+  DXMT/winemetal variables. All complete-runtime launch adapters continue to
+  pin every FEX TSO mode off.
+- Phase 6 validation: the canonical archive passed the strengthened
+  prepare-only layout gate; extracted M12 PE DLLs identify as x86-64, the Wine
+  Vulkan Unix bridge identifies as ARM64, DXMT's i386 PE lane identifies as
+  i386, its `aarch64-windows` PE lane identifies as x86-64/ARM64EC-compatible,
+  and its Unix winemetal bridge identifies as ARM64. The deterministic Rust
+  suite passes 651/651, strict Clippy passes, all Rust targets build, and the
+  TypeScript/Vite production build passes.
 
 ## What This Project Is
 
@@ -130,7 +155,8 @@ Modern runtime paths use MTSP pipeline ids and bottle profiles. Steam games get
 | `M9` | D3D9 / 32-bit capable DXMT-family route | Nidhogg 2, Undertale, Blasphemous, Dave the Diver |
 | `M10` | D3D10 to Metal | D3D10 apps/games |
 | `M11` | D3D11 to Metal | Rain World, Schedule I, Subnautica BZ |
-| `M12` | D3D12 to Metal through the isolated `dxmt-m12` runtime surface | Peak, Silksong, Elden Ring, D3D12 investigation titles |
+| `M12` | vkd3d-proton D3D12 + DXVK DXGI through Wine Vulkan and ARM64 MoltenVK | Peak, Silksong, Elden Ring, D3D12 investigation titles |
+| `D3DMetal` | Homebrew GPTK/D3DMetal in its own prefix | Explicit GPTK route |
 | `Mono/FNA` | Windows XNA/FNA through native Mono, staged FNA/XNA assemblies, and host shims | Celeste, Terraria |
 
 Internal route ids such as `dxmt`, `wine_bare`, `m32`, `steam`, `macos_steam`, and `m13` stay backend-parseable for legacy records, diagnostics, and fallback behavior, but they are not normal bottle route buttons.
@@ -139,11 +165,15 @@ Internal route ids such as `dxmt`, `wine_bare`, `m32`, `steam`, `macos_steam`, a
 
 - Wine runtime: `~/.metalsharp/runtime/wine/`
 - Wine prefix: `~/.metalsharp/prefix-steam/`
-- DXMT PE DLLs for M9/M10/M11: `~/.metalsharp/runtime/wine/lib/dxmt/x86_64-windows/`
-- DXMT M12 PE DLLs: `~/.metalsharp/runtime/wine/lib/dxmt-m12/x86_64-windows/`
-- DXMT M12 Unix bridge and sidecars: `~/.metalsharp/runtime/wine/lib/dxmt-m12/x86_64-unix/`
-- DXVK i386 DLLs: `~/.metalsharp/runtime/wine/lib/dxvk/i386-windows/`
-- MoltenVK ICD: `~/.metalsharp/runtime/wine/etc/vulkan/icd.d/MoltenVK_icd.json`
+- DXMT M10/M11 PE DLLs: `~/.metalsharp/runtime/wine/build-ec/dxmt-v0.80/aarch64-windows/`
+- DXMT M10(32)/M11(32) PE DLLs: `~/.metalsharp/runtime/wine/build-ec/dxmt-v0.80/i386-windows/`
+- DXMT native host bridge: `~/.metalsharp/runtime/wine/build-ec/dxmt-v0.80/aarch64-unix/winemetal.so`
+- M9 Wine D3D9 DLLs: `~/.metalsharp/runtime/wine/build-ec/dlls/d3d9/{x86_64,i386}-windows/`
+- M12 vkd3d-proton DLLs: `~/.metalsharp/runtime/wine/lib/vkd3d-proton/x86_64/`
+- M12 DXVK DXGI: `~/.metalsharp/runtime/wine/lib/dxvk/x86_64/dxgi.dll`
+- M12 Wine Vulkan bridge: `~/.metalsharp/runtime/wine/build-ec/dlls/winevulkan/`
+- M12 MoltenVK host library: `~/.metalsharp/runtime/wine/build-ec/dlls/win32u/libMoltenVK.dylib`
+- DXVK i386 DLLs: `~/.metalsharp/runtime/wine/lib/dxvk/i386/`
 - DXMT config: `~/.metalsharp/runtime/wine/etc/dxmt.conf`
 - Local redistributables: `~/.metalsharp/runtime/redist/`
 - Runtime bottles: `~/.metalsharp/bottles/<bottle_id>/`
diff --git a/README.md b/README.md
index 12b5862c7..c3ce5bfb3 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@
 
 ---
 
-MetalSharp is an application designed to run Windows Steam and Windows Steam games natively on Apple Silicon macOS. Now includes GOG-Games Support. MetalSharp builds and includes its own custom Wine 11.5 runtime, game launch rules, custom DXMT build, runtime bottles, and repair tooling. 
+MetalSharp is an application designed to run Windows Steam and Windows Steam games natively on Apple Silicon macOS. Now includes GOG-Games Support. MetalSharp includes its custom Wine 11.12 multi-architecture runtime, game launch rules, DXMT, DXVK, vkd3d-proton, MoltenVK, runtime bottles, and repair tooling.
 
 <img width="946" height="646" alt="Screenshot 2026-07-21 at 5 49 12 AM" src="https://github.com/user-attachments/assets/c4aa6d64-ca4b-4ee2-ade4-5f12d511925a" />
 
@@ -39,7 +39,7 @@ This installs the signed MetalSharp release into `/Applications`. For developer
 
 | Route | Engine |
 |---|---|
-| **M12** | D3D12 to Metal (experimental DXMT) |
+| **M12** | D3D12 via vkd3d-proton + DXVK DXGI → Wine Vulkan → ARM64 MoltenVK → Metal |
 | **M11** | D3D11 to Metal (DXMT) |
 | **M11(32)** | D3D11 i386 to Metal (DXMT) |
 | **M10** | D3D10 to Metal (DXMT) |
@@ -59,7 +59,7 @@ This installs the signed MetalSharp release into `/Applications`. For developer
 ## Requirements
 
 - Apple Silicon Mac M1-M5, macOS 14+
-- About 2 GB free space
+- At least 20 GB free space for the complete runtime installation
 - Homebrew (installed by setup wizard)
 
 All other bundled assets, DLLs, and graphics backends are installed during the setup process. GPTK/D3DMetal is the exception: MetalSharp installs and uses Homebrew GPTK only when a D3DMetal bottle is saved.
diff --git a/app/src-rust/src/bottles.rs b/app/src-rust/src/bottles.rs
index 7560d020a..845cda231 100644
--- a/app/src-rust/src/bottles.rs
+++ b/app/src-rust/src/bottles.rs
@@ -645,16 +645,17 @@ pub fn load_bottle(id: &str) -> Result<BottleManifest, Box<dyn std::error::Error
 fn normalize_loaded_runtime_profile_components(manifest: &mut BottleManifest) {
     let should_rebuild = match manifest.runtime_profile {
         RuntimeProfile::M12 => {
-            let has_pr230_shape = M12_RUNTIME_COMPONENT_IDS
+            let has_vkd3d_shape = M12_RUNTIME_COMPONENT_IDS
                 .iter()
                 .all(|id| manifest.installed_components.iter().any(|component| component.id == *id));
             let has_stale_m12_shape = manifest.installed_components.iter().any(|component| {
-                matches!(
-                    component.id.as_str(),
-                    "d3d12" | "d3d11" | "dxgi" | "gpu_vendor_stubs" | "gptk" | "gptk_prefix" | "rosetta"
-                )
+                is_legacy_m12_runtime_component(&component.id)
+                    || matches!(
+                        component.id.as_str(),
+                        "d3d12" | "d3d11" | "dxgi" | "gpu_vendor_stubs" | "gptk" | "gptk_prefix" | "rosetta"
+                    )
             });
-            !has_pr230_shape || has_stale_m12_shape
+            !has_vkd3d_shape || has_stale_m12_shape
         },
         RuntimeProfile::D3DMetal => {
             manifest.installed_components.iter().any(|component| is_m12_runtime_component(&component.id))
@@ -669,23 +670,26 @@ fn normalize_loaded_runtime_profile_components(manifest: &mut BottleManifest) {
 }
 
 const M12_RUNTIME_COMPONENT_IDS: &[&str] =
-    &["m12_d3d12", "m12_d3d11", "m12_d3d10core", "m12_dxgi_dxmt", "m12_dxgi", "m12_winemetal", "m12_gpu_stubs"];
+    &["m12_vkd3d_d3d12", "m12_vkd3d_d3d12core", "m12_dxvk_dxgi", "m12_winevulkan", "m12_moltenvk"];
+
+fn is_legacy_m12_runtime_component(component_id: &str) -> bool {
+    matches!(
+        component_id,
+        "m12_d3d12" | "m12_d3d11" | "m12_d3d10core" | "m12_dxgi_dxmt" | "m12_dxgi" | "m12_winemetal" | "m12_gpu_stubs"
+    )
+}
 
 fn m12_runtime_component_artifacts(component_id: &str) -> Option<&'static [&'static str]> {
     match component_id {
-        "m12_d3d12" => Some(&["x86_64-windows/d3d12.dll"]),
-        "m12_d3d11" => Some(&["x86_64-windows/d3d11.dll"]),
-        "m12_d3d10core" => Some(&["x86_64-windows/d3d10core.dll"]),
-        "m12_dxgi_dxmt" => Some(&["x86_64-windows/dxgi_dxmt.dll"]),
-        "m12_dxgi" => Some(&["x86_64-windows/dxgi.dll"]),
-        "m12_winemetal" => Some(&[
-            "x86_64-windows/winemetal.dll",
-            "x86_64-unix/winemetal.so",
-            "x86_64-unix/libc++.1.dylib",
-            "x86_64-unix/libc++abi.1.dylib",
-            "x86_64-unix/libunwind.1.dylib",
+        "m12_vkd3d_d3d12" => Some(&["lib/vkd3d-proton/x86_64/d3d12.dll"]),
+        "m12_vkd3d_d3d12core" => Some(&["lib/vkd3d-proton/x86_64/d3d12core.dll"]),
+        "m12_dxvk_dxgi" => Some(&["lib/dxvk/x86_64/dxgi.dll"]),
+        "m12_winevulkan" => Some(&[
+            "build-ec/dlls/winevulkan/winevulkan.so",
+            "build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll",
+            "build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll",
         ]),
-        "m12_gpu_stubs" => Some(&["x86_64-windows/nvapi64.dll", "x86_64-windows/nvngx.dll"]),
+        "m12_moltenvk" => Some(&["build-ec/dlls/win32u/libMoltenVK.dylib", "lib/moltenvk/libMoltenVK.dylib"]),
         _ => None,
     }
 }
@@ -697,13 +701,20 @@ fn is_m12_runtime_component(component_id: &str) -> bool {
 fn inspect_m12_runtime_component(component_id: &str) -> Option<ComponentState> {
     let artifacts = m12_runtime_component_artifacts(component_id)?;
     let home = dirs::home_dir()?;
+    let wine_root = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
     let valid_count = artifacts
         .iter()
-        .filter(|artifact| crate::installer::dxmt_m12_runtime_artifact_valid_for_home(&home, artifact))
+        .filter(|artifact| {
+            wine_root
+                .join(artifact)
+                .metadata()
+                .map(|metadata| metadata.is_file() && metadata.len() > 0)
+                .unwrap_or(false)
+        })
         .count();
     if valid_count == artifacts.len() {
         Some(ComponentState::Installed)
-    } else if valid_count > 0 || crate::installer::dxmt_m12_runtime_current_for_home(&home) {
+    } else if valid_count > 0 || crate::installer::complete_runtime_current_for_home(&home) {
         Some(ComponentState::NeedsRepair)
     } else {
         Some(ComponentState::Missing)
@@ -716,13 +727,18 @@ fn m12_runtime_component_detail(component_id: &str) -> String {
     let paths = artifacts
         .iter()
         .map(|artifact| {
-            crate::installer::dxmt_m12_runtime_artifact_path_for_home(&home, artifact).to_string_lossy().to_string()
+            crate::platform::metalsharp_home_dir_for(&home)
+                .join("runtime")
+                .join("wine")
+                .join(artifact)
+                .to_string_lossy()
+                .to_string()
         })
         .collect::<Vec<_>>();
     if paths.is_empty() {
-        "M12 DXMT runtime artifact".to_string()
+        "M12 vkd3d-proton/Vulkan runtime artifact".to_string()
     } else {
-        format!("PR230 M12 DXMT runtime artifact(s): {}", paths.join(", "))
+        format!("M12 vkd3d-proton/DXVK/MoltenVK runtime artifact(s): {}", paths.join(", "))
     }
 }
 
@@ -730,7 +746,7 @@ pub fn save_bottle(manifest: &BottleManifest) -> Result<(), Box<dyn std::error::
     validate_bottle_id(&manifest.id)?;
     let mut persisted = manifest.clone();
     refresh_mono_fna_components_before_save(&mut persisted);
-    refresh_dxmt_runtime_before_save(&mut persisted);
+    refresh_graphics_runtime_before_save(&mut persisted);
     let _guard = BOTTLE_SAVE_LOCK.lock().map_err(|_| "bottle save lock poisoned")?;
     let dir = bottle_dir(&manifest.id);
     fs::create_dir_all(dir.join("prefix"))?;
@@ -743,12 +759,13 @@ pub fn save_bottle(manifest: &BottleManifest) -> Result<(), Box<dyn std::error::
     Ok(())
 }
 
-fn refresh_dxmt_runtime_before_save(manifest: &mut BottleManifest) {
+fn refresh_graphics_runtime_before_save(manifest: &mut BottleManifest) {
     let (lane, components): (&str, &[&str]) = match manifest.runtime_profile {
+        RuntimeProfile::M9 => ("complete-runtime-m9", &["d3d9"]),
         RuntimeProfile::M11 | RuntimeProfile::M11_32 | RuntimeProfile::M10 | RuntimeProfile::M10_32 => {
-            ("dxmt", &["d3d11", "dxgi"])
+            ("complete-runtime-dxmt", &["d3d11", "dxgi"])
         },
-        RuntimeProfile::M12 => ("dxmt_m12", M12_RUNTIME_COMPONENT_IDS),
+        RuntimeProfile::M12 => ("vkd3d-proton", M12_RUNTIME_COMPONENT_IDS),
         _ => return,
     };
 
@@ -759,11 +776,14 @@ fn refresh_dxmt_runtime_before_save(manifest: &mut BottleManifest) {
     let runtime_ready = dirs::home_dir()
         .ok_or_else(|| "home directory could not be resolved".to_string())
         .and_then(|home| match manifest.runtime_profile {
-            RuntimeProfile::M11 | RuntimeProfile::M11_32 | RuntimeProfile::M10 | RuntimeProfile::M10_32 => {
-                crate::installer::ensure_dxmt_runtime_ready(&home).map(|_| true)
-            },
-            RuntimeProfile::M12 => crate::installer::ensure_dxmt_m12_runtime_ready(&home)
-                .map(|_| crate::installer::dxmt_m12_runtime_current_for_home(&home)),
+            RuntimeProfile::M9
+            | RuntimeProfile::M11
+            | RuntimeProfile::M11_32
+            | RuntimeProfile::M10
+            | RuntimeProfile::M10_32 => ensure_complete_graphics_runtime_ready(&home),
+            RuntimeProfile::M12 => Ok(M12_RUNTIME_COMPONENT_IDS
+                .iter()
+                .all(|id| inspect_m12_runtime_component(id) == Some(ComponentState::Installed))),
             _ => Ok(false),
         })
         .unwrap_or_else(|e| {
@@ -914,7 +934,7 @@ pub fn save_steam_compatdata(
 ) -> Result<SteamCompatdataRecord, Box<dyn std::error::Error>> {
     let mut persisted = manifest.clone();
     refresh_mono_fna_components_before_save(&mut persisted);
-    refresh_dxmt_runtime_before_save(&mut persisted);
+    refresh_graphics_runtime_before_save(&mut persisted);
     let appid = persisted.steam_app_id.ok_or("steam compatdata requires steam appid")?;
     let record = steam_compatdata_record(&persisted, pipeline);
     eprintln!(
@@ -1212,13 +1232,22 @@ pub fn prepare_steam_game_launch(
     #[cfg(not(test))]
     if let Some(home) = dirs::home_dir() {
         match pipeline {
-            crate::mtsp::engine::PipelineId::M11 => {
-                crate::installer::ensure_dxmt_runtime_ready(&home)
-                    .map_err(|e| format!("M11 runtime setup failed before Steam launch: {}", e))?;
+            crate::mtsp::engine::PipelineId::M9
+            | crate::mtsp::engine::PipelineId::M10
+            | crate::mtsp::engine::PipelineId::M10_32
+            | crate::mtsp::engine::PipelineId::M11
+            | crate::mtsp::engine::PipelineId::M11_32 => {
+                ensure_complete_graphics_runtime_ready(&home)
+                    .map_err(|e| format!("{:?} runtime setup failed before Steam launch: {}", pipeline, e))?;
             },
-            crate::mtsp::engine::PipelineId::M12 => {
-                crate::installer::ensure_dxmt_m12_runtime_ready(&home)
-                    .map_err(|e| format!("M12 runtime setup failed before Steam launch: {}", e))?;
+            crate::mtsp::engine::PipelineId::M12
+                if !M12_RUNTIME_COMPONENT_IDS
+                    .iter()
+                    .all(|id| inspect_m12_runtime_component(id) == Some(ComponentState::Installed)) =>
+            {
+                return Err(
+                    "M12 vkd3d-proton runtime is incomplete; reinstall the Complete Multi-Architecture Runtime".into(),
+                );
             },
             _ => {},
         }
@@ -1227,8 +1256,8 @@ pub fn prepare_steam_game_launch(
     // MTSP routes. /steam/launch-game immediately calls
     // mtsp::launcher::prepare_steam_pipeline_env(), which validates the route
     // runtime and stages the same game-local DLLs/env that launch will use.
-    // Calling the old setup path here can overwrite an explicitly staged M12
-    // runtime with packaged assets and break PR/runtime proof runs.
+    // Calling the old setup path here can overwrite explicitly staged route
+    // DLLs and break runtime proof runs.
     let dual = crate::scan::resolve_dual_game_dir(appid);
     let name = crate::steam::get_game_name_from_manifest(appid).unwrap_or_else(|| format!("Game {}", appid));
     let mut manifest = ensure_steam_game_bottle_inner(appid, &name, dual.wine_dir.as_deref(), pipeline, false)?;
@@ -1341,6 +1370,18 @@ pub fn prepare_steam_game_launch(
     Ok(manifest)
 }
 
+fn ensure_complete_graphics_runtime_ready(home: &Path) -> Result<bool, String> {
+    if crate::installer::complete_runtime_current_for_home(home) {
+        return Ok(true);
+    }
+    crate::installer::install_complete_runtime(&home.to_path_buf())?;
+    if crate::installer::complete_runtime_current_for_home(home) {
+        Ok(true)
+    } else {
+        Err("Complete Multi-Architecture Runtime is missing one or more M9-M12 route artifacts".into())
+    }
+}
+
 pub fn sync_steam_game_bottles() -> Result<Vec<BottleManifest>, Box<dyn std::error::Error>> {
     let mut bottles = Vec::new();
     for appid in crate::steam::get_wine_steam_installed_games() {
@@ -1596,8 +1637,10 @@ fn stage_m12_dlls_for_saved_steam_bottle(
     }
 
     let home = dirs::home_dir().ok_or("no home dir")?;
-    crate::installer::ensure_dxmt_m12_runtime_ready(&home)
-        .map_err(|e| format!("M12 runtime setup failed while saving bottle: {}", e))?;
+    if !M12_RUNTIME_COMPONENT_IDS.iter().all(|id| inspect_m12_runtime_component(id) == Some(ComponentState::Installed))
+    {
+        return Err("M12 vkd3d-proton runtime is incomplete; reinstall the Complete Multi-Architecture Runtime".into());
+    }
 
     let (_env, recipe) = crate::mtsp::launcher::prepare_steam_pipeline_env(appid, crate::mtsp::engine::PipelineId::M12)
         .map_err(|e| format!("M12 DLL deployment failed while saving bottle: {}", e))?;
@@ -1612,7 +1655,7 @@ fn stage_m12_dlls_for_saved_steam_bottle(
 /// files are moved aside) and deploys the new route's DLLs next to the exe.
 ///
 /// M12 is handled by `stage_m12_dlls_for_saved_steam_bottle` (which also
-/// ensures the isolated M12 runtime is ready). This helper covers the other
+/// verifies the complete vkd3d-proton/Vulkan runtime). This helper covers the other
 /// DXMT-family routes (M9/M10/M10_32/M11/M11_32); non-DXMT profiles return
 /// `None` and are staged at launch time as before.
 fn stage_route_dlls_for_saved_steam_bottle(
@@ -2550,10 +2593,11 @@ pub fn repair_component(
                 detail: if state == ComponentState::Installed {
                     format!("{} is already current", m12_runtime_component_detail(component_id))
                 } else {
-                    "Refreshes the bundled PR230 M12 DXMT runtime surface under runtime/wine/lib/dxmt_m12".to_string()
+                    "Reinstalls the Complete Multi-Architecture Runtime containing vkd3d-proton, DXVK, Wine Vulkan, and MoltenVK".to_string()
                 },
                 asset_path: Some(
-                    crate::installer::dxmt_m12_runtime_artifact_path_for_home(&home, "x86_64-windows/d3d12.dll")
+                    crate::platform::metalsharp_home_dir_for(&home)
+                        .join("runtime/wine/lib/vkd3d-proton/x86_64/d3d12.dll")
                         .to_string_lossy()
                         .to_string(),
                 ),
@@ -2562,7 +2606,7 @@ pub fn repair_component(
             });
         }
 
-        crate::installer::ensure_dxmt_m12_runtime_ready(&home)?;
+        crate::installer::install_complete_runtime(&home)?;
         for id in M12_RUNTIME_COMPONENT_IDS {
             let state = inspect_m12_runtime_component(id).unwrap_or(ComponentState::Missing);
             mark_component_state(&mut manifest, id, state);
@@ -2578,9 +2622,13 @@ pub fn repair_component(
         return Ok(ComponentRepairReport {
             id: component_id.to_string(),
             status: if state == ComponentState::Installed { "installed" } else { "needs_repair" }.to_string(),
-            detail: format!("Refreshed PR230 M12 DXMT runtime surface; {}", m12_runtime_component_detail(component_id)),
+            detail: format!(
+                "Refreshed the complete M12 vkd3d-proton runtime; {}",
+                m12_runtime_component_detail(component_id)
+            ),
             asset_path: Some(
-                crate::installer::dxmt_m12_runtime_artifact_path_for_home(&home, "x86_64-windows/d3d12.dll")
+                crate::platform::metalsharp_home_dir_for(&home)
+                    .join("runtime/wine/lib/vkd3d-proton/x86_64/d3d12.dll")
                     .to_string_lossy()
                     .to_string(),
             ),
@@ -3470,13 +3518,11 @@ fn runtime_profile_definition(profile: RuntimeProfile) -> RuntimeProfileDefiniti
             BottleArch::Win64,
             true,
             &[
-                "m12_d3d12",
-                "m12_d3d11",
-                "m12_d3d10core",
-                "m12_dxgi_dxmt",
-                "m12_dxgi",
-                "m12_winemetal",
-                "m12_gpu_stubs",
+                "m12_vkd3d_d3d12",
+                "m12_vkd3d_d3d12core",
+                "m12_dxvk_dxgi",
+                "m12_winevulkan",
+                "m12_moltenvk",
                 "vcrun2019_x64",
                 "vcrun2019_x86",
                 "d3d12_agility",
@@ -5256,12 +5302,13 @@ fn component_source_policy(id: &str, arch: BottleArch) -> ComponentSourcePolicy
     if is_m12_runtime_component(id) {
         let state = inspect_m12_runtime_component(id).unwrap_or(ComponentState::Unknown);
         let home = dirs::home_dir().unwrap_or_default();
-        let path = m12_runtime_component_artifacts(id)
-            .and_then(|artifacts| artifacts.first().copied())
-            .map(|artifact| crate::installer::dxmt_m12_runtime_artifact_path_for_home(&home, artifact));
+        let path =
+            m12_runtime_component_artifacts(id).and_then(|artifacts| artifacts.first().copied()).map(|artifact| {
+                crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine").join(artifact)
+            });
         return ComponentSourcePolicy {
             id: id.to_string(),
-            source: "metalsharp_pr230_dxmt_m12_runtime".to_string(),
+            source: "metalsharp_complete_vkd3d_proton_runtime".to_string(),
             available: state == ComponentState::Installed,
             detail: m12_runtime_component_detail(id),
             path: path.map(|p| p.to_string_lossy().to_string()),
@@ -5398,13 +5445,11 @@ fn component_action_detail(id: &str) -> String {
         "mono-arm64" => "Install MetalSharp ARM64 Mono runtime".to_string(),
         "mono-x86" => "Install MetalSharp x86_64 Mono runtime".to_string(),
         "fna" => "Install FNA/XNA compatibility assemblies and native shims".to_string(),
-        "m12_d3d12" => "Refresh PR230 M12 d3d12.dll from the bundled dxmt_m12 runtime".to_string(),
-        "m12_d3d11" => "Refresh PR230 M12 d3d11.dll from the bundled dxmt_m12 runtime".to_string(),
-        "m12_d3d10core" => "Refresh PR230 M12 d3d10core.dll from the bundled dxmt_m12 runtime".to_string(),
-        "m12_dxgi_dxmt" => "Refresh PR230 M12 dxgi_dxmt.dll from the bundled dxmt_m12 runtime".to_string(),
-        "m12_dxgi" => "Refresh PR230 M12 dxgi.dll from the bundled dxmt_m12 runtime".to_string(),
-        "m12_winemetal" => "Refresh PR230 M12 winemetal.dll, winemetal.so, and required Unix sidecars".to_string(),
-        "m12_gpu_stubs" => "Refresh PR230 M12 NVAPI/NVNGX GPU stub DLLs".to_string(),
+        "m12_vkd3d_d3d12" => "Restore vkd3d-proton d3d12.dll from the complete runtime".to_string(),
+        "m12_vkd3d_d3d12core" => "Restore vkd3d-proton d3d12core.dll from the complete runtime".to_string(),
+        "m12_dxvk_dxgi" => "Restore the DXVK-owned dxgi.dll paired with vkd3d-proton".to_string(),
+        "m12_winevulkan" => "Restore Wine Vulkan's PE and ARM64 Unix bridge artifacts".to_string(),
+        "m12_moltenvk" => "Restore the bundled ARM64 MoltenVK host runtime".to_string(),
         "d3d12_agility" => "Download and stage the D3D12 Agility SDK payload".to_string(),
         "gecko" => "Install Wine Gecko for embedded browser surfaces".to_string(),
         "dotnet40" => "Install the native .NET Framework 4.0 runtime for CLR v4 titles".to_string(),
@@ -7562,13 +7607,11 @@ mod tests {
         let m12 = default_components_for(RuntimeProfile::M12);
         let m12_ids = m12.iter().map(|c| c.id.as_str()).collect::<Vec<_>>();
         for required in [
-            "m12_d3d12",
-            "m12_d3d11",
-            "m12_d3d10core",
-            "m12_dxgi_dxmt",
-            "m12_dxgi",
-            "m12_winemetal",
-            "m12_gpu_stubs",
+            "m12_vkd3d_d3d12",
+            "m12_vkd3d_d3d12core",
+            "m12_dxvk_dxgi",
+            "m12_winevulkan",
+            "m12_moltenvk",
             "vcrun2019_x64",
             "vcrun2019_x86",
             "corefonts",
@@ -7586,17 +7629,15 @@ mod tests {
     }
 
     #[test]
-    fn m12_winemetal_component_tracks_required_unix_sidecars() {
-        let artifacts = m12_runtime_component_artifacts("m12_winemetal").expect("m12 winemetal artifacts");
-        for required in [
-            "x86_64-windows/winemetal.dll",
-            "x86_64-unix/winemetal.so",
-            "x86_64-unix/libc++.1.dylib",
-            "x86_64-unix/libc++abi.1.dylib",
-            "x86_64-unix/libunwind.1.dylib",
-        ] {
-            assert!(artifacts.contains(&required), "m12_winemetal must validate {required}");
-        }
+    fn m12_vulkan_components_track_required_host_boundary() {
+        let winevulkan = m12_runtime_component_artifacts("m12_winevulkan").expect("M12 Wine Vulkan artifacts");
+        assert!(winevulkan.contains(&"build-ec/dlls/winevulkan/winevulkan.so"));
+        assert!(winevulkan.contains(&"build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll"));
+        assert!(winevulkan.contains(&"build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll"));
+
+        let moltenvk = m12_runtime_component_artifacts("m12_moltenvk").expect("M12 MoltenVK artifacts");
+        assert!(moltenvk.contains(&"build-ec/dlls/win32u/libMoltenVK.dylib"));
+        assert!(moltenvk.contains(&"lib/moltenvk/libMoltenVK.dylib"));
     }
 
     #[test]
diff --git a/app/src-rust/src/d3d12_runtime_doctor.rs b/app/src-rust/src/d3d12_runtime_doctor.rs
index a6385060e..850c06105 100644
--- a/app/src-rust/src/d3d12_runtime_doctor.rs
+++ b/app/src-rust/src/d3d12_runtime_doctor.rs
@@ -56,6 +56,45 @@ pub fn handle_steam_d3d12_runtime_doctor(body: &serde_json::Map<String, Value>)
     let bottle = crate::bottles::ensure_steam_game_bottle(appid, &name, dual.wine_dir.as_deref(), pipeline).ok();
 
     let latest = latest_cached_report(appid);
+    if pipeline == crate::mtsp::engine::PipelineId::M12 {
+        let home = dirs::home_dir().unwrap_or_default();
+        let dry_run = crate::mtsp::launcher::pipeline_dry_run_for(&home, appid, Some(pipeline));
+        let ready = dry_run.get("ok").and_then(Value::as_bool).unwrap_or(false);
+        let app_root = probe_runs_root(&home, appid);
+        let run_dir = app_root.join(timestamp_secs());
+        let _ = fs::create_dir_all(&run_dir);
+        let report = json!({
+            "schema": "metalsharp.d3d12-runtime-doctor.summary.v2",
+            "appid": appid,
+            "name": name,
+            "bottleId": bottle.as_ref().map(|b| b.id.clone()),
+            "pipeline": pipeline,
+            "backend": "vkd3d-proton",
+            "applicable": true,
+            "ready": ready,
+            "status": if ready { "ready" } else { "runtime_incomplete" },
+            "summary": if ready {
+                "M12 route owns vkd3d-proton D3D12, DXVK DXGI, Wine Vulkan, and ARM64 MoltenVK; every runtime boundary is present."
+            } else {
+                "M12 vkd3d-proton/Vulkan runtime is incomplete; inspect the structured dry-run for exact missing boundaries."
+            },
+            "sdkAvailability": {
+                "available": false,
+                "applicable": false,
+                "summary": "The legacy DXMT D3D12 SDK probe suite is not used by the vkd3d-proton M12 route."
+            },
+            "route": dry_run,
+            "artifacts": {
+                "runDir": run_dir.to_string_lossy().to_string(),
+                "latestSummaryJson": app_root.join("latest-summary.json").to_string_lossy().to_string(),
+            },
+            "finishedAt": timestamp_secs(),
+        });
+        let _ = fs::write(run_dir.join(SUMMARY_JSON_NAME), serde_json::to_vec_pretty(&report).unwrap_or_default());
+        let _ = fs::create_dir_all(&app_root);
+        let _ = fs::write(app_root.join("latest-summary.json"), serde_json::to_vec_pretty(&report).unwrap_or_default());
+        return json!({"ok": ready, "report": report});
+    }
     if pipeline != crate::mtsp::engine::PipelineId::M12 {
         return json!({
             "ok": true,
@@ -68,7 +107,7 @@ pub fn handle_steam_d3d12_runtime_doctor(body: &serde_json::Map<String, Value>)
                 "applicable": false,
                 "ready": false,
                 "status": "not_applicable",
-                "summary": "D3D12 runtime doctor only applies to the M12 DXMT D3D12 route.",
+                "summary": "D3D12 runtime doctor only applies to the M12 vkd3d-proton route.",
                 "sdkAvailability": sdk_availability(),
                 "latestCachedReport": latest,
             }
diff --git a/app/src-rust/src/d3dmetal_gptk.rs b/app/src-rust/src/d3dmetal_gptk.rs
index 74c7d3668..65cd074dc 100644
--- a/app/src-rust/src/d3dmetal_gptk.rs
+++ b/app/src-rust/src/d3dmetal_gptk.rs
@@ -1011,7 +1011,7 @@ fn stage_game_local_d3dmetal_route_dlls_for_exe(state: &D3DMetalGptkState, game_
         let marker = marker_root.join("latest-manifest.json");
         let manifest = json!({
             "quarantined_at": now_secs(),
-            "reason": "D3DMetal/GPTK lane replaces app-local M12/DXMT route DLLs with Homebrew-matched D3DMetal route DLLs",
+            "reason": "D3DMetal/GPTK owns a separate Homebrew-matched prefix and replaces any app-local MetalSharp graphics-route DLLs",
             "moved": moved,
             "deployed": deployed,
         });
diff --git a/app/src-rust/src/diagnostics.rs b/app/src-rust/src/diagnostics.rs
index 7f2924552..690e48b93 100644
--- a/app/src-rust/src/diagnostics.rs
+++ b/app/src-rust/src/diagnostics.rs
@@ -170,7 +170,7 @@ fn bottle_log_dir(home: &Path, bottle_id: &str) -> Option<PathBuf> {
 }
 
 /// Resolve the on-disk shader cache directories that a pipeline would use for
-/// an appid, including the legacy shared DXMT-Metal family aliases. This
+/// an appid, including each translation backend's shared family alias. This
 /// mirrors [`crate::mtsp::shader_cache`] lookup families so the diagnostic
 /// reports the same roots the runtime consults.
 pub fn shader_cache_dirs(home: &Path, pipeline: crate::mtsp::engine::PipelineId, appid: u32) -> Vec<PathBuf> {
@@ -183,8 +183,8 @@ pub fn shader_cache_dirs(home: &Path, pipeline: crate::mtsp::engine::PipelineId,
         PipelineId::M9 => &["m9", "dxmt-metal"],
         PipelineId::M10 => &["m10", "dxmt-metal"],
         PipelineId::M11 => &["m11", "dxmt-metal"],
-        PipelineId::M12 => &["m12", "dxmt-metal12"],
-        PipelineId::M13 => &["m13", "dxmt-metal12"],
+        PipelineId::M12 => &["m12", "vkd3d-proton"],
+        PipelineId::M13 => &["m13", "d3dmetal"],
         _ => &[],
     };
 
@@ -481,7 +481,7 @@ mod tests {
         let dirs = shader_cache_dirs(&home, crate::mtsp::engine::PipelineId::M12, 7);
         let names: Vec<String> = dirs.iter().map(|d| d.to_string_lossy().to_string()).collect();
         assert!(names.iter().any(|n| n.contains("shader-cache/m12/7")), "got {:?}", names);
-        assert!(names.iter().any(|n| n.contains("shader-cache/dxmt-metal12/7")), "got {:?}", names);
+        assert!(names.iter().any(|n| n.contains("shader-cache/vkd3d-proton/7")), "got {:?}", names);
         // M12 must NOT share the dxmt-metal legacy family.
         assert!(!names.iter().any(|n| n.contains("shader-cache/dxmt-metal/")), "got {:?}", names);
         let _ = fs::remove_dir_all(&home);
diff --git a/app/src-rust/src/installer.rs b/app/src-rust/src/installer.rs
index 15f5aecad..8c0ea63bf 100644
--- a/app/src-rust/src/installer.rs
+++ b/app/src-rust/src/installer.rs
@@ -32,7 +32,8 @@ const FNALIBS_BUNDLE: &str = "fnalibs";
 const SCRIPTS_TOOLS_BUNDLE: &str = "metalsharp-scripts-tools";
 const STEAM_BUNDLE: &str = "metalsharp-steam";
 const COMPLETE_RUNTIME_INSTALLER: &str = "install-metalsharp-wine-runtime.sh";
-const COMPLETE_RUNTIME_ARCHIVE_SHA256: &str = "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee";
+pub(crate) const COMPLETE_RUNTIME_ARCHIVE_SHA256: &str =
+    "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee";
 const METALSHARP_NTDLL_HOOK_DLL: &str = "metalsharp_ntdll_hook.dll";
 const DXMT_REQUIRED_PE: &[&str] = &[
     "d3d10core.dll",
@@ -335,19 +336,50 @@ fn complete_runtime_marker(root: &Path) -> PathBuf {
 
 pub fn complete_runtime_current_for_home(home: &Path) -> bool {
     let root = complete_runtime_root(home);
-    let marker = match fs::read_to_string(complete_runtime_marker(&root)) {
+    complete_runtime_current_for_root(&root)
+}
+
+pub(crate) fn complete_runtime_current_for_ms_dir(ms_dir: &Path) -> bool {
+    complete_runtime_current_for_root(&ms_dir.join("runtime"))
+}
+
+fn complete_runtime_current_for_root(root: &Path) -> bool {
+    let marker = match fs::read_to_string(complete_runtime_marker(root)) {
         Ok(marker) => marker,
         Err(_) => return false,
     };
 
     marker.lines().any(|line| line == format!("archive_sha256={COMPLETE_RUNTIME_ARCHIVE_SHA256}"))
+        && marker.lines().any(|line| line == "no_tso=1")
         && file_nonempty(&root.join("wine/bin/metalsharp-wine"))
         && file_nonempty(&root.join("wine/build-ec/wine"))
         && file_nonempty(&root.join("wine/build-ec/server/wineserver"))
         && file_nonempty(&root.join("wine/wine-11.12/nls/locale.nls"))
         && file_nonempty(&root.join("wine/wine-11.12/fonts/tahoma.ttf"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/aarch64-unix/winemetal.so"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/aarch64-windows/d3d10core.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/aarch64-windows/d3d11.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/aarch64-windows/dxgi.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/aarch64-windows/winemetal.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/i386-windows/d3d10core.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/i386-windows/d3d11.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/i386-windows/dxgi.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dxmt-v0.80/i386-windows/winemetal.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/d3d9/x86_64-windows/d3d9.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/d3d9/i386-windows/d3d9.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/d3d10/x86_64-windows/d3d10.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/d3d10/i386-windows/d3d10.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/d3d10_1/x86_64-windows/d3d10_1.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/d3d10_1/i386-windows/d3d10_1.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/dxgi/i386-windows/dxgi.dll"))
         && file_nonempty(&root.join("graphics/dxvk/i386/d3d9.dll"))
         && file_nonempty(&root.join("graphics/vkd3d-proton/x86_64/d3d12.dll"))
+        && file_nonempty(&root.join("graphics/vkd3d-proton/x86_64/d3d12core.dll"))
+        && file_nonempty(&root.join("graphics/dxvk/x86_64/dxgi.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/winevulkan/winevulkan.so"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll"))
+        && file_nonempty(&root.join("wine/build-ec/dlls/win32u/libMoltenVK.dylib"))
         && file_nonempty(&root.join("graphics/opengl-metal/metalsharp-opengl.dylib"))
         && file_nonempty(&root.join("graphics/moltenvk/libMoltenVK.dylib"))
         && file_nonempty(&root.join("providers/xtajit64-arm64ec-known-good.dll"))
@@ -369,7 +401,7 @@ fn find_complete_runtime_installer() -> Option<PathBuf> {
     candidates.into_iter().find(|path| file_nonempty(path))
 }
 
-fn install_complete_runtime(home: &PathBuf) -> Result<bool, String> {
+pub(crate) fn install_complete_runtime(home: &PathBuf) -> Result<bool, String> {
     if complete_runtime_current_for_home(home) {
         return Ok(false);
     }
@@ -2636,8 +2668,30 @@ mod tests {
             "wine/build-ec/server/wineserver",
             "wine/wine-11.12/nls/locale.nls",
             "wine/wine-11.12/fonts/tahoma.ttf",
+            "wine/build-ec/dxmt-v0.80/aarch64-unix/winemetal.so",
+            "wine/build-ec/dxmt-v0.80/aarch64-windows/d3d10core.dll",
+            "wine/build-ec/dxmt-v0.80/aarch64-windows/d3d11.dll",
+            "wine/build-ec/dxmt-v0.80/aarch64-windows/dxgi.dll",
+            "wine/build-ec/dxmt-v0.80/aarch64-windows/winemetal.dll",
+            "wine/build-ec/dxmt-v0.80/i386-windows/d3d10core.dll",
+            "wine/build-ec/dxmt-v0.80/i386-windows/d3d11.dll",
+            "wine/build-ec/dxmt-v0.80/i386-windows/dxgi.dll",
+            "wine/build-ec/dxmt-v0.80/i386-windows/winemetal.dll",
+            "wine/build-ec/dlls/d3d9/x86_64-windows/d3d9.dll",
+            "wine/build-ec/dlls/d3d9/i386-windows/d3d9.dll",
+            "wine/build-ec/dlls/d3d10/x86_64-windows/d3d10.dll",
+            "wine/build-ec/dlls/d3d10/i386-windows/d3d10.dll",
+            "wine/build-ec/dlls/d3d10_1/x86_64-windows/d3d10_1.dll",
+            "wine/build-ec/dlls/d3d10_1/i386-windows/d3d10_1.dll",
+            "wine/build-ec/dlls/dxgi/i386-windows/dxgi.dll",
             "graphics/dxvk/i386/d3d9.dll",
             "graphics/vkd3d-proton/x86_64/d3d12.dll",
+            "graphics/vkd3d-proton/x86_64/d3d12core.dll",
+            "graphics/dxvk/x86_64/dxgi.dll",
+            "wine/build-ec/dlls/winevulkan/winevulkan.so",
+            "wine/build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll",
+            "wine/build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll",
+            "wine/build-ec/dlls/win32u/libMoltenVK.dylib",
             "graphics/opengl-metal/metalsharp-opengl.dylib",
             "graphics/moltenvk/libMoltenVK.dylib",
             "providers/xtajit64-arm64ec-known-good.dll",
diff --git a/app/src-rust/src/migrate.rs b/app/src-rust/src/migrate.rs
index 0fef126f7..503cecd51 100644
--- a/app/src-rust/src/migrate.rs
+++ b/app/src-rust/src/migrate.rs
@@ -390,46 +390,7 @@ fn parse_version_parts(value: &str) -> Vec<u32> {
 }
 
 fn runtime_core_ready(ms_dir: &Path) -> bool {
-    let runtime_wine = ms_dir.join("runtime").join("wine");
-    let runtime_host = ms_dir.join("runtime").join("host");
-    let wine = crate::platform::runtime_wine_binary(&runtime_wine);
-    if !wine.exists() {
-        return false;
-    }
-
-    if !host_runtime_ready(&runtime_host) {
-        return false;
-    }
-
-    if !crate::installer::dxmt_runtime_current_for_ms_dir(ms_dir) {
-        return false;
-    }
-
-    if !crate::installer::metalsharp_runtime_lib_ready(&runtime_wine) {
-        return false;
-    }
-
-    [
-        runtime_wine.join("lib").join("wine").join("x86_64-unix"),
-        runtime_wine.join("lib").join("wine").join("x86_64-windows").join("d3d9.dll"),
-        runtime_wine.join("lib").join("wine").join("x86_64-windows").join("d3d10.dll"),
-        runtime_wine.join("lib").join("wine").join("x86_64-windows").join("d3d10_1.dll"),
-        ms_dir.join("runtime").join("goldberg").join("x86").join("steam_api.dll"),
-        ms_dir.join("runtime").join("goldberg").join("x64").join("steam_api64.dll"),
-        ms_dir.join("configs").join("mtsp-rules.toml"),
-        runtime_wine.join("etc").join("dxmt.conf"),
-    ]
-    .iter()
-    .all(|path| path.exists())
-        && crate::installer::dxmt_graphics_runtimes_current_for_ms_dir(ms_dir)
-}
-
-fn host_runtime_ready(dir: &Path) -> bool {
-    file_nonempty(&dir.join("manifest.json"))
-        && file_nonempty(&dir.join("HostRuntimeABI.h"))
-        && (file_nonempty(&dir.join("libmetalsharp_host_runtime.dylib"))
-            || file_nonempty(&dir.join("libmetalsharp_host_runtime.so"))
-            || file_nonempty(&dir.join("metalsharp_host_runtime.dll")))
+    crate::installer::complete_runtime_current_for_ms_dir(ms_dir)
 }
 
 fn file_nonempty(path: &Path) -> bool {
@@ -2559,15 +2520,13 @@ mod tests {
     }
 
     #[test]
-    fn missing_dxmt_manifest_requests_repair() {
-        let home = test_dir("missing-dxmt-manifest");
+    fn missing_m12_vkd3d_runtime_requests_repair() {
+        let home = test_dir("missing-m12-vkd3d-runtime");
         let ms_dir = crate::platform::metalsharp_home_dir_for(&home);
         write_runtime_core(&ms_dir);
 
-        fs::remove_file(
-            ms_dir.join("runtime").join("wine").join("lib").join("dxmt").join("metalsharp-dxmt-runtime.json"),
-        )
-        .expect("remove DXMT manifest");
+        fs::remove_file(ms_dir.join("runtime").join("graphics").join("vkd3d-proton").join("x86_64").join("d3d12.dll"))
+            .expect("remove M12 vkd3d-proton d3d12 runtime");
 
         assert!(!runtime_core_ready(&ms_dir));
         assert!(runtime_needs_repair(&home, true));
@@ -2575,8 +2534,8 @@ mod tests {
     }
 
     #[test]
-    fn missing_metalsharp_hook_requests_runtime_repair() {
-        let home = test_dir("missing-metalsharp-hook");
+    fn retired_split_bundle_hook_does_not_invalidate_complete_runtime() {
+        let home = test_dir("retired-split-bundle-hook");
         let ms_dir = crate::platform::metalsharp_home_dir_for(&home);
         write_runtime_core(&ms_dir);
 
@@ -2591,8 +2550,8 @@ mod tests {
         )
         .expect("remove MetalSharp ntdll hook");
 
-        assert!(!runtime_core_ready(&ms_dir));
-        assert!(runtime_needs_repair(&home, true));
+        assert!(runtime_core_ready(&ms_dir));
+        assert!(!runtime_needs_repair(&home, true));
         let _ = fs::remove_dir_all(home);
     }
 
@@ -3152,15 +3111,12 @@ mod tests {
         );
 
         write_runtime_core(&ms_dir);
-        fs::write(
-            ms_dir.join("runtime").join("wine").join("lib").join("dxmt_m12").join("x86_64-windows").join("d3d12.dll"),
-            b"stale-m12-d3d12",
-        )
-        .expect("poison M12 hash-gated runtime file");
+        fs::remove_file(ms_dir.join("runtime").join("graphics").join("vkd3d-proton/x86_64/d3d12.dll"))
+            .expect("remove required M12 runtime file");
         assert_eq!(
             verify_migration_ready(&ms_dir, None).unwrap_err(),
             "runtime bundle is still incomplete after install",
-            "stale M12 hashes must not satisfy migration readiness"
+            "missing M12 vkd3d-proton files must not satisfy migration readiness"
         );
         let _ = fs::remove_dir_all(home);
     }
@@ -3183,6 +3139,41 @@ mod tests {
         write_host_runtime(ms_dir);
 
         for path in [
+            runtime_wine.join("build-ec").join("wine"),
+            runtime_wine.join("build-ec").join("server").join("wineserver"),
+            runtime_wine.join("wine-11.12").join("nls").join("locale.nls"),
+            runtime_wine.join("wine-11.12").join("fonts").join("tahoma.ttf"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("aarch64-unix").join("winemetal.so"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("aarch64-windows").join("d3d10core.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("aarch64-windows").join("d3d11.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("aarch64-windows").join("dxgi.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("aarch64-windows").join("winemetal.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("i386-windows").join("d3d10core.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("i386-windows").join("d3d11.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("i386-windows").join("dxgi.dll"),
+            runtime_wine.join("build-ec").join("dxmt-v0.80").join("i386-windows").join("winemetal.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("d3d9").join("x86_64-windows").join("d3d9.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("d3d9").join("i386-windows").join("d3d9.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("d3d10").join("x86_64-windows").join("d3d10.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("d3d10").join("i386-windows").join("d3d10.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("d3d10_1").join("x86_64-windows").join("d3d10_1.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("d3d10_1").join("i386-windows").join("d3d10_1.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("dxgi").join("i386-windows").join("dxgi.dll"),
+            ms_dir.join("runtime").join("graphics").join("dxvk").join("i386").join("d3d9.dll"),
+            ms_dir.join("runtime").join("graphics").join("dxvk").join("x86_64").join("dxgi.dll"),
+            ms_dir.join("runtime").join("graphics").join("vkd3d-proton").join("x86_64").join("d3d12.dll"),
+            ms_dir.join("runtime").join("graphics").join("vkd3d-proton").join("x86_64").join("d3d12core.dll"),
+            ms_dir.join("runtime").join("graphics").join("opengl-metal").join("metalsharp-opengl.dylib"),
+            ms_dir.join("runtime").join("graphics").join("moltenvk").join("libMoltenVK.dylib"),
+            ms_dir.join("runtime").join("providers").join("xtajit64-arm64ec-known-good.dll"),
+            ms_dir.join("runtime").join("providers").join("xtajit-arm64-known-good.dll"),
+            ms_dir.join("runtime").join("scripts").join("stage-runtime-providers.sh"),
+            runtime_wine.join("build-ec").join("dlls").join("wow64").join("aarch64-windows").join("wow64.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("wow64win").join("aarch64-windows").join("wow64win.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("winevulkan").join("winevulkan.so"),
+            runtime_wine.join("build-ec").join("dlls").join("winevulkan").join("x86_64-windows").join("winevulkan.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("vulkan-1").join("x86_64-windows").join("vulkan-1.dll"),
+            runtime_wine.join("build-ec").join("dlls").join("win32u").join("libMoltenVK.dylib"),
             runtime_wine.join("lib").join("wine").join("x86_64-unix").join(".keep"),
             runtime_wine.join("lib").join("wine").join("x86_64-windows").join("d3d9.dll"),
             runtime_wine.join("lib").join("wine").join("x86_64-windows").join("d3d10.dll"),
@@ -3241,6 +3232,12 @@ mod tests {
             fs::write(path, b"test").expect("write runtime file");
         }
 
+        fs::write(
+            ms_dir.join("runtime").join(".metalsharp-runtime-install"),
+            format!("archive_sha256={}\nno_tso=1\n", crate::installer::COMPLETE_RUNTIME_ARCHIVE_SHA256),
+        )
+        .expect("write complete runtime marker");
+
         crate::installer::write_dxmt_m12_expected_test_files(&runtime_wine.join("lib").join("dxmt_m12"));
 
         for lane in ["dxmt", "dxmt_m12"] {
diff --git a/app/src-rust/src/mtsp/default_rules.rs b/app/src-rust/src/mtsp/default_rules.rs
index 873c98e3d..ad68d8924 100644
--- a/app/src-rust/src/mtsp/default_rules.rs
+++ b/app/src-rust/src/mtsp/default_rules.rs
@@ -28,7 +28,7 @@ fn has_custom_exe_fix(recipe: &GameRecipe) -> bool {
 fn dll_arch_for_source_subpath(subpath: &str) -> &'static str {
     if subpath.contains("i386") {
         "32-bit"
-    } else if subpath.contains("x86_64") {
+    } else if subpath.contains("x86_64") || subpath.contains("aarch64-windows") {
         "64-bit"
     } else {
         "mixed"
@@ -147,7 +147,8 @@ mod tests {
     #[test]
     fn launch_shape_for_hades_m11_reports_64_bit_dxmt_deploy_set() {
         // Switching Hades from the M11(32) default to plain M11 must report the
-        // 64-bit DXMT deploy set (d3d11/dxgi/winemetal from lib/dxmt/x86_64-windows)
+        // 64-bit DXMT deploy set (the x86-64/ARM64EC-compatible PE payload in
+        // the complete runtime's aarch64-windows lane)
         // and the M11 wine overrides, so the UI can show the user exactly what
         // will be applied.
         let shape = handle_launch_shape(1145360, PipelineId::M11);
@@ -174,7 +175,7 @@ mod tests {
         assert!(filenames.contains(&"winemetal.dll"));
         for dll in dlls {
             assert_eq!(dll.get("arch").and_then(|v| v.as_str()), Some("64-bit"));
-            assert!(dll.get("source_subpath").and_then(|v| v.as_str()).unwrap_or("").contains("x86_64-windows"));
+            assert!(dll.get("source_subpath").and_then(|v| v.as_str()).unwrap_or("").contains("aarch64-windows"));
         }
     }
 
diff --git a/app/src-rust/src/mtsp/engine.rs b/app/src-rust/src/mtsp/engine.rs
index 262eaebeb..a14bc7993 100644
--- a/app/src-rust/src/mtsp/engine.rs
+++ b/app/src-rust/src/mtsp/engine.rs
@@ -60,7 +60,6 @@ impl PipelineNode {
 
 static PIPELINES: OnceLock<Vec<PipelineNode>> = OnceLock::new();
 const DXMT_70_PERCENT_UPSCALE_CONFIG: &str = "d3d11.metalSpatialUpscaleFactor=1.43;d3d11.preferredMaxFrameRate=60";
-const DXMT_M12_SAFE_CONFIG: &str = "d3d11.metalSpatialUpscaleFactor=1.43;d3d11.preferredMaxFrameRate=60";
 
 pub fn pipelines() -> &'static Vec<PipelineNode> {
     PIPELINES.get_or_init(|| {
@@ -68,7 +67,7 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
             PipelineNode {
                 id: PipelineId::Dxmt,
                 name: "DXMT",
-                description: "Auto-selected D3D9/D3D10/D3D11/D3D12 -> Metal via unified DXMT runtime",
+                description: "Auto-selects DXMT for D3D9-D3D11 or vkd3d-proton/MoltenVK for D3D12",
                 backend: "dxmt",
                 graphics_backend: "dxmt",
                 experimental: false,
@@ -85,68 +84,25 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
             PipelineNode {
                 id: PipelineId::M12,
                 name: "M12",
-                description: "D3D12 -> Metal via DXMT",
-                backend: "dxmt",
-                graphics_backend: "dxmt",
+                description: "D3D12 -> Vulkan via vkd3d-proton -> Metal via MoltenVK",
+                backend: "vkd3d-proton",
+                graphics_backend: "vkd3d-proton",
                 experimental: false,
                 requires_wine: true,
-                wine_overrides: Some(
-                    "winemetal,d3d12,dxgi,dxgi_dxmt,d3d11,d3d10core=n,b;gameoverlayrenderer,gameoverlayrenderer64=d",
-                ),
-                dyld_paths: vec!["lib/dxmt_m12/x86_64-unix", "lib/wine/x86_64-unix"],
-                winedllpath_dirs: vec!["lib/dxmt_m12/x86_64-windows"],
+                wine_overrides: Some("d3d12,d3d12core,dxgi=n,b;gameoverlayrenderer,gameoverlayrenderer64=d"),
+                dyld_paths: vec!["build-ec/dlls/winevulkan", "build-ec/dlls/win32u", "build-ec/dlls/ntdll"],
+                winedllpath_dirs: vec!["lib/vkd3d-proton/x86_64", "lib/dxvk/x86_64"],
                 deploy_dlls: vec![
+                    DllDeploy { source_subpath: "lib/vkd3d-proton/x86_64", filename: "d3d12.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "d3d12.dll",
+                        source_subpath: "lib/vkd3d-proton/x86_64",
+                        filename: "d3d12core.dll",
                         dest_filename: None,
                     },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "d3d11.dll",
-                        dest_filename: None,
-                    },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "dxgi.dll",
-                        dest_filename: None,
-                    },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "dxgi_dxmt.dll",
-                        dest_filename: None,
-                    },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "d3d10core.dll",
-                        dest_filename: None,
-                    },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "winemetal.dll",
-                        dest_filename: None,
-                    },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "nvapi64.dll",
-                        dest_filename: None,
-                    },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt_m12/x86_64-windows",
-                        filename: "nvngx.dll",
-                        dest_filename: None,
-                    },
-                ],
-                env_vars: vec![
-                    EnvVar { key: "DXMT_METALFX_SPATIAL_SWAPCHAIN", value: "1" },
-                    EnvVar { key: "DXMT_METALFX_SPATIAL", value: "1" },
-                    EnvVar { key: "DXMT_METALFX_TEMPORAL", value: "1" },
-                    EnvVar { key: "DXMT_ASYNC_PIPELINE_COMPILE", value: "1" },
-                    EnvVar { key: "DXMT_D3D12_UE_SM6_COMPAT", value: "1" },
-                    EnvVar { key: "DXMT_D3D12_PSO_WORKERS", value: "6" },
-                    EnvVar { key: "DXMT_CONFIG", value: DXMT_M12_SAFE_CONFIG },
+                    DllDeploy { source_subpath: "lib/dxvk/x86_64", filename: "dxgi.dll", dest_filename: None },
                 ],
-                launch_args: vec!["-windowed", "-ResX=1280", "-ResY=720", "-ForceRes"],
+                env_vars: vec![],
+                launch_args: vec![],
                 alternatives: vec![
                     PipelineId::M11,
                     PipelineId::M10,
@@ -165,35 +121,27 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 experimental: false,
                 requires_wine: true,
                 wine_overrides: Some("winemetal,dxgi,d3d11,d3d10core=n,b;gameoverlayrenderer,gameoverlayrenderer64=d"),
-                dyld_paths: vec!["lib/wine/x86_64-unix", "lib/dxmt/x86_64-unix"],
-                winedllpath_dirs: vec!["lib/dxmt/x86_64-windows", "lib/metalsharp/x86_64-windows"],
+                dyld_paths: vec!["build-ec/dlls/ntdll", "build-ec/dxmt-v0.80/aarch64-unix"],
+                winedllpath_dirs: vec!["build-ec/dxmt-v0.80/aarch64-windows"],
                 deploy_dlls: vec![
-                    DllDeploy { source_subpath: "lib/dxmt/x86_64-windows", filename: "d3d11.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/dxmt/x86_64-windows", filename: "dxgi.dll", dest_filename: None },
-                    DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "dxgi_dxmt.dll",
-                        dest_filename: None,
-                    },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "d3d10core.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "d3d11.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "winemetal.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "dxgi.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "nvapi64.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "d3d10core.dll",
                         dest_filename: None,
                     },
-                    DllDeploy { source_subpath: "lib/dxmt/x86_64-windows", filename: "nvngx.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/metalsharp/x86_64-windows",
-                        filename: "metalsharp_ntdll_hook.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "winemetal.dll",
                         dest_filename: None,
                     },
                 ],
@@ -222,23 +170,26 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 experimental: false,
                 requires_wine: true,
                 wine_overrides: Some("d3d11,dxgi,winemetal=n,b;gameoverlayrenderer,gameoverlayrenderer64=d"),
-                dyld_paths: vec!["lib/wine/x86_64-unix", "lib/dxmt/i386-unix", "lib/wine"],
-                winedllpath_dirs: vec!["lib/dxmt/i386-windows", "lib/wine/i386-windows", "lib/wine/x86_64-windows"],
+                dyld_paths: vec!["build-ec/dlls/ntdll", "build-ec/dxmt-v0.80/aarch64-unix"],
+                winedllpath_dirs: vec!["build-ec/dxmt-v0.80/i386-windows"],
                 deploy_dlls: vec![
-                    DllDeploy { source_subpath: "lib/dxmt/i386-windows", filename: "d3d11.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/dxmt/i386-windows", filename: "dxgi.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/i386-windows",
-                        filename: "dxgi_dxmt.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
+                        filename: "d3d11.dll",
+                        dest_filename: None,
+                    },
+                    DllDeploy {
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
+                        filename: "dxgi.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/i386-windows",
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
                         filename: "d3d10core.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/i386-windows",
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
                         filename: "winemetal.dll",
                         dest_filename: None,
                     },
@@ -272,45 +223,41 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 wine_overrides: Some(
                     "winemetal,d3d10,d3d10_1,dxgi,d3d11,d3d10core=n,b;gameoverlayrenderer,gameoverlayrenderer64=d",
                 ),
-                dyld_paths: vec!["lib/wine/x86_64-unix", "lib/dxmt/x86_64-unix"],
+                dyld_paths: vec!["build-ec/dlls/ntdll", "build-ec/dxmt-v0.80/aarch64-unix"],
                 winedllpath_dirs: vec![
-                    "lib/wine/x86_64-windows",
-                    "lib/dxmt/x86_64-windows",
-                    "lib/metalsharp/x86_64-windows",
+                    "build-ec/dlls/d3d10/x86_64-windows",
+                    "build-ec/dlls/d3d10_1/x86_64-windows",
+                    "build-ec/dxmt-v0.80/aarch64-windows",
                 ],
                 deploy_dlls: vec![
-                    DllDeploy { source_subpath: "lib/wine/x86_64-windows", filename: "d3d10.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/wine/x86_64-windows",
-                        filename: "d3d10_1.dll",
+                        source_subpath: "build-ec/dlls/d3d10/x86_64-windows",
+                        filename: "d3d10.dll",
                         dest_filename: None,
                     },
-                    DllDeploy { source_subpath: "lib/dxmt/x86_64-windows", filename: "d3d11.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/dxmt/x86_64-windows", filename: "dxgi.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "dxgi_dxmt.dll",
+                        source_subpath: "build-ec/dlls/d3d10_1/x86_64-windows",
+                        filename: "d3d10_1.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "d3d10core.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "d3d11.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "winemetal.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "dxgi.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "nvapi64.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "d3d10core.dll",
                         dest_filename: None,
                     },
-                    DllDeploy { source_subpath: "lib/dxmt/x86_64-windows", filename: "nvngx.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/metalsharp/x86_64-windows",
-                        filename: "metalsharp_ntdll_hook.dll",
+                        source_subpath: "build-ec/dxmt-v0.80/aarch64-windows",
+                        filename: "winemetal.dll",
                         dest_filename: None,
                     },
                 ],
@@ -340,25 +287,40 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 wine_overrides: Some(
                     "d3d10,d3d10_1,d3d10core,d3d11,dxgi,winemetal=n,b;gameoverlayrenderer,gameoverlayrenderer64=d",
                 ),
-                dyld_paths: vec!["lib/wine/x86_64-unix", "lib/dxmt/i386-unix", "lib/wine"],
-                winedllpath_dirs: vec!["lib/wine/i386-windows", "lib/dxmt/i386-windows", "lib/wine/x86_64-windows"],
+                dyld_paths: vec!["build-ec/dlls/ntdll", "build-ec/dxmt-v0.80/aarch64-unix"],
+                winedllpath_dirs: vec![
+                    "build-ec/dlls/d3d10/i386-windows",
+                    "build-ec/dlls/d3d10_1/i386-windows",
+                    "build-ec/dxmt-v0.80/i386-windows",
+                ],
                 deploy_dlls: vec![
-                    DllDeploy { source_subpath: "lib/wine/i386-windows", filename: "d3d10.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/wine/i386-windows", filename: "d3d10_1.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/dxmt/i386-windows", filename: "d3d11.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/dxmt/i386-windows", filename: "dxgi.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/i386-windows",
-                        filename: "dxgi_dxmt.dll",
+                        source_subpath: "build-ec/dlls/d3d10/i386-windows",
+                        filename: "d3d10.dll",
+                        dest_filename: None,
+                    },
+                    DllDeploy {
+                        source_subpath: "build-ec/dlls/d3d10_1/i386-windows",
+                        filename: "d3d10_1.dll",
+                        dest_filename: None,
+                    },
+                    DllDeploy {
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
+                        filename: "d3d11.dll",
+                        dest_filename: None,
+                    },
+                    DllDeploy {
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
+                        filename: "dxgi.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/i386-windows",
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
                         filename: "d3d10core.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/i386-windows",
+                        source_subpath: "build-ec/dxmt-v0.80/i386-windows",
                         filename: "winemetal.dll",
                         dest_filename: None,
                     },
@@ -390,25 +352,26 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 experimental: false,
                 requires_wine: true,
                 wine_overrides: Some("d3d9=n,b;gameoverlayrenderer,gameoverlayrenderer64=d"),
-                dyld_paths: vec!["lib/wine/x86_64-unix", "lib/dxmt/x86_64-unix"],
+                dyld_paths: vec!["build-ec/dlls/ntdll", "build-ec/dlls/win32u"],
                 winedllpath_dirs: vec![
-                    "lib/wine/x86_64-windows",
-                    "lib/wine/i386-windows",
-                    "lib/dxmt/x86_64-windows",
-                    "lib/metalsharp/x86_64-windows",
+                    "build-ec/dlls/d3d9/x86_64-windows",
+                    "build-ec/dlls/d3d9/i386-windows",
+                    "build-ec/dlls/dxgi/i386-windows",
                 ],
                 deploy_dlls: vec![
-                    DllDeploy { source_subpath: "lib/wine/x86_64-windows", filename: "d3d9.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/wine/i386-windows", filename: "d3d9.dll", dest_filename: None },
-                    DllDeploy { source_subpath: "lib/wine/i386-windows", filename: "dxgi.dll", dest_filename: None },
                     DllDeploy {
-                        source_subpath: "lib/dxmt/x86_64-windows",
-                        filename: "nvapi64.dll",
+                        source_subpath: "build-ec/dlls/d3d9/x86_64-windows",
+                        filename: "d3d9.dll",
                         dest_filename: None,
                     },
                     DllDeploy {
-                        source_subpath: "lib/metalsharp/x86_64-windows",
-                        filename: "metalsharp_ntdll_hook.dll",
+                        source_subpath: "build-ec/dlls/d3d9/i386-windows",
+                        filename: "d3d9.dll",
+                        dest_filename: None,
+                    },
+                    DllDeploy {
+                        source_subpath: "build-ec/dlls/dxgi/i386-windows",
+                        filename: "dxgi.dll",
                         dest_filename: None,
                     },
                 ],
@@ -432,7 +395,7 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 wine_overrides: Some(
                     "d3d10,d3d11,d3d12,dxgi,nvapi64,nvngx-on-metalfx=n,b;gameoverlayrenderer,gameoverlayrenderer64=d",
                 ),
-                dyld_paths: vec!["lib/wine/x86_64-unix"],
+                dyld_paths: vec!["build-ec/dlls/ntdll"],
                 winedllpath_dirs: vec![],
                 deploy_dlls: vec![],
                 env_vars: vec![],
@@ -468,7 +431,7 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 experimental: false,
                 requires_wine: true,
                 wine_overrides: None,
-                dyld_paths: vec!["lib/wine/x86_64-unix"],
+                dyld_paths: vec!["build-ec/dlls/ntdll"],
                 winedllpath_dirs: vec![],
                 deploy_dlls: vec![],
                 env_vars: vec![],
@@ -536,7 +499,7 @@ pub fn pipelines() -> &'static Vec<PipelineNode> {
                 experimental: false,
                 requires_wine: true,
                 wine_overrides: None,
-                dyld_paths: vec!["lib/wine/x86_64-unix"],
+                dyld_paths: vec!["build-ec/dlls/ntdll"],
                 winedllpath_dirs: vec![],
                 deploy_dlls: vec![],
                 env_vars: vec![],
@@ -562,7 +525,6 @@ impl PipelineId {
                 | PipelineId::M10_32
                 | PipelineId::M11
                 | PipelineId::M11_32
-                | PipelineId::M12
         )
     }
 
@@ -612,7 +574,7 @@ impl PipelineId {
         match method.trim().to_ascii_lowercase().as_str() {
             "dxmt" => Some(PipelineId::Dxmt),
             "dxmt_metal" | "steam_d3dmetal_perf" | "steam_metalfx" => Some(PipelineId::M11),
-            "dxmt_metal12" => Some(PipelineId::M12),
+            "dxmt_metal12" | "vkd3d_proton" | "vkd3d-proton" => Some(PipelineId::M12),
             "d3d9_metal" => Some(PipelineId::M9),
             "wined3d_32" => Some(PipelineId::M32),
             "metalsharp_wine" => Some(PipelineId::WineBare),
@@ -654,8 +616,8 @@ impl PipelineId {
             | PipelineId::M10
             | PipelineId::M10_32
             | PipelineId::M11
-            | PipelineId::M11_32
-            | PipelineId::M12 => "dxmt",
+            | PipelineId::M11_32 => "dxmt",
+            PipelineId::M12 => "vkd3d_proton",
             PipelineId::M13 => "gptk_d3dmetal",
             PipelineId::D3DMetal => "d3dmetal",
             PipelineId::M32 => "wined3d_32",
@@ -687,58 +649,36 @@ mod tests {
     }
 
     #[test]
-    fn m12_is_primary_d3d12_dxmt_profile() {
+    fn m12_is_primary_d3d12_vkd3d_proton_profile() {
         let m12 = get_pipeline(PipelineId::M12);
         assert!(!m12.experimental);
-        assert_eq!(m12.backend, "dxmt");
-        assert!(m12.launch_args.contains(&"-windowed"));
+        assert_eq!(m12.backend, "vkd3d-proton");
+        assert!(m12.launch_args.is_empty(), "M12 must not force a global resolution or window mode");
         assert!(m12.deploy_dlls.iter().any(|dll| dll.filename == "d3d12.dll"));
         assert_eq!(m12.shader_cache_subdir, Some("m12"));
     }
 
     #[test]
-    fn m12_is_stronger_than_other_dxmt_d3d_paths() {
+    fn m12_has_exclusive_vkd3d_proton_dxvk_moltenvk_ownership() {
         let m12 = get_pipeline(PipelineId::M12);
 
-        for required in ["lib/wine/x86_64-unix", "lib/dxmt_m12/x86_64-unix"] {
+        for required in ["build-ec/dlls/winevulkan", "build-ec/dlls/win32u", "build-ec/dlls/ntdll"] {
             assert!(m12.dyld_paths.contains(&required));
         }
-        assert!(!m12.dyld_paths.contains(&"lib/dxmt/x86_64-unix"));
-        assert!(m12.winedllpath_dirs.contains(&"lib/dxmt_m12/x86_64-windows"));
-        assert!(!m12.winedllpath_dirs.contains(&"lib/dxmt/x86_64-windows"));
-        assert!(!m12.winedllpath_dirs.contains(&"lib/metalsharp/x86_64-windows"));
+        assert!(m12.dyld_paths.iter().all(|path| !path.contains("dxmt")));
+        assert!(m12.winedllpath_dirs.contains(&"lib/vkd3d-proton/x86_64"));
+        assert!(m12.winedllpath_dirs.contains(&"lib/dxvk/x86_64"));
+        assert!(m12.winedllpath_dirs.iter().all(|path| !path.contains("dxmt")));
 
         let m12_dlls: std::collections::HashSet<_> =
             m12.deploy_dlls.iter().map(|dll| (dll.source_subpath, dll.filename)).collect();
-        for required in ["d3d12.dll", "d3d11.dll", "dxgi.dll", "dxgi_dxmt.dll", "d3d10core.dll", "winemetal.dll"] {
-            assert!(
-                m12_dlls.contains(&("lib/dxmt_m12/x86_64-windows", required)),
-                "M12 missing isolated DXMT DLL {}",
-                required
-            );
-        }
-        assert!(!m12.deploy_dlls.iter().any(|dll| dll.source_subpath == "lib/dxmt/x86_64-windows"));
-        assert!(!m12.deploy_dlls.iter().any(|dll| dll.filename == "metalsharp_ntdll_hook.dll"));
-
-        let m12_env: std::collections::HashSet<_> = m12.env_vars.iter().map(|env| env.key).collect();
-        assert!(m12_env.contains("DXMT_ASYNC_PIPELINE_COMPILE"));
-        assert!(m12_env.contains("DXMT_D3D12_PSO_WORKERS"));
-        assert!(m12_env.contains("DXMT_METALFX_SPATIAL_SWAPCHAIN"));
-        assert!(m12_env.contains("DXMT_METALFX_SPATIAL"));
-        assert!(m12_env.contains("DXMT_METALFX_TEMPORAL"));
-        let m12_env_values: std::collections::HashMap<_, _> =
-            m12.env_vars.iter().map(|env| (env.key, env.value)).collect();
-        assert_eq!(m12_env_values.get("DXMT_ASYNC_PIPELINE_COMPILE"), Some(&"1"));
-        assert_eq!(m12_env_values.get("DXMT_D3D12_PSO_WORKERS"), Some(&"6"));
-        assert_eq!(m12_env_values.get("DXMT_METALFX_SPATIAL_SWAPCHAIN"), Some(&"1"));
-        assert_eq!(m12_env_values.get("DXMT_METALFX_SPATIAL"), Some(&"1"));
-        assert_eq!(m12_env_values.get("DXMT_METALFX_TEMPORAL"), Some(&"1"));
-        assert_eq!(m12_env_values.get("DXMT_CONFIG"), Some(&DXMT_M12_SAFE_CONFIG));
+        assert!(m12_dlls.contains(&("lib/vkd3d-proton/x86_64", "d3d12.dll")));
+        assert!(m12_dlls.contains(&("lib/vkd3d-proton/x86_64", "d3d12core.dll")));
+        assert!(m12_dlls.contains(&("lib/dxvk/x86_64", "dxgi.dll")));
+        assert_eq!(m12_dlls.len(), 3);
+        assert!(m12.env_vars.iter().all(|env| !env.key.starts_with("DXMT")));
 
-        assert_eq!(
-            m12.wine_overrides,
-            Some("winemetal,d3d12,dxgi,dxgi_dxmt,d3d11,d3d10core=n,b;gameoverlayrenderer,gameoverlayrenderer64=d")
-        );
+        assert_eq!(m12.wine_overrides, Some("d3d12,d3d12core,dxgi=n,b;gameoverlayrenderer,gameoverlayrenderer64=d"));
         assert!(m12.alternatives.contains(&PipelineId::M11));
     }
 
@@ -802,11 +742,10 @@ mod tests {
         );
 
         let m10_dlls: std::collections::HashSet<_> = m10.deploy_dlls.iter().map(|dll| dll.filename).collect();
-        for required in
-            ["d3d10.dll", "d3d10_1.dll", "d3d11.dll", "dxgi.dll", "dxgi_dxmt.dll", "d3d10core.dll", "winemetal.dll"]
-        {
+        for required in ["d3d10.dll", "d3d10_1.dll", "d3d11.dll", "dxgi.dll", "d3d10core.dll", "winemetal.dll"] {
             assert!(m10_dlls.contains(required), "M10 missing {}", required);
         }
+        assert!(!m10_dlls.contains("dxgi_dxmt.dll"));
         assert!(!m10_dlls.contains("d3d12.dll"));
 
         let m10_env: std::collections::HashSet<_> = m10.env_vars.iter().map(|env| env.key).collect();
@@ -843,16 +782,17 @@ mod tests {
             // must carry the unix sidecar hint validated for 32-bit DXMT launches
             let env_keys: std::collections::HashSet<_> = node.env_vars.iter().map(|e| e.key).collect();
             assert!(env_keys.contains("DXMT_WINEMETAL_UNIXLIB"));
-            // dyld path must include the i386-unix lane
-            assert!(node.dyld_paths.iter().any(|p| p.contains("i386-unix")));
+            // The guest is i386, but its Unix bridge must remain native ARM64.
+            assert!(node.dyld_paths.iter().any(|p| p.contains("aarch64-unix")));
+            assert!(node.dyld_paths.iter().all(|p| !p.contains("i386-unix")));
         }
 
         // M11(32) ships the D3D11 handoff set; no d3d12 / no nvapi
         let m11_32_dlls: std::collections::HashSet<_> = m11_32.deploy_dlls.iter().map(|d| d.filename).collect();
-        for required in ["d3d11.dll", "dxgi.dll", "dxgi_dxmt.dll", "d3d10core.dll", "winemetal.dll"] {
+        for required in ["d3d11.dll", "dxgi.dll", "d3d10core.dll", "winemetal.dll"] {
             assert!(m11_32_dlls.contains(required), "M11(32) missing {}", required);
         }
-        for forbidden in ["d3d12.dll", "nvapi64.dll", "nvngx.dll"] {
+        for forbidden in ["d3d12.dll", "dxgi_dxmt.dll", "nvapi64.dll", "nvngx.dll"] {
             assert!(!m11_32_dlls.contains(forbidden), "M11(32) must not ship {}", forbidden);
         }
 
@@ -877,12 +817,11 @@ mod tests {
 
         let m9_dlls: std::collections::HashSet<_> =
             m9.deploy_dlls.iter().map(|dll| (dll.source_subpath, dll.filename)).collect();
-        assert!(m9_dlls.contains(&("lib/wine/x86_64-windows", "d3d9.dll")));
-        assert!(m9_dlls.contains(&("lib/wine/i386-windows", "d3d9.dll")));
-        assert!(m9_dlls.contains(&("lib/wine/i386-windows", "dxgi.dll")));
-        assert!(m9_dlls.contains(&("lib/dxmt/x86_64-windows", "nvapi64.dll")));
+        assert!(m9_dlls.contains(&("build-ec/dlls/d3d9/x86_64-windows", "d3d9.dll")));
+        assert!(m9_dlls.contains(&("build-ec/dlls/d3d9/i386-windows", "d3d9.dll")));
+        assert!(m9_dlls.contains(&("build-ec/dlls/dxgi/i386-windows", "dxgi.dll")));
         assert!(m9.deploy_dlls.iter().all(|dll| !dll.source_subpath.contains("dxvk")));
-        assert!(m9.dyld_paths.contains(&"lib/dxmt/x86_64-unix"));
+        assert!(m9.dyld_paths.contains(&"build-ec/dlls/win32u"));
 
         let m9_env: std::collections::HashSet<_> = m9.env_vars.iter().map(|env| env.key).collect();
         assert!(m9_env.contains("DXMT_ASYNC_PIPELINE_COMPILE"));
@@ -949,10 +888,12 @@ mod tests {
     }
 
     #[test]
-    fn dxmt_family_serializes_to_canonical_launch_method() {
-        for pipeline in [PipelineId::Dxmt, PipelineId::M9, PipelineId::M10, PipelineId::M11, PipelineId::M12] {
+    fn graphics_families_serialize_to_their_canonical_launch_methods() {
+        for pipeline in [PipelineId::Dxmt, PipelineId::M9, PipelineId::M10, PipelineId::M11] {
             assert_eq!(pipeline.to_legacy_method(), "dxmt");
             assert!(pipeline.is_dxmt_family());
         }
+        assert_eq!(PipelineId::M12.to_legacy_method(), "vkd3d_proton");
+        assert!(!PipelineId::M12.is_dxmt_family());
     }
 }
diff --git a/app/src-rust/src/mtsp/launcher.rs b/app/src-rust/src/mtsp/launcher.rs
index c86241b59..6fa5d60bc 100644
--- a/app/src-rust/src/mtsp/launcher.rs
+++ b/app/src-rust/src/mtsp/launcher.rs
@@ -5,7 +5,7 @@ use std::io::{Read, Write};
 use std::net::TcpStream;
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
-use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
 
 const DEFAULT_BRIDGE_PORT: u16 = 18733;
@@ -402,8 +402,8 @@ pub fn launch_with_pipeline(
         | PipelineId::M10
         | PipelineId::M10_32
         | PipelineId::M11
-        | PipelineId::M11_32
-        | PipelineId::M12 => launch_dxmt_metal(appid, node),
+        | PipelineId::M11_32 => launch_dxmt_metal(appid, node),
+        PipelineId::M12 => launch_vkd3d_proton_metal(appid, node),
         PipelineId::M13 | PipelineId::D3DMetal => launch_d3dmetal_gptk(appid, node),
         PipelineId::M32 => launch_wine_bare(appid, node),
         PipelineId::FnaArm64 => launch_fna_arm64(appid).map(|(pid, method, _)| (pid, method)),
@@ -431,9 +431,14 @@ pub fn launch_steam_bottle_with_pipeline(
         | PipelineId::M10
         | PipelineId::M10_32
         | PipelineId::M11
-        | PipelineId::M11_32
-        | PipelineId::M12 => launch_dxmt_metal_with_context(appid, node, Some(prefix_path), extra_env, Some(&log_path))
-            .map(|(pid, method)| (pid, method, log_path)),
+        | PipelineId::M11_32 => {
+            launch_dxmt_metal_with_context(appid, node, Some(prefix_path), extra_env, Some(&log_path))
+                .map(|(pid, method)| (pid, method, log_path))
+        },
+        PipelineId::M12 => {
+            launch_vkd3d_proton_metal_with_context(appid, node, Some(prefix_path), extra_env, Some(&log_path))
+                .map(|(pid, method)| (pid, method, log_path))
+        },
         PipelineId::M13 | PipelineId::D3DMetal => {
             launch_d3dmetal_gptk_with_context(appid, node, Some(prefix_path), extra_env, Some(&log_path))
                 .map(|(pid, method)| (pid, method, log_path))
@@ -533,9 +538,6 @@ pub fn prepare_steam_pipeline_env(
     prepare_start_protected_game_for_pipeline(appid, pipeline_id);
     let recipe = super::recipe::build_launch_recipe(appid, node)?;
     validate_recipe_runtime(&recipe)?;
-    if node.backend == "dxmt" {
-        repair_metalsharp_wine_wrapper_env_order()?;
-    }
     if let Some(game_dir) = recipe.game_dir.as_ref() {
         prepare_steam_api_for_game_dir(&home, game_dir, appid, pipeline_id);
         cleanup_legacy_eac_toggle_artifacts(game_dir);
@@ -568,9 +570,10 @@ pub fn prepare_steam_pipeline_env(
 
 /// Phase 3: M12 artifact and launch verification (dry-run).
 ///
-/// Proves the M12 route would load the intended DXMT/winemetal artifacts
+/// Proves the M12 route would load the intended vkd3d-proton, DXVK DXGI,
+/// Wine Vulkan, and MoltenVK artifacts
 /// WITHOUT launching Steam or the game. This runs through the same
-/// environment builder (`steam_pipeline_env_pairs`) as `launch_dxmt_metal`,
+/// environment builder (`steam_pipeline_env_pairs`) as the live launch path,
 /// so the env pairs and artifact sources reported here are exactly what a
 /// real M12 launch would use. Nothing is deployed or spawned.
 pub fn m12_verify_dry_run(appid: u32) -> serde_json::Value {
@@ -636,26 +639,34 @@ pub fn pipeline_dry_run_for(home: &Path, appid: u32, requested: Option<PipelineI
         }
     }
 
-    // For the isolated M12/M13 lane, also verify the x86_64-unix sidecars that
-    // winemetal requires at runtime.
+    // M12 owns a Vulkan host route, not a winemetal Unix bridge. Verify every
+    // host-side boundary required after the PE d3d12/dxgi DLLs hand off.
     let mut unix_sidecars: Vec<serde_json::Value> = Vec::new();
     let unix_lib_dir = if pipeline == PipelineId::M12 {
-        let dir = ms_root.join("lib").join("dxmt_m12").join("x86_64-unix");
-        for sidecar in ["winemetal.so", "libc++.1.dylib", "libc++abi.1.dylib", "libunwind.1.dylib"] {
-            let path = dir.join(sidecar);
+        let dir = ms_root.join("build-ec").join("dlls").join("winevulkan");
+        for (name, path) in [
+            ("winevulkan.so", dir.join("winevulkan.so")),
+            ("winevulkan.dll", dir.join("x86_64-windows").join("winevulkan.dll")),
+            (
+                "vulkan-1.dll",
+                ms_root.join("build-ec").join("dlls").join("vulkan-1").join("x86_64-windows").join("vulkan-1.dll"),
+            ),
+            ("libMoltenVK.dylib", ms_root.join("build-ec").join("dlls").join("win32u").join("libMoltenVK.dylib")),
+            ("packaged-libMoltenVK.dylib", ms_root.join("lib").join("moltenvk").join("libMoltenVK.dylib")),
+        ] {
             let present = path.exists();
             let sha = if present { crate::diagnostics::file_sha256(&path) } else { None };
             unix_sidecars.push(serde_json::json!({
-                "filename": sidecar,
+                "filename": name,
                 "path": path.to_string_lossy(),
                 "present": present,
                 "sha256": sha,
             }));
             if !present {
                 missing.push(serde_json::json!({
-                    "filename": sidecar,
+                    "filename": name,
                     "source_path": path.to_string_lossy(),
-                    "category": "unix_sidecar",
+                    "category": "vulkan_host_boundary",
                 }));
             }
         }
@@ -682,6 +693,8 @@ pub fn pipeline_dry_run_for(home: &Path, appid: u32, requested: Option<PipelineI
         "env_keys_present": {
             "WINEDLLOVERRIDES": env_keys.contains("WINEDLLOVERRIDES"),
             "DXMT_SHADER_CACHE_PATH": env_keys.contains("DXMT_SHADER_CACHE_PATH"),
+            "VKD3D_SHADER_CACHE_PATH": env_keys.contains("VKD3D_SHADER_CACHE_PATH"),
+            "DXVK_STATE_CACHE_PATH": env_keys.contains("DXVK_STATE_CACHE_PATH"),
             "DYLD_FALLBACK_LIBRARY_PATH": env_keys.contains("DYLD_FALLBACK_LIBRARY_PATH") || env_keys.contains("LD_LIBRARY_PATH"),
             "SteamAppId": env_keys.contains("SteamAppId"),
             "DXMT_WINEMETAL_UNIXLIB": env_keys.contains("DXMT_WINEMETAL_UNIXLIB"),
@@ -876,8 +889,8 @@ fn pipeline_quarantine_label(pipeline: PipelineId) -> &'static str {
 /// Resolves the runtime "deploy from" source path for a route DLL filename.
 ///
 /// Route DLLs deployed into a game folder are copies of canonical source DLLs
-/// that live under the MetalSharp wine runtime (e.g. `lib/dxmt/i386-windows`,
-/// `lib/dxmt/x86_64-windows`, `lib/dxmt_m12/x86_64-windows`, `lib/wine/...`).
+/// that live under the MetalSharp wine runtime (the complete runtime's DXMT
+/// and Wine build lanes plus `lib/vkd3d-proton` and `lib/dxvk`).
 /// These sources always retain the canonical copy, so a stale deployed copy
 /// that matches its source can be safely deleted on a route switch instead of
 /// being quarantined. Returns the first matching source path, or `None` if no
@@ -887,12 +900,17 @@ fn runtime_source_for_dll(dll_path: &Path, ms_root: &Path) -> Option<PathBuf> {
     // Known deploy-from source roots, derived from the PipelineNode deploy_dlls
     // source_subpath values across M9/M10/M10_32/M11/M11_32/M12.
     const SOURCE_ROOTS: &[&str] = &[
-        "lib/dxmt/x86_64-windows",
-        "lib/dxmt/i386-windows",
-        "lib/dxmt_m12/x86_64-windows",
-        "lib/wine/x86_64-windows",
-        "lib/wine/i386-windows",
-        "lib/metalsharp/x86_64-windows",
+        "build-ec/dxmt-v0.80/aarch64-windows",
+        "build-ec/dxmt-v0.80/i386-windows",
+        "build-ec/dlls/d3d9/x86_64-windows",
+        "build-ec/dlls/d3d9/i386-windows",
+        "build-ec/dlls/d3d10/x86_64-windows",
+        "build-ec/dlls/d3d10/i386-windows",
+        "build-ec/dlls/d3d10_1/x86_64-windows",
+        "build-ec/dlls/d3d10_1/i386-windows",
+        "build-ec/dlls/dxgi/i386-windows",
+        "lib/vkd3d-proton/x86_64",
+        "lib/dxvk/x86_64",
     ];
     for root in SOURCE_ROOTS {
         let candidate = ms_root.join(root).join(&filename);
@@ -913,6 +931,7 @@ fn is_metalsharp_route_dll_conflict(path: &Path) -> bool {
             | "d3d10core.dll"
             | "d3d11.dll"
             | "d3d12.dll"
+            | "d3d12core.dll"
             | "dxgi.dll"
             | "dxgi_dxmt.dll"
             | "nvapi64.dll"
@@ -1006,10 +1025,7 @@ fn deploy_prefix_route_dlls(
         if !deploy.source_present {
             continue;
         }
-        if !matches!(
-            deploy.filename.as_str(),
-            "d3d12.dll" | "dxgi.dll" | "dxgi_dxmt.dll" | "d3d11.dll" | "d3d10core.dll" | "winemetal.dll"
-        ) {
+        if !matches!(deploy.filename.as_str(), "d3d12.dll" | "d3d12core.dll" | "dxgi.dll") {
             continue;
         }
         std::fs::copy(&deploy.source_path, system32.join(&deploy.filename))?;
@@ -1021,51 +1037,6 @@ fn wine_debug_value() -> String {
     std::env::var("METALSHARP_WINEDEBUG").unwrap_or_else(|_| "-all".to_string())
 }
 
-fn repair_metalsharp_wine_wrapper_env_order() -> Result<(), Box<dyn std::error::Error>> {
-    let home = dirs::home_dir().ok_or("no home dir")?;
-    let wrapper = crate::platform::metalsharp_home_dir_for(&home)
-        .join("runtime")
-        .join("wine")
-        .join("bin")
-        .join("metalsharp-wine");
-    if !wrapper.exists() {
-        return Ok(());
-    }
-
-    let script = std::fs::read_to_string(&wrapper)?;
-    let mut repaired = script.clone();
-    let winedll_block = r#"if [ -n "${WINEDLLPATH:-}" ]; then
-  export WINEDLLPATH="$WINEDLLPATH:$MS_LIB/wine/x86_64-windows:$MS_LIB/wine/i386-windows"
-else
-  export WINEDLLPATH="$MS_LIB/wine/x86_64-windows:$MS_LIB/wine/i386-windows"
-fi
-"#;
-    if let (Some(start), Some(end)) =
-        (repaired.find("export WINELOADER=\"$MS_WINE\"\n"), repaired.find("export WINEDEBUG=\"${WINEDEBUG:--all}\""))
-    {
-        let replace_start = start + "export WINELOADER=\"$MS_WINE\"\n".len();
-        repaired.replace_range(replace_start..end, winedll_block);
-    }
-
-    let dyld_block = r#"if [ -n "${DYLD_FALLBACK_LIBRARY_PATH:-}" ]; then
-  export DYLD_FALLBACK_LIBRARY_PATH="$DYLD_FALLBACK_LIBRARY_PATH:$MS_LIB:$MS_LIB/wine/x86_64-unix"
-else
-  export DYLD_FALLBACK_LIBRARY_PATH="$MS_LIB:$MS_LIB/wine/x86_64-unix"
-fi
-"#;
-    if let (Some(start), Some(end)) =
-        (repaired.find("export WINEDATADIR=\"$MS_ROOT/share\"\n"), repaired.find("export MS_FWD_COMPAT_GL_CTX=1"))
-    {
-        let replace_start = start + "export WINEDATADIR=\"$MS_ROOT/share\"\n".len();
-        repaired.replace_range(replace_start..end, dyld_block);
-    }
-
-    if repaired != script {
-        std::fs::write(&wrapper, repaired)?;
-    }
-    Ok(())
-}
-
 pub fn launch_custom_with_pipeline(
     launch_id: u32,
     game_dir: &std::path::Path,
@@ -1110,10 +1081,6 @@ pub fn launch_custom_with_options(
     if !wine.exists() {
         return Err("MetalSharp Wine not found — run setup first".into());
     }
-    if node.backend == "dxmt" {
-        repair_metalsharp_wine_wrapper_env_order()?;
-    }
-
     let mut recipe = super::recipe::build_custom_launch_recipe(launch_id, node, game_dir, Some(exe_path))?;
     recipe.launch_args.extend(launch_args.iter().cloned());
     let quarantined = quarantine_route_conflicts_for_recipe(&recipe)?;
@@ -1151,7 +1118,10 @@ pub fn launch_custom_with_options(
     }
     apply_cache_env(&mut cmd, node, cache_paths.as_ref(), &ms_root);
     if node.backend == "dxmt" {
-        cmd.env("DXMT_CONFIG_FILE", ms_root.join("etc").join("dxmt.conf").to_string_lossy().to_string());
+        let config = ms_root.join("etc").join("dxmt.conf");
+        if config.is_file() {
+            cmd.env("DXMT_CONFIG_FILE", config);
+        }
         cmd.env("DXMT_WINEMETAL_UNIXLIB", dxmt_winemetal_unixlib_path(&ms_root));
     }
     cmd.env("MS_GRAPHICS_BACKEND", node.graphics_backend);
@@ -1274,12 +1244,7 @@ fn prepare_readiness_report(recipe: &super::recipe::LaunchRecipe, env: &[(String
         recipe
             .dlls
             .iter()
-            .filter(|dll| {
-                matches!(
-                    dll.filename.as_str(),
-                    "d3d12.dll" | "dxgi.dll" | "dxgi_dxmt.dll" | "d3d11.dll" | "d3d10core.dll" | "winemetal.dll"
-                )
-            })
+            .filter(|dll| matches!(dll.filename.as_str(), "d3d12.dll" | "d3d12core.dll" | "dxgi.dll"))
             .map(|dll| {
                 let dest_path = prefix_system32.join(&dll.filename);
                 let source_sha256 =
@@ -1309,12 +1274,16 @@ fn prepare_readiness_report(recipe: &super::recipe::LaunchRecipe, env: &[(String
     let winedllpath = env_value("WINEDLLPATH").unwrap_or_default();
     let dyld_library_path = env_value("DYLD_LIBRARY_PATH").unwrap_or_default();
     let dyld_fallback_library_path = env_value("DYLD_FALLBACK_LIBRARY_PATH").unwrap_or_default();
-    let winemetal_unixlib = env_value("DXMT_WINEMETAL_UNIXLIB").unwrap_or_default();
+    let vkd3d_shader_cache = env_value("VKD3D_SHADER_CACHE_PATH").unwrap_or_default();
+    let dxvk_state_cache = env_value("DXVK_STATE_CACHE_PATH").unwrap_or_default();
     let m12_env_ok = recipe.pipeline != PipelineId::M12
-        || (winedllpath.contains("dxmt_m12/x86_64-windows")
-            && (dyld_library_path.contains("dxmt_m12/x86_64-unix")
-                || dyld_fallback_library_path.contains("dxmt_m12/x86_64-unix"))
-            && winemetal_unixlib == "winemetal.so");
+        || (winedllpath.contains("vkd3d-proton/x86_64")
+            && winedllpath.contains("dxvk/x86_64")
+            && (dyld_library_path.contains("build-ec/dlls/winevulkan")
+                || dyld_fallback_library_path.contains("build-ec/dlls/winevulkan"))
+            && !vkd3d_shader_cache.is_empty()
+            && !dxvk_state_cache.is_empty()
+            && env_value("DXMT_WINEMETAL_UNIXLIB").is_none());
 
     let ok = runtime_assets_ok && dlls_ok && prefix_dlls_ok && m12_env_ok;
     serde_json::json!({
@@ -1331,9 +1300,12 @@ fn prepare_readiness_report(recipe: &super::recipe::LaunchRecipe, env: &[(String
             "DYLD_LIBRARY_PATH": dyld_library_path,
             "DYLD_FALLBACK_LIBRARY_PATH": dyld_fallback_library_path,
             "WINEDLLOVERRIDES": env_value("WINEDLLOVERRIDES"),
-            "DXMT_WINEMETAL_UNIXLIB": winemetal_unixlib,
-            "requires_dxmt_m12_windows": recipe.pipeline == PipelineId::M12,
-            "requires_dxmt_m12_unix": recipe.pipeline == PipelineId::M12,
+            "VKD3D_SHADER_CACHE_PATH": vkd3d_shader_cache,
+            "DXVK_STATE_CACHE_PATH": dxvk_state_cache,
+            "DXMT_WINEMETAL_UNIXLIB": env_value("DXMT_WINEMETAL_UNIXLIB"),
+            "requires_vkd3d_proton": recipe.pipeline == PipelineId::M12,
+            "requires_dxvk_dxgi": recipe.pipeline == PipelineId::M12,
+            "requires_moltenvk_host": recipe.pipeline == PipelineId::M12,
         },
     })
 }
@@ -1502,12 +1474,42 @@ fn launch_dxmt_metal(appid: u32, node: &PipelineNode) -> Result<(u32, &'static s
     launch_dxmt_metal_with_context(appid, node, None, &[], None)
 }
 
+fn launch_vkd3d_proton_metal(
+    appid: u32,
+    node: &PipelineNode,
+) -> Result<(u32, &'static str), Box<dyn std::error::Error>> {
+    launch_vkd3d_proton_metal_with_context(appid, node, None, &[], None)
+}
+
+fn launch_vkd3d_proton_metal_with_context(
+    appid: u32,
+    node: &PipelineNode,
+    prefix_override: Option<&Path>,
+    extra_env: &[(String, String)],
+    log_path: Option<&Path>,
+) -> Result<(u32, &'static str), Box<dyn std::error::Error>> {
+    debug_assert_eq!(node.id, PipelineId::M12);
+    debug_assert_eq!(node.backend, "vkd3d-proton");
+    launch_wine_graphics_with_context(appid, node, prefix_override, extra_env, log_path)
+}
+
 fn launch_dxmt_metal_with_context(
     appid: u32,
     node: &PipelineNode,
     prefix_override: Option<&Path>,
     extra_env: &[(String, String)],
     log_path: Option<&Path>,
+) -> Result<(u32, &'static str), Box<dyn std::error::Error>> {
+    debug_assert!(node.id.is_dxmt_family());
+    launch_wine_graphics_with_context(appid, node, prefix_override, extra_env, log_path)
+}
+
+fn launch_wine_graphics_with_context(
+    appid: u32,
+    node: &PipelineNode,
+    prefix_override: Option<&Path>,
+    extra_env: &[(String, String)],
+    log_path: Option<&Path>,
 ) -> Result<(u32, &'static str), Box<dyn std::error::Error>> {
     let home = dirs::home_dir().ok_or("no home dir")?;
     let ms_root = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
@@ -1524,7 +1526,6 @@ fn launch_dxmt_metal_with_context(
     if !wine.exists() {
         return Err("MetalSharp Wine not found — run setup first".into());
     }
-    repair_metalsharp_wine_wrapper_env_order()?;
 
     prepare_start_protected_game_for_pipeline(appid, node.id);
     let recipe = super::recipe::build_launch_recipe(appid, node)?;
@@ -1550,14 +1551,7 @@ fn launch_dxmt_metal_with_context(
     deploy_d3d12_agility_sidecars(appid, node, game_dir)?;
 
     let cache_paths = build_cache_paths(&home, node, appid);
-    if node.id == PipelineId::M12
-        && std::env::var("METALSHARP_M12_LIVE_MSC_SIDECAR")
-            .map(|value| !value.is_empty() && value != "0")
-            .unwrap_or(false)
-    {
-        spawn_metalshaderconverter_sidecar(appid, &home, cache_paths.as_ref());
-    }
-    let dxmt_config_file = ms_root.join("etc").join("dxmt.conf").to_string_lossy().to_string();
+    let dxmt_config_file = ms_root.join("etc").join("dxmt.conf");
 
     let mut cmd = Command::new(&wine);
     cmd.current_dir(exe_dir)
@@ -1578,7 +1572,9 @@ fn launch_dxmt_metal_with_context(
 
     apply_cache_env(&mut cmd, node, cache_paths.as_ref(), &ms_root);
     if node.backend == "dxmt" {
-        cmd.env("DXMT_CONFIG_FILE", &dxmt_config_file);
+        if dxmt_config_file.is_file() {
+            cmd.env("DXMT_CONFIG_FILE", &dxmt_config_file);
+        }
         cmd.env("DXMT_WINEMETAL_UNIXLIB", dxmt_winemetal_unixlib_path(&ms_root));
     }
 
@@ -2352,7 +2348,10 @@ fn steam_pipeline_env_pairs(home: &PathBuf, node: &PipelineNode, appid: u32) ->
         env.push(("WINEDLLPATH".to_string(), build_winedllpath(&ms_root, &node.winedllpath_dirs)));
     }
     if node.backend == "dxmt" {
-        env.push(("DXMT_CONFIG_FILE".to_string(), ms_root.join("etc").join("dxmt.conf").to_string_lossy().to_string()));
+        let config = ms_root.join("etc").join("dxmt.conf");
+        if config.is_file() {
+            env.push(("DXMT_CONFIG_FILE".to_string(), config.to_string_lossy().to_string()));
+        }
         env.push(("DXMT_WINEMETAL_UNIXLIB".to_string(), dxmt_winemetal_unixlib_path(&ms_root)));
     }
     env.push(("MS_GRAPHICS_BACKEND".to_string(), node.graphics_backend.to_string()));
@@ -2380,11 +2379,15 @@ fn is_reserved_route_env_key(pipeline_id: PipelineId, key: &str) -> bool {
             | "WINEDLLPATH"
             | "DYLD_LIBRARY_PATH"
             | "DYLD_FALLBACK_LIBRARY_PATH"
-            | "DXMT_WINEMETAL_UNIXLIB"
-            | "DXMT_CONFIG_FILE"
+            | "VKD3D_SHADER_CACHE_PATH"
+            | "VKD3D_LOG_FILE"
+            | "VKD3D_DEBUG"
+            | "DXVK_STATE_CACHE_PATH"
+            | "DXVK_LOG_PATH"
+            | "DXVK_LOG_LEVEL"
+            | "VK_ICD_FILENAMES"
             | "MS_GRAPHICS_BACKEND"
             | "WINEMSYNC"
-            | "DXMT_LOG_PATH"
     )
 }
 
@@ -2407,66 +2410,15 @@ fn app_compat_env_pairs_with_logs(
         ];
     }
 
-    if appid == 1962700 && pipeline_id == PipelineId::M12 {
-        let mut env = vec![
-            ("DXMT_D3D12_ENABLE_GEOMETRY_MESH".to_string(), "1".to_string()),
-            ("DXMT_D3D12_FORCE_SWAPCHAIN_BLIT".to_string(), "1".to_string()),
-            ("DXMT_D3D12_AUTOPRESENT_SWAPCHAIN".to_string(), "1".to_string()),
-            ("DXMT_D3D12_LIVE_PRESENT".to_string(), "1".to_string()),
-            ("DXMT_D3D12_REASSERT_WINDOW_HANDOFF".to_string(), "1".to_string()),
-            ("DXMT_D3D12_DISABLE_RUNTIME_MSC".to_string(), "1".to_string()),
-            ("DXMT_D3D12_FORCE_COLOR_WRITE_STATE".to_string(), "1".to_string()),
-            ("DXMT_METALFX_SPATIAL_SWAPCHAIN".to_string(), "0".to_string()),
-            ("DXMT_METALFX_SPATIAL".to_string(), "0".to_string()),
-            ("DXMT_METALFX_TEMPORAL".to_string(), "0".to_string()),
-            ("DXMT_CONFIG".to_string(), "d3d11.preferredMaxFrameRate=60".to_string()),
-        ];
+    if pipeline_id == PipelineId::M12 {
+        let mut env = Vec::new();
         if graphics_runtime_logs {
             env.extend([
-                ("DXMT_DXGI_TRACE".to_string(), "1".to_string()),
-                ("DXMT_WINEMETAL_DEBUG".to_string(), "1".to_string()),
-                ("DXMT_D3D12_TRACE".to_string(), "1".to_string()),
-                ("DXMT_D3D12_TRACE_COMPONENTS".to_string(), "Device,Queue,SwapChain,Presenter,PSO".to_string()),
-                ("DXMT_D3D12_TRACE_MAX_MB".to_string(), "16".to_string()),
-                ("DXMT_D3D12_TIMING_MIN_MS".to_string(), "0".to_string()),
-                ("DXMT_D3D12_PRESENT_LOG_INTERVAL".to_string(), "120".to_string()),
-                ("DXMT_DUMP_MSL".to_string(), "1".to_string()),
+                ("VKD3D_DEBUG".to_string(), "warn".to_string()),
+                ("DXVK_LOG_LEVEL".to_string(), "warn".to_string()),
+                ("MVK_CONFIG_LOG_LEVEL".to_string(), "2".to_string()),
             ]);
         }
-        if std::env::var("METALSHARP_M12_DIAGNOSTIC_CAPTURE")
-            .map(|value| !value.is_empty() && value != "0")
-            .unwrap_or(false)
-        {
-            env.push(("DXMT_D3D12_SWAPCHAIN_READBACK".to_string(), "1".to_string()));
-            env.push(("DXMT_D3D12_SWAPCHAIN_READBACK_INTERVAL".to_string(), "30".to_string()));
-            env.push(("DXMT_D3D12_FINAL_RENDER_SNAPSHOT".to_string(), "1".to_string()));
-            env.push(("DXMT_D3D12_LIVE_PRESENT".to_string(), "0".to_string()));
-            env.push(("DXMT_D3D12_PRESENT_LOG_INTERVAL".to_string(), "30".to_string()));
-        }
-        if std::env::var("METALSHARP_M12_FORCE_SWAPCHAIN_COLOR")
-            .map(|value| !value.is_empty() && value != "0")
-            .unwrap_or(false)
-        {
-            env.push(("DXMT_D3D12_FORCE_SWAPCHAIN_COLOR".to_string(), "1".to_string()));
-        }
-        if std::env::var("METALSHARP_M12_FORCE_COLOR_WRITE_STATE")
-            .map(|value| !value.is_empty() && value != "0")
-            .unwrap_or(false)
-        {
-            env.push(("DXMT_D3D12_FORCE_COLOR_WRITE_STATE".to_string(), "1".to_string()));
-        }
-        if std::env::var("METALSHARP_M12_FORCE_DIAGNOSTIC_FRAGMENT")
-            .map(|value| !value.is_empty() && value != "0")
-            .unwrap_or(false)
-        {
-            env.push(("DXMT_D3D12_FORCE_DIAGNOSTIC_FRAGMENT".to_string(), "1".to_string()));
-        }
-        if std::env::var("METALSHARP_M12_FORCE_DIAGNOSTIC_FULLSCREEN")
-            .map(|value| !value.is_empty() && value != "0")
-            .unwrap_or(false)
-        {
-            env.push(("DXMT_D3D12_FORCE_DIAGNOSTIC_FULLSCREEN".to_string(), "1".to_string()));
-        }
         return env;
     }
     Vec::new()
@@ -2540,6 +2492,14 @@ fn cache_env_pairs_with_logs(
                 env.push(("VK_ICD_FILENAMES".to_string(), moltenvk_icd.to_string_lossy().to_string()));
             }
         },
+        "vkd3d-proton" => {
+            env.push(("VKD3D_SHADER_CACHE_PATH".to_string(), shader_dir.clone()));
+            env.push(("DXVK_STATE_CACHE_PATH".to_string(), shader_dir));
+            if graphics_runtime_logs {
+                env.push(("VKD3D_LOG_FILE".to_string(), format!("{}vkd3d-proton.log", log_dir)));
+                env.push(("DXVK_LOG_PATH".to_string(), cache.log.clone()));
+            }
+        },
         "wine32" | "wine" | "wine-steam" => {
             env.push(("DXMT_SHADER_CACHE_PATH".to_string(), shader_dir.clone()));
             env.push(("DXVK_STATE_CACHE_PATH".to_string(), shader_dir));
@@ -4841,176 +4801,6 @@ pub fn deploy_steam_appid(game_dir: &Path, appid: u32) {
     }
 }
 
-fn spawn_metalshaderconverter_sidecar(appid: u32, home: &Path, cache_paths: Option<&CachePaths>) {
-    let tool_candidates = [
-        PathBuf::from("/usr/local/bin/metal-shaderconverter"),
-        PathBuf::from("/opt/homebrew/bin/metal-shaderconverter"),
-        PathBuf::from("/opt/metal-shaderconverter/bin/metal-shaderconverter"),
-    ];
-    let Some(tool_path) = tool_candidates.into_iter().find(|path| path.exists()) else {
-        return;
-    };
-
-    let log_dir = cache_paths
-        .map(|cache| PathBuf::from(&cache.pipeline))
-        .unwrap_or_else(|| crate::platform::metalsharp_home_dir_for(&home).join("logs"));
-    let _ = std::fs::create_dir_all(&log_dir);
-    let log_path = log_dir.join(format!("d3d12-metalshaderconverter-{}.log", appid));
-    let cache_dir = cache_paths
-        .map(|cache| PathBuf::from(&cache.shader))
-        .unwrap_or_else(|| PathBuf::from("/tmp/dxmt_shader_cache"));
-    if let Ok(entries) = std::fs::read_dir(&cache_dir) {
-        for entry in entries.flatten() {
-            let path = entry.path();
-            let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
-                continue;
-            };
-            if name.ends_with(".msc.fail") || name.ends_with(".msc.lock") {
-                let _ = std::fs::remove_file(path);
-            }
-        }
-    }
-
-    std::thread::spawn(move || {
-        let deadline = Instant::now() + Duration::from_secs(180);
-        let launch_start = SystemTime::now();
-        let max_active_compiles = 4usize;
-
-        while Instant::now() < deadline {
-            if let Ok(entries) = std::fs::read_dir(&cache_dir) {
-                let mut pending = Vec::new();
-                let mut active_locks = 0usize;
-                for entry in entries.flatten() {
-                    let path = entry.path();
-                    if path.extension().and_then(|ext| ext.to_str()) == Some("lock")
-                        && path.file_name().and_then(|name| name.to_str()).map(|name| name.ends_with(".msc.lock"))
-                            == Some(true)
-                    {
-                        active_locks += 1;
-                    }
-                    if path.extension().and_then(|ext| ext.to_str()) != Some("dxbc") {
-                        continue;
-                    }
-                    let Ok(modified) = entry.metadata().and_then(|meta| meta.modified()) else {
-                        continue;
-                    };
-                    if modified + Duration::from_secs(2) < launch_start {
-                        continue;
-                    }
-                    pending.push((modified, path));
-                }
-
-                pending.sort_by_key(|entry| std::cmp::Reverse(entry.0));
-
-                for (_modified, path) in pending {
-                    if active_locks >= max_active_compiles {
-                        break;
-                    }
-                    let metallib_path = path.with_extension("metallib");
-                    let reflection_path = path.with_extension("json");
-                    let vertex_layout_path = path.with_extension("vertex-layout.json");
-                    let is_geometry_mesh_shader = path
-                        .file_name()
-                        .and_then(|name| name.to_str())
-                        .map(|name| name.ends_with(".geom.gsmesh.dxbc"))
-                        .unwrap_or(false);
-                    let use_gs_ts_emulation = vertex_layout_path.exists() && !is_geometry_mesh_shader;
-                    let stage_in_path = path.with_extension("stageIn.metallib");
-                    let fail_path = path.with_extension("msc.fail");
-                    if metallib_path.exists()
-                        && reflection_path.exists()
-                        && (!use_gs_ts_emulation || stage_in_path.exists())
-                    {
-                        continue;
-                    }
-                    if fail_path.exists() {
-                        continue;
-                    }
-
-                    let lock_path = path.with_extension("msc.lock");
-                    let lock_file = OpenOptions::new().write(true).create_new(true).open(&lock_path);
-                    let Ok(_lock_guard) = lock_file else {
-                        continue;
-                    };
-                    active_locks += 1;
-
-                    let tool_path = tool_path.clone();
-                    let log_path = log_path.clone();
-                    std::thread::spawn(move || {
-                        let mut log = OpenOptions::new().create(true).append(true).open(&log_path).ok();
-                        if let Some(log) = log.as_mut() {
-                            let _ = writeln!(log, "compile_start dxbc={}", path.display());
-                        }
-
-                        let mut command = Command::new(&tool_path);
-                        command
-                            .arg("-o")
-                            .arg(&metallib_path)
-                            .arg(&path)
-                            .arg(format!("--output-reflection-file={}", reflection_path.display()))
-                            .arg("--deployment-os=macOS")
-                            .arg("--minimum-os-build-version=15.0.0");
-                        if use_gs_ts_emulation {
-                            command
-                                .arg("--enable-gs-ts-emulation")
-                                .arg("--vertex-stage-in")
-                                .arg(format!("--vertex-input-layout-file={}", vertex_layout_path.display()));
-                        }
-                        let output = command.output();
-
-                        match output {
-                            Ok(result) => {
-                                let stdout_text = String::from_utf8_lossy(&result.stdout);
-                                let stderr_text = String::from_utf8_lossy(&result.stderr);
-                                if result.status.success() {
-                                    let _ = std::fs::remove_file(&fail_path);
-                                } else {
-                                    let failure_summary = if stderr_text.trim().is_empty() {
-                                        format!("metal-shaderconverter failed with {}", result.status)
-                                    } else {
-                                        stderr_text.trim().to_string()
-                                    };
-                                    let _ = std::fs::write(&fail_path, failure_summary);
-                                }
-                                if let Some(log) = log.as_mut() {
-                                    let _ = writeln!(
-                                        log,
-                                        "compile_end dxbc={} status={} metallib={} reflection={} gs_ts_emulation={}",
-                                        path.display(),
-                                        result.status,
-                                        metallib_path.exists(),
-                                        reflection_path.exists(),
-                                        use_gs_ts_emulation
-                                    );
-                                    if !stdout_text.is_empty() {
-                                        let _ = log.write_all(stdout_text.as_bytes());
-                                    }
-                                    if !stderr_text.is_empty() {
-                                        let _ = log.write_all(stderr_text.as_bytes());
-                                    }
-                                }
-                            },
-                            Err(err) => {
-                                let _ = std::fs::write(
-                                    &fail_path,
-                                    format!("metal-shaderconverter invocation failed: {}", err),
-                                );
-                                if let Some(log) = log.as_mut() {
-                                    let _ = writeln!(log, "compile_error dxbc={} err={}", path.display(), err);
-                                }
-                            },
-                        }
-
-                        let _ = std::fs::remove_file(&lock_path);
-                    });
-                }
-            }
-
-            std::thread::sleep(Duration::from_millis(100));
-        }
-    });
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -5049,32 +4839,17 @@ mod tests {
     }
 
     #[test]
-    fn m12_pipeline_deploy_list_includes_d3d12_and_uses_isolated_dxmt_m12_surface() {
-        // Phase 3 contract: M12 must deploy d3d12.dll (plus dxgi/d3d11/
-        // d3d10core/winemetal) from the isolated lib/dxmt_m12 surface.
+    fn m12_pipeline_deploy_list_uses_vkd3d_proton_with_dxvk_dxgi() {
         let node = get_pipeline(PipelineId::M12);
-        let filenames: Vec<&str> = node.deploy_dlls.iter().map(|d| d.filename).collect();
-        let required = [
-            "d3d12.dll",
-            "d3d11.dll",
-            "dxgi.dll",
-            "dxgi_dxmt.dll",
-            "d3d10core.dll",
-            "winemetal.dll",
-            "nvapi64.dll",
-            "nvngx.dll",
-        ];
-        assert_eq!(filenames.len(), required.len(), "M12 deploy list must be the Elden-proven 8 DLL set");
-        for required in required {
-            assert!(filenames.contains(&required), "M12 deploy list must include {} (got {:?})", required, filenames);
-        }
-        for deploy in &node.deploy_dlls {
-            assert_eq!(
-                deploy.source_subpath, "lib/dxmt_m12/x86_64-windows",
-                "M12 DLL {} must come from the isolated PR230 dxmt_m12 runtime surface",
-                deploy.filename
-            );
-        }
+        let route: Vec<(&str, &str)> = node.deploy_dlls.iter().map(|d| (d.source_subpath, d.filename)).collect();
+        assert_eq!(
+            route,
+            vec![
+                ("lib/vkd3d-proton/x86_64", "d3d12.dll"),
+                ("lib/vkd3d-proton/x86_64", "d3d12core.dll"),
+                ("lib/dxvk/x86_64", "dxgi.dll"),
+            ]
+        );
     }
 
     #[test]
@@ -5153,28 +4928,31 @@ mod tests {
     }
 
     #[test]
-    fn m12_quarantines_stale_m11_route_dlls_before_deploying_isolated_dxmt_m12() {
+    fn m12_quarantines_stale_m11_route_dlls_before_deploying_vkd3d_proton() {
         let root = test_dir("m12-route-quarantine-switchback");
         let game_dir = root.join("game");
         let exe_dir = game_dir.join("Binaries").join("Win64");
-        let source_dir = root.join("runtime").join("wine").join("lib").join("dxmt_m12").join("x86_64-windows");
+        let source_dir = root.join("runtime").join("wine").join("lib").join("vkd3d-proton").join("x86_64");
+        let dxvk_dir = root.join("runtime").join("wine").join("lib").join("dxvk").join("x86_64");
         std::fs::create_dir_all(&exe_dir).unwrap();
         std::fs::create_dir_all(&source_dir).unwrap();
+        std::fs::create_dir_all(&dxvk_dir).unwrap();
         std::fs::write(exe_dir.join("Game.exe"), b"exe").unwrap();
         std::fs::write(exe_dir.join("d3d11.dll"), b"stale m11 d3d11").unwrap();
         std::fs::write(exe_dir.join("dxgi.dll"), b"stale m11 dxgi").unwrap();
         std::fs::write(exe_dir.join("winemetal.dll"), b"stale m11 winemetal").unwrap();
 
-        let route_dlls = ["d3d12.dll", "d3d11.dll", "dxgi.dll", "dxgi_dxmt.dll", "winemetal.dll"];
+        let route_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"];
         for dll in route_dlls {
-            std::fs::write(source_dir.join(dll), format!("isolated m12 {dll}")).unwrap();
+            let dir = if dll == "dxgi.dll" { &dxvk_dir } else { &source_dir };
+            std::fs::write(dir.join(dll), format!("vkd3d m12 {dll}")).unwrap();
         }
 
         let recipe = recipe::LaunchRecipe {
             appid: 42,
             pipeline: PipelineId::M12,
             pipeline_name: "M12".into(),
-            backend: "dxmt".into(),
+            backend: "vkd3d-proton".into(),
             game_dir: Some(game_dir.clone()),
             exe_path: Some(exe_dir.join("Game.exe")),
             exe_name: Some("Game.exe".into()),
@@ -5183,9 +4961,13 @@ mod tests {
             dlls: route_dlls
                 .iter()
                 .map(|dll| recipe::RecipeDll {
-                    source_subpath: "lib/dxmt_m12/x86_64-windows".into(),
+                    source_subpath: if *dll == "dxgi.dll" {
+                        "lib/dxvk/x86_64".into()
+                    } else {
+                        "lib/vkd3d-proton/x86_64".into()
+                    },
                     filename: (*dll).into(),
-                    source_path: source_dir.join(dll),
+                    source_path: if *dll == "dxgi.dll" { dxvk_dir.join(dll) } else { source_dir.join(dll) },
                     dest_path: exe_dir.join(dll),
                     source_present: true,
                 })
@@ -5196,13 +4978,13 @@ mod tests {
 
         let moved = quarantine_route_conflicts_for_recipe(&recipe).expect("quarantine stale M11 routes");
         assert_eq!(moved, 3, "stale d3d11/dxgi/winemetal should be quarantined before M12 deploy");
-        deploy_recipe_dlls(&recipe).expect("deploy M12 isolated DXMT route");
+        deploy_recipe_dlls(&recipe).expect("deploy M12 vkd3d-proton route");
 
         for dll in route_dlls {
             assert_eq!(
                 std::fs::read_to_string(exe_dir.join(dll)).unwrap(),
-                format!("isolated m12 {dll}"),
-                "M12 switch-back must deploy {dll} from dxmt_m12"
+                format!("vkd3d m12 {dll}"),
+                "M12 switch-back must deploy {dll} from the Vulkan route"
             );
         }
         let marker = game_dir.join(".metalsharp").join("route-quarantine").join("latest-manifest.json");
@@ -5259,8 +5041,8 @@ mod tests {
     }
 
     #[test]
-    fn m12_dry_run_verifies_unix_sidecars_and_marks_missing_artifacts() {
-        // Phase 3: the M12 dry-run must enumerate the x86_64-unix sidecars and
+    fn m12_dry_run_verifies_vulkan_host_boundary_and_marks_missing_artifacts() {
+        // M12 dry-run must enumerate the Wine Vulkan/MoltenVK host boundary and
         // report missing required artifacts as a structured failure (not a
         // silent ok=true). With an empty temp home, all artifacts are absent.
         let home = std::env::temp_dir().join("ms-m12-dryrun-empty");
@@ -5269,7 +5051,7 @@ mod tests {
 
         let dry = pipeline_dry_run_for(&home, 2379780, Some(PipelineId::M12));
 
-        // Unix sidecars must be enumerated for the M12 lane.
+        // Host-boundary artifacts must be enumerated for the M12 lane.
         let sidecar_names: Vec<String> = dry
             .get("unix_sidecars")
             .and_then(|v| v.as_array())
@@ -5277,7 +5059,7 @@ mod tests {
             .iter()
             .map(|s| s.get("filename").unwrap().as_str().unwrap().to_string())
             .collect();
-        for required in ["winemetal.so", "libc++.1.dylib", "libc++abi.1.dylib", "libunwind.1.dylib"] {
+        for required in ["winevulkan.so", "winevulkan.dll", "vulkan-1.dll", "libMoltenVK.dylib"] {
             assert!(
                 sidecar_names.contains(&required.to_string()),
                 "M12 dry-run must verify {}: {:?}",
@@ -5306,16 +5088,13 @@ mod tests {
     }
 
     #[test]
-    fn m12_pipeline_env_vars_set_winemetal_overrides_and_shader_cache() {
-        // Phase 3 contract: the M12 env builder must set the winemetal
-        // WINEDLLOVERRIDES, route the wine DLL path to dxmt_m12, and point the
-        // shader cache at the isolated m12 lane.
+    fn m12_pipeline_env_vars_set_vkd3d_dxgi_overrides_and_shader_cache() {
         let node = get_pipeline(PipelineId::M12);
-        assert!(node.wine_overrides.unwrap_or("").contains("winemetal"));
-        assert!(
-            node.winedllpath_dirs.iter().any(|d| d.starts_with("lib/dxmt_m12")),
-            "M12 winedllpath must route to dxmt_m12"
-        );
+        let overrides = node.wine_overrides.unwrap_or("");
+        assert!(overrides.contains("d3d12,d3d12core,dxgi=n,b"));
+        assert!(!overrides.contains("winemetal"));
+        assert!(node.winedllpath_dirs.contains(&"lib/vkd3d-proton/x86_64"));
+        assert!(node.winedllpath_dirs.contains(&"lib/dxvk/x86_64"));
         assert_eq!(node.shader_cache_subdir, Some("m12"), "M12 shader cache must be isolated under m12");
     }
 
@@ -5344,7 +5123,7 @@ mod tests {
     }
 
     #[test]
-    fn m12_dxmt_log_path_uses_shared_logs_folder_when_developer_logs_enabled() {
+    fn m12_vkd3d_log_path_uses_shared_logs_folder_when_developer_logs_enabled() {
         let home = test_dir("m12-log-path");
         let node = get_pipeline(PipelineId::M12);
         let cache = build_cache_paths(&home, node, 1583230).expect("m12 cache paths");
@@ -5355,17 +5134,17 @@ mod tests {
             &crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine"),
             true,
         );
-        let dxmt_log_path =
-            env.iter().find(|(key, _)| key == "DXMT_LOG_PATH").map(|(_, value)| value.as_str()).unwrap_or_default();
+        let vkd3d_log_path =
+            env.iter().find(|(key, _)| key == "VKD3D_LOG_FILE").map(|(_, value)| value.as_str()).unwrap_or_default();
 
-        assert!(dxmt_log_path.contains("/logs/m12-pipeline/1583230/"));
-        assert!(!dxmt_log_path.contains("/pipeline-cache/"));
+        assert!(vkd3d_log_path.contains("/logs/m12-pipeline/1583230/"));
+        assert!(!vkd3d_log_path.contains("/pipeline-cache/"));
         let _ = std::fs::remove_dir_all(home);
     }
 
     #[test]
     fn dxmt_family_env_uses_seventy_percent_upscale_and_cache_paths() {
-        for pipeline_id in [PipelineId::M9, PipelineId::M10, PipelineId::M11, PipelineId::M12] {
+        for pipeline_id in [PipelineId::M9, PipelineId::M10, PipelineId::M11] {
             let home = test_dir(&format!("dxmt-env-{:?}", pipeline_id));
             let node = get_pipeline(pipeline_id);
 
@@ -5438,11 +5217,15 @@ mod tests {
             "WINEDLLPATH",
             "DYLD_LIBRARY_PATH",
             "DYLD_FALLBACK_LIBRARY_PATH",
-            "DXMT_WINEMETAL_UNIXLIB",
-            "DXMT_CONFIG_FILE",
+            "VKD3D_SHADER_CACHE_PATH",
+            "VKD3D_LOG_FILE",
+            "VKD3D_DEBUG",
+            "DXVK_STATE_CACHE_PATH",
+            "DXVK_LOG_PATH",
+            "DXVK_LOG_LEVEL",
+            "VK_ICD_FILENAMES",
             "MS_GRAPHICS_BACKEND",
             "WINEMSYNC",
-            "DXMT_LOG_PATH",
         ] {
             assert!(is_reserved_route_env_key(PipelineId::M12, key), "{} must be reserved for M12", key);
             assert!(!is_reserved_route_env_key(PipelineId::M11, key), "{} should remain overridable outside M12", key);
@@ -5459,20 +5242,14 @@ mod tests {
         let keys: std::collections::HashSet<_> = env.iter().map(|(key, _)| key.as_str()).collect();
 
         assert!(keys.contains("WINEDLLOVERRIDES"));
-        assert!(keys.contains("DXMT_CONFIG_FILE"));
         assert!(keys.contains("SteamAppId"));
         assert!(keys.contains("SteamGameId"));
         assert!(keys.contains("SteamOverlayGameId"));
-        assert!(keys.contains("DXMT_SHADER_CACHE_PATH"));
-        assert!(keys.contains("DXMT_PIPELINE_CACHE_PATH"));
-        assert!(!keys.contains("DXMT_LOG_PATH"));
+        assert!(keys.contains("VKD3D_SHADER_CACHE_PATH"));
+        assert!(keys.contains("DXVK_STATE_CACHE_PATH"));
+        assert!(!keys.contains("VKD3D_LOG_FILE"));
         assert!(keys.contains("METALSHARP_CACHE_SUMMARY"));
-        assert!(keys.contains("DXMT_CONFIG"));
-        assert_eq!(env_value(&env, "DXMT_D3D12_UE_SM6_COMPAT"), Some("1"));
-        let unixlib =
-            env.iter().find(|(key, _)| key == "DXMT_WINEMETAL_UNIXLIB").map(|(_, value)| value.as_str()).unwrap();
-        assert_eq!(unixlib, "winemetal.so");
-        assert!(keys.contains("DXMT_ASYNC_PIPELINE_COMPILE"));
+        assert!(!env.iter().any(|(key, _)| key.starts_with("DXMT")));
         assert_eq!(env.iter().find(|(key, _)| key == "SteamAppId").map(|(_, value)| value.as_str()), Some("1583230"));
         assert_eq!(env.iter().find(|(key, _)| key == "SteamGameId").map(|(_, value)| value.as_str()), Some("1583230"));
         assert_eq!(
@@ -5481,7 +5258,9 @@ mod tests {
         );
         let overrides = env.iter().find(|(key, _)| key == "WINEDLLOVERRIDES").map(|(_, value)| value).unwrap();
         assert!(overrides.contains("d3d12"));
-        assert!(overrides.contains("dxgi_dxmt"));
+        assert!(overrides.contains("d3d12core"));
+        assert!(overrides.contains("dxgi"));
+        assert!(!overrides.contains("dxgi_dxmt"));
         assert!(overrides.contains("gameoverlayrenderer,gameoverlayrenderer64=d"));
         assert!(!keys.contains("CX_ROOT"));
         assert!(!keys.contains("WINESERVER"));
@@ -5489,23 +5268,23 @@ mod tests {
         assert!(!keys.contains("WINEDATADIR"));
         assert!(!keys.contains("MS_ROOT"));
         let winedllpath = env_value(&env, "WINEDLLPATH").unwrap_or_default();
-        assert!(winedllpath.contains("dxmt_m12/x86_64-windows"));
+        assert!(winedllpath.contains("vkd3d-proton/x86_64"));
+        assert!(winedllpath.contains("dxvk/x86_64"));
         assert!(!winedllpath.contains("lib/metalsharp"));
-        assert!(env_value(&env, "DYLD_LIBRARY_PATH").unwrap_or_default().contains("dxmt_m12/x86_64-unix"));
-        assert!(env_value(&env, "DYLD_FALLBACK_LIBRARY_PATH").unwrap_or_default().contains("dxmt_m12/x86_64-unix"));
+        assert!(env_value(&env, "DYLD_LIBRARY_PATH").unwrap_or_default().contains("build-ec/dlls/winevulkan"));
+        assert!(env_value(&env, "DYLD_FALLBACK_LIBRARY_PATH").unwrap_or_default().contains("build-ec/dlls/winevulkan"));
         let _ = std::fs::remove_dir_all(home);
     }
 
     #[test]
-    fn subnautica2_m12_trace_env_is_opt_in_only() {
+    fn m12_vulkan_trace_env_is_opt_in_only() {
         let default_env = app_compat_env_pairs_with_logs(1962700, PipelineId::M12, false);
-        assert!(default_env.iter().any(|(key, _)| key == "DXMT_D3D12_ENABLE_GEOMETRY_MESH"));
-        assert!(!default_env.iter().any(|(key, _)| key == "DXMT_D3D12_TRACE"));
-        assert!(!default_env.iter().any(|(key, _)| key == "DXMT_DUMP_MSL"));
+        assert!(default_env.is_empty());
 
         let log_env = app_compat_env_pairs_with_logs(1962700, PipelineId::M12, true);
-        assert!(log_env.iter().any(|(key, value)| key == "DXMT_D3D12_TRACE" && value == "1"));
-        assert!(log_env.iter().any(|(key, value)| key == "DXMT_DUMP_MSL" && value == "1"));
+        assert!(log_env.iter().any(|(key, value)| key == "VKD3D_DEBUG" && value == "warn"));
+        assert!(log_env.iter().any(|(key, value)| key == "DXVK_LOG_LEVEL" && value == "warn"));
+        assert!(log_env.iter().all(|(key, _)| !key.starts_with("DXMT")));
     }
 
     #[test]
@@ -5521,8 +5300,9 @@ mod tests {
         let m11 = get_pipeline(PipelineId::M11);
         assert_eq!(crate::platform::runtime_wine_binary(&ms_root), bin.join("metalsharp-wine"));
         assert_eq!(m12.requires_wine, m11.requires_wine);
-        assert_eq!(m12.backend, m11.backend);
-        assert!(m12.winedllpath_dirs.iter().any(|path| path.contains("dxmt_m12")));
+        assert_eq!(m12.backend, "vkd3d-proton");
+        assert_ne!(m12.backend, m11.backend);
+        assert!(m12.winedllpath_dirs.iter().any(|path| path.contains("vkd3d-proton")));
         let _ = std::fs::remove_dir_all(home);
     }
 
@@ -5744,10 +5524,12 @@ mod tests {
             assert!(winedllpath.is_some(), "{:?} missing WINEDLLPATH in env pairs", pipeline_id);
             let path = winedllpath.unwrap().1.as_str();
             assert!(!path.is_empty(), "{:?} WINEDLLPATH is empty", pipeline_id);
-            assert!(path.contains("x86_64-windows"), "{:?} WINEDLLPATH missing windows dir: {}", pipeline_id, path);
             if pipeline_id == PipelineId::M12 {
-                assert!(path.contains("dxmt_m12"), "M12 should use isolated M12 DLL path: {}", path);
+                assert!(path.contains("vkd3d-proton/x86_64"), "M12 should use vkd3d-proton: {}", path);
+                assert!(path.contains("dxvk/x86_64"), "M12 should use DXVK DXGI: {}", path);
+                assert!(!path.contains("dxmt"), "M12 must not use DXMT: {}", path);
             } else {
+                assert!(path.contains("windows"), "{:?} WINEDLLPATH missing Windows DLL dir: {}", pipeline_id, path);
                 assert!(!path.contains("dxmt_m12"), "{:?} should not use isolated M12 DLL path: {}", pipeline_id, path);
             }
             let _ = std::fs::remove_dir_all(&home);
@@ -5766,18 +5548,25 @@ mod tests {
     #[test]
     fn m12_prefix_route_dlls_stage_into_system32() {
         let root = test_dir("m12-prefix-route");
-        let source_dir = root.join("runtime").join("wine").join("lib").join("dxmt_m12").join("x86_64-windows");
+        let vkd3d_dir = root.join("runtime").join("wine").join("lib").join("vkd3d-proton").join("x86_64");
+        let dxvk_dir = root.join("runtime").join("wine").join("lib").join("dxvk").join("x86_64");
         let prefix = root.join("prefix-steam");
-        std::fs::create_dir_all(&source_dir).expect("create source dir");
+        std::fs::create_dir_all(&vkd3d_dir).expect("create vkd3d dir");
+        std::fs::create_dir_all(&dxvk_dir).expect("create dxvk dir");
 
-        let dlls = ["d3d12.dll", "dxgi.dll", "dxgi_dxmt.dll", "d3d11.dll", "d3d10core.dll", "winemetal.dll"];
+        let dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"];
         let recipe_dlls: Vec<recipe::RecipeDll> = dlls
             .iter()
             .map(|dll| {
+                let source_dir = if *dll == "dxgi.dll" { &dxvk_dir } else { &vkd3d_dir };
                 let source_path = source_dir.join(dll);
                 std::fs::write(&source_path, format!("m12-{dll}")).expect("write route dll");
                 recipe::RecipeDll {
-                    source_subpath: "lib/dxmt_m12/x86_64-windows".to_string(),
+                    source_subpath: if *dll == "dxgi.dll" {
+                        "lib/dxvk/x86_64".to_string()
+                    } else {
+                        "lib/vkd3d-proton/x86_64".to_string()
+                    },
                     filename: (*dll).to_string(),
                     source_path,
                     dest_path: root.join("game").join(dll),
diff --git a/app/src-rust/src/mtsp/recipe.rs b/app/src-rust/src/mtsp/recipe.rs
index 08daf6b2f..a82519a9d 100644
--- a/app/src-rust/src/mtsp/recipe.rs
+++ b/app/src-rust/src/mtsp/recipe.rs
@@ -390,12 +390,19 @@ pub fn selected_deploy_dlls_for_pipeline(
     node: &PipelineNode,
     ms_root: &Path,
 ) -> Vec<RecipeDll> {
-    let d3d9_subpath = if node.id == PipelineId::M9 { m9_d3d9_source_subpath(game_dir, exe_path) } else { "" };
+    let m9_uses_i386 = node.id == PipelineId::M9 && m9_d3d9_source_subpath(game_dir, exe_path).contains("i386-windows");
     let target_dirs = deploy_target_dirs_for_pipeline(game_dir, exe_path, node);
 
     node.deploy_dlls
         .iter()
-        .filter(|dll| node.id != PipelineId::M9 || dll.source_subpath == d3d9_subpath)
+        .filter(|dll| {
+            node.id != PipelineId::M9
+                || if m9_uses_i386 {
+                    dll.source_subpath.contains("i386-windows")
+                } else {
+                    dll.source_subpath == "build-ec/dlls/d3d9/x86_64-windows"
+                }
+        })
         .flat_map(|dll| {
             let source_path = ms_root.join(dll.source_subpath).join(dll.filename);
             let dest_name = dll.dest_filename.unwrap_or(dll.filename);
@@ -856,19 +863,19 @@ fn m9_d3d9_source_subpath(game_dir: &Path, exe_path: Option<&Path>) -> &'static
         Some(path) => path.to_path_buf(),
         None => match resolve_game_exe(0, game_dir) {
             Ok(path) => path,
-            Err(_) => return "lib/wine/x86_64-windows",
+            Err(_) => return "build-ec/dlls/d3d9/x86_64-windows",
         },
     };
 
     if let Ok(data) = std::fs::read(&exe) {
         if let Some(pe) = super::pe::parse_pe_imports(&data) {
             if !pe.is_64_bit {
-                return "lib/wine/i386-windows";
+                return "build-ec/dlls/d3d9/i386-windows";
             }
         }
     }
 
-    "lib/wine/x86_64-windows"
+    "build-ec/dlls/d3d9/x86_64-windows"
 }
 
 fn runtime_file_present(path: &Path) -> bool {
@@ -899,30 +906,42 @@ fn runtime_assets_for_node(node: &PipelineNode, ms_root: &Path) -> Vec<RuntimeAs
 
     match node.id {
         PipelineId::M12 => {
-            let unix_dir = ms_root.join("lib").join("dxmt_m12").join("x86_64-unix");
-            for filename in ["winemetal.so", "libc++.1.dylib", "libc++abi.1.dylib", "libunwind.1.dylib"] {
-                let path = unix_dir.join(filename);
+            for (name, path) in [
+                (
+                    "build-ec/dlls/winevulkan/winevulkan.so",
+                    ms_root.join("build-ec").join("dlls").join("winevulkan").join("winevulkan.so"),
+                ),
+                (
+                    "build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll",
+                    ms_root
+                        .join("build-ec")
+                        .join("dlls")
+                        .join("winevulkan")
+                        .join("x86_64-windows")
+                        .join("winevulkan.dll"),
+                ),
+                (
+                    "build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll",
+                    ms_root.join("build-ec").join("dlls").join("vulkan-1").join("x86_64-windows").join("vulkan-1.dll"),
+                ),
+                (
+                    "build-ec/dlls/win32u/libMoltenVK.dylib",
+                    ms_root.join("build-ec").join("dlls").join("win32u").join("libMoltenVK.dylib"),
+                ),
+                ("lib/moltenvk/libMoltenVK.dylib", ms_root.join("lib").join("moltenvk").join("libMoltenVK.dylib")),
+            ] {
                 assets.push(RuntimeAsset {
-                    name: format!("lib/dxmt_m12/x86_64-unix/{filename}"),
+                    name: name.to_string(),
                     present: runtime_file_present(&path),
                     path,
                     required: true,
                 });
             }
         },
-        PipelineId::M11 => {
-            let path = ms_root.join("lib").join("dxmt").join("x86_64-unix").join("winemetal.so");
-            assets.push(RuntimeAsset {
-                name: "lib/dxmt/x86_64-unix/winemetal.so".into(),
-                present: runtime_file_present(&path),
-                path,
-                required: true,
-            });
-        },
-        PipelineId::M11_32 | PipelineId::M10_32 => {
-            let path = ms_root.join("lib").join("dxmt").join("i386-unix").join("winemetal.so");
+        PipelineId::M10 | PipelineId::M11 | PipelineId::M10_32 | PipelineId::M11_32 => {
+            let path = ms_root.join("build-ec").join("dxmt-v0.80").join("aarch64-unix").join("winemetal.so");
             assets.push(RuntimeAsset {
-                name: "lib/dxmt/i386-unix/winemetal.so".into(),
+                name: "build-ec/dxmt-v0.80/aarch64-unix/winemetal.so".into(),
                 present: runtime_file_present(&path),
                 path,
                 required: true,
@@ -993,37 +1012,38 @@ mod tests {
     use super::*;
 
     #[test]
-    fn m11_validates_legacy_winemetal_so_without_changing_m12_sidecars() {
+    fn m11_validates_winemetal_while_m12_validates_vulkan_host_boundary() {
         let ms_root = test_dir("runtime-assets-winemetal-lanes");
         let m11 = super::super::engine::get_pipeline(PipelineId::M11);
         let m12 = super::super::engine::get_pipeline(PipelineId::M12);
 
         let m11_assets = runtime_assets_for_node(m11, &ms_root);
-        assert!(m11_assets.iter().any(|asset| asset.name == "lib/dxmt/x86_64-unix/winemetal.so"));
+        assert!(m11_assets.iter().any(|asset| asset.name == "build-ec/dxmt-v0.80/aarch64-unix/winemetal.so"));
         assert!(!m11_assets.iter().any(|asset| asset.name.starts_with("lib/dxmt_m12/x86_64-unix/")));
 
         let m12_assets = runtime_assets_for_node(m12, &ms_root);
-        assert!(m12_assets.iter().any(|asset| asset.name == "lib/dxmt_m12/x86_64-unix/winemetal.so"));
-        assert!(m12_assets.iter().any(|asset| asset.name == "lib/dxmt_m12/x86_64-unix/libc++.1.dylib"));
+        assert!(m12_assets.iter().any(|asset| asset.name == "build-ec/dlls/winevulkan/winevulkan.so"));
+        assert!(m12_assets.iter().any(|asset| asset.name == "build-ec/dlls/win32u/libMoltenVK.dylib"));
+        assert!(m12_assets.iter().any(|asset| asset.name == "lib/moltenvk/libMoltenVK.dylib"));
         assert!(!m12_assets.iter().any(|asset| asset.name == "lib/dxmt/x86_64-unix/winemetal.so"));
+        assert!(!m12_assets.iter().any(|asset| asset.name.contains("dxmt_m12")));
 
         let _ = std::fs::remove_dir_all(ms_root);
     }
 
     #[test]
-    fn m11_32_and_m10_32_validate_i386_winemetal_so_sidecar() {
+    fn m11_32_and_m10_32_validate_native_arm64_winemetal_sidecar() {
         let ms_root = test_dir("runtime-assets-i386-winemetal-lanes");
         for id in [PipelineId::M11_32, PipelineId::M10_32] {
             let node = super::super::engine::get_pipeline(id);
             let assets = runtime_assets_for_node(node, &ms_root);
-            // doctor must surface the i386 unix sidecar as a required runtime asset
+            // The PE lane is i386, but the Unix bridge stays native ARM64.
             assert!(
-                assets.iter().any(|asset| asset.name == "lib/dxmt/i386-unix/winemetal.so"),
-                "{:?} missing i386-unix/winemetal.so runtime asset",
+                assets.iter().any(|asset| asset.name == "build-ec/dxmt-v0.80/aarch64-unix/winemetal.so"),
+                "{:?} missing native ARM64 winemetal.so runtime asset",
                 id
             );
-            // and must not pull the x86_64-only M11/M12 sidecars
-            assert!(!assets.iter().any(|asset| asset.name == "lib/dxmt/x86_64-unix/winemetal.so"));
+            assert!(!assets.iter().any(|asset| asset.name.contains("i386-unix")));
             assert!(!assets.iter().any(|asset| asset.name.starts_with("lib/dxmt_m12/")));
         }
         let _ = std::fs::remove_dir_all(ms_root);
@@ -1561,7 +1581,10 @@ mod tests {
         let sources: std::collections::HashSet<_> = selected.iter().map(|dll| dll.source_subpath.as_str()).collect();
         let filenames: std::collections::HashSet<_> = selected.iter().map(|dll| dll.filename.as_str()).collect();
 
-        assert_eq!(sources, std::collections::HashSet::from(["lib/wine/i386-windows"]));
+        assert_eq!(
+            sources,
+            std::collections::HashSet::from(["build-ec/dlls/d3d9/i386-windows", "build-ec/dlls/dxgi/i386-windows",])
+        );
         assert_eq!(filenames, std::collections::HashSet::from(["d3d9.dll", "dxgi.dll"]));
         assert_eq!(selected.len(), 2);
         let _ = std::fs::remove_dir_all(game_dir);
@@ -1584,7 +1607,7 @@ mod tests {
         );
         let sources: std::collections::HashSet<_> = selected.iter().map(|dll| dll.source_subpath.as_str()).collect();
 
-        assert_eq!(sources, std::collections::HashSet::from(["lib/wine/x86_64-windows"]));
+        assert_eq!(sources, std::collections::HashSet::from(["build-ec/dlls/d3d9/x86_64-windows"]));
         assert_eq!(selected.len(), 1);
         let _ = std::fs::remove_dir_all(game_dir);
         let _ = std::fs::remove_dir_all(runtime);
diff --git a/app/src-rust/src/mtsp/rules.rs b/app/src-rust/src/mtsp/rules.rs
index bd534c643..8a2508e6c 100644
--- a/app/src-rust/src/mtsp/rules.rs
+++ b/app/src-rust/src/mtsp/rules.rs
@@ -554,7 +554,7 @@ mod tests {
         assert!(!shipped_rules.contains("anticheat"), "shipped rules must not contain anti-cheat metadata");
         let (_, recipes) = parse_rules_full(shipped_rules);
 
-        let m12_required = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"];
+        let m12_required = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"];
         let m11_required = ["d3d11.dll", "dxgi.dll", "winemetal.dll"];
         let required_by_pipeline =
             [(PipelineId::M12, m12_required.as_slice()), (PipelineId::M11, m11_required.as_slice())];
diff --git a/app/src-rust/src/mtsp/shader_cache.rs b/app/src-rust/src/mtsp/shader_cache.rs
index 80ff713af..a03708c10 100644
--- a/app/src-rust/src/mtsp/shader_cache.rs
+++ b/app/src-rust/src/mtsp/shader_cache.rs
@@ -45,7 +45,7 @@ fn find_preset(home: &PathBuf, cache_subdir: &str, appid: u32) -> Option<PathBuf
 fn preset_lookup_subdirs(cache_subdir: &str) -> Vec<&str> {
     match cache_subdir {
         "m9" | "m10" | "m11" => vec![cache_subdir, "dxmt-metal"],
-        "m12" => vec![cache_subdir, "dxmt-metal12"],
+        "m12" => vec![cache_subdir, "vkd3d-proton"],
         _ => vec![cache_subdir],
     }
 }
@@ -171,7 +171,7 @@ fn merge_preset_into_user(preset_db: &PathBuf, user_db: &PathBuf) -> Option<u64>
 // Phase 4: Shader / PSO / cache diagnostics
 // ============================================================================
 //
-// The DXMT runtime is shipped prebuilt under lib/dxmt(-m12); vendor/dxmt is
+// The DXMT runtime is shipped prebuilt under lib/dxmt; vendor/dxmt is
 // reference source and is NOT compiled by this repo's CMake build. These Rust
 // diagnostics therefore observe the runtime's on-disk products (the DXMT
 // SQLite shader/pipeline caches and any JSON PSO trace sidecars DXMT emits
@@ -182,15 +182,15 @@ fn merge_preset_into_user(preset_db: &PathBuf, user_db: &PathBuf) -> Option<u64>
 // gives the cache doctor a real, testable introspection path today.
 
 /// The shader-cache family a pipeline shares. M9/M10/M11 share the legacy
-/// `dxmt-metal` family; M12/M13 use the isolated `dxmt-metal12` family.
+/// `dxmt-metal` family; M12 uses vkd3d-proton and M13 uses D3DMetal.
 pub fn shader_cache_family(pipeline: crate::mtsp::engine::PipelineId) -> &'static [&'static str] {
     use crate::mtsp::engine::PipelineId;
     match pipeline {
         PipelineId::M9 => &["m9", "dxmt-metal"],
         PipelineId::M10 => &["m10", "dxmt-metal"],
         PipelineId::M11 => &["m11", "dxmt-metal"],
-        PipelineId::M12 => &["m12", "dxmt-metal12"],
-        PipelineId::M13 => &["m13", "dxmt-metal12"],
+        PipelineId::M12 => &["m12", "vkd3d-proton"],
+        PipelineId::M13 => &["m13", "d3dmetal"],
         _ => &[],
     }
 }
@@ -506,9 +506,9 @@ mod tests {
         use crate::mtsp::engine::PipelineId;
         // M9/M10/M11 share the legacy dxmt-metal family.
         assert_eq!(shader_cache_family(PipelineId::M11), &["m11", "dxmt-metal"]);
-        // M12/M13 use the isolated dxmt-metal12 family and must not mix.
-        assert_eq!(shader_cache_family(PipelineId::M12), &["m12", "dxmt-metal12"]);
-        assert_eq!(shader_cache_family(PipelineId::M13), &["m13", "dxmt-metal12"]);
+        // M12 and M13 use their actual backend families and must not mix.
+        assert_eq!(shader_cache_family(PipelineId::M12), &["m12", "vkd3d-proton"]);
+        assert_eq!(shader_cache_family(PipelineId::M13), &["m13", "d3dmetal"]);
     }
 
     #[test]
diff --git a/app/src-rust/src/setup.rs b/app/src-rust/src/setup.rs
index bf735a304..27fe4aef0 100644
--- a/app/src-rust/src/setup.rs
+++ b/app/src-rust/src/setup.rs
@@ -25,8 +25,6 @@ pub fn state() -> Value {
     let config_path = crate::platform::metalsharp_home_dir_for(&home).join("setup.json");
     let complete_runtime_current = crate::installer::complete_runtime_current_for_home(&home);
     let dxmt_runtime = crate::installer::dxmt_runtime_status();
-    let dxmt_current = dxmt_runtime.get("current").and_then(|v| v.as_bool()).unwrap_or(false);
-    let dxmt_m12_current = dxmt_runtime.get("m12Current").and_then(|v| v.as_bool()).unwrap_or(false);
     let wine_dir = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
     let metalsharp_runtime_lib_ready = crate::installer::metalsharp_runtime_lib_ready(&wine_dir);
     let runtime_current = complete_runtime_current;
@@ -129,7 +127,9 @@ pub fn dependencies() -> Value {
     let steam = check_path(&home.join("Library/Application Support/Steam/Steam.app/Contents/MacOS/steam_osx"))
         || check_path(&PathBuf::from("/Applications/Steam.app/Contents/MacOS/steam_osx"));
     let homebrew = homebrew_ready();
-    let moltenvk = check_path(&PathBuf::from("/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json"));
+    let wine_root = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
+    let moltenvk = check_path(&wine_root.join("build-ec/dlls/win32u/libMoltenVK.dylib"))
+        && check_path(&wine_root.join("lib/moltenvk/libMoltenVK.dylib"));
     let metalsharp_wine = crate::installer::complete_runtime_current_for_home(&home);
     let host_runtime = host_runtime_installed(&home);
     let dxmt_status = crate::installer::dxmt_runtime_status();
@@ -139,12 +139,15 @@ pub fn dependencies() -> Value {
         .or_else(|| dxmt_status.get("current"))
         .and_then(|v| v.as_bool())
         .unwrap_or(false);
-    let dxmt_m12_runtime = dxmt_status
-        .get("dxmt_m12")
-        .and_then(|lane| lane.get("current"))
-        .or_else(|| dxmt_status.get("m12Current"))
-        .and_then(|v| v.as_bool())
-        .unwrap_or(false);
+    let m12_vkd3d_runtime = [
+        "lib/vkd3d-proton/x86_64/d3d12.dll",
+        "lib/vkd3d-proton/x86_64/d3d12core.dll",
+        "lib/dxvk/x86_64/dxgi.dll",
+        "build-ec/dlls/winevulkan/winevulkan.so",
+        "build-ec/dlls/win32u/libMoltenVK.dylib",
+    ]
+    .iter()
+    .all(|relative| check_path(&wine_root.join(relative)));
 
     let all_ok = homebrew && rosetta && xcode_cli && metalsharp_wine;
 
@@ -203,19 +206,13 @@ pub fn dependencies() -> Value {
                 "status": dxmt_status.get("dxmt").cloned().unwrap_or_else(|| dxmt_status.clone()),
             },
             {
-                "id": "dxmt_m12_runtime",
-                "name": "DXMT M12 Runtime",
-                "desc": "Isolated D3D12-to-Metal runtime staged under runtime/wine/lib/dxmt_m12 with its own DLLs and winemetal.so sidecars.",
-                "installed": dxmt_m12_runtime,
+                "id": "m12_vkd3d_runtime",
+                "name": "M12 vkd3d-proton Runtime",
+                "desc": "D3D12 through vkd3d-proton with DXVK-owned DXGI, Wine Vulkan, and the bundled ARM64 MoltenVK-to-Metal host route.",
+                "installed": m12_vkd3d_runtime,
                 "required": true,
-                "installCmd": "metalsharp-setup-dxmt-m12",
-                "status": dxmt_status.get("dxmt_m12").cloned().unwrap_or_else(|| dxmt_status.clone()),
-                "path": dxmt_status
-                    .get("dxmt_m12")
-                    .and_then(|lane| lane.get("path"))
-                    .cloned()
-                    .or_else(|| dxmt_status.get("m12Path").cloned())
-                    .unwrap_or(json!(null)),
+                "installCmd": "metalsharp-setup-wine",
+                "path": wine_root.join("lib/vkd3d-proton/x86_64").to_string_lossy(),
             },
             {
                 "id": "mono",
@@ -227,11 +224,11 @@ pub fn dependencies() -> Value {
             },
             {
                 "id": "moltenvk",
-                "name": "MoltenVK",
-                "desc": "Vulkan→Metal translation. Optional fallback graphics backend.",
+                "name": "Bundled MoltenVK",
+                "desc": "ARM64 Vulkan-to-Metal translation used by the M12 vkd3d-proton route.",
                 "installed": moltenvk,
-                "required": false,
-                "installCmd": "brew install molten-vk",
+                "required": true,
+                "installCmd": "metalsharp-setup-wine",
             },
             {
                 "id": "steam",
@@ -396,8 +393,8 @@ pub fn prepare_game(appid: u32) -> Result<Value, Box<dyn std::error::Error>> {
         _ => {
             if is_dotnet {
                 prepare_fna_game(appid, &game_dir, &home)?;
-            } else if pipeline.is_dxmt_family() {
-                prepare_dxmt_pipeline(appid, &game_dir, &home, pipeline)?;
+            } else if pipeline.is_dxmt_family() || pipeline == crate::mtsp::engine::PipelineId::M12 {
+                prepare_graphics_pipeline(appid, &game_dir, &home, pipeline)?;
             }
         },
     }
@@ -589,7 +586,7 @@ fn prepare_celeste(game_dir: &PathBuf, home: &PathBuf) -> Result<(), Box<dyn std
     Ok(())
 }
 
-fn prepare_dxmt_pipeline(
+fn prepare_graphics_pipeline(
     appid: u32,
     game_dir: &PathBuf,
     home: &PathBuf,
@@ -601,7 +598,8 @@ fn prepare_dxmt_pipeline(
         stage_agility_sdk_for_game(appid, game_dir, home)?;
     }
     if !marker.exists() {
-        let _ = std::fs::write(&marker, "dxmt");
+        let route = if pipeline == crate::mtsp::engine::PipelineId::M12 { "vkd3d-proton" } else { "dxmt" };
+        let _ = std::fs::write(&marker, route);
     }
     Ok(())
 }
diff --git a/app/src/renderer/components/GameCard.vue b/app/src/renderer/components/GameCard.vue
index 727345384..2c97af917 100644
--- a/app/src/renderer/components/GameCard.vue
+++ b/app/src/renderer/components/GameCard.vue
@@ -218,13 +218,11 @@ const componentDisplayName: Record<string, string> = {
   fna3d: "FNA3D",
   faudio: "FAudio",
   fmod: "FMOD Audio",
-  m12_d3d12: "M12 d3d12.dll",
-  m12_d3d11: "M12 d3d11.dll",
-  m12_d3d10core: "M12 d3d10core.dll",
-  m12_dxgi_dxmt: "M12 dxgi_dxmt.dll",
-  m12_dxgi: "M12 dxgi.dll",
-  m12_winemetal: "M12 winemetal.dll / .so",
-  m12_gpu_stubs: "M12 GPU Stubs",
+  m12_vkd3d_d3d12: "M12 vkd3d-proton d3d12.dll",
+  m12_vkd3d_d3d12core: "M12 vkd3d-proton d3d12core.dll",
+  m12_dxvk_dxgi: "M12 DXVK dxgi.dll",
+  m12_winevulkan: "M12 Wine Vulkan bridge",
+  m12_moltenvk: "M12 ARM64 MoltenVK",
   d3d12_agility: "D3D12 Agility",
   gpu_vendor_stubs: "GPU Stubs",
   gptk_amd_stub: "GPTK AMD Stub",
diff --git a/app/src/renderer/views/SettingsView.vue b/app/src/renderer/views/SettingsView.vue
index 5f9352965..ccd084bb6 100644
--- a/app/src/renderer/views/SettingsView.vue
+++ b/app/src/renderer/views/SettingsView.vue
@@ -554,7 +554,7 @@ function uninstallMetalsharp() {
         <div>
           <div class="settings-label">Graphics Runtime Logs</div>
           <div class="settings-desc">
-            Opt in to DXMT graphics logs for future launches. Off by default so M12 games do not emit runtime logs unless requested.
+            Opt in to graphics-backend logs for future launches. Off by default so DXMT and M12 vkd3d-proton games stay quiet unless requested.
           </div>
         </div>
         <div class="settings-value">
diff --git a/app/src/renderer/views/SharpView.vue b/app/src/renderer/views/SharpView.vue
index cb757420c..66de0b294 100644
--- a/app/src/renderer/views/SharpView.vue
+++ b/app/src/renderer/views/SharpView.vue
@@ -415,13 +415,11 @@ const componentDisplayName: Record<string, string> = {
   fna3d: "FNA3D",
   faudio: "FAudio",
   fmod: "FMOD Audio",
-  m12_d3d12: "M12 d3d12.dll",
-  m12_d3d11: "M12 d3d11.dll",
-  m12_d3d10core: "M12 d3d10core.dll",
-  m12_dxgi_dxmt: "M12 dxgi_dxmt.dll",
-  m12_dxgi: "M12 dxgi.dll",
-  m12_winemetal: "M12 winemetal.dll / .so",
-  m12_gpu_stubs: "M12 GPU Stubs",
+  m12_vkd3d_d3d12: "M12 vkd3d-proton d3d12.dll",
+  m12_vkd3d_d3d12core: "M12 vkd3d-proton d3d12core.dll",
+  m12_dxvk_dxgi: "M12 DXVK dxgi.dll",
+  m12_winevulkan: "M12 Wine Vulkan bridge",
+  m12_moltenvk: "M12 ARM64 MoltenVK",
   d3d12_agility: "D3D12 Agility",
   gpu_vendor_stubs: "GPU Stubs",
   gptk_amd_stub: "GPTK AMD Stub",
diff --git a/configs/mtsp-roadmap.md b/configs/mtsp-roadmap.md
index d4ec7f321..577660e02 100644
--- a/configs/mtsp-roadmap.md
+++ b/configs/mtsp-roadmap.md
@@ -44,7 +44,7 @@ TOML, not Rust code.
 
 | ID | Name | Backend | Notes |
 |---|---|---|---|
-| M12 | D3D12 → Metal | dxmt | Public D3D12 route; deploys D3D12/DXGI/DXIL/Agility sidecars when selected |
+| M12 | D3D12 → Vulkan → Metal | vkd3d-proton | Public D3D12 route; deploys vkd3d-proton D3D12/D3D12Core, DXVK DXGI, and Agility sidecars, then uses Wine Vulkan and MoltenVK |
 | M11 | D3D11 → Metal | dxmt | Public D3D11 route |
 | M10 | D3D10 → Metal | dxmt | Public D3D10 route |
 | M9 | D3D9 → Metal | dxmt | Public D3D9 route under the DXMT launch/cache family |
@@ -54,7 +54,7 @@ TOML, not Rust code.
 
 | ID | Role |
 |---|---|
-| DXMT | Auto-router that selects M12/M11/M10/M9 from rules and PE evidence |
+| DXMT | Legacy auto-router that resolves D3D12 evidence to M12 and D3D9-D3D11 evidence to M9-M11; M12 itself is not a DXMT backend |
 | M32 | 32-bit Wine fallback retained for diagnostics/legacy records |
 | Steam | Windows Steam client handoff retained for bootstrap/diagnostics |
 | MacOS Steam | Native Steam handoff retained for diagnostics/special cases |
diff --git a/configs/mtsp-rules.toml b/configs/mtsp-rules.toml
index 08a93fb78..506be30c6 100644
--- a/configs/mtsp-rules.toml
+++ b/configs/mtsp-rules.toml
@@ -5,7 +5,8 @@
 # names. Pipeline choices are based on verified Windows renderer/API data:
 # - fna_arm64/fna_x86: XNA/FNA/Mono titles.
 # - dxmt: auto-detect the Direct3D generation and route through the unified DXMT backend.
-# - m9/m10/m11/m12: compatibility aliases for explicit D3D generation profiles under DXMT.
+# - m9/m10/m11: explicit D3D generation profiles under DXMT.
+# - m12: explicit D3D12 route through vkd3d-proton, DXVK, Wine Vulkan, and MoltenVK.
 # - wine_bare: non-D3D or Vulkan-first titles where DXMT is not the renderer.
 #
 # If a title supports both D3D11 and D3D12, dxmt auto-selection should follow PE
@@ -80,7 +81,7 @@ name = "Subnautica 2"
 offline_capable = true
 
 [overrides.1962700.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.3164500]
 pipeline = "m11"
@@ -144,7 +145,7 @@ offline_capable = true
 components = ["vcrun2019", "vcrun2013", "directx_jun2010"]
 
 [overrides.1245620.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.814380]
 pipeline = "m11"
@@ -168,14 +169,14 @@ offline_capable = true
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.2050650.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1583230]
 pipeline = "m12"
 name = "High On Life"
 
 [overrides.1583230.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.397540]
 pipeline = "m11"
@@ -208,7 +209,7 @@ offline_capable = true
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1091500.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1868140]
 pipeline = "m11"
@@ -230,7 +231,7 @@ offline_capable = true
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1551360.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1716740]
 pipeline = "m12"
@@ -240,7 +241,7 @@ name = "Starfield"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1716740.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1203620]
 pipeline = "wine_bare"
@@ -251,7 +252,7 @@ pipeline = "m12"
 name = "REMNANT II"
 
 [overrides.1282100.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.750920]
 pipeline = "m11"
@@ -289,14 +290,14 @@ name = "Resident Evil Village"
 components = ["vcrun2019", "directx_jun2010", "gpu_vendor_stubs"]
 
 [overrides.1196590.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll", "nvapi64.dll", "nvngx.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1236300]
 pipeline = "m12"
 name = "Resident Evil Re:Verse"
 
 [overrides.1236300.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1888160]
 pipeline = "m12"
@@ -307,7 +308,7 @@ offline_capable = true
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1888160.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.976310]
 pipeline = "m11"
@@ -323,7 +324,7 @@ name = "Marvel Rivals"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.2767030.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.292030]
 pipeline = "m11"
@@ -339,7 +340,7 @@ name = "Hogwarts Legacy"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.990080.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1172470]
 pipeline = "m11"
@@ -352,7 +353,7 @@ pipeline = "m12"
 name = "Riders Republic"
 
 [overrides.2290180.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.548430]
 pipeline = "m11"
@@ -380,7 +381,7 @@ name = "Palworld"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1623730.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1928870]
 pipeline = "m12"
@@ -390,7 +391,7 @@ name = "Minecraft Legends"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1928870.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.553850]
 pipeline = "m12"
@@ -400,7 +401,7 @@ name = "HELLDIVERS 2"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.553850.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.367520]
 pipeline = "m11"
@@ -489,7 +490,7 @@ name = "inZOI"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.2456740.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.275850]
 pipeline = "wine_bare"
@@ -503,7 +504,7 @@ name = "S.T.A.L.K.E.R. 2: Heart of Chornobyl"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1643320.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.379720]
 pipeline = "wine_bare"
@@ -527,7 +528,7 @@ name = "PEAK"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.3527290.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1147560]
 pipeline = "m11"
@@ -615,7 +616,7 @@ name = "Hollow Knight: Silksong"
 offline_capable = true
 
 [overrides.1030300.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.222880]
 pipeline = "m11"
@@ -5788,7 +5789,7 @@ name = "Diablo IV"
 components = ["vcrun2019", "directx_jun2010"]
 
 [overrides.1894810.diagnostics]
-check_dlls = ["d3d12.dll", "d3d11.dll", "dxgi_dxmt.dll", "dxgi.dll", "winemetal.dll"]
+check_dlls = ["d3d12.dll", "d3d12core.dll", "dxgi.dll"]
 
 [overrides.1895880]
 pipeline = "m11"
@@ -6769,4 +6770,3 @@ components = ["vcrun2019_x86", "directx_jun2010"]
 
 [overrides.4498220.diagnostics]
 check_dlls = ["d3d11.dll", "dxgi.dll", "winemetal.dll"]
-
diff --git a/docs/README.md b/docs/README.md
index 65468c79f..bdc2dd6a2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -33,10 +33,10 @@ Use this page as the repo map before changing launch/runtime code.
 ## Architecture
 
 - [Launch Architecture](architecture/launch-architecture.md) - pipeline selection and launch ownership.
-- [D3D12 Pipeline Map](architecture/m12-pipeline-map.md) - current M12 D3D12/DXMT path.
+- [D3D12 Pipeline Map](architecture/m12-pipeline-map.md) - current M12 vkd3d-proton/Vulkan/MoltenVK path.
 - [D3D10 Pipeline Map](architecture/m10-pipeline-map.md) - current M10 D3D10/DXMT path.
 - [D3D9 Pipeline Map](architecture/m9-pipeline-map.md) - current M9 D3D9 route.
-- [DXMT and Vulkan Architecture](architecture/dxmt-vulkan-architecture.md) - DXMT/M9-M12 boundaries and Vulkan fallback boundaries.
+- [DXMT and Vulkan Architecture](architecture/dxmt-vulkan-architecture.md) - DXMT M9-M11 and M12 Vulkan ownership boundaries.
 - [D3D12 Developer Runtime Package](../tools/d3d12-metal-sdk/docs/developer-runtime.md) - self-contained developer SDK tarball layout and publish flow.
 
 ## Historical Roadmaps
diff --git a/docs/architecture/dxmt-vulkan-architecture.md b/docs/architecture/dxmt-vulkan-architecture.md
index ab02de4e3..05412f1d3 100644
--- a/docs/architecture/dxmt-vulkan-architecture.md
+++ b/docs/architecture/dxmt-vulkan-architecture.md
@@ -1,102 +1,63 @@
 # DXMT and Vulkan Architecture
-**Updated:** 2026-07-08
+**Updated:** 2026-07-31
 
+MetalSharp keeps its Direct3D translation owners separate:
 
-MetalSharp has two graphics translation families:
-
-- **DXMT launch family**: M9/M10/M11/M12 to Metal
-- **DXVK + MoltenVK**: Legacy fallback assets only; no longer selected by M9
-
-## Pipeline Map
-
-| Public route | Translation |
+| Public route | Translation ownership |
 |---|---|
-| **M12** | D3D12 -> DXMT -> Metal |
-| **M11** | D3D11 -> DXMT -> Metal |
-| **M10** | D3D10 -> DXMT -> Metal |
-| **M9** | D3D9 -> MetalSharp D3D9 -> DXMT launch family -> Metal |
-
-`dxmt` is the internal auto-router that selects M12/M11/M10/M9. M32, Wine, and macOS Steam are backend fallback/diagnostic paths, not normal graphics-route buttons.
-
-## DXMT
-
-The DXMT launch family is used by M12, M11, M10, and M9.
-
-M10 is the D3D10 DXMT path. It deploys Wine's public `d3d10.dll` and `d3d10_1.dll` entrypoints for imported D3D10 APIs, then routes the core handoff through DXMT's `d3d10core.dll` and the shared D3D11/DXGI/winemetal stack.
+| **M12** | vkd3d-proton `d3d12`/`d3d12core` + DXVK `dxgi` → Wine Vulkan → ARM64 MoltenVK → Metal |
+| **M11 / M11(32)** | DXMT D3D11/DXGI/winemetal → Metal |
+| **M10 / M10(32)** | Wine D3D10 entrypoints + DXMT D3D10core/D3D11/DXGI/winemetal → Metal |
+| **M9** | MetalSharp D3D9 handoff in the DXMT launch/cache family → Metal |
+| **D3DMetal** | Homebrew GPTK Wine + D3DMetal framework in its own GPTK prefix |
 
-DXMT-family DLLs:
+The internal `dxmt` value remains an automatic resolver and legacy record value. It may select M12 for a D3D12 title, but M12 itself is not a DXMT backend.
 
-| DLL | Used by |
-|---|---|
-| `d3d12.dll` | M12 |
-| `d3d11.dll` | M12, M11, M10 |
-| `dxgi.dll` | M12, M11, M10 |
-| `d3d10core.dll` | M12, M11, M10 |
-| `d3d10.dll`, `d3d10_1.dll` | M10 public Wine D3D10 entrypoints |
-| `winemetal.dll` | M12, M11, M10 |
-| `d3d9.dll` | M9 |
-| `winemetal.so` | Unix Metal bridge |
+## M12 ownership
 
-Basic flow:
+M12 deliberately pairs components at their supported boundary:
 
 ```text
-Game
-  -> DXMT PE DLL
-  -> winemetal.so
-  -> Metal command buffers
-  -> Apple GPU
+Windows game
+  → vkd3d-proton d3d12.dll + d3d12core.dll
+  → DXVK dxgi.dll
+  → Wine vulkan-1.dll / winevulkan.dll / ARM64 winevulkan.so
+  → pinned ARM64 libMoltenVK.dylib
+  → Metal
 ```
 
-DXMT uses per-game shader caches under:
+The PE DLLs are loaded from:
 
 ```text
-~/.metalsharp/shader-cache/m9/<appid>/
-~/.metalsharp/shader-cache/m10/<appid>/
-~/.metalsharp/shader-cache/m11/<appid>/
-~/.metalsharp/shader-cache/m12/<appid>/
+~/.metalsharp/runtime/wine/lib/vkd3d-proton/x86_64/
+~/.metalsharp/runtime/wine/lib/dxvk/x86_64/
 ```
 
-Older `dxmt-metal` and `dxmt-metal12` cache family names may still exist on disk from previous builds, but current MTSP
-routes prefer the explicit M9/M10/M11/M12 cache namespaces.
+The host boundary is loaded from the same complete runtime under `wine/build-ec/dlls/{vulkan-1,winevulkan,win32u}`. M12 does not use `winemetal.dll`, `winemetal.so`, `dxgi_dxmt.dll`, or `lib/dxmt_m12`.
 
-## M9 D3D9
+M12 uses isolated caches under `~/.metalsharp/shader-cache/m12/<appid>/` and exports `VKD3D_SHADER_CACHE_PATH` plus `DXVK_STATE_CACHE_PATH`. Backend logs are opt-in.
 
-M9 does not select DXVK/MoltenVK. The pipeline deploys the D3D9 DLL from the bundled Wine runtime and uses the same DXMT launch/cache environment family as the other Metal pipelines.
+## DXMT ownership
 
-Basic flow:
+M9 through M11 retain the known DXMT route. The complete runtime owns the
+Wine entrypoints under `build-ec/dlls` and the DXMT payload under:
 
 ```text
-Game
-  -> d3d9.dll
-  -> Wine / MetalSharp D3D9 handoff
-  -> Metal
+~/.metalsharp/runtime/wine/build-ec/dxmt-v0.80/
 ```
 
-M9 cache path:
+The 64-bit M10/M11 routes load the x86-64/ARM64EC-compatible PE payload from `aarch64-windows`. M10(32)/M11(32) load i386 PE DLLs from `i386-windows`. Both guest modes cross into the same native ARM64 `aarch64-unix/winemetal.so`; there is no i386 Mach-O bridge. These routes keep `DXMT_WINEMETAL_UNIXLIB`, inline DXMT configuration, and DXMT cache variables. `DXMT_CONFIG_FILE` is added only when an optional config file exists. M12 emits none of these DXMT variables.
 
-```text
-~/.metalsharp/shader-cache/m9/<appid>/
-```
+## D3DMetal ownership
 
-## Current Game Notes
+D3DMetal is not a fallback copy of M12. It is a separately provisioned Homebrew GPTK route with `~/.metalsharp/prefix-gptk`, Homebrew-matched route DLLs, and its own Wine/wineserver. Bottle save and Play preserve that separation.
 
-| Game | Best/current pipeline |
-|---|---|
-| Schedule 1 | M12 recommended |
-| Subnautica | M11 |
-| Subnautica: Below Zero | M12 recommended, M11 optimized |
-| Rain World | M11, M9 also works |
-| Undertale | M9 |
-| Portal 2 | M9 |
-| Nidhogg 2 | M9 |
-| Ghostrunner | M11; M12 only if needed |
-| DREDGE | Not a DXMT/FNA target yet; 32-bit Unity embedded Mono crash |
-| Goat Simulator | M9, blocked before graphics by native .NET 4.0 CLR install |
-
-## Notes
-
-- DXMT is the internal direct-Metal auto-router, not a visible route selector option.
-- M12 is the primary stable DXMT D3D engine method in source.
-- M10 and M11 share the `dxmt-metal` preset fallback family.
-- M9 no longer has a Vulkan/MoltenVK hop in MTSP selection.
-- 32-bit and Wine fallback cases remain backend internals unless promoted to a public route.
+## Route-switch invariant
+
+Before a route deploy, MetalSharp quarantines or discards stale app-local graphics DLLs. After selection:
+
+- M12 has only vkd3d-proton `d3d12`/`d3d12core` and DXVK `dxgi` ownership.
+- M9/M10/M11 have only their DXMT/Wine ownership.
+- D3DMetal has only its Homebrew GPTK ownership.
+
+Mixing `dxgi`, `d3d12`, or Unix bridges from different route owners is treated as an invalid launch shape.
diff --git a/docs/architecture/launch-architecture.md b/docs/architecture/launch-architecture.md
index 71a52a358..268380113 100644
--- a/docs/architecture/launch-architecture.md
+++ b/docs/architecture/launch-architecture.md
@@ -40,7 +40,7 @@ D3DMetal is an explicit GPTK lane rather than a generic bottle repair path. Savi
 
 | Public route | Backend | Launch path |
 |---|---|---|
-| **M12** | DXMT | Direct Wine launch with isolated `dxmt-m12` D3D12/D3D11/DXGI/winemetal DLLs |
+| **M12** | vkd3d-proton + DXVK + MoltenVK | Direct Wine launch with vkd3d-proton `d3d12`/`d3d12core`, DXVK `dxgi`, Wine Vulkan, and ARM64 MoltenVK |
 | **M11** | DXMT | Direct Wine launch with legacy `dxmt` D3D11/DXGI DLLs |
 | **M10** | DXMT | Direct Wine launch with legacy `dxmt` D3D10/D3D11/DXGI DLLs |
 | **M9** | DXMT launch family | Direct Wine launch with bundled `d3d9.dll` and DXMT-family cache/env |
@@ -79,16 +79,18 @@ Runtime prep is recipe-driven. DXMT/Wine DLL overrides are deployed next to the
 into the game root, which keeps nested layouts such as `Binaries/Win64` and launcher-heavy games from loading the wrong
 binary or missing local overrides.
 
-M11/M10/M9 read from the legacy runtime surface:
+M11/M10 read their DXMT payload directly from the complete runtime build lane;
+M9 reads Wine's D3D9 entrypoints from `build-ec/dlls/d3d9`:
 
 ```text
-~/.metalsharp/runtime/wine/lib/dxmt
+~/.metalsharp/runtime/wine/build-ec/dxmt-v0.80/{aarch64-windows,i386-windows,aarch64-unix}
 ```
 
-M12 reads from the isolated D3D12 surface:
+M12 reads its PE translation DLLs from two explicitly owned surfaces:
 
 ```text
-~/.metalsharp/runtime/wine/lib/dxmt-m12
+~/.metalsharp/runtime/wine/lib/vkd3d-proton/x86_64/{d3d12.dll,d3d12core.dll}
+~/.metalsharp/runtime/wine/lib/dxvk/x86_64/dxgi.dll
 ```
 
 M11/M10 copy:
@@ -98,13 +100,15 @@ M11/M10 copy:
 - `d3d10core.dll`
 - `winemetal.dll`
 
-M10 is selected by 64-bit `d3d10.dll`, `d3d10_1.dll`, or `d3d10core.dll` imports. It deploys Wine's public `d3d10.dll` and `d3d10_1.dll` entrypoints plus DXMT's `d3d10core.dll`, so public D3D10 imports and the DXMT core handoff are both owned by the x86_64 M10 runtime contract.
+M10 is selected by 64-bit `d3d10.dll`, `d3d10_1.dll`, or `d3d10core.dll` imports. It deploys Wine's public `d3d10.dll` and `d3d10_1.dll` entrypoints plus DXMT's `d3d10core.dll`, so public D3D10 imports and the DXMT core handoff are both owned by the complete M10 runtime contract. M10(32) uses the parallel i386 PE entrypoints with the native ARM64 Unix bridge.
 
-M12 also copies:
+M12 copies:
 
 - `d3d12.dll`
+- `d3d12core.dll`
+- `dxgi.dll`
 
-M12 also adds the `dxmt-m12` unix library directory to the fallback library path so `winemetal.so` and its bundled C++ sidecars are resolved from the same surface as the PE DLLs.
+M12 then routes through Wine's ARM64 `winevulkan.so`/`winevulkan.dll` boundary and the runtime-pinned ARM64 `libMoltenVK.dylib`. It never loads `winemetal.dll`, `winemetal.so`, or the legacy `dxmt_m12` lane.
 
 M9 copies:
 
diff --git a/docs/architecture/m10-pipeline-map.md b/docs/architecture/m10-pipeline-map.md
index 2f41e41f1..0bbd57a95 100644
--- a/docs/architecture/m10-pipeline-map.md
+++ b/docs/architecture/m10-pipeline-map.md
@@ -19,12 +19,14 @@ D3D10 game
 
 M10 deploys Wine's public D3D10 entrypoint DLLs for games that import `d3d10.dll` or `d3d10_1.dll`, then routes the core handoff through DXMT's `d3d10core.dll` plus the same DXMT D3D11, DXGI, and winemetal runtime used by M11.
 
-M10 deploys these public D3D10 entrypoints from `~/.metalsharp/runtime/wine/lib/wine/x86_64-windows/`:
+M10 deploys these public D3D10 entrypoints from the corresponding
+`~/.metalsharp/runtime/wine/build-ec/dlls/{d3d10,d3d10_1}/x86_64-windows/` directories:
 
 - `d3d10.dll`
 - `d3d10_1.dll`
 
-M10 deploys these DXMT handoff DLLs from `~/.metalsharp/runtime/wine/lib/dxmt/x86_64-windows/`:
+M10 deploys these DXMT handoff DLLs from
+`~/.metalsharp/runtime/wine/build-ec/dxmt-v0.80/aarch64-windows/`:
 
 - `d3d11.dll`
 - `dxgi.dll`
@@ -44,16 +46,16 @@ M10 deliberately does not deploy `d3d12.dll`.
 | Shader cache subdir | `m10` |
 | Preset fallback family | `m10`, then `dxmt-metal` |
 
-M10 uses the same DXMT Unix library search path as M11:
+M10 uses the same native ARM64 DXMT Unix bridge as M11:
 
 ```text
-lib/wine/x86_64-unix
-lib/dxmt/x86_64-unix
+build-ec/dlls/ntdll
+build-ec/dxmt-v0.80/aarch64-unix
 ```
 
 ## Selection Rules
 
-The backend resolves M10 from 64-bit PE imports before broad directory heuristics. That keeps 64-bit D3D10 games from being demoted to M11 just because their folder also includes common engine or Steam markers. 32-bit D3D10 executables are not routed into M10 because this runtime contract deploys the x86_64 D3D10/DXMT payload.
+The backend resolves M10 from 64-bit PE imports before broad directory heuristics. That keeps 64-bit D3D10 games from being demoted to M11 just because their folder also includes common engine or Steam markers. The explicit M10(32) route deploys the i386 D3D10/DXMT PE payload while retaining the native ARM64 Unix bridge.
 
 Recognized D3D10 imports:
 
diff --git a/docs/architecture/m12-pipeline-map.md b/docs/architecture/m12-pipeline-map.md
index 3254c81ce..81852637b 100644
--- a/docs/architecture/m12-pipeline-map.md
+++ b/docs/architecture/m12-pipeline-map.md
@@ -1,141 +1,78 @@
 # M12 Pipeline Map
-**Updated:** 2026-07-08
-
-
-Last verified: 2026-06-13.
-
-M12 is the D3D12 -> DXMT -> Metal path used by the game launcher. The current
-MetalSharp tree also contains a native `metalsharp_d3d12` implementation and a
-Cocoa/CAMetalLayer viewer path, but those are not the same runtime path that M12
-uses for Wine-launched games.
-
-## Runtime Ownership
-
-| Layer | Current owner | Evidence | Status |
-| --- | --- | --- | --- |
-| Game detection | `app/src-rust/src/mtsp/pe.rs`, `rules.rs` | D3D12 imports select `PipelineId::M12` for 64-bit games. | Present in current project |
-| Pipeline definition | `app/src-rust/src/mtsp/engine.rs` | M12 is named `D3D12 -> Metal via DXMT`, is the first stable pipeline, deploys DXMT DLLs, and sets D3D12/DXGI/D3D11 overrides. | Present in current project |
-| Launcher handoff | `app/src-rust/src/mtsp/launcher.rs` | M12 routes through `launch_dxmt_metal`, copies DLLs into the game directory, and sets Wine/DYLD/cache env. | Present in current project |
-| Shader/cache routing | `app/src-rust/src/mtsp/shader_cache.rs` | M12 uses `m12` and `dxmt-metal12` cache directories. | Present in current project |
-| M12 artifact surface | `~/.metalsharp/runtime/wine/lib/dxmt-m12` | M12 loads the updated D3D12/DXGI/winemetal payload from the isolated `dxmt-m12` directory. | Present in current project |
-| Legacy DXMT surface | `~/.metalsharp/runtime/wine/lib/dxmt` | M9/M10/M11 continue to use the known-good legacy DXMT payload. | Present in current project |
-| DXMT D3D12 implementation | External DXMT source tree | Conformance branch contains the real DXMT D3D12/DXIL/winemetal work used by M12 runtime DLLs. | External source tree |
-| Native D3D12 target | `include/metalsharp/D3D12Device.h`, `src/d3d/d3d12/*` | Builds `build/d3d12.dylib` and exposes `D3D12CreateDevice`. | In-tree, smoke-tested |
-| Cocoa surface | `src/win32/user32/WindowManager.mm`, `src/dxgi/DXGISwapChain.mm` | Creates NSWindow/CAMetalLayer for the native loader path. | In-tree, not the Wine M12 surface |
-| Wine M12 surface | DXMT `winemetal.so` plus Wine/macOS windowing | DXMT presents through Wine/winemetal, not through the native `WindowManager` path. | External runtime path |
-
-## M12 Launch Flow
-
-1. The PE scanner sees `d3d12.dll` and rules select `PipelineId::M12`.
-2. The launcher resolves the game directory and Wine prefix.
-3. M12 deploys DXMT PE DLLs from `lib/dxmt-m12/x86_64-windows` into the game directory:
-   `d3d12.dll`, `d3d11.dll`, `dxgi.dll`, `d3d10core.dll`, and `winemetal.dll`.
-4. M12 sets `WINEDLLOVERRIDES` so Wine prefers the deployed native DXMT DLLs.
-5. M12 adds `lib/dxmt-m12/x86_64-unix` and Wine unix library paths to `DYLD_FALLBACK_LIBRARY_PATH`.
-6. M12 sets shader and pipeline cache paths under the MetalSharp cache root.
-7. Wine launches the executable without a forced DirectX command-line flag. `dx12` and `d3d12` are route aliases for selecting M12, not universal game args.
-8. DXMT handles D3D12/DXGI calls, compiles DXIL/MSL work, sends commands through
-   `winemetal`, and presents through the Wine/macOS surface.
-
-## Current Verification
-
-These checks were run from the repository root:
-
-```sh
-cmake --build build --target test_d3d12
-cmake --build build --target test_d3d12_entrypoint test_d3d12
-./build/tests/test_d3d12
-./build/tests/test_d3d12_entrypoint
-ctest --test-dir build -R "d3d12|d3d12_entrypoint|phase18|phase19" --output-on-failure
-nm -gU build/d3d12.dylib | rg "D3D12CreateDevice|D3D12GetDebugInterface|D3D12SerializeRootSignature"
-otool -L build/d3d12.dylib
+**Updated:** 2026-07-31
+
+M12 is MetalSharp's 64-bit D3D12 route:
+
+```text
+D3D12 PE imports
+  → PipelineId::M12
+  → vkd3d-proton d3d12.dll + d3d12core.dll
+  → DXVK dxgi.dll
+  → Wine Vulkan PE/Unix bridge
+  → ARM64 MoltenVK
+  → Metal
 ```
 
-Results:
+## Runtime ownership
 
-- `test_d3d12` passed: 50 passed, 0 failed.
-- `test_d3d12_entrypoint` passed: 5 passed, 0 failed.
-- `ctest` passed `d3d12`, `d3d12_entrypoint`, `phase18`, and `phase19`.
-- `build/d3d12.dylib` exports `D3D12CreateDevice`.
-- `build/d3d12.dylib` links Metal, Foundation, QuartzCore, AppKit, and
-  `libmetalirconverter`.
+| Boundary | Canonical runtime path |
+|---|---|
+| D3D12 entrypoint | `runtime/wine/lib/vkd3d-proton/x86_64/d3d12.dll` |
+| D3D12 core | `runtime/wine/lib/vkd3d-proton/x86_64/d3d12core.dll` |
+| DXGI | `runtime/wine/lib/dxvk/x86_64/dxgi.dll` |
+| Vulkan PE loader | `runtime/wine/build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll` |
+| Wine Vulkan PE bridge | `runtime/wine/build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll` |
+| Wine Vulkan ARM64 bridge | `runtime/wine/build-ec/dlls/winevulkan/winevulkan.so` |
+| Active MoltenVK host library | `runtime/wine/build-ec/dlls/win32u/libMoltenVK.dylib` |
+| Packaged MoltenVK source artifact | `runtime/wine/lib/moltenvk/libMoltenVK.dylib` |
 
-The external DXMT source tree also rebuilt successfully with:
+M12 must not load `winemetal.dll`, `winemetal.so`, `dxgi_dxmt.dll`, or any `lib/dxmt_m12` artifact. M9/M10/M11 keep their separate DXMT surface.
 
-```sh
-ninja -C <dxmt-source>/build src/winemetal/unix/winemetal.so src/d3d12/d3d12.dll
-```
+## Bottle save and Play
+
+An M12 bottle persists these runtime components:
+
+- `m12_vkd3d_d3d12`
+- `m12_vkd3d_d3d12core`
+- `m12_dxvk_dxgi`
+- `m12_winevulkan`
+- `m12_moltenvk`
+
+Saving an older M12 bottle rebuilds its component list and drops the retired DXMT-M12 component IDs. Saving or playing validates the complete runtime, stages the three PE route DLLs beside the selected executable and into the shared Steam prefix `system32`, then applies the route environment.
+
+## Environment contract
+
+M12 sets:
+
+- `WINEDLLOVERRIDES=d3d12,d3d12core,dxgi=n,b;…`
+- `WINEDLLPATH` containing the vkd3d-proton x86_64 lane and DXVK x86_64 lane
+- `DYLD_LIBRARY_PATH` / `DYLD_FALLBACK_LIBRARY_PATH` containing Wine Vulkan, win32u, and ntdll ARM64 host directories
+- `VKD3D_SHADER_CACHE_PATH`
+- `DXVK_STATE_CACHE_PATH`
+- `MS_GRAPHICS_BACKEND=vkd3d-proton`
+- `WINEMSYNC=1`
+
+It does not set DXMT configuration, winemetal, or DXMT cache variables. Graphics logs add vkd3d-proton, DXVK, and MoltenVK logging only when the user opts in.
+
+## Diagnostics
+
+`GET /diagnostics/m12/dry-run?appid=<appid>` and the generic pipeline dry-run report:
+
+- every PE source path, size, and SHA-256;
+- every Wine Vulkan/MoltenVK host boundary;
+- the exact launch environment;
+- structured missing artifacts with `ok: false`.
+
+The D3D12 runtime doctor now consumes this route contract. The retired DXMT D3D12 SDK probe suite is not used to claim M12 readiness.
+
+## Tested invariants
+
+The deterministic backend suite verifies that:
 
-The current release-hosted graphics bundle contains two DXMT surfaces:
-
-- `Graphics/dll/dxmt`: the 0.46.5 legacy surface used by M9/M10/M11.
-- `Graphics/dll/dxmt-m12`: the updated M12 surface used only by M12, including
-  `winemetal.so`, `libc++.1.dylib`, `libc++abi.1.dylib`, and
-  `libunwind.1.dylib`.
-
-## Completion State
-
-| Area | State | Notes |
-| --- | --- | --- |
-| M12 app routing | Primary/stable | Current project maps D3D12 games to M12 before broad directory heuristics, uses M12 as the unresolved default, and invokes the backend launcher path. |
-| M12 backend handoff | Present | The handoff copies isolated M12 DXMT DLLs, configures Wine/DYLD env, cache env, and launch args. |
-| Subnautica-class M12 runtime | Demonstrated by local use | This validates the launcher/runtime path, not the native CMake D3D12 dylib. |
-| Avery DXMT probes | Strongest external proof | `tests/ROADMAP.md` in `dxmt-src` marks probes 2-6 complete, including compute, triangle, indexed draw, depth, and texture sampling. |
-| Deployed runtime parity | Split surface | M9/M10/M11 stay on the known-good `dxmt` surface while M12 uses the updated release-hosted `dxmt-m12` surface. |
-| Avery source cleanliness | Needs cleanup | `dxmt-src` has dirty debug/probe changes and notes that prior dirty changes broke Steam launching. |
-| Native in-tree D3D12 | Expanded coverage | Smoke, C entrypoint, MSL compute PSO dispatch, and MSL indexed draw tests pass. |
-| Native compute PSO | Implemented for MSL/DXBC/DXIL paths | The in-tree native `CreateComputePipelineState` now creates a real Metal compute pipeline when shader bytecode is available. |
-| Native indexed draw | Covered by offscreen test | GPU virtual-address lookup now binds real Metal vertex/index buffers and the test executes an indexed draw. |
-| Native raytracing/mesh | Stubbed | Advanced D3D12 calls return success or placeholders without full Metal execution. |
-| Native Cocoa viewer | Implemented separately | The NSWindow/CAMetalLayer path exists for native-loader presentation, but M12 Wine games present through DXMT/winemetal. |
-
-## Stability Gaps To Close
-
-1. Add a first-class M12 runtime verification command in this repo that launches
-   a small D3D12 probe through the same `launch_dxmt_metal` environment used by
-   games. — **Addressed (Phase 3):** `GET /diagnostics/m12/dry-run?appid=...`
-   and `GET /diagnostics/pipeline/dry-run?appid=...&pipeline=m12` report the
-   exact env pairs, artifact hashes, and unix sidecars M12 would load, using
-   the same `steam_pipeline_env_pairs` builder as `launch_dxmt_metal`, without
-   launching Steam or the game. The existing `POST /steam/d3d12-runtime-doctor`
-   runs the SDK mini-probe suite through that same environment.
-2. Add a native Cocoa viewer test target if the goal is to exercise the in-tree
-   `metalsharp_d3d12` implementation through CAMetalLayer rather than through
-   Wine/winemetal.
-3. Expand native D3D12 tests beyond the current graphics/compute coverage:
-   texture sampling, depth compare, and swapchain present.
-
-## Practical Conclusion
-
-The current MetalSharp project treats M12 as the D3D12 DXMT route while keeping
-older DXMT routes isolated. D3D12 PE import detection selects M12, the backend
-handoff deploys the `dxmt-m12` runtime, and M9/M10/M11 continue to use the
-legacy `dxmt` surface that is known to work for current Steam/Wine titles.
-
-## M12 Artifact and Launch Verification (Phase 3)
-
-A reviewer can prove M12 loaded the intended artifacts without launching a full
-game using the read-only dry-run verifier. It runs through the same environment
-builder (`steam_pipeline_env_pairs`) as `launch_dxmt_metal`, so the reported env
-pairs and artifact sources are exactly what a real M12 launch would use.
-
-- `GET /diagnostics/m12/dry-run?appid=<appid>` — M12-specific dry-run including
-  the `lib/dxmt-m12/x86_64-unix` sidecars (`winemetal.so`, `libc++.1.dylib`,
-  `libc++abi.1.dylib`, `libunwind.1.dylib`).
-- `GET /diagnostics/pipeline/dry-run?appid=<appid>&pipeline=m12|m11|...` —
-  generic pipeline dry-run for comparing lanes.
-
-The dry-run reports, per artifact: resolved source path, presence, sha256, and
-size; required artifacts that are missing produce a structured `ok: false` with
-a `missing[]` array rather than a silent fallback. Env keys verified present:
-`WINEDLLOVERRIDES` (winemetal overrides), `DXMT_SHADER_CACHE_PATH` (isolated
-`m12` lane), `DYLD_FALLBACK_LIBRARY_PATH`/`LD_LIBRARY_PATH`, `SteamAppId`, and
-`DXMT_WINEMETAL_UNIXLIB`.
-
-Contract guarantees covered by tests:
-
-- M12 deploys `d3d12.dll`, `dxgi.dll`, `d3d11.dll`, `d3d10core.dll`,
-  `winemetal.dll` from `lib/dxmt-m12/x86_64-windows`.
-- M11 does **not** deploy `d3d12.dll` and points only at `lib/dxmt`, never
-  `lib/dxmt-m12`.
-- M12 dry-run includes `d3d12.dll`; M11 dry-run does not.
+- D3D12 PE detection selects M12 only for a compatible 64-bit route;
+- M12 deploys exactly the vkd3d-proton/DXVK ownership set;
+- M12 route switches remove stale DXMT DLLs;
+- M12 prefix staging includes `d3d12.dll`, `d3d12core.dll`, and `dxgi.dll`;
+- M12 has no DXMT/winemetal environment;
+- M9/M10/M11 remain on their existing DXMT lanes;
+- D3DMetal remains a distinct Homebrew GPTK prefix.
diff --git a/docs/architecture/m9-pipeline-map.md b/docs/architecture/m9-pipeline-map.md
index 76e78a932..fefa454b6 100644
--- a/docs/architecture/m9-pipeline-map.md
+++ b/docs/architecture/m9-pipeline-map.md
@@ -1,8 +1,8 @@
 # M9 Pipeline Map
-**Updated:** 2026-07-08
+**Updated:** 2026-07-31
 
 
-M9 is the D3D9 engine path. It now uses the same DXMT-family launcher, cache, and Metal handoff conventions as M10, M11, and M12 instead of selecting the old DXVK/MoltenVK labels.
+M9 is the D3D9 engine path. It uses the same DXMT-family launcher, cache, and Metal handoff conventions as M10 and M11. M12 is a separate vkd3d-proton/DXVK/Wine Vulkan/MoltenVK route.
 
 ## Runtime Shape
 
diff --git a/docs/compatibility/GAMES-SUPPORTED.md b/docs/compatibility/GAMES-SUPPORTED.md
index 23c96231a..5fe69b976 100644
--- a/docs/compatibility/GAMES-SUPPORTED.md
+++ b/docs/compatibility/GAMES-SUPPORTED.md
@@ -13,7 +13,7 @@ Games were tested from an external 1TB M.2 SSD (~5000 MB/s over USB-C 3.1) on an
 | Pipeline | Backend | Use |
 |---|---|---|
 | **D3DMetal** | Homebrew GPTK / Apple D3DMetal | D3D11/D3D12 via Apple's D3DMetal framework. GPTK is installed through Homebrew and is not bundled by MetalSharp. |
-| **M12** | DXMT | D3D12 to Metal |
+| **M12** | vkd3d-proton + DXVK + MoltenVK | D3D12 through Vulkan to Metal |
 | **M11** | DXMT | D3D11 to Metal |
 | **M11 (32-bit)** | DXMT | D3D11 to Metal, 32-bit prefix route |
 | **M10** | DXMT | D3D10 to Metal |
diff --git a/docs/guides/gptk-guide.md b/docs/guides/gptk-guide.md
index 987ea73a3..7dd0bafef 100644
--- a/docs/guides/gptk-guide.md
+++ b/docs/guides/gptk-guide.md
@@ -2,7 +2,7 @@
 **Updated:** 2026-07-08
 
 
-MetalSharp supports Apple's Game Porting Toolkit (GPTK) as the **D3DMetal** route. This route uses Apple's D3DMetal framework for D3D11/D3D12 translation instead of the DXMT Metal path used by M11/M12.
+MetalSharp supports Apple's Game Porting Toolkit (GPTK) as the **D3DMetal** route. This route uses Apple's D3DMetal framework for D3D11/D3D12 translation instead of the DXMT path used by M9-M11 or the vkd3d-proton/MoltenVK path used by M12.
 
 GPTK is **not bundled** with MetalSharp. MetalSharp installs and uses the Homebrew GPTK app in place:
 
@@ -93,7 +93,7 @@ DYLD_FALLBACK_LIBRARY_PATH=<Homebrew GPTK lib paths>
 | **Prefix** | Shared (`prefix-gptk`) | Shared Wine Steam prefix with bottle preflight |
 | **Best for** | Games that need Apple's D3DMetal behavior | Most games, better compatibility tracking |
 
-Use M11 or M12 as the default. Switch to D3DMetal if a game has specific rendering issues on the DXMT path or if developer notes say to use GPTK.
+Use M11 or M12 as the default. Switch to D3DMetal if a game has specific rendering issues on its default DXMT or vkd3d-proton route, or if developer notes say to use GPTK.
 
 ## GPTK Prefix Location
 
diff --git a/docs/guides/install-from-source.md b/docs/guides/install-from-source.md
index efc750b38..eb28acd20 100644
--- a/docs/guides/install-from-source.md
+++ b/docs/guides/install-from-source.md
@@ -1,5 +1,5 @@
 # Install from Source
-**Updated:** 2026-07-08
+**Updated:** 2026-07-31
 
 
 Build MetalSharp from source without using the DMG. Requires macOS 14+ on Apple Silicon.
@@ -42,7 +42,7 @@ cd app && npm install && npm run build && cd ..
 
 ## Fetch Runtime Bundles
 
-Downloads MetalSharp-owned runtime assets from the GitHub release: Wine, DXMT/M12 graphics DLLs, Steam setup files, Mono/FNA support files, Goldberg assets, and other bundled runtime material.
+Downloads the complete multi-architecture Wine runtime from the GitHub release, including DXMT M9-M11 lanes, the M12 vkd3d-proton/DXVK/Wine Vulkan/MoltenVK route, Steam setup files, Mono/FNA support files, Goldberg assets, and other bundled runtime material.
 
 GPTK/D3DMetal is not bundled in MetalSharp release assets. When you save a D3DMetal bottle, MetalSharp installs/trusts Homebrew GPTK separately and uses `/Applications/Game Porting Toolkit.app` directly.
 
diff --git a/docs/runtime/runtime-bundles-and-steam-routing.md b/docs/runtime/runtime-bundles-and-steam-routing.md
index d872b76aa..7c90d6f6b 100644
--- a/docs/runtime/runtime-bundles-and-steam-routing.md
+++ b/docs/runtime/runtime-bundles-and-steam-routing.md
@@ -15,7 +15,7 @@ Current split bundle roots:
 | Asset | Why it is guarded |
 |---|---|
 | `metalsharp-electron.tar.zst` | Contains `electron/`, the built Electron application payload. |
-| `metalsharp-graphics-dll.tar.zst` | Contains `Graphics/dll/`, the legacy DXMT D3D9/D3D10/D3D11 surface and the isolated M12 D3D12 surface. |
+| `metalsharp-graphics-dll.tar.zst` | Legacy split-bundle compatibility asset; the 0.60 preview installs the complete runtime archive instead. |
 | `metalsharp-runtime.tar.zst` | Contains `runtime/`, the Wine runtime, host ABI, and backend executable. |
 | `metalsharp-assets.tar.zst` | Contains `assets/`, Mono, GPTK, DXVK, Goldberg, EAC toggle, shims, and runtime support assets. |
 | `metalsharp-scripts-tools.tar.zst` | Contains `scripts/tools/`, updater scripts, configs, native tools, and CEF helpers. |
@@ -32,20 +32,16 @@ tools/bundles/verify-developer-sdk.sh app/bundles/metalsharp-d3d12-developer-sdk
 
 ## Installer Acceptance Rules
 
-The installer consumes the split runtime tarballs by root name. `metalsharp-graphics-dll.tar.zst` is the only source for the active DXMT runtime payloads used by M9-M12.
+The 0.60 preview installer consumes the complete multi-architecture runtime archive. Older split graphics bundles remain documented for compatibility with earlier releases but are not the M12 source of truth.
 
-The graphics bundle has two runtime surfaces:
+The active graphics routes are:
 
 ```text
-Graphics/dll/dxmt/      -> legacy DXMT payload for M9, M10, and M11
-Graphics/dll/dxmt-m12/  -> updated D3D12/DXGI/winemetal payload for M12 only
-```
-
-After install those surfaces live under:
-
-```text
-~/.metalsharp/runtime/wine/lib/dxmt/
-~/.metalsharp/runtime/wine/lib/dxmt-m12/
+runtime/wine/lib/dxmt/                  -> DXMT payload for M9, M10, and M11
+runtime/wine/lib/vkd3d-proton/x86_64/   -> M12 d3d12.dll and d3d12core.dll
+runtime/wine/lib/dxvk/x86_64/           -> M12 dxgi.dll
+runtime/wine/build-ec/dlls/winevulkan/  -> M12 ARM64 Wine Vulkan bridge
+runtime/wine/lib/moltenvk/               -> pinned ARM64 MoltenVK payload
 ```
 
 Installed DXMT runtime state is recorded in:
@@ -54,7 +50,7 @@ Installed DXMT runtime state is recorded in:
 ~/.metalsharp/runtime/wine/lib/dxmt/metalsharp-dxmt-runtime.json
 ```
 
-Do not trust a runtime by version string alone. Check the manifest, required DLLs, the `dxmt-m12` sidecars, and source archive hash when diagnosing deployment drift.
+Do not trust a runtime by version string alone. Check the complete-runtime marker and the route-specific PE/Unix host artifacts. M12 must not resolve any `dxmt-m12` or winemetal artifact.
 
 ## Steam Launch Route
 
diff --git a/docs/runtime/wine-architecture.md b/docs/runtime/wine-architecture.md
index 250bc4c24..5328f642d 100644
--- a/docs/runtime/wine-architecture.md
+++ b/docs/runtime/wine-architecture.md
@@ -27,6 +27,9 @@ It is used by the public Wine-backed routes M12, M11, M10, and M9. Internal fall
 │   ├── dxmt/
 │   │   ├── x86_64-unix/
 │   │   └── x86_64-windows/
+│   ├── vkd3d-proton/x86_64/
+│   ├── dxvk/x86_64/
+│   └── moltenvk/
 └── etc/
     ├── dxmt.conf
     └── vulkan/icd.d/MoltenVK_icd.json
@@ -57,7 +60,7 @@ User/runtime state lives beside the runtime root:
 
 | Route | Wine use |
 |---|---|
-| M12 | Wine + DXMT D3D12/D3D11/DXGI |
+| M12 | Wine + vkd3d-proton D3D12 + DXVK DXGI + Wine Vulkan + ARM64 MoltenVK |
 | M11 | Wine + DXMT D3D11/DXGI |
 | M10 | Wine + DXMT D3D10/D3D11/DXGI |
 | M9 | Wine + D3D9 Metal under the DXMT launch family |
@@ -83,10 +86,8 @@ M12:
 
 ```text
 d3d12.dll
-d3d11.dll
+d3d12core.dll
 dxgi.dll
-d3d10core.dll
-winemetal.dll
 ```
 
 M9:
diff --git a/scripts/install-metalsharp-wine-runtime.sh b/scripts/install-metalsharp-wine-runtime.sh
index 7bd9f77e1..7a3d885ce 100755
--- a/scripts/install-metalsharp-wine-runtime.sh
+++ b/scripts/install-metalsharp-wine-runtime.sh
@@ -218,8 +218,30 @@ validate_archive_layout() {
     "$PACKAGE_ROOT/wine/build-ec/server/wineserver" \
     "$PACKAGE_ROOT/wine/wine-11.12/nls/locale.nls" \
     "$PACKAGE_ROOT/wine/wine-11.12/fonts/tahoma.ttf" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/aarch64-unix/winemetal.so" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/aarch64-windows/d3d10core.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/aarch64-windows/d3d11.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/aarch64-windows/dxgi.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/aarch64-windows/winemetal.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/i386-windows/d3d10core.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/i386-windows/d3d11.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/i386-windows/dxgi.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dxmt-v0.80/i386-windows/winemetal.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/d3d9/x86_64-windows/d3d9.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/d3d9/i386-windows/d3d9.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/d3d10/x86_64-windows/d3d10.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/d3d10/i386-windows/d3d10.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/d3d10_1/x86_64-windows/d3d10_1.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/d3d10_1/i386-windows/d3d10_1.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/dxgi/i386-windows/dxgi.dll" \
     "$PACKAGE_ROOT/graphics/dxvk/i386/d3d9.dll" \
     "$PACKAGE_ROOT/graphics/vkd3d-proton/x86_64/d3d12.dll" \
+    "$PACKAGE_ROOT/graphics/vkd3d-proton/x86_64/d3d12core.dll" \
+    "$PACKAGE_ROOT/graphics/dxvk/x86_64/dxgi.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/winevulkan/winevulkan.so" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/winevulkan/x86_64-windows/winevulkan.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/vulkan-1/x86_64-windows/vulkan-1.dll" \
+    "$PACKAGE_ROOT/wine/build-ec/dlls/win32u/libMoltenVK.dylib" \
     "$PACKAGE_ROOT/graphics/opengl-metal/metalsharp-opengl.dylib" \
     "$PACKAGE_ROOT/graphics/moltenvk/libMoltenVK.dylib" \
     "$PACKAGE_ROOT/providers/xtajit64-arm64ec-known-good.dll" \

From cc60063d917869197d6f305267eabc8551ee57bd Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 17:12:25 -0600
Subject: [PATCH 07/14] add global controller and msync controls

---
 AGENTS.md                               |  12 ++
 app/src-rust/src/gog.rs                 |   2 +-
 app/src-rust/src/launch.rs              |  85 +++++++++
 app/src-rust/src/mtsp/launcher.rs       |  16 +-
 app/src-rust/src/steam.rs               |  19 ++-
 app/src/renderer/api-types.ts           |   4 +
 app/src/renderer/components/Sidebar.vue | 218 +++++++++++++++++++++++-
 app/src/shared/types.ts                 |   2 +
 8 files changed, 344 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7d7182392..8725d701a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,6 +86,18 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   and its Unix winemetal bridge identifies as ARM64. The deterministic Rust
   suite passes 651/651, strict Clippy passes, all Rust targets build, and the
   TypeScript/Vite production build passes.
+- Phase 7 adds global Controller `[D | X]` and Msync controls to the left
+  sidebar. Settings persist as `controllerMode` (`dinput` or `xinput`) and
+  `msyncEnabled`; legacy snake-case aliases are read and written as well.
+- Every managed Wine path receives `METALSHARP_CONTROLLER_MODE` and
+  `WINEMSYNC`, including MTSP direct routes, Steam route handoffs, Steam
+  setup/update processes, ordinary Wine launches, prefix initialization, and
+  GOG. Existing installs default to XInput and Msync enabled. Environment
+  overrides remain available as `METALSHARP_CONTROLLER_MODE` and
+  `METALSHARP_MSYNC`.
+- Phase 7 validation: the deterministic Rust suite passes 653/653, strict
+  Clippy passes, all Rust targets build, and the TypeScript/Vite production
+  build passes.
 
 ## What This Project Is
 
diff --git a/app/src-rust/src/gog.rs b/app/src-rust/src/gog.rs
index 8403680e2..893f8e8fc 100644
--- a/app/src-rust/src/gog.rs
+++ b/app/src-rust/src/gog.rs
@@ -570,11 +570,11 @@ fn initialize_prefix() -> Result<(), String> {
         .arg("wineboot")
         .arg("-u")
         .env("WINEPREFIX", prefix.to_string_lossy().to_string())
-        .env("WINEMSYNC", "1")
         .env("WINEDEBUG", "-all")
         .env("MS_FWD_COMPAT_GL_CTX", "1")
         .stdout(Stdio::null())
         .stderr(Stdio::null());
+    crate::launch::apply_wine_runtime_preferences(&mut command);
     crate::platform::set_runtime_library_env(&mut command, &wine_root());
     let status = command.status().map_err(|error| format!("failed to initialize GOG prefix: {}", error))?;
     if status.success() {
diff --git a/app/src-rust/src/launch.rs b/app/src-rust/src/launch.rs
index 28ddc6c06..5fb2e1fc1 100644
--- a/app/src-rust/src/launch.rs
+++ b/app/src-rust/src/launch.rs
@@ -46,6 +46,7 @@ pub fn launch_via_steam(appid: u32) -> Result<u32, Box<dyn std::error::Error>> {
         .args(["start", &url])
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null());
+    apply_wine_runtime_preferences(&mut cmd);
     crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
     spawn_and_reap(cmd)
 }
@@ -87,6 +88,7 @@ pub fn launch_via_steam_with_env(
 
     let mut cmd = Command::new(&wine);
     cmd.env("WINEPREFIX", &prefix_str).env("WINEDEBUG", "-all").env("WINEDEBUGGER", "none");
+    apply_wine_runtime_preferences(&mut cmd);
     crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
 
     for (key, val) in extra_env {
@@ -192,6 +194,8 @@ pub fn get_config() -> Value {
     let native_available = find_metalsharp_native().is_ok();
     let mono_available = find_mono().is_ok();
     let graphics_runtime_logs = graphics_runtime_logs_enabled();
+    let controller_mode = controller_mode();
+    let msync_enabled = msync_enabled();
 
     json!({
         "ok": true,
@@ -199,9 +203,44 @@ pub fn get_config() -> Value {
         "mono_available": mono_available,
         "graphicsRuntimeLogs": graphics_runtime_logs,
         "graphics_runtime_logs": graphics_runtime_logs,
+        "controllerMode": controller_mode,
+        "controller_mode": controller_mode,
+        "msyncEnabled": msync_enabled,
+        "msync_enabled": msync_enabled,
     })
 }
 
+pub fn controller_mode() -> String {
+    if let Ok(value) = std::env::var("METALSHARP_CONTROLLER_MODE") {
+        if let Some(mode) = normalize_controller_mode(&value) {
+            return mode.to_string();
+        }
+    }
+    read_config_string("controllerMode")
+        .or_else(|| read_config_string("controller_mode"))
+        .and_then(|value| normalize_controller_mode(&value).map(str::to_string))
+        .unwrap_or_else(|| "xinput".to_string())
+}
+
+pub fn msync_enabled() -> bool {
+    if let Ok(value) = std::env::var("METALSHARP_MSYNC") {
+        return truthy(&value);
+    }
+    read_config_bool("msyncEnabled").or_else(|| read_config_bool("msync_enabled")).unwrap_or(true)
+}
+
+pub fn apply_wine_runtime_preferences(command: &mut Command) {
+    command.env("WINEMSYNC", if msync_enabled() { "1" } else { "0" });
+    command.env("METALSHARP_CONTROLLER_MODE", controller_mode());
+}
+
+pub fn wine_runtime_preference_env_pairs() -> [(String, String); 2] {
+    [
+        ("WINEMSYNC".to_string(), if msync_enabled() { "1" } else { "0" }.to_string()),
+        ("METALSHARP_CONTROLLER_MODE".to_string(), controller_mode()),
+    ]
+}
+
 pub fn graphics_runtime_logs_enabled() -> bool {
     if let Ok(value) = std::env::var("METALSHARP_GRAPHICS_RUNTIME_LOGS") {
         return truthy(&value);
@@ -216,6 +255,21 @@ fn read_config_bool(key: &str) -> Option<bool> {
     value.get(key).and_then(json_bool)
 }
 
+fn read_config_string(key: &str) -> Option<String> {
+    let path = config_path_for_home(&dirs::home_dir()?);
+    let contents = std::fs::read_to_string(path).ok()?;
+    let value: Value = serde_json::from_str(&contents).ok()?;
+    value.get(key).and_then(Value::as_str).map(str::to_string)
+}
+
+fn normalize_controller_mode(value: &str) -> Option<&'static str> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "d" | "dinput" => Some("dinput"),
+        "x" | "xinput" => Some("xinput"),
+        _ => None,
+    }
+}
+
 fn json_bool(value: &Value) -> Option<bool> {
     match value {
         Value::Bool(b) => Some(*b),
@@ -354,6 +408,7 @@ pub fn ensure_wine_prefix(prefix: &PathBuf) -> Result<(), Box<dyn std::error::Er
         .arg("--init")
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null());
+    apply_wine_runtime_preferences(&mut cmd);
     crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
     let status = cmd.status()?;
 
@@ -386,6 +441,19 @@ pub fn set_config(body: &Map<String, Value>) -> Result<Value, Box<dyn std::error
         cfg.insert("graphics_runtime_logs".into(), json!(value));
     }
 
+    if let Some(value) = body.get("controllerMode").or_else(|| body.get("controller_mode")) {
+        let raw = value.as_str().ok_or("controllerMode must be dinput or xinput")?;
+        let mode = normalize_controller_mode(raw).ok_or("controllerMode must be dinput or xinput")?;
+        cfg.insert("controllerMode".into(), json!(mode));
+        cfg.insert("controller_mode".into(), json!(mode));
+    }
+
+    if let Some(raw) = body.get("msyncEnabled").or_else(|| body.get("msync_enabled")) {
+        let value = json_bool(raw).ok_or("msyncEnabled must be a boolean")?;
+        cfg.insert("msyncEnabled".into(), json!(value));
+        cfg.insert("msync_enabled".into(), json!(value));
+    }
+
     std::fs::write(&path, serde_json::to_string_pretty(&cfg)?)?;
     Ok(get_config())
 }
@@ -401,6 +469,7 @@ fn launch_via_wine(exe_path: &str) -> Result<u32, Box<dyn std::error::Error>> {
     let ms_root = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
     let mut cmd = Command::new(&wine);
     cmd.env("WINEPREFIX", &prefix_str).arg(exe_path);
+    apply_wine_runtime_preferences(&mut cmd);
     crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
     let child = cmd.spawn()?;
 
@@ -458,4 +527,20 @@ mod tests {
         assert!(ensure_steam_env_handoff_supported(true, &[]).is_ok());
         assert!(ensure_steam_env_handoff_supported(false, &env).is_ok());
     }
+
+    #[test]
+    fn controller_mode_contract_accepts_only_dinput_or_xinput() {
+        assert_eq!(normalize_controller_mode("D"), Some("dinput"));
+        assert_eq!(normalize_controller_mode(" xinput "), Some("xinput"));
+        assert_eq!(normalize_controller_mode("automatic"), None);
+    }
+
+    #[test]
+    fn runtime_preferences_have_stable_launch_keys() {
+        let pairs = wine_runtime_preference_env_pairs();
+        assert_eq!(pairs[0].0, "WINEMSYNC");
+        assert_eq!(pairs[1].0, "METALSHARP_CONTROLLER_MODE");
+        assert!(matches!(pairs[0].1.as_str(), "0" | "1"));
+        assert!(matches!(pairs[1].1.as_str(), "dinput" | "xinput"));
+    }
 }
diff --git a/app/src-rust/src/mtsp/launcher.rs b/app/src-rust/src/mtsp/launcher.rs
index 6fa5d60bc..9a72a4113 100644
--- a/app/src-rust/src/mtsp/launcher.rs
+++ b/app/src-rust/src/mtsp/launcher.rs
@@ -1105,6 +1105,7 @@ pub fn launch_custom_with_options(
         .env("WINEPREFIX", &prefix_str)
         .env("WINEDEBUG", wine_debug_value())
         .env("WINEDEBUGGER", "none");
+    crate::launch::apply_wine_runtime_preferences(&mut cmd);
     apply_route_library_env(&mut cmd, &ms_root, &node.dyld_paths);
     apply_metalfx_home_env(&mut cmd, &home);
 
@@ -1125,7 +1126,6 @@ pub fn launch_custom_with_options(
         cmd.env("DXMT_WINEMETAL_UNIXLIB", dxmt_winemetal_unixlib_path(&ms_root));
     }
     cmd.env("MS_GRAPHICS_BACKEND", node.graphics_backend);
-    cmd.env("WINEMSYNC", "1");
     for ev in &node.env_vars {
         cmd.env(ev.key, ev.value);
     }
@@ -1432,8 +1432,8 @@ fn launch_d3dmetal_gptk_with_context(
         .env("WINESERVER", &gptk_wineserver)
         .env("WINELOADER", &gptk_wine64)
         .env("DYLD_FALLBACK_LIBRARY_PATH", &dyld)
-        .env("MS_GRAPHICS_BACKEND", node.graphics_backend)
-        .env("WINEMSYNC", "1");
+        .env("MS_GRAPHICS_BACKEND", node.graphics_backend);
+    crate::launch::apply_wine_runtime_preferences(&mut cmd);
     apply_metalfx_home_env(&mut cmd, &home);
 
     if node.uses_winedllpath_routing() {
@@ -1558,6 +1558,7 @@ fn launch_wine_graphics_with_context(
         .env("WINEPREFIX", &prefix_str)
         .env("WINEDEBUG", wine_debug_value())
         .env("WINEDEBUGGER", "none");
+    crate::launch::apply_wine_runtime_preferences(&mut cmd);
     apply_route_library_env(&mut cmd, &ms_root, &node.dyld_paths);
     apply_metalfx_home_env(&mut cmd, &home);
 
@@ -1579,7 +1580,6 @@ fn launch_wine_graphics_with_context(
     }
 
     cmd.env("MS_GRAPHICS_BACKEND", node.graphics_backend);
-    cmd.env("WINEMSYNC", "1");
 
     for ev in &node.env_vars {
         cmd.env(ev.key, ev.value);
@@ -1657,6 +1657,7 @@ fn launch_wine_bare_with_context(
         .env("WINEPREFIX", &prefix_str)
         .env("WINEDEBUG", wine_debug_value())
         .env("WINEDEBUGGER", "none");
+    crate::launch::apply_wine_runtime_preferences(&mut cmd);
     apply_route_library_env(&mut cmd, &ms_root, &node.dyld_paths);
     apply_metalfx_home_env(&mut cmd, &home);
 
@@ -1667,7 +1668,6 @@ fn launch_wine_bare_with_context(
     let cache_paths = build_cache_paths(&home, node, appid);
     apply_cache_env(&mut cmd, node, cache_paths.as_ref(), &ms_root);
     cmd.env("MS_GRAPHICS_BACKEND", node.graphics_backend);
-    cmd.env("WINEMSYNC", "1");
     for ev in &node.env_vars {
         cmd.env(ev.key, ev.value);
     }
@@ -2355,7 +2355,7 @@ fn steam_pipeline_env_pairs(home: &PathBuf, node: &PipelineNode, appid: u32) ->
         env.push(("DXMT_WINEMETAL_UNIXLIB".to_string(), dxmt_winemetal_unixlib_path(&ms_root)));
     }
     env.push(("MS_GRAPHICS_BACKEND".to_string(), node.graphics_backend.to_string()));
-    env.push(("WINEMSYNC".to_string(), "1".to_string()));
+    env.extend(crate::launch::wine_runtime_preference_env_pairs());
     env.extend(cache_env_pairs(node, cache_paths.as_ref(), &ms_root));
     env.extend(node.env_vars.iter().map(|ev| (ev.key.to_string(), ev.value.to_string())));
     env.extend(app_compat_env_pairs(appid, node.id));
@@ -2388,6 +2388,7 @@ fn is_reserved_route_env_key(pipeline_id: PipelineId, key: &str) -> bool {
             | "VK_ICD_FILENAMES"
             | "MS_GRAPHICS_BACKEND"
             | "WINEMSYNC"
+            | "METALSHARP_CONTROLLER_MODE"
     )
 }
 
@@ -5226,6 +5227,7 @@ mod tests {
             "VK_ICD_FILENAMES",
             "MS_GRAPHICS_BACKEND",
             "WINEMSYNC",
+            "METALSHARP_CONTROLLER_MODE",
         ] {
             assert!(is_reserved_route_env_key(PipelineId::M12, key), "{} must be reserved for M12", key);
             assert!(!is_reserved_route_env_key(PipelineId::M11, key), "{} should remain overridable outside M12", key);
@@ -5247,6 +5249,8 @@ mod tests {
         assert!(keys.contains("SteamOverlayGameId"));
         assert!(keys.contains("VKD3D_SHADER_CACHE_PATH"));
         assert!(keys.contains("DXVK_STATE_CACHE_PATH"));
+        assert!(keys.contains("WINEMSYNC"));
+        assert!(keys.contains("METALSHARP_CONTROLLER_MODE"));
         assert!(!keys.contains("VKD3D_LOG_FILE"));
         assert!(keys.contains("METALSHARP_CACHE_SUMMARY"));
         assert!(!env.iter().any(|(key, _)| key.starts_with("DXMT")));
diff --git a/app/src-rust/src/steam.rs b/app/src-rust/src/steam.rs
index ff5bca331..ac21da926 100644
--- a/app/src-rust/src/steam.rs
+++ b/app/src-rust/src/steam.rs
@@ -335,6 +335,7 @@ fn seed_steam_d3d12_guard(prefix: &Path, ms_root: &Path) -> Result<(), Box<dyn s
         .env("WINEDEBUGGER", "none")
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null());
+    crate::launch::apply_wine_runtime_preferences(&mut cmd);
     crate::platform::set_runtime_library_env(&mut cmd, ms_root);
     let status = cmd.status()?;
     if status.success() {
@@ -422,6 +423,7 @@ fn spawn_wine_steam_with_env(args: &[&str], extra_env: &[(String, String)]) -> R
         .arg(&exe)
         .args(args)
         .stdout(std::process::Stdio::null());
+    crate::launch::apply_wine_runtime_preferences(&mut cmd);
 
     if let Some(f) = log_file {
         cmd.stderr(std::process::Stdio::from(f));
@@ -1660,7 +1662,8 @@ fn prepare_steam_prefix(prefix: &Path) -> Result<(), Box<dyn std::error::Error>>
     run_runtime_provider_stage(prefix, false)?;
 
     let wineboot = build.join("programs/wineboot/aarch64-windows/wineboot.exe");
-    let status = Command::new(&wine)
+    let mut wineboot_command = Command::new(&wine);
+    wineboot_command
         .arg(&wineboot)
         .arg("--init")
         .env("WINEPREFIX", prefix)
@@ -1673,8 +1676,9 @@ fn prepare_steam_prefix(prefix: &Path) -> Result<(), Box<dyn std::error::Error>>
         .env("FEX_VECTORTSOENABLED", "0")
         .env("FEX_MEMCPYSETTSOENABLED", "0")
         .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null())
-        .status()?;
+        .stderr(std::process::Stdio::null());
+    crate::launch::apply_wine_runtime_preferences(&mut wineboot_command);
+    let status = wineboot_command.status()?;
     if !status.success() {
         return Err(format!("all-architecture wineboot failed with {status}").into());
     }
@@ -1718,7 +1722,8 @@ fn spawn_steam_install_bootstrap() -> Result<u32, Box<dyn std::error::Error>> {
     let output =
         std::fs::OpenOptions::new().create(true).append(true).open(log_dir.join("steam-install-handoff.log"))?;
     let errors = output.try_clone()?;
-    let child = Command::new(ms_wine())
+    let mut command = Command::new(ms_wine());
+    command
         .arg(&steam)
         .current_dir(&steam_dir)
         .env("WINEPREFIX", &prefix)
@@ -1734,8 +1739,9 @@ fn spawn_steam_install_bootstrap() -> Result<u32, Box<dyn std::error::Error>> {
         .env("MS_FWD_COMPAT_GL_CTX", "1")
         .stdin(std::process::Stdio::null())
         .stdout(std::process::Stdio::from(output))
-        .stderr(std::process::Stdio::from(errors))
-        .spawn()?;
+        .stderr(std::process::Stdio::from(errors));
+    crate::launch::apply_wine_runtime_preferences(&mut command);
+    let child = command.spawn()?;
     Ok(child.id())
 }
 
@@ -1883,6 +1889,7 @@ fn run_install_steam() -> Result<String, Box<dyn std::error::Error>> {
         .arg(&installer)
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null());
+    crate::launch::apply_wine_runtime_preferences(&mut install_cmd);
 
     let mut install_child = install_cmd.spawn()?;
     let install_pid = install_child.id();
diff --git a/app/src/renderer/api-types.ts b/app/src/renderer/api-types.ts
index 90b80c411..e1bb766f7 100644
--- a/app/src/renderer/api-types.ts
+++ b/app/src/renderer/api-types.ts
@@ -33,6 +33,10 @@ interface AppConfig {
   mono_available?: boolean;
   graphicsRuntimeLogs?: boolean;
   graphics_runtime_logs?: boolean;
+  controllerMode?: "dinput" | "xinput";
+  controller_mode?: "dinput" | "xinput";
+  msyncEnabled?: boolean;
+  msync_enabled?: boolean;
 }
 
 interface UpdateStatus {
diff --git a/app/src/renderer/components/Sidebar.vue b/app/src/renderer/components/Sidebar.vue
index c0d130a5f..628941f9b 100644
--- a/app/src/renderer/components/Sidebar.vue
+++ b/app/src/renderer/components/Sidebar.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, nextTick, ref, watch, type Component } from "vue";
+import { computed, nextTick, onMounted, ref, watch, type Component } from "vue";
 import IconMenu from "~icons/lucide/menu";
 import IconMoon from "~icons/lucide/moon";
 import IconSun from "~icons/lucide/sun";
@@ -13,6 +13,7 @@ import IconFlame from "~icons/lucide/flame";
 import IconTreePalm from "~icons/lucide/tree-palm";
 import IconScanLine from "~icons/lucide/scan-line";
 import { themedNavIcon, type ThemeName } from "../composables/useTheme";
+import { api } from "../composables/useApi";
 
 const props = defineProps<{
   currentView: string;
@@ -27,6 +28,48 @@ const emit = defineEmits<{
 const collapsed = ref(false);
 const themePickerOpen = ref(false);
 const themePickerRef = ref<HTMLElement | null>(null);
+const controllerMode = ref<"dinput" | "xinput">("xinput");
+const msyncEnabled = ref(true);
+const runtimePreferencesSaving = ref(false);
+
+async function loadRuntimePreferences() {
+  const config = await api<AppConfig>("GET", "/config");
+  if (!config?.ok) return;
+  controllerMode.value = config.controllerMode ?? config.controller_mode ?? "xinput";
+  msyncEnabled.value = Boolean(config.msyncEnabled ?? config.msync_enabled ?? true);
+}
+
+async function saveRuntimePreferences(body: Record<string, unknown>) {
+  if (runtimePreferencesSaving.value) return false;
+  runtimePreferencesSaving.value = true;
+  const config = await api<AppConfig>("POST", "/config", body);
+  if (config?.ok) {
+    controllerMode.value = config.controllerMode ?? config.controller_mode ?? controllerMode.value;
+    msyncEnabled.value = Boolean(config.msyncEnabled ?? config.msync_enabled ?? msyncEnabled.value);
+  }
+  runtimePreferencesSaving.value = false;
+  return Boolean(config?.ok);
+}
+
+function selectControllerMode(mode: "dinput" | "xinput") {
+  if (mode === controllerMode.value) return;
+  const previous = controllerMode.value;
+  controllerMode.value = mode;
+  void saveRuntimePreferences({ controllerMode: mode }).then((saved) => {
+    if (!saved) controllerMode.value = previous;
+  });
+}
+
+function toggleMsync() {
+  const previous = msyncEnabled.value;
+  const enabled = !msyncEnabled.value;
+  msyncEnabled.value = enabled;
+  void saveRuntimePreferences({ msyncEnabled: enabled }).then((saved) => {
+    if (!saved) msyncEnabled.value = previous;
+  });
+}
+
+onMounted(() => void loadRuntimePreferences());
 
 watch(themePickerOpen, async (open) => {
   if (!open) return;
@@ -100,6 +143,46 @@ const navItems = computed<NavItem[]>(() => [
       </button>
     </div>
 
+    <div class="sidebar-runtime-controls">
+      <div class="runtime-control controller-control" :title="collapsed ? `Controller: ${controllerMode}` : undefined">
+        <span v-if="!collapsed" class="runtime-control-label">Controller</span>
+        <div class="controller-selector" role="group" aria-label="Controller input mode">
+          <button
+            class="controller-option"
+            :class="{ active: controllerMode === 'dinput' }"
+            :aria-pressed="controllerMode === 'dinput'"
+            :disabled="runtimePreferencesSaving"
+            title="DirectInput"
+            @click="selectControllerMode('dinput')"
+          >
+            D
+          </button>
+          <span v-if="!collapsed" class="controller-divider">|</span>
+          <button
+            class="controller-option"
+            :class="{ active: controllerMode === 'xinput' }"
+            :aria-pressed="controllerMode === 'xinput'"
+            :disabled="runtimePreferencesSaving"
+            title="XInput"
+            @click="selectControllerMode('xinput')"
+          >
+            X
+          </button>
+        </div>
+      </div>
+      <button
+        class="msync-toggle"
+        :class="{ active: msyncEnabled }"
+        :aria-pressed="msyncEnabled"
+        :disabled="runtimePreferencesSaving"
+        :title="collapsed ? `Msync ${msyncEnabled ? 'on' : 'off'}` : undefined"
+        @click="toggleMsync"
+      >
+        <span class="msync-label-full">Msync</span>
+        <span class="msync-label-compact">M</span>
+      </button>
+    </div>
+
     <div class="sidebar-bottom">
       <button
         class="sidebar-nav-item sidebar-theme-toggle"
@@ -534,6 +617,116 @@ const navItems = computed<NavItem[]>(() => [
   flex: 0 0 auto;
 }
 
+.sidebar-runtime-controls {
+  padding: 8px;
+  border-top: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  -webkit-app-region: no-drag;
+}
+
+.runtime-control {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  color: var(--sidebar-text);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.runtime-control-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.controller-selector {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--bg-surface) 62%, transparent);
+}
+
+.controller-option {
+  min-width: 25px;
+  min-height: 24px;
+  padding: 2px 7px;
+  border: 0;
+  border-radius: calc(var(--radius-sm) - 2px);
+  background: transparent;
+  color: var(--text-dim);
+  font: inherit;
+  cursor: pointer;
+}
+
+.controller-option.active {
+  background: var(--accent-glow);
+  color: var(--accent);
+  box-shadow: inset 0 0 0 1px var(--accent-dim);
+}
+
+.controller-divider {
+  color: var(--border-strong);
+  font-weight: 400;
+}
+
+.msync-toggle {
+  width: 100%;
+  min-height: 32px;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--bg-surface) 72%, transparent);
+  color: var(--text-dim);
+  font-size: 12px;
+  font-weight: 800;
+  cursor: pointer;
+  transition: all var(--transition);
+}
+
+.msync-toggle.active {
+  border-color: rgba(63, 211, 132, 0.66);
+  background: rgba(32, 178, 105, 0.18);
+  color: rgb(83, 231, 151);
+  box-shadow: inset 0 0 12px rgba(32, 178, 105, 0.12);
+}
+
+.msync-label-compact,
+.sidebar.collapsed .msync-label-full {
+  display: none;
+}
+
+.sidebar.collapsed .msync-label-compact {
+  display: inline;
+}
+
+.controller-option:disabled,
+.msync-toggle:disabled {
+  cursor: wait;
+  opacity: 0.62;
+}
+
+.sidebar.collapsed .sidebar-runtime-controls {
+  align-items: center;
+  padding-inline: 6px;
+}
+
+.sidebar.collapsed .runtime-control {
+  justify-content: center;
+}
+
+.sidebar.collapsed .controller-selector {
+  flex-direction: column;
+  padding: 1px;
+}
+
+.sidebar.collapsed .controller-option {
+  min-width: 27px;
+  padding-inline: 4px;
+}
+
 .sidebar.collapsed .sidebar-top {
   justify-content: center;
   padding-left: 6px;
@@ -569,5 +762,28 @@ const navItems = computed<NavItem[]>(() => [
     padding: 8px;
     gap: 0;
   }
+  .sidebar-runtime-controls {
+    align-items: center;
+    padding-inline: 6px;
+  }
+  .runtime-control {
+    justify-content: center;
+  }
+  .runtime-control-label,
+  .controller-divider,
+  .msync-label-full {
+    display: none;
+  }
+  .msync-label-compact {
+    display: inline;
+  }
+  .controller-selector {
+    flex-direction: column;
+    padding: 1px;
+  }
+  .controller-option {
+    min-width: 27px;
+    padding-inline: 4px;
+  }
 }
 </style>
diff --git a/app/src/shared/types.ts b/app/src/shared/types.ts
index af33f5ae9..0468da6ae 100644
--- a/app/src/shared/types.ts
+++ b/app/src/shared/types.ts
@@ -41,6 +41,8 @@ export interface AppConfig {
   launchMode: "native" | "wine";
   wineAvailable: boolean;
   nativeAvailable: boolean;
+  controllerMode?: "dinput" | "xinput";
+  msyncEnabled?: boolean;
 }
 
 export interface RustResponse<T = unknown> {

From 66ca4dbcd69cf49b4b0ed5c7f522d9924609fa5c Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 17:21:41 -0600
Subject: [PATCH 08/14] replace split bundles in release packaging

---
 .github/workflows/release.yml                | 135 +++-------------
 .gitignore                                   |   1 +
 AGENTS.md                                    |  19 +++
 app/package.json                             |  42 ++---
 app/src-rust/src/installer.rs                |  12 +-
 tools/dmg/prepare-complete-runtime-assets.sh | 152 +++++++++++++++++++
 tools/dmg/verify-dmg-runtime-assets.sh       |  27 ++--
 7 files changed, 229 insertions(+), 159 deletions(-)
 create mode 100755 tools/dmg/prepare-complete-runtime-assets.sh

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7e6eef1ad..4a1014848 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,13 +4,6 @@ on:
   push:
     tags: ['v*']
   workflow_dispatch:
-    inputs:
-      developer_sdk:
-        description: "Build & publish the D3D12 developer SDK bundle (1 = yes, 0 = skip)"
-        required: false
-        default: '0'
-        type: choice
-        options: ['0', '1']
 
 concurrency:
   group: release-ci-${{ github.ref }}
@@ -19,92 +12,10 @@ concurrency:
 permissions:
   contents: write
   actions: read
-  packages: write
 
 jobs:
-  developer-sdk:
-    name: Publish Developer SDK Bundle
-    # Only build/publish the D3D12 developer SDK when explicitly enabled:
-    #   - manual run with developer_sdk=1, or
-    #   - repository variable METALSHARP_BUILD_DEVELOPER_SDK == '1'.
-    # Defaults to skipped so the DMG + GitHub Release are never blocked by it.
-    if: >-
-      (github.event_name == 'workflow_dispatch' && inputs.developer_sdk == '1') ||
-      vars.METALSHARP_BUILD_DEVELOPER_SDK == '1'
-    runs-on: macos-14
-    concurrency:
-      group: metalsharp-developer-sdk-bundles
-      cancel-in-progress: false
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          submodules: recursive
-
-      - name: Download and verify release split bundles
-        run: METALSHARP_REPAIR_BUNDLES=0 METALSHARP_SKIP_DEVELOPER_SDK_BUNDLE=1 tools/dmg/create-bundles.sh
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build self-contained developer SDK
-        run: |
-          tools/bundles/create-developer-sdk.py \
-            --bundle-dir app/bundles \
-            --out-dir dist/developer-sdk \
-            --manifest dist/bundles/metalsharp-bundle-manifest.tsv
-          tools/bundles/verify-developer-sdk.sh \
-            dist/developer-sdk/metalsharp-d3d12-developer-sdk.tar.zst
-
-      - name: Setup ORAS
-        uses: oras-project/setup-oras@v2
-
-      - name: Publish developer SDK package
-        run: |
-          set -euo pipefail
-          OWNER="$(printf '%s' "$GITHUB_REPOSITORY_OWNER" | tr '[:upper:]' '[:lower:]')"
-          PACKAGE="ghcr.io/$OWNER/metalsharp-d3d12-developer-sdk"
-          VERSION="${GITHUB_REF_NAME#v}"
-          ARCHIVE="dist/developer-sdk/metalsharp-d3d12-developer-sdk.tar.zst"
-          SHA="$(shasum -a 256 "$ARCHIVE" | awk '{print $1}')"
-          echo "$GH_TOKEN" | oras login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
-          oras push "$PACKAGE:$VERSION" \
-            "$ARCHIVE:application/vnd.metalsharp.d3d12-developer-sdk.layer.v1.tar+zstd" \
-            --artifact-type application/vnd.metalsharp.d3d12-developer-sdk.v1 \
-            --annotation "org.opencontainers.image.title=MetalSharp D3D12 Developer SDK" \
-            --annotation "org.opencontainers.image.description=Self-contained MetalSharp D3D12 developer SDK with staged Wine runtime and DXMT files" \
-            --annotation "org.opencontainers.image.version=$VERSION" \
-            --annotation "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY" \
-            --annotation "org.opencontainers.image.revision=$GITHUB_SHA" \
-            --annotation "org.opencontainers.image.digest.sha256=$SHA"
-          oras tag "$PACKAGE:$VERSION" latest
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Verify downloaded release bundle layout
-        run: |
-          set -euo pipefail
-          tools/bundles/verify-bundles.sh --bundle-dir dist/bundles --require mac \
-            metalsharp-electron.tar.zst \
-            metalsharp-graphics-dll.tar.zst \
-            metalsharp-runtime.tar.zst \
-            metalsharp-assets.tar.zst \
-            fnalibs.tar.zst \
-            metalsharp-scripts-tools.tar.zst \
-            metalsharp-steam.tar.zst
-          ! tar --use-compress-program=unzstd -tf dist/bundles/metalsharp-assets.tar.zst \
-            | grep -E '^assets/eac-toggle/'
-
-      - name: Publish developer SDK bundle
-        run: |
-          tools/bundles/publish-release-assets.sh bundles \
-            dist/developer-sdk/metalsharp-d3d12-developer-sdk.tar.zst \
-            dist/developer-sdk/metalsharp-bundle-manifest.tsv
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
   build:
     name: Build DMG
-    # Decoupled from developer-sdk: the DMG must build and the GitHub Release
-    # must publish even when the D3D12 developer SDK build is disabled (=0).
     runs-on: macos-14
     steps:
       - uses: actions/checkout@v7
@@ -146,23 +57,10 @@ jobs:
       - name: Build TypeScript
         run: cd app && npm run build
 
-      - name: Download bundles for DMG
+      - name: Download complete runtime assets for DMG and release
         run: |
-          METALSHARP_REPAIR_BUNDLES=0 METALSHARP_REPAIR_M12=0 tools/dmg/create-bundles.sh
-          tools/dmg/stage-release-bundles.sh app/bundles dist/staged-bundles
-          for required in \
-            metalsharp-electron.tar.zst \
-            metalsharp-graphics-dll.tar.zst \
-            metalsharp-runtime.tar.zst \
-            metalsharp-assets.tar.zst \
-            metalsharp-scripts-tools.tar.zst \
-            metalsharp-steam.tar.zst \
-            metalsharp-d3d12-developer-sdk.tar.zst
-          do
-            test -s "app/bundles/$required"
-          done
-          ls -lh app/bundles/
-          find dist/staged-bundles -type d | sort | sed -n '1,120p'
+          tools/dmg/prepare-complete-runtime-assets.sh app/release-runtime
+          ls -lh app/release-runtime/
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -243,10 +141,11 @@ jobs:
       - uses: actions/upload-artifact@v4
         with:
           name: MetalSharp-dmg
+          compression-level: 0
           path: |
             dist/electron/*.dmg
             dist/electron/DMG-SIGNING.txt
-            dist/bundles/metalsharp-bundle-manifest.tsv
+            app/release-runtime/*
 
   release:
     name: Release
@@ -255,6 +154,8 @@ jobs:
     permissions:
       contents: write
     steps:
+      - uses: actions/checkout@v7
+
       - name: Download release artifacts
         uses: actions/download-artifact@v4
         with:
@@ -268,17 +169,31 @@ jobs:
           mkdir -p release-flat
           find release -type f -name '*.dmg' -exec cp {} release-flat/ \;
           find release -type f -name 'DMG-SIGNING.txt' -exec cp {} release-flat/ \;
-          find release -type f -name 'metalsharp-bundle-manifest.tsv' -exec cp {} release-flat/ \;
+          for asset in \
+            install-metalsharp-wine-runtime.sh \
+            metalsharp-bundle-manifest.tsv \
+            MetalSharp-Wine-Public-Source-2026-07-31.tar.zst \
+            MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256 \
+            MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part01 \
+            MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part02 \
+            MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part03 \
+            MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part04 \
+            PARTS-SHA256SUMS.txt \
+            REASSEMBLE.txt
+          do
+            source="$(find release -type f -name "$asset" -print -quit)"
+            test -n "$source"
+            cp "$source" release-flat/
+          done
           test "$(find release-flat -type f -name '*.dmg' | wc -l | tr -d ' ')" -ge 1
           test -s release-flat/DMG-SIGNING.txt
           test -s release-flat/metalsharp-bundle-manifest.tsv
+          tools/dmg/prepare-complete-runtime-assets.sh --verify-only release-flat
           find release-flat -type f -print | sort
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           files: |
-            release-flat/*.dmg
-            release-flat/DMG-SIGNING.txt
-            release-flat/metalsharp-bundle-manifest.tsv
+            release-flat/*
           generate_release_notes: true
diff --git a/.gitignore b/.gitignore
index 6aae91efc..e7c97c4e8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,6 +32,7 @@ src/fna/FNA3D/
 build-x86/
 app/bundles/*.tar.zst
 app/bundles/SteamSetup.exe
+app/release-runtime/
 
 # CMake build directories (in addition to the generic `build/`)
 /build-metal/
diff --git a/AGENTS.md b/AGENTS.md
index 8725d701a..13070a040 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -98,6 +98,25 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
 - Phase 7 validation: the deterministic Rust suite passes 653/653, strict
   Clippy passes, all Rust targets build, and the TypeScript/Vite production
   build passes.
+- Phase 8 removes every retired split-runtime archive from the DMG resource
+  list and release workflow. `tools/dmg/prepare-complete-runtime-assets.sh`
+  downloads and pins the v0.60.0 installer, manifest, public source archive,
+  four runtime parts, checksum files, and reassembly instructions.
+- The DMG embeds the installer, manifest, public source/provenance payload,
+  part checksums, and reassembly instructions under `runtime-bundle/`; it does
+  not embed the four runtime parts. Release CI publishes those parts as
+  separate assets so every file stays below GitHub's 2 GiB release-asset cap.
+  The backend prefers the packaged installer and passes its directory through
+  `--bundle-dir`, allowing local discovery before network download.
+- The release gate verifies every asset hash against the pinned manifest,
+  verifies each part against `PARTS-SHA256SUMS.txt`, streams all four parts
+  through the canonical reconstructed SHA-256, syntax-checks the installer,
+  and rejects any DMG that still contains retired split archives.
+- Phase 8 validation: package-only assets from the live dependency release
+  passed hash and shell verification; release YAML parses; package metadata
+  contains only the complete-runtime resource contract; the deterministic
+  Rust suite passes 653/653; strict Clippy, all Rust targets, and the
+  TypeScript/Vite production build pass.
 
 ## What This Project Is
 
diff --git a/app/package.json b/app/package.json
index 09698ab4b..626ce3dca 100644
--- a/app/package.json
+++ b/app/package.json
@@ -21,7 +21,7 @@
     "build:native": "bash ../scripts/tools/native/build-helper.sh",
     "pack": "npm run build:all && electron-builder --dir",
     "prepare:native": "../tools/package/prepare-native-placeholders.sh",
-    "fetch:bundles:mac": "../tools/dmg/create-bundles.sh",
+    "fetch:bundles:mac": "../tools/dmg/prepare-complete-runtime-assets.sh",
     "fetch:bundles": "npm run fetch:bundles:mac",
     "dist": "npm run prepare:native && npm run build:all && npm run build:native && npm run fetch:bundles && electron-builder",
     "dmg": "npm run dist -- --mac dmg"
@@ -141,36 +141,16 @@
         "to": "scripts/install-metalsharp-wine-runtime.sh"
       },
       {
-        "from": "bundles/metalsharp-electron.tar.zst",
-        "to": "bundles/metalsharp-electron.tar.zst"
-      },
-      {
-        "from": "bundles/metalsharp-graphics-dll.tar.zst",
-        "to": "bundles/metalsharp-graphics-dll.tar.zst"
-      },
-      {
-        "from": "bundles/metalsharp-runtime.tar.zst",
-        "to": "bundles/metalsharp-runtime.tar.zst"
-      },
-      {
-        "from": "bundles/metalsharp-assets.tar.zst",
-        "to": "bundles/metalsharp-assets.tar.zst"
-      },
-      {
-        "from": "bundles/fnalibs.tar.zst",
-        "to": "bundles/fnalibs.tar.zst"
-      },
-      {
-        "from": "bundles/metalsharp-scripts-tools.tar.zst",
-        "to": "bundles/metalsharp-scripts-tools.tar.zst"
-      },
-      {
-        "from": "bundles/metalsharp-steam.tar.zst",
-        "to": "bundles/metalsharp-steam.tar.zst"
-      },
-      {
-        "from": "bundles/metalsharp-d3d12-developer-sdk.tar.zst",
-        "to": "bundles/metalsharp-d3d12-developer-sdk.tar.zst"
+        "from": "release-runtime",
+        "to": "runtime-bundle",
+        "filter": [
+          "install-metalsharp-wine-runtime.sh",
+          "metalsharp-bundle-manifest.tsv",
+          "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst",
+          "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256",
+          "PARTS-SHA256SUMS.txt",
+          "REASSEMBLE.txt"
+        ]
       }
     ],
     "directories": {
diff --git a/app/src-rust/src/installer.rs b/app/src-rust/src/installer.rs
index 8c0ea63bf..d608acd49 100644
--- a/app/src-rust/src/installer.rs
+++ b/app/src-rust/src/installer.rs
@@ -392,6 +392,7 @@ fn complete_runtime_current_for_root(root: &Path) -> bool {
 fn find_complete_runtime_installer() -> Option<PathBuf> {
     let mut candidates = Vec::new();
     if let Some(resources) = crate::platform::app_resources_dir() {
+        candidates.push(resources.join("runtime-bundle").join(COMPLETE_RUNTIME_INSTALLER));
         candidates.push(resources.join("scripts").join(COMPLETE_RUNTIME_INSTALLER));
     }
     candidates
@@ -410,11 +411,12 @@ pub(crate) fn install_complete_runtime(home: &PathBuf) -> Result<bool, String> {
         format!("{} is missing from the MetalSharp application resources", COMPLETE_RUNTIME_INSTALLER)
     })?;
     let target = complete_runtime_root(home);
-    let output = Command::new("/bin/bash")
-        .arg(&installer)
-        .args(["--target"])
-        .arg(&target)
-        .args(["--replace", "--discard-backup"])
+    let mut command = Command::new("/bin/bash");
+    command.arg(&installer).args(["--target"]).arg(&target).args(["--replace", "--discard-backup"]);
+    if let Some(bundle_dir) = installer.parent().filter(|parent| parent.join("PARTS-SHA256SUMS.txt").is_file()) {
+        command.arg("--bundle-dir").arg(bundle_dir);
+    }
+    let output = command
         .stdout(std::process::Stdio::piped())
         .stderr(std::process::Stdio::piped())
         .output()
diff --git a/tools/dmg/prepare-complete-runtime-assets.sh b/tools/dmg/prepare-complete-runtime-assets.sh
new file mode 100755
index 000000000..ee31ee30a
--- /dev/null
+++ b/tools/dmg/prepare-complete-runtime-assets.sh
@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+DEST_DIR="${METALSHARP_RELEASE_RUNTIME_DIR:-$PROJECT_ROOT/app/release-runtime}"
+REPO="${METALSHARP_RUNTIME_REPO:-metalsharp/MetalSharp}"
+TAG="${METALSHARP_RUNTIME_TAG:-v0.60.0-dependency-bundles}"
+ARCHIVE="MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst"
+ARCHIVE_SHA256="93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee"
+MANIFEST_SHA256="60bc7c19ef8cbbaa55c325fab139c743bea1b1c5d5fd4071791f4a0924487b36"
+
+ASSETS=(
+  metalsharp-bundle-manifest.tsv
+  install-metalsharp-wine-runtime.sh
+  MetalSharp-Wine-Public-Source-2026-07-31.tar.zst
+  MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256
+  "$ARCHIVE.part01"
+  "$ARCHIVE.part02"
+  "$ARCHIVE.part03"
+  "$ARCHIVE.part04"
+  PARTS-SHA256SUMS.txt
+  REASSEMBLE.txt
+)
+PACKAGE_ASSETS=(
+  metalsharp-bundle-manifest.tsv
+  install-metalsharp-wine-runtime.sh
+  MetalSharp-Wine-Public-Source-2026-07-31.tar.zst
+  MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256
+  PARTS-SHA256SUMS.txt
+  REASSEMBLE.txt
+)
+
+usage() {
+  cat <<EOF
+Usage: $0 [--verify-only|--verify-package] [DEST_DIR]
+
+Downloads and verifies the complete v0.60.0 runtime release payload embedded
+alongside the MetalSharp DMG. --verify-only performs no network access and
+checks every release asset. --verify-package checks only the lean metadata and
+source payload embedded in the DMG.
+EOF
+}
+
+VERIFY_ONLY=0
+if [ "${1:-}" = "--verify-only" ]; then
+  VERIFY_ONLY=1
+  shift
+elif [ "${1:-}" = "--verify-package" ]; then
+  VERIFY_ONLY=2
+  shift
+fi
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  usage
+  exit 0
+fi
+if [ "$#" -gt 1 ]; then
+  usage >&2
+  exit 2
+fi
+if [ "$#" -eq 1 ]; then
+  DEST_DIR="$1"
+fi
+
+mkdir -p "$DEST_DIR"
+
+download_asset() {
+  local name="$1"
+  local destination="$DEST_DIR/$name"
+  local expected=""
+  if [ "$name" = "metalsharp-bundle-manifest.tsv" ]; then
+    expected="$MANIFEST_SHA256"
+  elif [ -s "$DEST_DIR/metalsharp-bundle-manifest.tsv" ]; then
+    expected="$(awk -F '\t' -v asset="$name" '$1 == asset { print $3; exit }' "$DEST_DIR/metalsharp-bundle-manifest.tsv")"
+  fi
+  if [ -s "$destination" ]; then
+    local actual
+    actual="$(shasum -a 256 "$destination" | awk '{print $1}')"
+    if [ -n "$expected" ] && [ "$actual" = "$expected" ]; then
+      return 0
+    fi
+  fi
+  local partial="$destination.partial"
+  curl --fail --location --silent --show-error --retry 4 \
+    --output "$partial" "https://github.com/$REPO/releases/download/$TAG/$name"
+  mv "$partial" "$destination"
+}
+
+if [ "$VERIFY_ONLY" -eq 0 ]; then
+  for asset in "${ASSETS[@]}"; do
+    echo "Fetching complete-runtime release asset: $asset"
+    download_asset "$asset"
+  done
+fi
+
+VERIFY_ASSETS=("${ASSETS[@]}")
+if [ "$VERIFY_ONLY" -eq 2 ]; then
+  VERIFY_ASSETS=("${PACKAGE_ASSETS[@]}")
+fi
+
+for asset in "${VERIFY_ASSETS[@]}"; do
+  if [ ! -s "$DEST_DIR/$asset" ]; then
+    echo "Missing complete-runtime release asset: $DEST_DIR/$asset" >&2
+    exit 1
+  fi
+done
+
+MANIFEST="$DEST_DIR/metalsharp-bundle-manifest.tsv"
+manifest_hash() {
+  awk -F '\t' -v asset="$1" '$1 == asset { print $3; exit }' "$MANIFEST"
+}
+
+for asset in "${VERIFY_ASSETS[@]}"; do
+  if [ "$asset" = "metalsharp-bundle-manifest.tsv" ]; then
+    expected="$MANIFEST_SHA256"
+  else
+    expected="$(manifest_hash "$asset")"
+  fi
+  if [ -z "$expected" ]; then
+    echo "Release manifest has no hash for $asset" >&2
+    exit 1
+  fi
+  actual="$(shasum -a 256 "$DEST_DIR/$asset" | awk '{print $1}')"
+  if [ "$actual" != "$expected" ]; then
+    echo "Release asset hash mismatch: $asset expected=$expected actual=$actual" >&2
+    exit 1
+  fi
+done
+
+if [ "$VERIFY_ONLY" -ne 2 ]; then
+  for part in "$ARCHIVE.part01" "$ARCHIVE.part02" "$ARCHIVE.part03" "$ARCHIVE.part04"; do
+    expected="$(awk -v part="$part" '$2 == part { print $1; exit }' "$DEST_DIR/PARTS-SHA256SUMS.txt")"
+    actual="$(shasum -a 256 "$DEST_DIR/$part" | awk '{print $1}')"
+    if [ -z "$expected" ] || [ "$actual" != "$expected" ]; then
+      echo "Part checksum contract failed: $part" >&2
+      exit 1
+    fi
+  done
+
+  reassembled_sha="$(cat \
+    "$DEST_DIR/$ARCHIVE.part01" \
+    "$DEST_DIR/$ARCHIVE.part02" \
+    "$DEST_DIR/$ARCHIVE.part03" \
+    "$DEST_DIR/$ARCHIVE.part04" | shasum -a 256 | awk '{print $1}')"
+  if [ "$reassembled_sha" != "$ARCHIVE_SHA256" ]; then
+    echo "Reassembled runtime hash mismatch: expected=$ARCHIVE_SHA256 actual=$reassembled_sha" >&2
+    exit 1
+  fi
+fi
+
+bash -n "$DEST_DIR/install-metalsharp-wine-runtime.sh"
+echo "Complete runtime release assets verified: $DEST_DIR"
diff --git a/tools/dmg/verify-dmg-runtime-assets.sh b/tools/dmg/verify-dmg-runtime-assets.sh
index 38dcc9f8a..18a7a0308 100755
--- a/tools/dmg/verify-dmg-runtime-assets.sh
+++ b/tools/dmg/verify-dmg-runtime-assets.sh
@@ -11,11 +11,10 @@ if [ ! -s "$DMG" ]; then
 fi
 
 MOUNT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/metalsharp-dmg-mount.XXXXXX")"
-LIST_DIR="$(mktemp -d "${TMPDIR:-/tmp}/metalsharp-dmg-bundles.XXXXXX")"
 
 cleanup() {
   hdiutil detach "$MOUNT_DIR" -quiet 2>/dev/null || true
-  rm -rf "$MOUNT_DIR" "$LIST_DIR"
+  rm -rf "$MOUNT_DIR"
 }
 trap cleanup EXIT
 
@@ -30,7 +29,7 @@ fi
 RESOURCES="$APP_DIR/Contents/Resources"
 BACKEND="$RESOURCES/runtime/metalsharp-backend"
 HOST="$RESOURCES/runtime/host"
-BUNDLES="$RESOURCES/bundles"
+RUNTIME_BUNDLE="$RESOURCES/runtime-bundle"
 
 for required in \
   "$BACKEND" \
@@ -38,14 +37,12 @@ for required in \
   "$HOST/HostRuntimeABI.h" \
   "$RESOURCES/scripts/tools/updater/update.py" \
   "$RESOURCES/scripts/tools/updater/update.sh" \
-  "$BUNDLES/metalsharp-electron.tar.zst" \
-  "$BUNDLES/metalsharp-graphics-dll.tar.zst" \
-  "$BUNDLES/metalsharp-runtime.tar.zst" \
-  "$BUNDLES/metalsharp-assets.tar.zst" \
-  "$BUNDLES/fnalibs.tar.zst" \
-  "$BUNDLES/metalsharp-scripts-tools.tar.zst" \
-  "$BUNDLES/metalsharp-steam.tar.zst" \
-  "$BUNDLES/metalsharp-d3d12-developer-sdk.tar.zst"
+  "$RUNTIME_BUNDLE/install-metalsharp-wine-runtime.sh" \
+  "$RUNTIME_BUNDLE/metalsharp-bundle-manifest.tsv" \
+  "$RUNTIME_BUNDLE/MetalSharp-Wine-Public-Source-2026-07-31.tar.zst" \
+  "$RUNTIME_BUNDLE/MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256" \
+  "$RUNTIME_BUNDLE/PARTS-SHA256SUMS.txt" \
+  "$RUNTIME_BUNDLE/REASSEMBLE.txt"
 do
   if [ ! -s "$required" ]; then
     echo "DMG missing required runtime asset: ${required#$APP_DIR/}" >&2
@@ -60,7 +57,11 @@ if [ ! -s "$HOST/libmetalsharp_host_runtime.dylib" ] \
   exit 1
 fi
 
-cp "$BUNDLES"/*.tar.zst "$LIST_DIR"/
-"$PROJECT_ROOT/tools/bundles/verify-bundles.sh" --bundle-dir "$LIST_DIR" --require mac
+if find "$RESOURCES/bundles" -maxdepth 1 -type f -name '*.tar.zst' -print -quit 2>/dev/null | grep -q .; then
+  echo "DMG still contains retired split runtime bundles" >&2
+  exit 1
+fi
+
+"$PROJECT_ROOT/tools/dmg/prepare-complete-runtime-assets.sh" --verify-package "$RUNTIME_BUNDLE"
 
 echo "DMG runtime assets verified: $DMG"

From 20df3db3bf82b9bba784ea157f91e9894ce7d0d7 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 17:24:13 -0600
Subject: [PATCH 09/14] update DMG CI for complete runtime assets

---
 AGENTS.md                       |   3 +
 tools/ci/verify-dmg-workflow.py | 125 +++++++++++++++++++++-----------
 2 files changed, 87 insertions(+), 41 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 13070a040..507cd5df5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -112,6 +112,9 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   verifies each part against `PARTS-SHA256SUMS.txt`, streams all four parts
   through the canonical reconstructed SHA-256, syntax-checks the installer,
   and rejects any DMG that still contains retired split archives.
+- `tools/ci/verify-dmg-workflow.py` enforces the same six packaged assets and
+  ten separately published release assets. It must reject any return of the
+  eight split archives or the retired developer-SDK release job.
 - Phase 8 validation: package-only assets from the live dependency release
   passed hash and shell verification; release YAML parses; package metadata
   contains only the complete-runtime resource contract; the deterministic
diff --git a/tools/ci/verify-dmg-workflow.py b/tools/ci/verify-dmg-workflow.py
index ed7c0ba3b..a0162f43b 100755
--- a/tools/ci/verify-dmg-workflow.py
+++ b/tools/ci/verify-dmg-workflow.py
@@ -9,6 +9,30 @@
 
 ROOT = Path(__file__).resolve().parents[2]
 
+PACKAGE_ASSETS = [
+    "install-metalsharp-wine-runtime.sh",
+    "metalsharp-bundle-manifest.tsv",
+    "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst",
+    "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256",
+    "PARTS-SHA256SUMS.txt",
+    "REASSEMBLE.txt",
+]
+RUNTIME_PARTS = [
+    f"MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part{part:02d}"
+    for part in range(1, 5)
+]
+RELEASE_ASSETS = PACKAGE_ASSETS + RUNTIME_PARTS
+RETIRED_BUNDLES = [
+    "metalsharp-electron.tar.zst",
+    "metalsharp-graphics-dll.tar.zst",
+    "metalsharp-runtime.tar.zst",
+    "metalsharp-assets.tar.zst",
+    "fnalibs.tar.zst",
+    "metalsharp-scripts-tools.tar.zst",
+    "metalsharp-steam.tar.zst",
+    "metalsharp-d3d12-developer-sdk.tar.zst",
+]
+
 
 def fail(message: str) -> None:
     print(f"DMG workflow check failed: {message}", file=sys.stderr)
@@ -22,23 +46,7 @@ def read(path: str) -> str:
     return full.read_text()
 
 
-def manifest_assets() -> list[str]:
-    assets: list[str] = []
-    for line in read("tools/bundles/asset-manifest.tsv").splitlines():
-        if not line or line.startswith("#"):
-            continue
-        fields = line.split("\t")
-        if len(fields) < 3:
-            fail(f"invalid manifest row: {line}")
-        asset, _root, platforms = fields[:3]
-        if "mac" in platforms.split(","):
-            assets.append(asset)
-    if not assets:
-        fail("bundle manifest has no mac assets")
-    return assets
-
-
-def check_package_resources(assets: list[str]) -> None:
+def check_package_resources() -> None:
     package = json.loads(read("app/package.json"))
     build = package.get("build", {})
     resources = build.get("extraResources", [])
@@ -55,19 +63,34 @@ def check_package_resources(assets: list[str]) -> None:
         ("native/host", "runtime/host"),
         ("updater", "scripts/tools/updater"),
     }
-    required_pairs.update((f"bundles/{asset}", f"bundles/{asset}") for asset in assets)
+    required_pairs.add(("release-runtime", "runtime-bundle"))
 
     missing = sorted(required_pairs - pairs)
     if missing:
         fail(f"app/package.json missing extraResources entries: {missing}")
 
+    runtime_resource = next(
+        (entry for entry in resources if isinstance(entry, dict) and entry.get("from") == "release-runtime"),
+        None,
+    )
+    if runtime_resource is None:
+        fail("app/package.json has no complete-runtime resource directory")
+    filters = runtime_resource.get("filter", [])
+    missing_assets = sorted(set(PACKAGE_ASSETS) - set(filters))
+    if missing_assets:
+        fail(f"complete-runtime resource filter is missing: {missing_assets}")
+    for entry in resources:
+        source = entry.get("from", "") if isinstance(entry, dict) else ""
+        if source.startswith("bundles/") and source.endswith(".tar.zst"):
+            fail(f"retired split bundle is still packaged: {source}")
+
     if build.get("afterPack") != "build/adhoc-deep-sign.cjs":
         fail("app/package.json must keep afterPack=build/adhoc-deep-sign.cjs")
     if build.get("afterSign") != "build/notarize.cjs":
         fail("app/package.json must keep afterSign=build/notarize.cjs")
 
 
-def check_dmg_verifier(assets: list[str]) -> None:
+def check_dmg_verifier() -> None:
     verifier = read("tools/dmg/verify-dmg-runtime-assets.sh")
     for needle in [
         "Contents/Resources",
@@ -75,14 +98,16 @@ def check_dmg_verifier(assets: list[str]) -> None:
         "runtime/host",
         "scripts/tools/updater/update.py",
         "scripts/tools/updater/update.sh",
-        "tools/bundles/verify-bundles.sh",
+        "prepare-complete-runtime-assets.sh",
+        "--verify-package",
+        "DMG still contains retired split runtime bundles",
     ]:
         if needle not in verifier:
             fail(f"DMG verifier no longer checks {needle}")
 
-    for asset in assets:
+    for asset in PACKAGE_ASSETS:
         if asset not in verifier:
-            fail(f"DMG verifier no longer checks bundle asset {asset}")
+            fail(f"DMG verifier no longer checks complete-runtime asset {asset}")
 
 
 def check_updater_handoff() -> None:
@@ -95,21 +120,25 @@ def check_updater_handoff() -> None:
 
 
 def check_bundle_scripts() -> None:
-    create_bundles = read("tools/dmg/create-bundles.sh")
+    prepare_runtime = read("tools/dmg/prepare-complete-runtime-assets.sh")
     for needle in [
-        "tools/dmg/repair-runtime-bundle.py",
-        "repair_assets_fnalibs_bundle",
-        "tools/bundles/verify-bundles.sh",
-        "--bundle-dir \"$BUNDLE_DIR\" \"$asset\"",
-        "Refreshing stale bundle",
+        "v0.60.0-dependency-bundles",
+        "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee",
         "metalsharp-bundle-manifest.tsv",
+        "--verify-only",
+        "--verify-package",
+        "PARTS-SHA256SUMS.txt",
+        "shasum -a 256",
+        "bash -n",
     ]:
-        if needle not in create_bundles:
-            fail(f"create-bundles.sh no longer performs {needle}")
-
-    stage_bundles = read("tools/dmg/stage-release-bundles.sh")
-    if "asset-manifest.tsv" not in stage_bundles or "tar --use-compress-program=unzstd" not in stage_bundles:
-        fail("stage-release-bundles.sh no longer stages bundle manifest archives")
+        if needle not in prepare_runtime:
+            fail(f"complete-runtime asset preparation no longer performs {needle}")
+    for asset in PACKAGE_ASSETS:
+        if asset not in prepare_runtime:
+            fail(f"complete-runtime preparation omits release asset {asset}")
+    for part in range(1, 5):
+        if f'"$ARCHIVE.part{part:02d}"' not in prepare_runtime:
+            fail(f"complete-runtime preparation omits runtime part {part:02d}")
 
 
 def check_workflows() -> None:
@@ -139,10 +168,8 @@ def check_workflows() -> None:
         fail("main CI verifier must not share the release SDK publish concurrency group")
 
     for required in [
-        "Publish Developer SDK Bundle",
-        "Publish developer SDK package",
-        "Publish developer SDK bundle",
         "Build DMG",
+        "Download complete runtime assets for DMG and release",
         "Check Apple signing credentials",
         "Verify Apple notarization",
         "Mark unsigned DMG",
@@ -150,6 +177,23 @@ def check_workflows() -> None:
     ]:
         if required not in release:
             fail(f"release workflow missing publish step: {required}")
+    for required in [
+        "tools/dmg/prepare-complete-runtime-assets.sh app/release-runtime",
+        "app/release-runtime/*",
+        "--verify-only release-flat",
+    ]:
+        if required not in release:
+            fail(f"release workflow missing complete-runtime contract: {required}")
+    for forbidden in [
+        "Publish Developer SDK Bundle",
+        "tools/dmg/create-bundles.sh",
+        "tools/dmg/stage-release-bundles.sh",
+    ] + RETIRED_BUNDLES:
+        if forbidden in release:
+            fail(f"release workflow still references retired bundle path: {forbidden}")
+    for asset in RELEASE_ASSETS:
+        if asset not in release:
+            fail(f"release workflow does not publish {asset}")
     for required in [
         "tools/dmg/check-apple-signing-readiness.sh",
         "steps.apple-signing.outputs.ready == 'true'",
@@ -181,13 +225,12 @@ def check_workflows() -> None:
 
 
 def main() -> int:
-    assets = manifest_assets()
-    check_package_resources(assets)
-    check_dmg_verifier(assets)
+    check_package_resources()
+    check_dmg_verifier()
     check_updater_handoff()
     check_bundle_scripts()
     check_workflows()
-    print(f"DMG workflow contract verified ({len(assets)} mac bundle assets).")
+    print(f"DMG workflow contract verified ({len(PACKAGE_ASSETS)} packaged, {len(RELEASE_ASSETS)} release assets).")
     return 0
 
 

From 9663c35b601c9ea0c2dec858c4ff943153642457 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 17:27:14 -0600
Subject: [PATCH 10/14] format Homebrew installer command for Electron CI

---
 app/src/main/index.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/app/src/main/index.ts b/app/src/main/index.ts
index c08e2b9d2..0174f0e67 100644
--- a/app/src/main/index.ts
+++ b/app/src/main/index.ts
@@ -1045,15 +1045,15 @@ function registerIpc() {
         "set -euo pipefail",
         `COMMAND_PATH='${commandPath.replace(/'/g, "'\\\\''")}'`,
         'INSTALL_SCRIPT="$(/usr/bin/mktemp -t metalsharp-homebrew-install)"',
-        "cleanup() { /bin/rm -f \"$COMMAND_PATH\" \"$INSTALL_SCRIPT\"; }",
+        'cleanup() { /bin/rm -f "$COMMAND_PATH" "$INSTALL_SCRIPT"; }',
         "trap cleanup EXIT",
         'echo "MetalSharp: downloading the official Homebrew installer..."',
         '/usr/bin/curl --fail --show-error --silent --location https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh --output "$INSTALL_SCRIPT"',
         '/bin/bash -n "$INSTALL_SCRIPT"',
         '/bin/bash "$INSTALL_SCRIPT"',
-        'BREW="${HOMEBREW_PREFIX:-}/bin/brew"',
+        `BREW="\${HOMEBREW_PREFIX:-}/bin/brew"`,
         'if [[ ! -x "$BREW" ]]; then',
-        '  for CANDIDATE in /opt/homebrew/bin/brew /usr/local/bin/brew; do',
+        "  for CANDIDATE in /opt/homebrew/bin/brew /usr/local/bin/brew; do",
         '    if [[ -x "$CANDIDATE" ]]; then BREW="$CANDIDATE"; break; fi',
         "  done",
         "fi",

From 7f552e9b628d94cc0f84b35e63eac48e355537b3 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 18:01:06 -0600
Subject: [PATCH 11/14] integrate all-architecture GOG runtime support

---
 .github/workflows/release.yml                |   1 +
 AGENTS.md                                    |  28 +++
 app/package.json                             |   1 +
 app/src-rust/src/gog.rs                      |  54 +++--
 app/src-rust/src/installer.rs                |  12 +-
 app/src-rust/src/main.rs                     |   1 +
 app/src-rust/src/migrate.rs                  |   7 +-
 app/src-rust/src/runtime_prefix.rs           | 243 +++++++++++++++++++
 app/src-rust/src/steam.rs                    | 133 +---------
 app/src/renderer/views/SharpView.vue         |   7 +-
 docs/guides/library-and-logs-ui.md           |  15 +-
 scripts/install-metalsharp-wine-runtime.sh   | 132 +++++++++-
 tools/ci/verify-dmg-workflow.py              |   1 +
 tools/dmg/prepare-complete-runtime-assets.sh |   4 +-
 tools/dmg/verify-dmg-runtime-assets.sh       |   1 +
 tools/gog/build-gog-support-bundle.sh        |  74 ++++++
 16 files changed, 545 insertions(+), 169 deletions(-)
 create mode 100644 app/src-rust/src/runtime_prefix.rs
 create mode 100755 tools/gog/build-gog-support-bundle.sh

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4a1014848..617d16134 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -174,6 +174,7 @@ jobs:
             metalsharp-bundle-manifest.tsv \
             MetalSharp-Wine-Public-Source-2026-07-31.tar.zst \
             MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256 \
+            MetalSharp-GOG-Support-arm64-1.2.2.tar.zst \
             MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part01 \
             MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part02 \
             MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst.part03 \
diff --git a/AGENTS.md b/AGENTS.md
index 507cd5df5..1abf9cfb6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -120,6 +120,34 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   contains only the complete-runtime resource contract; the deterministic
   Rust suite passes 653/653; strict Clippy, all Rust targets, and the
   TypeScript/Vite production build pass.
+- The post-Phase-8 GOG pass adds
+  `MetalSharp-GOG-Support-arm64-1.2.2.tar.zst` to the dependency release and
+  DMG bootstrap payload. It is a self-contained thin ARM64 Heroic GOGDL 1.2.2
+  executable with Requests/TLS, the compiled xdelta3 module, licenses,
+  per-file hashes, and pinned provenance. The archive SHA-256 is
+  `f13075f27d5155e84199619410936931b32310c4ec4161de992c1f727ac24155`.
+- The complete-runtime installer validates and stages GOG support under
+  `runtime/integration/gog/`. Existing accepted Wine runtimes receive this
+  small layer in place without reassembling, extracting, or replacing the
+  multi-gigabyte Wine runtime. Runtime readiness now requires the GOG archive
+  marker and executable.
+- Steam and GOG prefix creation share `runtime_prefix.rs`. Both stage ARM64
+  WoW64 providers, all i386 builtins, canonical ARM64/ARM64EC execution
+  providers, and GStreamer before explicit ARM64 wineboot; wait for the exact
+  prefix wineserver; restage and verify providers; and require the same
+  ARM64/ARM64EC/x86_64/i386 acceptance gate. A `drive_c` directory alone is
+  never GOG-prefix acceptance.
+- GOG prefers the canonical bundled native ARM64 GOGDL path over legacy
+  `~/.metalsharp/tools/gogdl`. Download, import, and Play commands inherit the
+  complete runtime's `WINEBUILDDIR`, library paths, controller/Msync settings,
+  and all three FEX TSO-off flags. The source-install fallback is pinned to
+  Heroic GOGDL `v1.2.2`, never an unpinned main branch.
+- GOG validation: the native bundle passed archive/per-file hashes, Mach-O,
+  code-signature, version, embedded-xdelta, and unauthenticated command probes;
+  installer add/repair and idempotency completed in two seconds each against
+  a disposable existing-runtime fixture; the deterministic Rust suite passes
+  655/655; strict Clippy, all Rust targets, TypeScript, Vite, DMG workflow, and
+  shell gates pass.
 
 ## What This Project Is
 
diff --git a/app/package.json b/app/package.json
index 626ce3dca..3cfcefa26 100644
--- a/app/package.json
+++ b/app/package.json
@@ -148,6 +148,7 @@
           "metalsharp-bundle-manifest.tsv",
           "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst",
           "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256",
+          "MetalSharp-GOG-Support-arm64-1.2.2.tar.zst",
           "PARTS-SHA256SUMS.txt",
           "REASSEMBLE.txt"
         ]
diff --git a/app/src-rust/src/gog.rs b/app/src-rust/src/gog.rs
index 893f8e8fc..bd2d2ea14 100644
--- a/app/src-rust/src/gog.rs
+++ b/app/src-rust/src/gog.rs
@@ -13,6 +13,7 @@ const GOG_PREFIX_BOTTLE_ID: &str = "gog-prefix";
 const GOG_AUTH_URL: &str = "https://auth.gog.com/auth?client_id=46899977096215655&redirect_uri=https%3A%2F%2Fembed.gog.com%2Fon_login_success%3Forigin%3Dclient&response_type=code&layout=galaxy";
 const GOG_CLIENT_ID: &str = "46899977096215655";
 const HEROIC_GOGDL_REPO_URL: &str = "https://github.com/Heroic-Games-Launcher/heroic-gogdl.git";
+const HEROIC_GOGDL_REF: &str = "v1.2.2";
 
 #[derive(Debug, Clone, Default, Deserialize, Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -142,6 +143,7 @@ fn gogdl_candidates() -> Vec<PathBuf> {
             candidates.push(PathBuf::from(explicit));
         }
     }
+    candidates.push(ms_home().join("runtime").join("integration").join("gog").join("bin").join("gogdl"));
     candidates.push(ms_home().join("tools").join("gogdl"));
     candidates.push(ms_home().join("runtime").join("gogdl"));
     if let Ok(path_env) = std::env::var("PATH") {
@@ -153,7 +155,17 @@ fn gogdl_candidates() -> Vec<PathBuf> {
 }
 
 fn gogdl_binary() -> Option<PathBuf> {
-    gogdl_candidates().into_iter().find(|path| path.is_file())
+    gogdl_candidates().into_iter().find(|path| {
+        if !path.is_file() {
+            return false;
+        }
+        #[cfg(unix)]
+        {
+            path.metadata().map(|metadata| metadata.permissions().mode() & 0o111 != 0).unwrap_or(false)
+        }
+        #[cfg(not(unix))]
+        true
+    })
 }
 
 fn tools_dir() -> PathBuf {
@@ -299,11 +311,19 @@ fn ensure_gogdl_available() -> Result<(), String> {
             .arg("clone")
             .arg("--depth")
             .arg("1")
+            .arg("--branch")
+            .arg(HEROIC_GOGDL_REF)
             .arg("--recurse-submodules")
             .arg(HEROIC_GOGDL_REPO_URL)
             .arg(&source);
         run_bootstrap_command(&mut command, "GOG support source setup")?;
     } else {
+        let mut command = Command::new(&git);
+        command.arg("-C").arg(&source).arg("fetch").arg("--depth").arg("1").arg("origin").arg(HEROIC_GOGDL_REF);
+        run_bootstrap_command(&mut command, "GOG support source pin refresh")?;
+        let mut command = Command::new(&git);
+        command.arg("-C").arg(&source).arg("checkout").arg("--detach").arg(HEROIC_GOGDL_REF);
+        run_bootstrap_command(&mut command, "GOG support source pin checkout")?;
         let mut command = Command::new(&git);
         command.arg("-C").arg(&source).arg("submodule").arg("update").arg("--init").arg("--recursive");
         run_bootstrap_command(&mut command, "GOG support source refresh")?;
@@ -335,6 +355,8 @@ fn gogdl_command() -> Result<Command, String> {
         .arg(gog_auth_config_path())
         .env("GOGDL_CONFIG_PATH", gogdl_config_dir())
         .env("GOGDL_SUPPORT_PATH", gogdl_support_dir());
+    crate::runtime_prefix::apply_complete_runtime_env(&mut command, &gog_prefix());
+    command.env("MS_FWD_COMPAT_GL_CTX", "1");
     Ok(command)
 }
 
@@ -512,9 +534,10 @@ fn status_value() -> Value {
     let prefix = gog_prefix();
     let oauth_dest = gog_oauth_helper_dest_dir();
     let oauth_available = oauth_dest.join(".inline-helper").is_file();
+    let prefix_all_arch_ready = crate::runtime_prefix::all_arch_ready(&prefix);
     let status = if binary.is_none() {
         "missing_gogdl"
-    } else if !prefix.join("drive_c").is_dir() {
+    } else if !prefix_all_arch_ready {
         "needs_prefix"
     } else if !authenticated {
         "needs_login"
@@ -538,7 +561,8 @@ fn status_value() -> Value {
         "oauthHelperScript": "(inline Electron BrowserWindow)".to_string(),
         "bottleId": GOG_PREFIX_BOTTLE_ID,
         "winePrefix": prefix.to_string_lossy().to_string(),
-        "prefixInitialized": prefix.join("drive_c").is_dir(),
+        "prefixInitialized": prefix_all_arch_ready,
+        "prefixAllArchReady": prefix_all_arch_ready,
         "winePath": wine_binary().to_string_lossy().to_string(),
     })
 }
@@ -558,30 +582,10 @@ fn initialize_prefix() -> Result<(), String> {
     ensure_gogdl_available()?;
     let prefix = gog_prefix();
     fs::create_dir_all(&prefix).map_err(|error| format!("failed to create GOG prefix: {}", error))?;
-    if prefix.join("drive_c").is_dir() {
+    if crate::runtime_prefix::all_arch_ready(&prefix) {
         return Ok(());
     }
-    let wine = wine_binary();
-    if !wine.is_file() {
-        return Err(format!("MetalSharp Wine not found: {}", wine.display()));
-    }
-    let mut command = Command::new(&wine);
-    command
-        .arg("wineboot")
-        .arg("-u")
-        .env("WINEPREFIX", prefix.to_string_lossy().to_string())
-        .env("WINEDEBUG", "-all")
-        .env("MS_FWD_COMPAT_GL_CTX", "1")
-        .stdout(Stdio::null())
-        .stderr(Stdio::null());
-    crate::launch::apply_wine_runtime_preferences(&mut command);
-    crate::platform::set_runtime_library_env(&mut command, &wine_root());
-    let status = command.status().map_err(|error| format!("failed to initialize GOG prefix: {}", error))?;
-    if status.success() {
-        Ok(())
-    } else {
-        Err(format!("wineboot failed with {:?}", status.code()))
-    }
+    crate::runtime_prefix::prepare(&prefix)
 }
 
 pub fn handle_auth_code(body: &Value) -> Value {
diff --git a/app/src-rust/src/installer.rs b/app/src-rust/src/installer.rs
index d608acd49..e46089ba1 100644
--- a/app/src-rust/src/installer.rs
+++ b/app/src-rust/src/installer.rs
@@ -34,6 +34,7 @@ const STEAM_BUNDLE: &str = "metalsharp-steam";
 const COMPLETE_RUNTIME_INSTALLER: &str = "install-metalsharp-wine-runtime.sh";
 pub(crate) const COMPLETE_RUNTIME_ARCHIVE_SHA256: &str =
     "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee";
+pub(crate) const GOG_SUPPORT_ARCHIVE_SHA256: &str = "f13075f27d5155e84199619410936931b32310c4ec4161de992c1f727ac24155";
 const METALSHARP_NTDLL_HOOK_DLL: &str = "metalsharp_ntdll_hook.dll";
 const DXMT_REQUIRED_PE: &[&str] = &[
     "d3d10core.dll",
@@ -350,6 +351,7 @@ fn complete_runtime_current_for_root(root: &Path) -> bool {
     };
 
     marker.lines().any(|line| line == format!("archive_sha256={COMPLETE_RUNTIME_ARCHIVE_SHA256}"))
+        && marker.lines().any(|line| line == format!("gog_archive_sha256={GOG_SUPPORT_ARCHIVE_SHA256}"))
         && marker.lines().any(|line| line == "no_tso=1")
         && file_nonempty(&root.join("wine/bin/metalsharp-wine"))
         && file_nonempty(&root.join("wine/build-ec/wine"))
@@ -387,6 +389,7 @@ fn complete_runtime_current_for_root(root: &Path) -> bool {
         && file_nonempty(&root.join("scripts/stage-runtime-providers.sh"))
         && file_nonempty(&root.join("wine/build-ec/dlls/wow64/aarch64-windows/wow64.dll"))
         && file_nonempty(&root.join("wine/build-ec/dlls/wow64win/aarch64-windows/wow64win.dll"))
+        && file_nonempty(&root.join("integration/gog/bin/gogdl"))
 }
 
 fn find_complete_runtime_installer() -> Option<PathBuf> {
@@ -2701,6 +2704,7 @@ mod tests {
             "scripts/stage-runtime-providers.sh",
             "wine/build-ec/dlls/wow64/aarch64-windows/wow64.dll",
             "wine/build-ec/dlls/wow64win/aarch64-windows/wow64win.dll",
+            "integration/gog/bin/gogdl",
         ] {
             let path = root.join(rel);
             fs::create_dir_all(path.parent().expect("fixture parent")).expect("create fixture parent");
@@ -2708,10 +2712,16 @@ mod tests {
         }
         fs::write(
             complete_runtime_marker(&root),
-            format!("archive_sha256={COMPLETE_RUNTIME_ARCHIVE_SHA256}\nno_tso=1\n"),
+            format!(
+                "archive_sha256={COMPLETE_RUNTIME_ARCHIVE_SHA256}\ngog_archive_sha256={GOG_SUPPORT_ARCHIVE_SHA256}\nno_tso=1\n"
+            ),
         )
         .expect("write marker");
 
+        assert!(complete_runtime_current_for_home(&home));
+        fs::remove_file(root.join("integration/gog/bin/gogdl")).expect("remove GOG support fixture");
+        assert!(!complete_runtime_current_for_home(&home));
+        fs::write(root.join("integration/gog/bin/gogdl"), b"fixture").expect("restore GOG support fixture");
         assert!(complete_runtime_current_for_home(&home));
         fs::remove_file(root.join("graphics/vkd3d-proton/x86_64/d3d12.dll")).expect("remove gate fixture");
         assert!(!complete_runtime_current_for_home(&home));
diff --git a/app/src-rust/src/main.rs b/app/src-rust/src/main.rs
index 541edf3af..2bf098691 100644
--- a/app/src-rust/src/main.rs
+++ b/app/src-rust/src/main.rs
@@ -34,6 +34,7 @@ mod migrate;
 mod mono;
 mod mtsp;
 mod platform;
+mod runtime_prefix;
 mod scan;
 mod setup;
 mod sharp_library;
diff --git a/app/src-rust/src/migrate.rs b/app/src-rust/src/migrate.rs
index 503cecd51..d074027e2 100644
--- a/app/src-rust/src/migrate.rs
+++ b/app/src-rust/src/migrate.rs
@@ -3168,6 +3168,7 @@ mod tests {
             ms_dir.join("runtime").join("providers").join("xtajit64-arm64ec-known-good.dll"),
             ms_dir.join("runtime").join("providers").join("xtajit-arm64-known-good.dll"),
             ms_dir.join("runtime").join("scripts").join("stage-runtime-providers.sh"),
+            ms_dir.join("runtime").join("integration").join("gog").join("bin").join("gogdl"),
             runtime_wine.join("build-ec").join("dlls").join("wow64").join("aarch64-windows").join("wow64.dll"),
             runtime_wine.join("build-ec").join("dlls").join("wow64win").join("aarch64-windows").join("wow64win.dll"),
             runtime_wine.join("build-ec").join("dlls").join("winevulkan").join("winevulkan.so"),
@@ -3234,7 +3235,11 @@ mod tests {
 
         fs::write(
             ms_dir.join("runtime").join(".metalsharp-runtime-install"),
-            format!("archive_sha256={}\nno_tso=1\n", crate::installer::COMPLETE_RUNTIME_ARCHIVE_SHA256),
+            format!(
+                "archive_sha256={}\ngog_archive_sha256={}\nno_tso=1\n",
+                crate::installer::COMPLETE_RUNTIME_ARCHIVE_SHA256,
+                crate::installer::GOG_SUPPORT_ARCHIVE_SHA256
+            ),
         )
         .expect("write complete runtime marker");
 
diff --git a/app/src-rust/src/runtime_prefix.rs b/app/src-rust/src/runtime_prefix.rs
new file mode 100644
index 000000000..d5a273e11
--- /dev/null
+++ b/app/src-rust/src/runtime_prefix.rs
@@ -0,0 +1,243 @@
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+const XTAJIT64_SHA256: &str = "7b9f55ceabe971ffa1f514570bb54ed7b5640959e4440e7f8a013e9af13ab7e6";
+const XTAJIT_SHA256: &str = "7d2ac83d2c0935e04d033d609c42d8307294225dcb4cb16b88af849e95c694ab";
+
+pub(crate) fn runtime_root() -> PathBuf {
+    crate::platform::metalsharp_home_dir().join("runtime")
+}
+
+pub(crate) fn wine_root() -> PathBuf {
+    runtime_root().join("wine")
+}
+
+pub(crate) fn apply_complete_runtime_env(command: &mut Command, prefix: &Path) {
+    let root = runtime_root();
+    command
+        .env("WINEPREFIX", prefix)
+        .env("WINEBUILDDIR", root.join("wine/build-ec"))
+        .env("FEX_TSOENABLED", "0")
+        .env("FEX_VECTORTSOENABLED", "0")
+        .env("FEX_MEMCPYSETTSOENABLED", "0");
+    crate::launch::apply_wine_runtime_preferences(command);
+    crate::platform::set_runtime_library_env(command, &root.join("wine"));
+}
+
+fn copy_file_required(source: &Path, destination: &Path, label: &str) -> Result<(), String> {
+    if !source.is_file() {
+        return Err(format!("complete runtime is missing {label}: {}", source.display()));
+    }
+    if let Some(parent) = destination.parent() {
+        std::fs::create_dir_all(parent).map_err(|error| format!("failed to create {}: {error}", parent.display()))?;
+    }
+    std::fs::copy(source, destination)
+        .map_err(|error| format!("failed to stage {label} from {}: {error}", source.display()))?;
+    Ok(())
+}
+
+fn stage_i386_builtins(build: &Path, prefix: &Path) -> Result<usize, String> {
+    let dll_root = build.join("dlls");
+    let syswow64 = prefix.join("drive_c/windows/syswow64");
+    std::fs::create_dir_all(&syswow64).map_err(|error| format!("failed to create {}: {error}", syswow64.display()))?;
+    let mut staged = 0usize;
+
+    let components =
+        std::fs::read_dir(&dll_root).map_err(|error| format!("failed to enumerate {}: {error}", dll_root.display()))?;
+    for component in components {
+        let component = component.map_err(|error| format!("failed to read Wine DLL entry: {error}"))?;
+        let lane = component.path().join("i386-windows");
+        if !lane.is_dir() {
+            continue;
+        }
+        let entries =
+            std::fs::read_dir(&lane).map_err(|error| format!("failed to enumerate {}: {error}", lane.display()))?;
+        for entry in entries {
+            let entry = entry.map_err(|error| format!("failed to read i386 Wine DLL entry: {error}"))?;
+            let path = entry.path();
+            if path.extension().and_then(|ext| ext.to_str()).is_some_and(|ext| ext.eq_ignore_ascii_case("dll")) {
+                std::fs::copy(&path, syswow64.join(entry.file_name()))
+                    .map_err(|error| format!("failed to stage {}: {error}", path.display()))?;
+                staged += 1;
+            }
+        }
+    }
+
+    if staged == 0 {
+        return Err("complete runtime contains no i386 Wine builtins to stage into the prefix".to_string());
+    }
+    Ok(staged)
+}
+
+fn run_runtime_provider_stage(prefix: &Path, verify_only: bool) -> Result<(), String> {
+    let root = runtime_root();
+    let script = root.join("scripts/stage-runtime-providers.sh");
+    let xtajit64 = root.join("providers/xtajit64-arm64ec-known-good.dll");
+    let xtajit = root.join("providers/xtajit-arm64-known-good.dll");
+    if !script.is_file() {
+        return Err(format!("runtime provider staging script is missing: {}", script.display()));
+    }
+
+    let output = Command::new("/bin/bash")
+        .arg(&script)
+        .arg(if verify_only { "--verify-prefix" } else { "--prefix" })
+        .arg(prefix)
+        .env("WINEBUILDDIR", root.join("wine/build-ec"))
+        .env("VKMT_XTAJIT64_SOURCE", &xtajit64)
+        .env("VKMT_XTAJIT_SOURCE", &xtajit)
+        .env("VKMT_XTAJIT64_SHA256", XTAJIT64_SHA256)
+        .env("VKMT_XTAJIT_SHA256", XTAJIT_SHA256)
+        .stdout(Stdio::null())
+        .stderr(Stdio::piped())
+        .output()
+        .map_err(|error| format!("failed to run runtime provider staging: {error}"))?;
+    if !output.status.success() {
+        return Err(format!(
+            "runtime provider {} failed: {}",
+            if verify_only { "verification" } else { "staging" },
+            String::from_utf8_lossy(&output.stderr).lines().last().unwrap_or("unknown error")
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn all_arch_ready(prefix: &Path) -> bool {
+    [
+        "system.reg",
+        "user.reg",
+        "drive_c/windows/system32/kernel32.dll",
+        "drive_c/windows/system32/ntdll.dll",
+        "drive_c/windows/system32/wow64.dll",
+        "drive_c/windows/system32/wow64win.dll",
+        "drive_c/windows/system32/xtajit64.dll",
+        "drive_c/windows/system32/xtajit.dll",
+        "drive_c/windows/syswow64/kernel32.dll",
+        "drive_c/windows/syswow64/ntdll.dll",
+        ".vkmt/gstreamer-runtime.sha256",
+    ]
+    .iter()
+    .all(|relative| prefix.join(relative).is_file())
+}
+
+pub(crate) fn prepare(prefix: &Path) -> Result<(), String> {
+    let root = runtime_root();
+    let build = root.join("wine/build-ec");
+    let wine = crate::platform::runtime_wine_binary(&root.join("wine"));
+    if !wine.is_file() {
+        return Err(format!("MetalSharp Wine not found: {}", wine.display()));
+    }
+
+    let system32 = prefix.join("drive_c/windows/system32");
+    std::fs::create_dir_all(&system32).map_err(|error| format!("failed to create {}: {error}", system32.display()))?;
+    std::fs::create_dir_all(prefix.join("drive_c/windows/syswow64"))
+        .map_err(|error| format!("failed to create prefix syswow64: {error}"))?;
+
+    copy_file_required(
+        &build.join("dlls/wow64/aarch64-windows/wow64.dll"),
+        &system32.join("wow64.dll"),
+        "ARM64 WoW64 provider",
+    )?;
+    copy_file_required(
+        &build.join("dlls/wow64win/aarch64-windows/wow64win.dll"),
+        &system32.join("wow64win.dll"),
+        "ARM64 WoW64 windowing provider",
+    )?;
+    stage_i386_builtins(&build, prefix)?;
+    run_runtime_provider_stage(prefix, false)?;
+
+    let wineboot = build.join("programs/wineboot/aarch64-windows/wineboot.exe");
+    if !wineboot.is_file() {
+        return Err(format!("ARM64 wineboot is missing: {}", wineboot.display()));
+    }
+    let mut wineboot_command = Command::new(&wine);
+    wineboot_command
+        .arg(&wineboot)
+        .arg("--init")
+        .env("WINEBOOTSTRAPMODE", "1")
+        .env("WINE_NO_EXPLORER", "1")
+        .env("WINEDEBUG", "-all")
+        .env("WINEDEBUGGER", "none")
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+    apply_complete_runtime_env(&mut wineboot_command, prefix);
+    let status =
+        wineboot_command.status().map_err(|error| format!("failed to run all-architecture wineboot: {error}"))?;
+    if !status.success() {
+        return Err(format!("all-architecture wineboot failed with {status}"));
+    }
+
+    let wineserver = crate::platform::runtime_wineserver(&root.join("wine"));
+    let wait_status = Command::new(&wineserver)
+        .arg("-w")
+        .env("WINEPREFIX", prefix)
+        .status()
+        .map_err(|error| format!("failed to wait for prefix wineserver: {error}"))?;
+    if !wait_status.success() {
+        return Err(format!("wineserver -w failed after prefix initialization with {wait_status}"));
+    }
+
+    run_runtime_provider_stage(prefix, false)?;
+    run_runtime_provider_stage(prefix, true)?;
+    if !all_arch_ready(prefix) {
+        return Err("prefix was initialized but the ARM64/ARM64EC/x86_64/i386 acceptance gate failed".to_string());
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn all_arch_gate_requires_every_provider_lane() {
+        let prefix = std::env::temp_dir().join(format!(
+            "metalsharp-runtime-prefix-gate-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|duration| duration.as_nanos())
+                .unwrap_or_default()
+        ));
+        for relative in [
+            "system.reg",
+            "user.reg",
+            "drive_c/windows/system32/kernel32.dll",
+            "drive_c/windows/system32/ntdll.dll",
+            "drive_c/windows/system32/wow64.dll",
+            "drive_c/windows/system32/wow64win.dll",
+            "drive_c/windows/system32/xtajit64.dll",
+            "drive_c/windows/system32/xtajit.dll",
+            "drive_c/windows/syswow64/kernel32.dll",
+            "drive_c/windows/syswow64/ntdll.dll",
+            ".vkmt/gstreamer-runtime.sha256",
+        ] {
+            let path = prefix.join(relative);
+            std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+            std::fs::write(path, b"fixture").unwrap();
+        }
+        assert!(all_arch_ready(&prefix));
+        std::fs::remove_file(prefix.join("drive_c/windows/system32/xtajit.dll")).unwrap();
+        assert!(!all_arch_ready(&prefix));
+        let _ = std::fs::remove_dir_all(prefix);
+    }
+
+    #[test]
+    fn complete_runtime_environment_disables_every_tso_mode() {
+        let prefix = PathBuf::from("/tmp/metalsharp-gog-prefix-fixture");
+        let mut command = Command::new("/usr/bin/true");
+        apply_complete_runtime_env(&mut command, &prefix);
+        let env = command
+            .get_envs()
+            .filter_map(|(key, value)| {
+                value.map(|value| (key.to_string_lossy().to_string(), value.to_string_lossy().to_string()))
+            })
+            .collect::<std::collections::HashMap<_, _>>();
+        assert_eq!(env.get("WINEPREFIX"), Some(&prefix.to_string_lossy().to_string()));
+        assert_eq!(env.get("FEX_TSOENABLED").map(String::as_str), Some("0"));
+        assert_eq!(env.get("FEX_VECTORTSOENABLED").map(String::as_str), Some("0"));
+        assert_eq!(env.get("FEX_MEMCPYSETTSOENABLED").map(String::as_str), Some("0"));
+        assert!(env.get("WINEBUILDDIR").is_some_and(|value| value.ends_with("runtime/wine/build-ec")));
+        assert!(env.contains_key("WINEMSYNC"));
+        assert!(env.contains_key("METALSHARP_CONTROLLER_MODE"));
+    }
+}
diff --git a/app/src-rust/src/steam.rs b/app/src-rust/src/steam.rs
index ac21da926..3ffaae01f 100644
--- a/app/src-rust/src/steam.rs
+++ b/app/src-rust/src/steam.rs
@@ -8,8 +8,6 @@ static STEAM_INSTALLING: AtomicBool = AtomicBool::new(false);
 static STEAM_INSTALL_HANDOFF: OnceLock<Mutex<SteamInstallHandoffState>> = OnceLock::new();
 const STEAM_INSTALL_HANDOFF_LIMIT: u8 = 2;
 const STEAM_INSTALL_MARKER: &str = ".metalsharp-steam-install-complete";
-const XTAJIT64_SHA256: &str = "7b9f55ceabe971ffa1f514570bb54ed7b5640959e4440e7f8a013e9af13ab7e6";
-const XTAJIT_SHA256: &str = "7d2ac83d2c0935e04d033d609c42d8307294225dcb4cb16b88af849e95c694ab";
 const STEAMWEBHELPER_WRAPPER_MAX_BYTES: u64 = 100_000;
 const STEAMWEBHELPER_WRAPPER_SHA256: &str = "f46a1e8c39c850ba22861f63559f13b4f68557acf04a92e6d1b899769b2ea1f9";
 const STEAM_D3D12_GUARD_APPS: &[&str] = &["Steam.exe", "steamwebhelper.exe", "steamwebhelper_real.exe"];
@@ -1562,139 +1560,12 @@ fn copy_file_required(source: &Path, destination: &Path, label: &str) -> Result<
     Ok(())
 }
 
-fn stage_i386_builtins(build: &Path, prefix: &Path) -> Result<usize, Box<dyn std::error::Error>> {
-    let dll_root = build.join("dlls");
-    let syswow64 = prefix.join("drive_c/windows/syswow64");
-    std::fs::create_dir_all(&syswow64)?;
-    let mut staged = 0usize;
-
-    for component in std::fs::read_dir(&dll_root)? {
-        let component = component?;
-        let lane = component.path().join("i386-windows");
-        if !lane.is_dir() {
-            continue;
-        }
-        for entry in std::fs::read_dir(lane)? {
-            let entry = entry?;
-            let path = entry.path();
-            if path.extension().and_then(|ext| ext.to_str()).is_some_and(|ext| ext.eq_ignore_ascii_case("dll")) {
-                std::fs::copy(&path, syswow64.join(entry.file_name()))?;
-                staged += 1;
-            }
-        }
-    }
-
-    if staged == 0 {
-        return Err("complete runtime contains no i386 Wine builtins to stage into the Steam prefix".into());
-    }
-    Ok(staged)
-}
-
-fn run_runtime_provider_stage(prefix: &Path, verify_only: bool) -> Result<(), Box<dyn std::error::Error>> {
-    let root = runtime_root();
-    let script = root.join("scripts/stage-runtime-providers.sh");
-    let xtajit64 = root.join("providers/xtajit64-arm64ec-known-good.dll");
-    let xtajit = root.join("providers/xtajit-arm64-known-good.dll");
-    if !script.is_file() {
-        return Err(format!("runtime provider staging script is missing: {}", script.display()).into());
-    }
-
-    let status = Command::new("/bin/bash")
-        .arg(&script)
-        .arg(if verify_only { "--verify-prefix" } else { "--prefix" })
-        .arg(prefix)
-        .env("WINEBUILDDIR", root.join("wine/build-ec"))
-        .env("VKMT_XTAJIT64_SOURCE", &xtajit64)
-        .env("VKMT_XTAJIT_SOURCE", &xtajit)
-        .env("VKMT_XTAJIT64_SHA256", XTAJIT64_SHA256)
-        .env("VKMT_XTAJIT_SHA256", XTAJIT_SHA256)
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::piped())
-        .output()?;
-    if !status.status.success() {
-        return Err(format!(
-            "runtime provider {} failed: {}",
-            if verify_only { "verification" } else { "staging" },
-            String::from_utf8_lossy(&status.stderr).lines().last().unwrap_or("unknown error")
-        )
-        .into());
-    }
-    Ok(())
-}
-
 pub(crate) fn steam_prefix_all_arch_ready(prefix: &Path) -> bool {
-    [
-        "system.reg",
-        "user.reg",
-        "drive_c/windows/system32/kernel32.dll",
-        "drive_c/windows/system32/ntdll.dll",
-        "drive_c/windows/system32/wow64.dll",
-        "drive_c/windows/system32/wow64win.dll",
-        "drive_c/windows/system32/xtajit64.dll",
-        "drive_c/windows/system32/xtajit.dll",
-        "drive_c/windows/syswow64/kernel32.dll",
-        "drive_c/windows/syswow64/ntdll.dll",
-        ".vkmt/gstreamer-runtime.sha256",
-    ]
-    .iter()
-    .all(|relative| prefix.join(relative).is_file())
+    crate::runtime_prefix::all_arch_ready(prefix)
 }
 
 fn prepare_steam_prefix(prefix: &Path) -> Result<(), Box<dyn std::error::Error>> {
-    let root = runtime_root();
-    let build = root.join("wine/build-ec");
-    let wine = ms_wine();
-    let system32 = prefix.join("drive_c/windows/system32");
-    std::fs::create_dir_all(&system32)?;
-    std::fs::create_dir_all(prefix.join("drive_c/windows/syswow64"))?;
-
-    copy_file_required(
-        &build.join("dlls/wow64/aarch64-windows/wow64.dll"),
-        &system32.join("wow64.dll"),
-        "ARM64 WoW64 provider",
-    )?;
-    copy_file_required(
-        &build.join("dlls/wow64win/aarch64-windows/wow64win.dll"),
-        &system32.join("wow64win.dll"),
-        "ARM64 WoW64 windowing provider",
-    )?;
-    stage_i386_builtins(&build, prefix)?;
-    run_runtime_provider_stage(prefix, false)?;
-
-    let wineboot = build.join("programs/wineboot/aarch64-windows/wineboot.exe");
-    let mut wineboot_command = Command::new(&wine);
-    wineboot_command
-        .arg(&wineboot)
-        .arg("--init")
-        .env("WINEPREFIX", prefix)
-        .env("WINEBUILDDIR", &build)
-        .env("WINEBOOTSTRAPMODE", "1")
-        .env("WINE_NO_EXPLORER", "1")
-        .env("WINEDEBUG", "-all")
-        .env("WINEDEBUGGER", "none")
-        .env("FEX_TSOENABLED", "0")
-        .env("FEX_VECTORTSOENABLED", "0")
-        .env("FEX_MEMCPYSETTSOENABLED", "0")
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null());
-    crate::launch::apply_wine_runtime_preferences(&mut wineboot_command);
-    let status = wineboot_command.status()?;
-    if !status.success() {
-        return Err(format!("all-architecture wineboot failed with {status}").into());
-    }
-
-    let wineserver = crate::platform::runtime_wineserver(&root.join("wine"));
-    let wait_status = Command::new(wineserver).arg("-w").env("WINEPREFIX", prefix).status()?;
-    if !wait_status.success() {
-        return Err(format!("wineserver -w failed after Steam prefix initialization with {wait_status}").into());
-    }
-
-    run_runtime_provider_stage(prefix, false)?;
-    run_runtime_provider_stage(prefix, true)?;
-    if !steam_prefix_all_arch_ready(prefix) {
-        return Err("Steam prefix was initialized but the ARM64/ARM64EC/x86_64/i386 acceptance gate failed".into());
-    }
-    Ok(())
+    crate::runtime_prefix::prepare(prefix).map_err(Into::into)
 }
 
 fn stop_steam_install_prefix() -> Result<(), Box<dyn std::error::Error>> {
diff --git a/app/src/renderer/views/SharpView.vue b/app/src/renderer/views/SharpView.vue
index 66de0b294..864ad2584 100644
--- a/app/src/renderer/views/SharpView.vue
+++ b/app/src/renderer/views/SharpView.vue
@@ -153,6 +153,7 @@ interface GogStatus {
   oauthHelperScript?: string | null;
   winePrefix: string;
   prefixInitialized: boolean;
+  prefixAllArchReady: boolean;
   winePath: string;
 }
 
@@ -1746,12 +1747,12 @@ onUnmounted(stopGogMonoPoll);
       <template v-else>
         <section class="gog-panel">
           <div v-if="!gogStatus?.gogdlAvailable" class="empty-state compact">
-            <h2>gogdl is not installed</h2>
-            <p>Install gogdl under ~/.metalsharp/tools/gogdl or set METALSHARP_GOGDL_BIN.</p>
+            <h2>GOG support is not installed</h2>
+            <p>Repair the Complete Multi-Architecture Runtime to restore the verified native ARM64 GOG bundle.</p>
           </div>
           <div v-else-if="!gogStatus?.prefixInitialized" class="empty-state compact">
             <h2>Initialize GOG prefix</h2>
-            <p>Create the isolated Wine prefix before connecting games.</p>
+            <p>Create the isolated ARM64, ARM64EC, x86_64, and i386/WoW64 Wine prefix before connecting games.</p>
           </div>
           <div v-else-if="!gogStatus?.authenticated" class="empty-state compact">
             <h2>Login to GOG to connect your games</h2>
diff --git a/docs/guides/library-and-logs-ui.md b/docs/guides/library-and-logs-ui.md
index 281da4465..a49b84e15 100644
--- a/docs/guides/library-and-logs-ui.md
+++ b/docs/guides/library-and-logs-ui.md
@@ -1,6 +1,6 @@
 # Library and Logs UI
 
-**Updated:** 2026-07-22
+**Updated:** 2026-07-31
 
 ## Library
 
@@ -18,6 +18,19 @@ Installed application cards show their app type, install state, and size on one
 
 Add Asset is unavailable for applications that are not associated with an app-specific bottle.
 
+### GOG
+
+GOG support is installed with the Complete Multi-Architecture Runtime. The
+bundled native ARM64 GOGDL client handles login, library synchronization,
+downloads, imports, uninstall, and Play without cloning source or installing
+Python packages on the user's machine.
+
+**Initialize GOG Prefix** creates or repairs one isolated prefix containing
+the accepted ARM64, ARM64EC, x86_64, and i386/WoW64 provider lanes. The GOG
+view does not treat a partial `drive_c` as initialized. GOG Play uses the same
+complete Wine runtime, no-TSO execution contract, controller mode, and Msync
+setting as the rest of MetalSharp.
+
 ## Logs
 
 The Logs view presents **Live log stream**, **Crash reports**, and **Recent log files** as three responsive selector buttons. Selecting one opens its content in a bounded panel below the selector row, so the page header and the other selectors stay in place.
diff --git a/scripts/install-metalsharp-wine-runtime.sh b/scripts/install-metalsharp-wine-runtime.sh
index 7a3d885ce..8b09145f9 100755
--- a/scripts/install-metalsharp-wine-runtime.sh
+++ b/scripts/install-metalsharp-wine-runtime.sh
@@ -12,6 +12,9 @@ PART01_SHA256="e3ff07bafe27fbf0f4fd7f761e962e7b3203e7e730c82d5d3e26fd5062bb0568"
 PART02_SHA256="5e3c4e96898daa954fbf629819f760aadc3c73481c6200b1ade5e577131aa133"
 PART03_SHA256="cf79389d77f0bd3002894f704948808510860306e0781b556ab91d233290a067"
 PART04_SHA256="cc33cc12386793f47c1bc090f1d55e89c5f6971160ce4c3cbb7372c099b1232b"
+GOG_ARCHIVE_NAME="MetalSharp-GOG-Support-arm64-1.2.2.tar.zst"
+GOG_ARCHIVE_SHA256="f13075f27d5155e84199619410936931b32310c4ec4161de992c1f727ac24155"
+GOG_PACKAGE_ROOT="MetalSharp-GOG-Support-arm64-1.2.2"
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CACHE_DIR="${METALSHARP_RUNTIME_CACHE:-$HOME/Library/Caches/MetalSharp/runtime-bundles/$TAG}"
@@ -23,14 +26,16 @@ PREPARE_ONLY=0
 REPLACE=0
 BACKUP_OLD=1
 STAGE_DIR=""
+GOG_STAGE_DIR=""
+GOG_PROBE=""
 
 usage() {
   cat <<'USAGE'
 Usage: install-metalsharp-wine-runtime.sh [options]
 
-Finds or downloads the four MetalSharp Wine runtime parts, verifies them,
-reassembles and validates the tar.zst, prepares MetalSharp launch wrappers,
-and installs the complete runtime transactionally.
+Finds or downloads the four MetalSharp Wine runtime parts and the native ARM64
+GOG support archive, verifies them, prepares MetalSharp launch wrappers, and
+installs the complete runtime transactionally.
 
 Options:
   --archive PATH       Use an already-reassembled runtime archive.
@@ -62,6 +67,12 @@ cleanup() {
   if [ -n "$STAGE_DIR" ] && [ -d "$STAGE_DIR" ]; then
     find "$STAGE_DIR" -depth -delete
   fi
+  if [ -n "$GOG_STAGE_DIR" ] && [ -d "$GOG_STAGE_DIR" ]; then
+    find "$GOG_STAGE_DIR" -depth -delete
+  fi
+  if [ -n "$GOG_PROBE" ] && [ -e "$GOG_PROBE" ]; then
+    find "$GOG_PROBE" -delete
+  fi
 }
 trap cleanup EXIT INT TERM
 
@@ -208,6 +219,34 @@ prepare_archive() {
   echo "$archive"
 }
 
+find_local_gog_archive() {
+  local candidate dir
+  for dir in "$BUNDLE_DIR" "$PWD" "$SCRIPT_DIR" "$HOME/Downloads" "$HOME/Desktop" "$CACHE_DIR"; do
+    [ -n "$dir" ] || continue
+    candidate="$dir/$GOG_ARCHIVE_NAME"
+    if verify_file "$candidate" "$GOG_ARCHIVE_SHA256" "$GOG_ARCHIVE_NAME"; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+prepare_gog_archive() {
+  local archive
+  if archive="$(find_local_gog_archive)"; then
+    echo "$archive"
+    return 0
+  fi
+  mkdir -p "$CACHE_DIR"
+  archive="$CACHE_DIR/$GOG_ARCHIVE_NAME"
+  [ ! -e "$archive" ] || find "$archive" -delete
+  download_asset "$GOG_ARCHIVE_NAME" "$archive"
+  verify_file "$archive" "$GOG_ARCHIVE_SHA256" "$GOG_ARCHIVE_NAME" \
+    || die "downloaded $GOG_ARCHIVE_NAME failed verification"
+  echo "$archive"
+}
+
 validate_archive_layout() {
   local archive="$1" listing required
   info "Testing zstd stream"
@@ -263,6 +302,30 @@ validate_archive_layout() {
   info "Archive layout verified"
 }
 
+validate_gog_archive() {
+  local archive="$1" listing binary
+  info "Testing native ARM64 GOG support archive"
+  "$ZSTD" -q -t "$archive"
+  listing="$("$ZSTD" -q -dc "$archive" | tar -tf -)"
+  for required in \
+    "$GOG_PACKAGE_ROOT/integration/gog/bin/gogdl" \
+    "$GOG_PACKAGE_ROOT/integration/gog/licenses/heroic-gogdl-GPL-3.0.txt" \
+    "$GOG_PACKAGE_ROOT/integration/gog/metadata/PROVENANCE.tsv" \
+    "$GOG_PACKAGE_ROOT/integration/gog/metadata/SHA256SUMS"; do
+    grep -Fqx "$required" <<< "$listing" || die "GOG support archive is missing: $required"
+  done
+  GOG_PROBE="$(mktemp "${TMPDIR:-/tmp}/metalsharp-gogdl.XXXXXX")"
+  binary="$GOG_PROBE"
+  "$ZSTD" -q -dc "$archive" \
+    | tar -xOf - "$GOG_PACKAGE_ROOT/integration/gog/bin/gogdl" > "$binary"
+  chmod 0755 "$binary"
+  file "$binary" | grep -q 'Mach-O 64-bit executable arm64' || die "bundled gogdl is not native ARM64"
+  [ "$("$binary" --version)" = "1.2.2" ] || die "bundled gogdl version probe failed"
+  find "$binary" -delete
+  GOG_PROBE=""
+  info "Native ARM64 GOG support archive verified"
+}
+
 write_launch_adapters() {
   local root="$1" bin="$1/wine/bin" launcher="$1/wine/bin/metalsharp-runtime-launcher"
   mkdir -p "$bin"
@@ -326,12 +389,52 @@ write_metalsharp_layout() {
   ln -s ../../graphics/moltenvk "$lib/moltenvk"
 }
 
+stage_gog_support() {
+  local root="$1" archive="$2" extracted destination backup
+  GOG_STAGE_DIR="$(mktemp -d "$(dirname "$root")/.metalsharp-gog-stage.XXXXXX")"
+  extracted="$GOG_STAGE_DIR"
+  "$ZSTD" -q -dc "$archive" | tar -xf - -C "$extracted"
+  (cd "$extracted/$GOG_PACKAGE_ROOT" \
+    && shasum -a 256 -c integration/gog/metadata/SHA256SUMS >/dev/null)
+  [ -x "$extracted/$GOG_PACKAGE_ROOT/integration/gog/bin/gogdl" ] \
+    || die "extracted native GOG support binary is missing"
+  mkdir -p "$root/integration"
+  destination="$root/integration/gog"
+  backup="$root/integration/.gog.backup.$$"
+  [ ! -e "$backup" ] || die "GOG support backup path already exists: $backup"
+  if [ -e "$destination" ]; then
+    mv "$destination" "$backup"
+  else
+    backup=""
+  fi
+  if ! mv "$extracted/$GOG_PACKAGE_ROOT/integration/gog" "$destination"; then
+    [ -z "$backup" ] || mv "$backup" "$destination"
+    die "failed to activate native GOG support"
+  fi
+  [ -z "$backup" ] || find "$backup" -depth -delete
+  find "$extracted" -depth -delete
+  GOG_STAGE_DIR=""
+}
+
 install_archive() {
-  local archive="$1" parent available_kb required_kb root backup marker
+  local archive="$1" gog_archive="$2" parent available_kb required_kb root backup marker marker_tmp
   parent="$(dirname "$TARGET")"
   marker="$TARGET/.metalsharp-runtime-install"
   if [ -f "$marker" ] && grep -Fq "archive_sha256=$ARCHIVE_SHA256" "$marker"; then
-    info "This exact runtime is already installed at $TARGET"
+    if grep -Fq "gog_archive_sha256=$GOG_ARCHIVE_SHA256" "$marker" \
+      && [ -x "$TARGET/integration/gog/bin/gogdl" ]; then
+      info "This exact runtime and GOG support bundle are already installed at $TARGET"
+      return 0
+    fi
+    info "Adding native ARM64 GOG support to the existing complete runtime"
+    stage_gog_support "$TARGET" "$gog_archive"
+    marker_tmp="${marker}.gog-update"
+    grep -Ev '^gog_archive(_sha256)?=' "$marker" > "$marker_tmp"
+    printf '%s\n' \
+      "gog_archive=$GOG_ARCHIVE_NAME" \
+      "gog_archive_sha256=$GOG_ARCHIVE_SHA256" >> "$marker_tmp"
+    mv "$marker_tmp" "$marker"
+    info "Installed native ARM64 GOG support at $TARGET/integration/gog"
     return 0
   fi
   if [ -e "$TARGET" ] && [ "$REPLACE" -ne 1 ]; then
@@ -359,10 +462,13 @@ install_archive() {
   repair_build_tree_links "$root"
   write_launch_adapters "$root"
   write_metalsharp_layout "$root"
+  stage_gog_support "$root" "$gog_archive"
   cat > "$root/.metalsharp-runtime-install" <<EOF
 release=$TAG
 archive=$ARCHIVE_NAME
 archive_sha256=$ARCHIVE_SHA256
+gog_archive=$GOG_ARCHIVE_NAME
+gog_archive_sha256=$GOG_ARCHIVE_SHA256
 installed_utc=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
 no_tso=1
 EOF
@@ -393,6 +499,20 @@ EOF
   [ -z "$backup" ] || info "Previous runtime backup: $backup"
 }
 
+GOG_ARCHIVE="$(prepare_gog_archive)"
+verify_file "$GOG_ARCHIVE" "$GOG_ARCHIVE_SHA256" "$GOG_ARCHIVE_NAME" \
+  || die "prepared GOG archive failed final verification"
+validate_gog_archive "$GOG_ARCHIVE"
+
+# Adding or verifying the small GOG layer on an already-accepted runtime must
+# not reread, reassemble, or extract the multi-gigabyte Wine archive.
+if [ -f "$TARGET/.metalsharp-runtime-install" ] \
+  && grep -Fq "archive_sha256=$ARCHIVE_SHA256" "$TARGET/.metalsharp-runtime-install"; then
+  [ "$PREPARE_ONLY" -eq 0 ] || { info "Prepared GOG archive: $GOG_ARCHIVE"; exit 0; }
+  install_archive "" "$GOG_ARCHIVE"
+  exit 0
+fi
+
 ARCHIVE="$(prepare_archive)"
 verify_file "$ARCHIVE" "$ARCHIVE_SHA256" "$ARCHIVE_NAME" \
   || die "prepared archive failed final verification"
@@ -403,4 +523,4 @@ if [ "$PREPARE_ONLY" -eq 1 ]; then
   exit 0
 fi
 
-install_archive "$ARCHIVE"
+install_archive "$ARCHIVE" "$GOG_ARCHIVE"
diff --git a/tools/ci/verify-dmg-workflow.py b/tools/ci/verify-dmg-workflow.py
index a0162f43b..a3999754c 100755
--- a/tools/ci/verify-dmg-workflow.py
+++ b/tools/ci/verify-dmg-workflow.py
@@ -14,6 +14,7 @@
     "metalsharp-bundle-manifest.tsv",
     "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst",
     "MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256",
+    "MetalSharp-GOG-Support-arm64-1.2.2.tar.zst",
     "PARTS-SHA256SUMS.txt",
     "REASSEMBLE.txt",
 ]
diff --git a/tools/dmg/prepare-complete-runtime-assets.sh b/tools/dmg/prepare-complete-runtime-assets.sh
index ee31ee30a..c7327dee4 100755
--- a/tools/dmg/prepare-complete-runtime-assets.sh
+++ b/tools/dmg/prepare-complete-runtime-assets.sh
@@ -8,13 +8,14 @@ REPO="${METALSHARP_RUNTIME_REPO:-metalsharp/MetalSharp}"
 TAG="${METALSHARP_RUNTIME_TAG:-v0.60.0-dependency-bundles}"
 ARCHIVE="MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst"
 ARCHIVE_SHA256="93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee"
-MANIFEST_SHA256="60bc7c19ef8cbbaa55c325fab139c743bea1b1c5d5fd4071791f4a0924487b36"
+MANIFEST_SHA256="bba8103217dbc72914a8496cb782882af0883fbb18664956ba365dba68fec4eb"
 
 ASSETS=(
   metalsharp-bundle-manifest.tsv
   install-metalsharp-wine-runtime.sh
   MetalSharp-Wine-Public-Source-2026-07-31.tar.zst
   MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256
+  MetalSharp-GOG-Support-arm64-1.2.2.tar.zst
   "$ARCHIVE.part01"
   "$ARCHIVE.part02"
   "$ARCHIVE.part03"
@@ -27,6 +28,7 @@ PACKAGE_ASSETS=(
   install-metalsharp-wine-runtime.sh
   MetalSharp-Wine-Public-Source-2026-07-31.tar.zst
   MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256
+  MetalSharp-GOG-Support-arm64-1.2.2.tar.zst
   PARTS-SHA256SUMS.txt
   REASSEMBLE.txt
 )
diff --git a/tools/dmg/verify-dmg-runtime-assets.sh b/tools/dmg/verify-dmg-runtime-assets.sh
index 18a7a0308..70205029d 100755
--- a/tools/dmg/verify-dmg-runtime-assets.sh
+++ b/tools/dmg/verify-dmg-runtime-assets.sh
@@ -41,6 +41,7 @@ for required in \
   "$RUNTIME_BUNDLE/metalsharp-bundle-manifest.tsv" \
   "$RUNTIME_BUNDLE/MetalSharp-Wine-Public-Source-2026-07-31.tar.zst" \
   "$RUNTIME_BUNDLE/MetalSharp-Wine-Public-Source-2026-07-31.tar.zst.sha256" \
+  "$RUNTIME_BUNDLE/MetalSharp-GOG-Support-arm64-1.2.2.tar.zst" \
   "$RUNTIME_BUNDLE/PARTS-SHA256SUMS.txt" \
   "$RUNTIME_BUNDLE/REASSEMBLE.txt"
 do
diff --git a/tools/gog/build-gog-support-bundle.sh b/tools/gog/build-gog-support-bundle.sh
new file mode 100755
index 000000000..763a04e8e
--- /dev/null
+++ b/tools/gog/build-gog-support-bundle.sh
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+GOGDL_TAG="v1.2.2"
+GOGDL_COMMIT="4928e46d1fc4e8f230fe45de277acb8358cbdd69"
+XDELTA_COMMIT="0525275fe4b553a10f38e455d30c60dc6ed9b45d"
+PYINSTALLER_VERSION="6.16.0"
+URLLIB3_VERSION="1.26.20"
+PACKAGE_ROOT="MetalSharp-GOG-Support-arm64-1.2.2"
+OUTPUT_DIR="${1:-$PWD}"
+
+fail() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+[ "$(uname -s)" = "Darwin" ] || fail "GOG support must be built on macOS"
+[ "$(uname -m)" = "arm64" ] || fail "GOG support must be built natively on Apple Silicon"
+for tool in git shasum tar zstd file codesign; do
+  command -v "$tool" >/dev/null 2>&1 || fail "required tool not found: $tool"
+done
+[ -x /usr/bin/python3 ] || fail "/usr/bin/python3 is required"
+mkdir -p "$OUTPUT_DIR"
+
+BUILD_DIR="$(mktemp -d "${TMPDIR:-/tmp}/metalsharp-gog-support.XXXXXX")"
+cleanup() {
+  find "$BUILD_DIR" -depth -delete 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+SOURCE="$BUILD_DIR/heroic-gogdl"
+VENV="$BUILD_DIR/venv"
+STAGE="$BUILD_DIR/$PACKAGE_ROOT"
+
+git clone --quiet --depth 1 --branch "$GOGDL_TAG" --recurse-submodules \
+  https://github.com/Heroic-Games-Launcher/heroic-gogdl.git "$SOURCE"
+[ "$(git -C "$SOURCE" rev-parse HEAD)" = "$GOGDL_COMMIT" ] || fail "unexpected heroic-gogdl commit"
+[ "$(git -C "$SOURCE/xdelta3" rev-parse HEAD)" = "$XDELTA_COMMIT" ] || fail "unexpected xdelta3 commit"
+
+/usr/bin/python3 -m venv "$VENV"
+"$VENV/bin/python" -m pip install --disable-pip-version-check --quiet --upgrade pip setuptools wheel
+"$VENV/bin/python" -m pip install --disable-pip-version-check --quiet \
+  "pyinstaller==$PYINSTALLER_VERSION" "urllib3==$URLLIB3_VERSION" "$SOURCE"
+"$VENV/bin/pyinstaller" --clean --noconfirm --onefile --name gogdl \
+  --distpath "$BUILD_DIR/dist" --workpath "$BUILD_DIR/work" --specpath "$BUILD_DIR" \
+  "$SOURCE/gogdl/cli.py" >/dev/null
+
+BINARY="$BUILD_DIR/dist/gogdl"
+file "$BINARY" | grep -q 'Mach-O 64-bit executable arm64' || fail "gogdl is not thin ARM64 Mach-O"
+codesign --verify --deep --strict "$BINARY"
+[ "$("$BINARY" --version)" = "1.2.2" ] || fail "gogdl version probe failed"
+"$VENV/bin/pyi-archive_viewer" -l "$BINARY" | grep -q 'gogdl_xdelta3.abi3.so' \
+  || fail "gogdl xdelta extension is not embedded"
+
+mkdir -p "$STAGE/integration/gog/bin" "$STAGE/integration/gog/licenses" "$STAGE/integration/gog/metadata"
+cp "$BINARY" "$STAGE/integration/gog/bin/gogdl"
+chmod 0755 "$STAGE/integration/gog/bin/gogdl"
+cp "$SOURCE/LICENSE" "$STAGE/integration/gog/licenses/heroic-gogdl-GPL-3.0.txt"
+cp "$SOURCE/README.md" "$STAGE/integration/gog/metadata/heroic-gogdl-README.md"
+cat > "$STAGE/integration/gog/metadata/PROVENANCE.tsv" <<EOF
+component\tversion\trevision\tlicense\tupstream
+heroic-gogdl\t1.2.2\t$GOGDL_COMMIT\tGPL-3.0\thttps://github.com/Heroic-Games-Launcher/heroic-gogdl
+xdelta3\t3.x\t$XDELTA_COMMIT\tApache-2.0\thttps://github.com/jmacd/xdelta
+PyInstaller\t$PYINSTALLER_VERSION\tpypi\tGPL-2.0-or-later-with-bootloader-exception\thttps://pyinstaller.org/
+requests\t2.32.5\tpypi\tApache-2.0\thttps://requests.readthedocs.io/
+urllib3\t$URLLIB3_VERSION\tpypi\tMIT\thttps://urllib3.readthedocs.io/
+EOF
+(cd "$STAGE" && find . -type f ! -path './integration/gog/metadata/SHA256SUMS' -print0 \
+  | sort -z | xargs -0 shasum -a 256 > integration/gog/metadata/SHA256SUMS)
+
+ARCHIVE="$OUTPUT_DIR/$PACKAGE_ROOT.tar.zst"
+tar -C "$BUILD_DIR" -cf - "$PACKAGE_ROOT" | zstd -T0 -19 -f -o "$ARCHIVE"
+shasum -a 256 "$ARCHIVE" > "$ARCHIVE.sha256"
+echo "Created $ARCHIVE"

From 00d74d90c3c9e8875a0be4673e4873fc8c702dc0 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 18:10:21 -0600
Subject: [PATCH 12/14] remove redundant Wine Mono install controls

---
 AGENTS.md                               |   6 +
 app/src-rust/src/main.rs                |  15 -
 app/src-rust/src/mono.rs                | 875 ------------------------
 app/src/renderer/views/SettingsView.vue | 182 +----
 app/src/renderer/views/SharpView.vue    | 216 +-----
 5 files changed, 28 insertions(+), 1266 deletions(-)
 delete mode 100644 app/src-rust/src/mono.rs

diff --git a/AGENTS.md b/AGENTS.md
index 1abf9cfb6..21133e694 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -148,6 +148,12 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   a disposable existing-runtime fixture; the deterministic Rust suite passes
   655/655; strict Clippy, all Rust targets, TypeScript, Vite, DMG workflow, and
   shell gates pass.
+- Wine Mono 11.2.0 is part of the complete runtime. The GOG and Settings tabs
+  no longer offer a second interactive MSI download/install/reset path, and
+  the retired `/wine-mono/*` backend endpoints and installer module are gone.
+  This does not remove bundled Mono, the Mono/FNA launch lanes, or bottle-level
+  compatibility metadata. Post-removal validation passes 644/644 Rust tests,
+  strict Clippy, all Rust targets, and the Electron production build.
 
 ## What This Project Is
 
diff --git a/app/src-rust/src/main.rs b/app/src-rust/src/main.rs
index 2bf098691..79386486b 100644
--- a/app/src-rust/src/main.rs
+++ b/app/src-rust/src/main.rs
@@ -31,7 +31,6 @@ mod launch;
 mod launcher_evidence;
 mod metalfx;
 mod migrate;
-mod mono;
 mod mtsp;
 mod platform;
 mod runtime_prefix;
@@ -1915,20 +1914,6 @@ fn route(req: &mut tiny_http::Request) -> RouteResponse {
             let body = read_body(req);
             resp(200, gog::handle_uninstall(&Value::Object(body)))
         },
-        (Method::Get, "/wine-mono/status") => {
-            let prefix = query_param(req.url(), "prefix").unwrap_or_else(|| "gog".to_string());
-            resp(200, mono::handle_status(&prefix))
-        },
-        (Method::Post, "/wine-mono/install") => {
-            let body = read_body(req);
-            let prefix = body.get("prefix").and_then(|v| v.as_str()).unwrap_or("gog").to_string();
-            resp(200, mono::handle_install(&prefix))
-        },
-        (Method::Post, "/wine-mono/reset") => {
-            let body = read_body(req);
-            let prefix = body.get("prefix").and_then(|v| v.as_str()).unwrap_or("gog").to_string();
-            resp(200, mono::handle_reset(&prefix))
-        },
         (Method::Post, "/sharp-library/install") => {
             let body = read_body(req);
             app_log(&format!("[SHARP-LIB] install: {}", body.get("srcPath").and_then(|v| v.as_str()).unwrap_or("?")));
diff --git a/app/src-rust/src/mono.rs b/app/src-rust/src/mono.rs
deleted file mode 100644
index a22598500..000000000
--- a/app/src-rust/src/mono.rs
+++ /dev/null
@@ -1,875 +0,0 @@
-//! Wine Mono install / upgrade surface.
-//!
-//! Provides the backend for the GOG "Install Mono" header button and the
-//! Settings "Upgrade Mono" action. Both download the official Wine Mono
-//! `x86.msi` for the pinned latest release and run it
-//! (`wine msiexec /i <msi> REINSTALLMODE=vomus REINSTALL=ALL /qn`) inside
-//! a self-cleaning, bounded state machine. Once the versioned
-//! `windows/mono/wine-mono-<version>/` directory exists in the prefix, the
-//! install is considered complete and the caller can hide its button.
-//!
-//! The installer harness explicitly defends against the Wine Mono MSI's
-//! embedded `RemoveExistingProducts` action that spawns a detached
-//! `msiexec REMOVE=ALL` for the prior `{AF2C9281-50A4-543B-A8E2-F0A38015A9F8}`
-//! product — those detached children are prone to outliving the wine
-//! parent if anyone deletes the install filesystem first. The harness:
-//!  1. kills the prefix's wineserver (`wineserver -k`) and sweeps any
-//!     leftover mono-related processes,
-//!  2. only then runs `wine msiexec /i ... REINSTALLMODE=vomus REINSTALL=ALL /qn`,
-//!  3. waits on the child with a hard timeout, and
-//!  4. always reaps orphan `msiexec REMOVE=ALL` /
-//!     `winedevice.exe` / `start.exe /exec msiexec` children before
-//!     updating the install state.
-//!
-//! Detection is prefix-filesystem based (no registry reads) so it works
-//! identically for the GOG prefix and the Steam prefix.
-
-use serde_json::{json, Value};
-use std::fs::{self, OpenOptions};
-use std::io::{Read, Write};
-use std::path::{Path, PathBuf};
-use std::process::{Child, Command, Stdio};
-use std::sync::OnceLock;
-use std::time::{Duration, Instant};
-
-/// Pinned "latest" Wine Mono release. Bumping this (version + msi filename +
-/// expected install dir) is the only change needed to ship a new mono.
-pub const WINE_MONO_LATEST_VERSION: &str = "11.2.0";
-const WINE_MONO_LATEST_MSI_FILENAME: &str = "wine-mono-11.2.0-x86.msi";
-const WINE_MONO_RELEASE_TAG: &str = "wine-mono-11.2.0";
-const WINE_MONO_INSTALL_DIR_NAME: &str = "wine-mono-11.2.0";
-
-fn wine_mono_msi_url() -> &'static str {
-    "https://github.com/wine-mono/wine-mono/releases/download/wine-mono-11.2.0/wine-mono-11.2.0-x86.msi"
-}
-
-fn now_secs() -> u64 {
-    std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs()).unwrap_or(0)
-}
-
-/// Directory used to cache the downloaded MSI so repeated installs/upgrades do
-/// not re-download. Lives under the MetalSharp data folder.
-fn mono_cache_dir() -> PathBuf {
-    crate::platform::metalsharp_home_dir().join("cache").join("wine-mono")
-}
-
-fn mono_cache_msi_path() -> PathBuf {
-    mono_cache_dir().join(WINE_MONO_LATEST_MSI_FILENAME)
-}
-
-/// In-flight install state so the renderer can poll a single status endpoint
-/// without re-deriving it. Mirrors the wineboot/poll patterns elsewhere.
-#[derive(Debug, Clone, Default, serde::Serialize)]
-struct MonoInstallState {
-    running: bool,
-    pid: Option<u32>,
-    /// Unix-epoch seconds when the current run started; lets the UI flag
-    /// installs that look hung for too long.
-    started_at: Option<u64>,
-    prefix: Option<String>,
-    log_path: Option<String>,
-    target_version: String,
-    last_error: Option<String>,
-    /// Background MSI download tracking so the frontend can show progress.
-    downloading: bool,
-    download_bytes: u64,
-    download_total: u64,
-    download_error: Option<String>,
-}
-
-static INSTALL_STATE: OnceLock<std::sync::Mutex<MonoInstallState>> = OnceLock::new();
-
-fn install_state() -> &'static std::sync::Mutex<MonoInstallState> {
-    INSTALL_STATE.get_or_init(|| {
-        std::sync::Mutex::new(MonoInstallState {
-            target_version: WINE_MONO_LATEST_VERSION.to_string(),
-            ..Default::default()
-        })
-    })
-}
-
-fn read_install_state() -> MonoInstallState {
-    install_state().lock().map(|s| s.clone()).unwrap_or_default()
-}
-
-fn mutate_install_state<F: FnOnce(&mut MonoInstallState)>(f: F) {
-    if let Ok(mut state) = install_state().lock() {
-        f(&mut state);
-    }
-}
-
-pub fn detect_wine_mono_version(prefix: &Path) -> Option<String> {
-    // The version marker is a synthetic directory we create after a
-    // successful install. Its presence means the current latest version
-    // was installed by us.
-    let marker = prefix.join("drive_c").join("windows").join("mono").join(WINE_MONO_INSTALL_DIR_NAME);
-    if marker.is_dir() {
-        Some(WINE_MONO_LATEST_VERSION.to_string())
-    } else {
-        None
-    }
-}
-
-/// True when ANY wine-mono is present in the prefix (either our version
-/// marker OR the mono-2.0 directory that the MSI creates). Used to decide
-/// fresh install vs upgrade.
-pub fn has_any_wine_mono(prefix: &Path) -> bool {
-    detect_wine_mono_version(prefix).is_some()
-        || prefix.join("drive_c").join("windows").join("mono").join("mono-2.0").is_dir()
-}
-
-/// Compare two dotted version strings (e.g. "11.2.0" vs "9.5.0") numerically.
-fn compare_versions(a: &str, b: &str) -> std::cmp::Ordering {
-    let mut a_it = a.split('.');
-    let mut b_it = b.split('.');
-    loop {
-        match (a_it.next(), b_it.next()) {
-            (Some(a_part), Some(b_part)) => {
-                let a_num = a_part.parse::<u64>().unwrap_or(0);
-                let b_num = b_part.parse::<u64>().unwrap_or(0);
-                match a_num.cmp(&b_num) {
-                    std::cmp::Ordering::Equal => continue,
-                    other => return other,
-                }
-            },
-            (Some(_), None) => return std::cmp::Ordering::Greater,
-            (None, Some(_)) => return std::cmp::Ordering::Less,
-            (None, None) => return std::cmp::Ordering::Equal,
-        }
-    }
-}
-
-/// True when our version marker is present — the definitive signal that
-/// the latest version was installed AND the install completed.
-pub fn is_wine_mono_latest(prefix: &Path) -> bool {
-    detect_wine_mono_version(prefix).as_deref() == Some(WINE_MONO_LATEST_VERSION)
-}
-
-/// For the UI status: "installed" means any mono exists.
-pub fn is_any_mono_installed(prefix: &Path) -> bool {
-    has_any_wine_mono(prefix)
-}
-
-/// Status payload shared by the GOG header button and the Settings row.
-/// `prefix_kind` is "gog" or "steam" so the renderer can label appropriately.
-pub fn wine_mono_status(prefix: &Path, prefix_kind: &str) -> Value {
-    let installed_version = detect_wine_mono_version(prefix);
-    let any_installed = is_any_mono_installed(prefix);
-    let up_to_date = installed_version.as_deref() == Some(WINE_MONO_LATEST_VERSION);
-    let state = read_install_state();
-    let started_at = state.started_at;
-    let elapsed_seconds = started_at.map(|start| now_secs().saturating_sub(start));
-    // Flag the install as stalled if it has been running for >75% of the
-    // hard timeout — this gives the UI a chance to surface a recovery
-    // affordance without forcing the user to wait the full timeout.
-    let stalled = state.running
-        && elapsed_seconds.map(|seconds| seconds >= (WINE_MONO_INSTALL_TIMEOUT.as_secs() * 3) / 4).unwrap_or(false);
-    json!({
-        "ok": true,
-        "prefixKind": prefix_kind,
-        "latestVersion": WINE_MONO_LATEST_VERSION,
-        "installedVersion": installed_version,
-        "installed": any_installed,
-        "upToDate": up_to_date,
-        "running": state.running,
-        "stalled": stalled,
-        "pid": state.pid,
-        "startedAt": started_at,
-        "elapsedSeconds": elapsed_seconds,
-        "logPath": state.log_path,
-        "targetVersion": state.target_version,
-        "lastError": state.last_error,
-        "msiCached": mono_cache_msi_path().is_file(),
-        "downloading": state.downloading,
-        "downloadBytes": state.download_bytes,
-        "downloadTotal": state.download_total,
-        "downloadError": state.download_error,
-    })
-}
-
-// ---------------------------------------------------------------------------
-// MSI staging — mirrors sharp_library::stage_installer_exe + current_dir
-// ---------------------------------------------------------------------------
-
-/// Copy the cached MSI into a staging directory inside the prefix so the
-/// installer runs with its working directory co-located with the prefix.
-/// Matches the Sharp Library pattern of staging the installer payload before
-/// execution.
-fn stage_msi_into_prefix(cached_msi: &Path, prefix: &Path) -> Result<PathBuf, String> {
-    let staging_dir = prefix.join(".ms-mono-install");
-    fs::create_dir_all(&staging_dir).map_err(|e| format!("create mono staging dir: {}", e))?;
-    let file_name = cached_msi.file_name().ok_or_else(|| "msi cache filename missing".to_string())?;
-    let staged = staging_dir.join(file_name);
-
-    // Only re-copy when the cached MSI is newer or the staged copy is absent.
-    let needs_copy = !staged.is_file()
-        || cached_msi.metadata().ok().and_then(|m| m.modified().ok())
-            > staged.metadata().ok().and_then(|m| m.modified().ok());
-    if needs_copy {
-        fs::copy(cached_msi, &staged).map_err(|e| format!("stage mono msi: {}", e))?;
-    }
-    Ok(staged)
-}
-
-// ---------------------------------------------------------------------------
-// Async download — non-blocking, progress reported through MonoInstallState
-// ---------------------------------------------------------------------------
-
-/// Spawn a background thread to download the MSI. Updates `MonoInstallState`
-/// with progress as bytes arrive. Idempotent: does nothing if a download is
-/// already in flight.
-fn spawn_msi_download() {
-    {
-        let state = read_install_state();
-        if state.downloading {
-            return;
-        }
-    }
-    mutate_install_state(|s| {
-        s.downloading = true;
-        s.download_bytes = 0;
-        s.download_total = 0;
-        s.download_error = None;
-    });
-
-    let cache_dir = mono_cache_dir();
-    let cache_path = mono_cache_msi_path();
-    let url = wine_mono_msi_url().to_string();
-
-    std::thread::spawn(move || {
-        let result = download_msi_to_cache(&url, &cache_dir, &cache_path);
-        match result {
-            Ok(_) => mutate_install_state(|s| {
-                s.downloading = false;
-            }),
-            Err(e) => mutate_install_state(|s| {
-                s.downloading = false;
-                s.download_error = Some(e);
-            }),
-        }
-    });
-}
-
-/// Synchronous download worker (runs on the background thread). Writes
-/// progress into `MonoInstallState` so the status-poll endpoint can surface
-/// byte-level progress to the frontend.
-fn download_msi_to_cache(url: &str, cache_dir: &Path, cache_path: &Path) -> Result<(), String> {
-    fs::create_dir_all(cache_dir).map_err(|e| format!("create wine-mono cache dir: {}", e))?;
-
-    let config = ureq::config::Config::builder()
-        .user_agent(format!("MetalSharp/wine-mono-{}", WINE_MONO_LATEST_VERSION))
-        .build();
-    let agent = ureq::Agent::new_with_config(config);
-    let response = agent.get(url).call().map_err(|e| format!("wine-mono download failed: {}", e))?;
-
-    let total: u64 = response
-        .headers()
-        .get("content-length")
-        .and_then(|v| v.to_str().ok())
-        .and_then(|v| v.parse::<u64>().ok())
-        .unwrap_or(0);
-    mutate_install_state(|s| {
-        s.download_total = total;
-    });
-
-    let tmp = cache_path.with_extension("msi.part");
-    let mut file = fs::File::create(&tmp).map_err(|e| format!("create wine-mono msi: {}", e))?;
-    let mut reader = response.into_body().into_reader();
-    let mut buf = [0u8; 65536];
-    let mut downloaded: u64 = 0;
-    loop {
-        let n = reader.read(&mut buf).map_err(|e| format!("wine-mono read: {}", e))?;
-        if n == 0 {
-            break;
-        }
-        file.write_all(&buf[..n]).map_err(|e| format!("wine-mono write: {}", e))?;
-        downloaded += n as u64;
-        mutate_install_state(|s| {
-            s.download_bytes = downloaded;
-        });
-        if total > 0 && downloaded >= total {
-            break;
-        }
-    }
-    drop(file);
-    fs::rename(&tmp, cache_path).map_err(|e| format!("finalize wine-mono msi: {}", e))?;
-    Ok(())
-}
-
-// ---------------------------------------------------------------------------
-// Process hygiene: kill & sweep helpers that bound the wine process tree
-// so the orphaned-`msiexec REMOVE=ALL` problem cannot reappear.
-// ---------------------------------------------------------------------------
-
-/// Hard timeout for the entire Wine Mono install. The MSI ships ~480 MB of
-/// files and on a busy Apple Silicon machine the install can legitimately
-/// take 5–8 minutes end to end. We allow 10 minutes and force a cleanup
-/// afterwards either way.
-const WINE_MONO_INSTALL_TIMEOUT: Duration = Duration::from_secs(10 * 60);
-
-/// Polling cadence when waiting on `child.wait()` so we can still apply the
-/// hard timeout and run orphan sweeps while the child is alive.
-const WINE_MONO_WAIT_POLL: Duration = Duration::from_millis(500);
-
-/// Run the prefix's `wineserver -k` to terminate any leftover wine/msiexec/
-/// winedevice processes attached to the prefix. Best effort — any error
-/// (e.g. wineserver missing) is swallowed because the sweep below is the
-/// real cleanup.
-fn kill_prefix_wineserver(prefix: &Path) {
-    let home = match dirs::home_dir() {
-        Some(home) => home,
-        None => return,
-    };
-    let ms_root = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
-    let wineserver = ms_root.join("bin").join("wineserver");
-    if !wineserver.is_file() {
-        return;
-    }
-    let mut cmd = Command::new(&wineserver);
-    cmd.arg("-k").env("WINEPREFIX", prefix.to_string_lossy().to_string());
-    crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
-    let _ = cmd.status();
-}
-
-/// Best-effort sweep of stale wine mono/wine-mono-related processes. We
-/// intentionally match by command-line fragment so we only kill processes
-/// we created (or whose previous attempt orphaned them) — not arbitrary
-/// wine installs on the user's machine.
-fn sweep_orphan_mono_processes(prefix: &Path) -> u32 {
-    let needle_prefix = prefix.to_string_lossy();
-    let output = Command::new("/bin/ps").args(["-axo", "pid=,command="]).output();
-    let stdout = match output {
-        Ok(output) => String::from_utf8_lossy(&output.stdout).to_string(),
-        Err(_) => return 0,
-    };
-    let mut killed: u32 = 0;
-    for line in stdout.lines() {
-        let trimmed = line.trim();
-        let Some((pid_text, command)) = trimmed.split_once(' ') else {
-            continue;
-        };
-        let Ok(pid) = pid_text.trim().parse::<u32>() else {
-            continue;
-        };
-        // Never signal ourselves.
-        if pid == std::process::id() {
-            continue;
-        }
-
-        // Match processes related to wine mono: msiexec working on the
-        // mono MSI, the wine start.exe wrapper, winedevice remnants, or
-        // anything running inside our prefix path.
-        let is_msiexec_orphan =
-            command.contains("msiexec") && (command.contains("REMOVE=ALL") || command.contains(needle_prefix.as_ref()));
-        let is_start_wrapper = command.contains("/exec msiexec") && command.contains(".ms-mono-install");
-        let is_winedevice = command.contains("winedevice");
-        let is_in_prefix = command.contains(needle_prefix.as_ref())
-            && (command.contains("wine") || command.contains("msiexec") || command.contains("winedevice"));
-        if is_msiexec_orphan || is_start_wrapper || is_winedevice || is_in_prefix {
-            // Escalate: TERM first, fall back to KILL if the process
-            // ignored TERM.
-            let _ = Command::new("/bin/kill").arg("-TERM").arg(pid.to_string()).status();
-            std::thread::sleep(Duration::from_millis(50));
-            if let Ok(status) = Command::new("/bin/kill").arg("-0").arg(pid.to_string()).status() {
-                if status.success() {
-                    let _ = Command::new("/bin/kill").arg("-KILL").arg(pid.to_string()).status();
-                }
-            }
-            killed += 1;
-        }
-    }
-    killed
-}
-
-/// Wait for `child` to exit, sweeping orphans every `WINE_MONO_WAIT_POLL` so
-/// we surface a clean state. Returns `Ok(status)` if the child exited within
-/// the timeout and `Err(message)` if the timeout fired — in which case the
-/// caller is expected to kill + sweep + reap the child.
-/// Wait for `child` to exit, polling every `WINE_MONO_WAIT_POLL`.
-/// We no longer sweep orphans during the wait — doing so killed the
-/// wineserver and winedevice processes that the MSI installer needs to
-/// function, causing exit code 1 and an empty install.
-/// The post-reap cleanup (kill_prefix_wineserver + sweep at the
-/// call site) handles leftover orphans.
-fn wait_with_sweep(child: &mut Child, _prefix: &Path, _sweep_log: &Path) -> Result<std::process::ExitStatus, String> {
-    let deadline = Instant::now() + WINE_MONO_INSTALL_TIMEOUT;
-    loop {
-        if let Ok(Some(status)) = child.try_wait() {
-            return Ok(status);
-        }
-        if Instant::now() >= deadline {
-            return Err(format!("Wine Mono installer exceeded {:?} budget", WINE_MONO_INSTALL_TIMEOUT));
-        }
-        std::thread::sleep(WINE_MONO_WAIT_POLL);
-    }
-}
-
-/// Remove leftover `Installer/*.msi` stub files and the `mono-2.0` install
-/// directory if (and only if) the prefix's wineserver is fully down. This
-/// matches what the Wine Mono MSI's `RemoveExistingProducts` action would
-/// have done had it not previously hung — we now do it ourselves, after
-/// killing the prefix's wineserver so the registry hive is unlocked.
-fn cleanup_prefix_for_mono_install(prefix: &Path) {
-    let mono_dir = prefix.join("drive_c").join("windows").join("mono").join("mono-2.0");
-    if mono_dir.is_dir() {
-        let _ = fs::remove_dir_all(&mono_dir);
-    }
-    let installer_dir = prefix.join("drive_c").join("windows").join("Installer");
-    if let Ok(entries) = fs::read_dir(&installer_dir) {
-        for entry in entries.flatten() {
-            if entry.path().extension().map(|e| e == "msi").unwrap_or(false) {
-                let _ = fs::remove_file(entry.path());
-            }
-        }
-    }
-    // Some Wine Mono installs also leave the registry entry for the old
-    // product; surface that in the log for diagnostic purposes (the MSI's
-    // REINSTALLMODE=vomus below handles it without external cleanup).
-}
-
-pub fn install_wine_mono_latest(prefix: &Path, prefix_kind: &str) -> Result<u32, String> {
-    // 1. Resolve wine binary — always use the real `wine` binary, not the
-    // `metalsharp-wine` wrapper, because the wrapper sets env vars that can
-    // interfere with msiexec.
-    let home = dirs::home_dir().ok_or_else(|| "no home dir".to_string())?;
-    let ms_root = crate::platform::metalsharp_home_dir_for(&home).join("runtime").join("wine");
-    let wine = ms_root.join("bin").join("wine");
-    if !wine.exists() {
-        return Err(format!("MetalSharp Wine not found: {}", wine.display()));
-    }
-
-    // 2. Ensure prefix directory exists (match sharp library)
-    fs::create_dir_all(prefix).map_err(|e| format!("create prefix dir: {}", e))?;
-    if !prefix.join("drive_c").is_dir() {
-        return Err(format!("prefix not initialized (no drive_c): {}", prefix.display()));
-    }
-
-    // 3. Verify the cached MSI is present
-    let cached_msi = mono_cache_msi_path();
-    if !cached_msi.is_file() || cached_msi.metadata().map(|m| m.len() < 1_000_000).unwrap_or(true) {
-        return Err("Wine Mono MSI not downloaded yet".to_string());
-    }
-
-    // 4. Re-stage the MSI into the prefix (each install gets a fresh copy).
-    let staged_msi = stage_msi_into_prefix(&cached_msi, prefix)?;
-
-    // 5. Log setup — single open, clone handle for stdout (match sharp)
-    let log_dir = crate::platform::metalsharp_home_dir_for(&home).join("logs");
-    fs::create_dir_all(&log_dir).map_err(|e| format!("create log dir: {}", e))?;
-    let log_path = log_dir.join(format!("wine-mono-install-{}.log", prefix_kind));
-
-    let mut log = OpenOptions::new()
-        .create(true)
-        .write(true)
-        .truncate(true)
-        .open(&log_path)
-        .map_err(|e| format!("open wine-mono log: {}", e))?;
-    let _ = writeln!(log, "installer_kind=msi");
-    let _ = writeln!(log, "prefix={}", prefix.display());
-    let _ = writeln!(log, "msi={}", staged_msi.display());
-    let _ = writeln!(log, "mono_version={}", WINE_MONO_LATEST_VERSION);
-    let _ = writeln!(log, "timeout={:?}; reinstall_mode=vomus; reinstall=ALL", WINE_MONO_INSTALL_TIMEOUT);
-    let _ = writeln!(log, "--- wine output ---");
-    let stdout = log.try_clone().map_err(|e| format!("clone log handle: {}", e))?;
-    let stderr = log.try_clone().map_err(|e| format!("clone stderr handle: {}", e))?;
-
-    // 6. Before cleanup, check whether wine-mono already exists so we
-    //    can decide between a fresh install and an upgrade install.
-    let has_existing_mono = has_any_wine_mono(prefix);
-
-    // 7. Hygiene: kill any wineserver for the prefix (optional — the
-    //    new wine will start its own) and sweep orphans so we don't
-    //    have stale processes from prior attempts. The sweep in
-    //    wait_with_sweep was removed because it was killing the
-    //    wineserver and winedevice that the MSI installer needs.
-    kill_prefix_wineserver(prefix);
-    sweep_orphan_mono_processes(prefix);
-    cleanup_prefix_for_mono_install(prefix);
-
-    // 8. Build the install command.
-    //
-    //    For a FRESH install (no prior wine-mono in the prefix), we use
-    //    a plain `msiexec /i <msi> /qn` — the REINSTALL flags cause the
-    //    MSI to exit with code 67 (ERROR_INSTALL_FAILURE) when there is
-    //    nothing to reinstall.
-    //
-    //    For an UPGRADE (prior wine-mono present), REINSTALLMODE=vomus
-    //    tells the MSI to overwrite, re-install missing, and update the
-    //    registry — patching the prior
-    //    {AF2C9281-50A4-543B-A8E2-F0A38015A9F8} reference rather than
-    //    detaching a hung msiexec REMOVE=ALL.
-    //    REINSTALL=ALL forces every feature to install.
-    let mut cmd = Command::new(&wine);
-    cmd.arg("msiexec").arg("/i").arg(&staged_msi);
-    if has_existing_mono {
-        cmd.arg("REINSTALLMODE=vomus").arg("REINSTALL=ALL");
-    }
-    cmd.arg("/qn")
-        .env("WINEPREFIX", prefix.to_string_lossy().to_string())
-        .env("WINEDEBUG", "-all")
-        .stdout(Stdio::from(stdout))
-        .stderr(Stdio::from(stderr));
-    if let Some(parent) = staged_msi.parent() {
-        cmd.current_dir(parent);
-    }
-    crate::platform::set_runtime_library_env(&mut cmd, &ms_root);
-
-    // 8. Spawn
-    let mut child = cmd.spawn().map_err(|e| format!("spawn wine msiexec: {}", e))?;
-    let pid = child.id();
-
-    mutate_install_state(|s| {
-        s.running = true;
-        s.pid = Some(pid);
-        s.started_at = Some(now_secs());
-        s.prefix = Some(prefix.to_string_lossy().to_string());
-        s.log_path = Some(log_path.to_string_lossy().to_string());
-        s.target_version = WINE_MONO_LATEST_VERSION.to_string();
-        s.last_error = None;
-    });
-
-    // Reap the installer process. Use the bounded wait+helper, then
-    // **always** kill+reap any stragglers and update state.
-    let prefix_for_thread: PathBuf = prefix.to_path_buf();
-    let log_for_thread: PathBuf = log_path.clone();
-    let pid_for_thread = pid;
-    std::thread::spawn(move || {
-        let wait_result = wait_with_sweep(&mut child, &prefix_for_thread, &log_for_thread);
-        // Always force-cleanup regardless of why wait returned.
-        kill_prefix_wineserver(&prefix_for_thread);
-        let _ = sweep_orphan_mono_processes(&prefix_for_thread);
-        // If the child is still around, terminate it directly.
-        if let Ok(None) = child.try_wait() {
-            let _ = child.kill();
-            let _ = child.wait();
-        }
-
-        match wait_result {
-            Ok(status) => {
-                if status.success() {
-                    let marker =
-                        prefix_for_thread.join("drive_c").join("windows").join("mono").join(WINE_MONO_INSTALL_DIR_NAME);
-                    let _ = fs::create_dir_all(&marker);
-                }
-                let still_latest =
-                    detect_wine_mono_version(&prefix_for_thread).as_deref() == Some(WINE_MONO_LATEST_VERSION);
-                mutate_install_state(|s| {
-                    s.running = false;
-                    s.pid = None;
-                    s.started_at = None;
-                    if !still_latest {
-                        s.last_error = Some(format!(
-                            "Wine Mono installer exited with {:?} but {} was not detected in {}",
-                            status.code(),
-                            WINE_MONO_LATEST_VERSION,
-                            prefix_for_thread.display()
-                        ));
-                    }
-                });
-            },
-            Err(error) => {
-                if let Ok(mut log) = fs::OpenOptions::new().create(true).append(true).open(&log_for_thread) {
-                    let _ = writeln!(log, "[metal-sharp] timeout: {}", error);
-                }
-                mutate_install_state(|s| {
-                    s.running = false;
-                    s.pid = None;
-                    s.started_at = None;
-                    s.last_error = Some(error);
-                });
-            },
-        }
-
-        // Drop the pid we recorded so any extra state is consistent.
-        mutate_install_state(|s| {
-            if s.pid == Some(pid_for_thread) {
-                s.pid = None;
-            }
-            s.started_at = None;
-        });
-    });
-
-    Ok(pid)
-}
-
-// ---------------------------------------------------------------------------
-// Public handlers
-// ---------------------------------------------------------------------------
-
-/// Path resolution for the two supported prefixes.
-pub fn prefix_for_kind(prefix_kind: &str) -> Result<PathBuf, String> {
-    match prefix_kind {
-        "gog" => Ok(crate::bottles::bottle_dir("gog-prefix").join("prefix")),
-        "steam" => Ok(crate::platform::metalsharp_home_dir().join("prefix-steam")),
-        other => Err(format!("unknown prefix kind: {}", other)),
-    }
-}
-
-pub fn handle_status(prefix_kind: &str) -> Value {
-    match prefix_for_kind(prefix_kind) {
-        Ok(prefix) => wine_mono_status(&prefix, prefix_kind),
-        Err(error) => json!({"ok": false, "error": error}),
-    }
-}
-
-/// Install handler with two-phase flow:
-///
-/// 1. **MSI not cached** → spawn async download, return immediately with
-///    `downloading: true`. The frontend polls `/wine-mono/status` for
-///    progress and re-calls this endpoint once `msiCached` is true.
-/// 2. **MSI cached** → stage into prefix and launch the installer.
-pub fn handle_install(prefix_kind: &str) -> Value {
-    let prefix = match prefix_for_kind(prefix_kind) {
-        Ok(p) => p,
-        Err(error) => return json!({"ok": false, "error": error}),
-    };
-
-    // If the latest is already installed, treat as a no-op success so a
-    // redundant button press does not re-launch the installer.
-    if is_wine_mono_latest(&prefix) {
-        return json!({
-            "ok": true,
-            "alreadyInstalled": true,
-            "status": wine_mono_status(&prefix, prefix_kind),
-        });
-    }
-
-    // If a download is already in progress, just return current status.
-    {
-        let state = read_install_state();
-        if state.downloading {
-            return json!({
-                "ok": true,
-                "downloading": true,
-                "status": wine_mono_status(&prefix, prefix_kind),
-            });
-        }
-    }
-
-    // Phase 1: MSI not cached yet — start async download.
-    if !mono_cache_msi_path().is_file() {
-        spawn_msi_download();
-        return json!({
-            "ok": true,
-            "downloading": true,
-            "status": wine_mono_status(&prefix, prefix_kind),
-        });
-    }
-
-    // Phase 2: MSI cached — launch the installer.
-    match install_wine_mono_latest(&prefix, prefix_kind) {
-        Ok(pid) => json!({
-            "ok": true,
-            "pid": pid,
-            "status": wine_mono_status(&prefix, prefix_kind),
-        }),
-        Err(error) => {
-            mutate_install_state(|s| {
-                s.running = false;
-                s.last_error = Some(error.clone());
-            });
-            json!({
-                "ok": false,
-                "error": error,
-                "status": wine_mono_status(&prefix, prefix_kind),
-            })
-        },
-    }
-}
-
-/// Hard-reset the Mono install for a prefix. Kills the prefix's wineserver,
-/// sweeps any orphan msiexec/winedevice processes (the hangover from
-/// previous failed install attempts), and clears the in-memory install state
-/// so the next click of "Install Mono" starts fresh.
-///
-/// This is a no-op if there is nothing to clean up; it does not touch the
-/// cached MSI in `~/.metalsharp/cache/wine-mono/` so a successful download
-/// is preserved across resets.
-pub fn handle_reset(prefix_kind: &str) -> Value {
-    let prefix = match prefix_for_kind(prefix_kind) {
-        Ok(p) => p,
-        Err(error) => {
-            mutate_install_state(|s| {
-                s.running = false;
-                s.pid = None;
-                s.started_at = None;
-                s.last_error = Some(error.clone());
-            });
-            return json!({"ok": false, "error": error});
-        },
-    };
-    kill_prefix_wineserver(&prefix);
-    let killed = sweep_orphan_mono_processes(&prefix);
-    mutate_install_state(|s| {
-        s.running = false;
-        s.pid = None;
-        s.started_at = None;
-        s.last_error = None;
-    });
-    json!({
-        "ok": true,
-        "killedProcesses": killed,
-        "prefix": prefix.to_string_lossy().to_string(),
-        "status": wine_mono_status(&prefix, prefix_kind),
-    })
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn latest_version_constants_are_consistent() {
-        assert!(WINE_MONO_LATEST_VERSION.contains('.'));
-        assert!(WINE_MONO_LATEST_MSI_FILENAME.contains(WINE_MONO_LATEST_VERSION));
-        assert!(WINE_MONO_INSTALL_DIR_NAME.contains(WINE_MONO_LATEST_VERSION));
-        assert!(wine_mono_msi_url().contains(WINE_MONO_RELEASE_TAG));
-        assert!(wine_mono_msi_url().ends_with(WINE_MONO_LATEST_MSI_FILENAME));
-    }
-
-    #[test]
-    fn compare_versions_is_numeric_not_lexicographic() {
-        assert!(compare_versions("11.2.0", "9.5.0").is_gt());
-        assert!(compare_versions("9.5.0", "11.2.0").is_lt());
-        assert!(compare_versions("11.2.0", "11.2.0").is_eq());
-        assert!(compare_versions("11.2.1", "11.2.0").is_gt());
-        assert!(compare_versions("11.3.0", "11.2.9").is_gt());
-        assert_eq!(compare_versions("2.0", "2.0.0"), std::cmp::Ordering::Less);
-    }
-
-    #[test]
-    fn detect_returns_none_when_mono_dir_absent() {
-        let tmp = std::env::temp_dir().join(format!(
-            "ms-mono-none-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
-        ));
-        assert_eq!(detect_wine_mono_version(&tmp), None);
-        assert!(!is_wine_mono_latest(&tmp));
-        let _ = std::fs::remove_dir_all(&tmp);
-    }
-
-    #[test]
-    fn detect_finds_version_marker_dir() {
-        let tmp = std::env::temp_dir().join(format!(
-            "ms-mono-detect-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
-        ));
-        let marker = tmp.join("drive_c/windows/mono").join(WINE_MONO_INSTALL_DIR_NAME);
-        std::fs::create_dir_all(&marker).unwrap();
-
-        assert_eq!(detect_wine_mono_version(&tmp), Some("11.2.0".to_string()));
-        assert!(is_wine_mono_latest(&tmp));
-
-        let status = wine_mono_status(&tmp, "gog");
-        assert_eq!(status.get("installedVersion").and_then(|v| v.as_str()), Some("11.2.0"));
-        assert_eq!(status.get("upToDate").and_then(|v| v.as_bool()), Some(true));
-        let _ = std::fs::remove_dir_all(&tmp);
-    }
-
-    #[test]
-    fn status_reports_not_installed_when_mono_2_0_absent() {
-        let tmp = std::env::temp_dir().join(format!(
-            "ms-mono-outdated-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
-        ));
-        let status = wine_mono_status(&tmp, "steam");
-        assert_eq!(status.get("installedVersion").and_then(|v| v.as_str()), None);
-        assert_eq!(status.get("upToDate").and_then(|v| v.as_bool()), Some(false));
-        assert_eq!(status.get("installed").and_then(|v| v.as_bool()), Some(false));
-        let _ = std::fs::remove_dir_all(&tmp);
-    }
-
-    #[test]
-    fn prefix_for_kind_resolves_known_prefixes() {
-        assert!(prefix_for_kind("gog").is_ok());
-        assert!(prefix_for_kind("steam").is_ok());
-        assert!(prefix_for_kind("unknown").is_err());
-    }
-
-    #[test]
-    fn handle_install_rejects_unknown_prefix_without_spawning() {
-        let result = handle_install("nope");
-        assert_eq!(result.get("ok").and_then(|v| v.as_bool()), Some(false));
-        assert!(result.get("error").is_some());
-    }
-
-    #[test]
-    fn wine_mono_status_includes_download_fields() {
-        let tmp = std::env::temp_dir().join(format!(
-            "ms-mono-dl-fields-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
-        ));
-        // Reset install state so the test starts clean.
-        mutate_install_state(|s| {
-            s.downloading = true;
-            s.download_bytes = 42;
-            s.download_total = 100;
-        });
-        let status = wine_mono_status(&tmp, "steam");
-        assert_eq!(status.get("downloading").and_then(|v| v.as_bool()), Some(true));
-        assert_eq!(status.get("downloadBytes").and_then(|v| v.as_u64()), Some(42));
-        assert_eq!(status.get("downloadTotal").and_then(|v| v.as_u64()), Some(100));
-        mutate_install_state(|s| {
-            s.downloading = false;
-            s.download_bytes = 0;
-            s.download_total = 0;
-        });
-        let _ = std::fs::remove_dir_all(&tmp);
-    }
-
-    #[test]
-    fn orphan_sweep_skips_self_pid_and_returns_zero_when_no_match() {
-        let tmp = std::env::temp_dir().join(format!(
-            "ms-mono-sweep-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
-        ));
-        // A path that will never appear in /bin/ps output for this machine.
-        let killed = sweep_orphan_mono_processes(&tmp);
-        // We can't assert the exact count (other tests may run concurrently),
-        // but we MUST NOT have signalled our own pid.
-        assert!(killed == killed, "sweep_orphan_mono_processes must complete and return a u32");
-        // Confirm our pid is alive (we did not signal ourselves).
-        let alive = std::process::Command::new("/bin/kill")
-            .arg("-0")
-            .arg(std::process::id().to_string())
-            .status()
-            .map(|s| s.success())
-            .unwrap_or(false);
-        assert!(alive, "sweep must never signal its own pid");
-        let _ = std::fs::remove_dir_all(&tmp);
-    }
-
-    #[test]
-    fn handle_reset_does_not_panic_and_reports_status() {
-        let result = handle_install("gog");
-        // We just want to make sure the reset call after install is
-        // observable. Pre-clean by running the reset directly.
-        let reset = handle_reset("gog");
-        assert_eq!(reset.get("ok").and_then(|v| v.as_bool()), Some(true));
-        let _ = result;
-    }
-
-    #[test]
-    fn status_reports_up_to_date_with_marker_after_reset() {
-        let tmp = std::env::temp_dir().join(format!(
-            "ms-mono-marker-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
-        ));
-        let marker = tmp.join("drive_c/windows/mono").join(WINE_MONO_INSTALL_DIR_NAME);
-        std::fs::create_dir_all(&marker).unwrap();
-        let status = wine_mono_status(&tmp, "gog");
-        assert_eq!(status.get("upToDate").and_then(|v| v.as_bool()), Some(true));
-        assert_eq!(status.get("installed").and_then(|v| v.as_bool()), Some(true));
-        let _ = std::fs::remove_dir_all(&tmp);
-    }
-}
diff --git a/app/src/renderer/views/SettingsView.vue b/app/src/renderer/views/SettingsView.vue
index ccd084bb6..bb537be8f 100644
--- a/app/src/renderer/views/SettingsView.vue
+++ b/app/src/renderer/views/SettingsView.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, inject, onMounted, onUnmounted, type Ref } from "vue";
+import { ref, inject, onMounted, type Ref } from "vue";
 import { useToast } from "../composables/useToast";
 import { api, getAPI } from "../composables/useApi";
 import type { AppConfig, UpdateStatus } from "../api-types";
@@ -42,111 +42,12 @@ const pipelineCache = ref<CacheSummary | null>(null);
 const apiKeyInput = ref("");
 const graphicsRuntimeLogs = ref(false);
 
-interface WineMonoStatus {
-  latestVersion: string;
-  installedVersion?: string | null;
-  installed: boolean;
-  upToDate: boolean;
-  running: boolean;
-  pid?: number | null;
-  logPath?: string | null;
-  targetVersion: string;
-  lastError?: string | null;
-  msiCached: boolean;
-  downloading: boolean;
-  downloadBytes: number;
-  downloadTotal: number;
-  downloadError?: string | null;
-}
-const steamMonoStatus = ref<WineMonoStatus | null>(null);
-const steamMonoLoading = ref(false);
-const steamMonoPollHandle = ref<ReturnType<typeof setInterval> | null>(null);
-
-async function refreshSteamMonoStatus() {
-  const result = await api<WineMonoStatus>("GET", "/wine-mono/status?prefix=steam");
-  if (result?.ok) steamMonoStatus.value = result;
-}
-
-async function upgradeSteamMono() {
-  steamMonoLoading.value = true;
-  // Short timeout — the backend now returns immediately (kicks off download or launches installer).
-  const result = await api<{ ok: boolean; pid?: number; alreadyInstalled?: boolean; downloading?: boolean; error?: string; status?: WineMonoStatus }>("POST", "/wine-mono/install", { prefix: "steam" }, 30 * 1000);
-  steamMonoLoading.value = false;
-  if (result?.ok) {
-    if (result.alreadyInstalled) {
-      await refreshSteamMonoStatus();
-      toast.show("Wine Mono is already up to date", "success");
-      return;
-    }
-    if (result.downloading) {
-      // Backend kicked off async download — poll for progress.
-      startSteamMonoPoll();
-      return;
-    }
-    // Installer launched.
-    toast.show("Wine Mono installer launched — complete it in the Wine window", "success");
-    startSteamMonoPoll();
-  } else {
-    toast.show(result?.error ?? "Failed to launch Wine Mono installer", "error");
-    await refreshSteamMonoStatus();
-  }
-}
-
-function steamMonoButtonLabel(): string {
-  const s = steamMonoStatus.value;
-  if (!s) return "Upgrade Mono";
-  if (s.downloading && s.downloadTotal > 0) {
-    const raw = (s.downloadBytes / s.downloadTotal) * 100;
-    const pct = Math.min(100, Math.floor(raw / 15) * 15);
-    return `Downloading Mono ${pct}%…`;
-  }
-  if (s.downloading) return "Downloading Mono…";
-  if (s.running) return "Running…";
-  if (steamMonoLoading.value) return "Installing…";
-  return "Upgrade Mono";
-}
-
-function startSteamMonoPoll() {
-  if (steamMonoPollHandle.value) return;
-  steamMonoPollHandle.value = setInterval(async () => {
-    await refreshSteamMonoStatus();
-    const status = steamMonoStatus.value;
-    if (!status) return;
-
-    // Download completed successfully → trigger the installer.
-    if (status.msiCached && !status.downloading && !status.running && !status.upToDate) {
-      stopSteamMonoPoll();
-      steamMonoLoading.value = true;
-      await upgradeSteamMono();
-      return;
-    }
-
-    if (status.upToDate) {
-      stopSteamMonoPoll();
-      toast.show(`Wine Mono ${status.latestVersion} installed`, "success");
-    } else if (!status.running && !status.downloading) {
-      // Installer exited without landing the latest version (user cancelled).
-      stopSteamMonoPoll();
-    }
-  }, 3000);
-}
-
-function stopSteamMonoPoll() {
-  if (steamMonoPollHandle.value) {
-    clearInterval(steamMonoPollHandle.value);
-    steamMonoPollHandle.value = null;
-  }
-}
-
 onMounted(async () => {
   apiKeyInput.value = steamApiKey.value ?? "";
   await refreshConfig();
   await refreshCacheSizes();
-  void refreshSteamMonoStatus();
 });
 
-onUnmounted(() => { stopSteamMonoPoll(); });
-
 async function refreshConfig() {
   const result = await api<AppConfig>("GET", "/config");
   if (result?.ok) {
@@ -366,7 +267,8 @@ function toggleLowPerformanceMode(enabled: boolean) {
 }
 
 async function forceKillProcesses() {
-  if (!confirm("Force kill MetalSharp Wine/runtime processes? This can stop active games, installers, and downloads.")) return;
+  if (!confirm("Force kill MetalSharp Wine/runtime processes? This can stop active games, installers, and downloads."))
+    return;
   const result = await api<{
     ok: boolean;
     terminated?: unknown[];
@@ -380,7 +282,10 @@ async function forceKillProcesses() {
   }
   const count = (result.terminated?.length ?? 0) + (result.killed?.length ?? 0);
   if (result.ok) {
-    toast.show(count > 0 ? `Force killed ${count} process${count === 1 ? "" : "es"}` : "No MetalSharp runtime processes found", "success");
+    toast.show(
+      count > 0 ? `Force killed ${count} process${count === 1 ? "" : "es"}` : "No MetalSharp runtime processes found",
+      "success",
+    );
   } else {
     toast.show(result.error ?? `Force kill completed with ${result.errors?.length ?? 0} error(s)`, "error");
   }
@@ -394,7 +299,9 @@ async function toggleGraphicsRuntimeLogs(enabled: boolean) {
     config.value = result;
     graphicsRuntimeLogs.value = Boolean(result.graphicsRuntimeLogs ?? result.graphics_runtime_logs);
     toast.show(
-      graphicsRuntimeLogs.value ? "Graphics runtime logs enabled for future launches" : "Graphics runtime logs disabled",
+      graphicsRuntimeLogs.value
+        ? "Graphics runtime logs enabled for future launches"
+        : "Graphics runtime logs disabled",
       "success",
     );
   } else {
@@ -509,7 +416,9 @@ function uninstallMetalsharp() {
       <div class="settings-row">
         <div>
           <div class="settings-label">Force Kill Processes</div>
-          <div class="settings-desc">Destructively stops MetalSharp Wine/runtime helper processes while keeping this app and backend alive.</div>
+          <div class="settings-desc">
+            Destructively stops MetalSharp Wine/runtime helper processes while keeping this app and backend alive.
+          </div>
         </div>
         <div class="settings-value">
           <button class="btn btn-danger btn-sm" @click="forceKillProcesses">Force Kill Processes</button>
@@ -518,7 +427,9 @@ function uninstallMetalsharp() {
       <div class="settings-row">
         <div>
           <div class="settings-label">Low Performance Mode</div>
-          <div class="settings-desc">Disables blur, glass, glow, and heavy motion while preserving layout and essential progress updates.</div>
+          <div class="settings-desc">
+            Disables blur, glass, glow, and heavy motion while preserving layout and essential progress updates.
+          </div>
         </div>
         <div class="settings-value">
           <span class="badge" :class="lowPerformanceMode ? 'badge-warn' : 'badge-ok'">
@@ -554,7 +465,8 @@ function uninstallMetalsharp() {
         <div>
           <div class="settings-label">Graphics Runtime Logs</div>
           <div class="settings-desc">
-            Opt in to graphics-backend logs for future launches. Off by default so DXMT and M12 vkd3d-proton games stay quiet unless requested.
+            Opt in to graphics-backend logs for future launches. Off by default so DXMT and M12 vkd3d-proton games stay
+            quiet unless requested.
           </div>
         </div>
         <div class="settings-value">
@@ -573,43 +485,6 @@ function uninstallMetalsharp() {
       </div>
     </div>
 
-    <div class="settings-section">
-      <h2>Runtime</h2>
-      <div v-if="steamMonoStatus && !steamMonoStatus.upToDate" class="settings-row">
-        <div>
-          <div class="settings-label">Wine Mono</div>
-          <div class="settings-desc">
-            Download and install Wine Mono {{ steamMonoStatus.latestVersion }} into the Steam prefix.
-            <span v-if="steamMonoStatus.installed">Installed: v{{ steamMonoStatus.installedVersion }}.</span>
-            <span v-else>No Wine Mono installed.</span>
-            <span v-if="steamMonoStatus.downloadError" class="download-error">Download failed: {{ steamMonoStatus.downloadError }}.</span>
-            The installer runs interactively in a Wine window.
-          </div>
-        </div>
-        <div class="settings-value">
-          <button
-            class="btn btn-primary btn-sm"
-            :disabled="steamMonoLoading || steamMonoStatus.running || steamMonoStatus.downloading"
-            @click="upgradeSteamMono"
-          >
-            {{ steamMonoButtonLabel() }}
-          </button>
-          <div v-if="steamMonoStatus.downloading && steamMonoStatus.downloadTotal > 0" class="mono-progress-bar">
-            <div class="mono-progress-fill" :style="{ width: Math.round((steamMonoStatus.downloadBytes / steamMonoStatus.downloadTotal) * 100) + '%' }"></div>
-          </div>
-        </div>
-      </div>
-      <div v-else-if="steamMonoStatus && steamMonoStatus.upToDate" class="settings-row">
-        <div>
-          <div class="settings-label">Wine Mono</div>
-          <div class="settings-desc">Wine Mono v{{ steamMonoStatus.installedVersion }} is up to date.</div>
-        </div>
-        <div class="settings-value">
-          <span class="badge badge-ok">Up to date</span>
-        </div>
-      </div>
-    </div>
-
     <div class="settings-section">
       <h2>Data &amp; Permissions</h2>
       <div class="settings-row">
@@ -715,7 +590,8 @@ function uninstallMetalsharp() {
         <div>
           <div class="settings-label">Uninstall MetalSharp</div>
           <div class="settings-desc">
-            Permanently deletes all Wine prefixes, bottles, Steam installation, Wine runtime, shader caches, and settings. The app will close after cleanup.
+            Permanently deletes all Wine prefixes, bottles, Steam installation, Wine runtime, shader caches, and
+            settings. The app will close after cleanup.
           </div>
         </div>
         <div class="settings-value">
@@ -832,22 +708,4 @@ function uninstallMetalsharp() {
 .btn-danger:hover {
   background: rgba(220, 60, 60, 0.25);
 }
-.download-error {
-  color: #dc3c3c;
-  font-weight: 500;
-}
-.mono-progress-bar {
-  width: 120px;
-  height: 6px;
-  background: var(--border);
-  border-radius: 3px;
-  overflow: hidden;
-  margin-top: 4px;
-}
-.mono-progress-fill {
-  height: 100%;
-  background: var(--accent);
-  border-radius: 3px;
-  transition: width 0.3s ease;
-}
 </style>
diff --git a/app/src/renderer/views/SharpView.vue b/app/src/renderer/views/SharpView.vue
index 864ad2584..cb4a1287a 100644
--- a/app/src/renderer/views/SharpView.vue
+++ b/app/src/renderer/views/SharpView.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref, onMounted, onUnmounted } from "vue";
+import { computed, ref, onMounted } from "vue";
 import { useToast } from "../composables/useToast";
 import { api, getAPI } from "../composables/useApi";
 import type { SharpApp } from "../api-types";
@@ -210,192 +210,6 @@ const gogGames = ref<GogGame[]>([]);
 const gogLoading = ref<Record<string, boolean>>({});
 const gogProgress = ref<Record<string, number>>({});
 
-interface WineMonoStatus {
-  latestVersion: string;
-  installedVersion?: string | null;
-  installed: boolean;
-  upToDate: boolean;
-  running: boolean;
-  stalled?: boolean;
-  pid?: number | null;
-  logPath?: string | null;
-  targetVersion: string;
-  startedAt?: number | null;
-  elapsedSeconds?: number | null;
-  lastError?: string | null;
-  msiCached: boolean;
-  downloading: boolean;
-  downloadBytes: number;
-  downloadTotal: number;
-  downloadError?: string | null;
-}
-const gogMonoStatus = ref<WineMonoStatus | null>(null);
-const gogMonoPollHandle = ref<ReturnType<typeof setInterval> | null>(null);
-
-const showGogInstallMono = computed(() => {
-  if (!gogStatus.value?.prefixInitialized) return false;
-  const status = gogMonoStatus.value;
-  if (!status) return true; // unknown — show until we confirm it is up to date
-  return !status.upToDate;
-});
-
-async function refreshGogMonoStatus() {
-  const result = await api<WineMonoStatus>("GET", "/wine-mono/status?prefix=gog");
-  if (result?.ok) gogMonoStatus.value = result;
-}
-
-async function installGogMono() {
-  if (!gogStatus.value?.prefixInitialized) {
-    toast.show("Initialize the GOG prefix first", "error");
-    return;
-  }
-  gogLoading.value.mono = true;
-  // Short timeout — the backend now returns immediately (kicks off download or launches installer).
-  const result = await api<{
-    ok: boolean;
-    pid?: number;
-    alreadyInstalled?: boolean;
-    downloading?: boolean;
-    error?: string;
-    status?: WineMonoStatus;
-  }>("POST", "/wine-mono/install", { prefix: "gog" }, 30 * 1000);
-  gogLoading.value.mono = false;
-  if (result?.ok) {
-    if (result.alreadyInstalled) {
-      await refreshGogMonoStatus();
-      toast.show("Wine Mono is already up to date", "success");
-      return;
-    }
-    if (result.downloading) {
-      // Backend kicked off async download — poll for progress.
-      startGogMonoPoll();
-      return;
-    }
-    // Installer launched.
-    toast.show("Wine Mono installer launched — complete it in the Wine window", "success");
-    startGogMonoPoll();
-  } else {
-    const errMsg = result?.error ?? "Failed to launch Wine Mono installer";
-    toast.show(errMsg, "error", 12_000);
-    await refreshGogMonoStatus();
-  }
-}
-
-async function resetGogMonoInstall() {
-  gogLoading.value.mono = true;
-  const result = await api<{ ok: boolean; killedProcesses?: number; error?: string }>(
-    "POST",
-    "/wine-mono/reset",
-    { prefix: "gog" },
-    15 * 1000,
-  );
-  gogLoading.value.mono = false;
-  await refreshGogMonoStatus();
-  if (result?.ok) {
-    const killed = result.killedProcesses ?? 0;
-    toast.show(
-      killed > 0
-        ? `Cleared ${killed} stuck Mono processes; click Install Mono to retry`
-        : "Mono install state cleared; click Install Mono to retry",
-      "success",
-    );
-  } else {
-    toast.show(result?.error ?? "Failed to reset Wine Mono install", "error");
-  }
-}
-
-function formatElapsedSeconds(seconds: number | null | undefined): string {
-  if (!seconds || seconds < 0) return "0:00";
-  const total = Math.floor(seconds);
-  const m = Math.floor(total / 60);
-  const s = total % 60;
-  return `${m}:${s.toString().padStart(2, "0")}`;
-}
-
-function gogMonoButtonLabel(): string {
-  const s = gogMonoStatus.value;
-  if (!s) return "Install Mono";
-  if (s.downloading && s.downloadTotal > 0) {
-    const raw = (s.downloadBytes / s.downloadTotal) * 100;
-    const pct = Math.min(100, Math.floor(raw / 5) * 5);
-    return `Downloading ${pct}%…`;
-  }
-  if (s.downloading) return "Downloading Mono…";
-  if (s.running && s.stalled) return "Stalled — tap to retry";
-  if (s.running) {
-    const elapsed = formatElapsedSeconds(s.elapsedSeconds);
-    return `Running… ${elapsed}`;
-  }
-  if (gogLoading.value.mono) return "Installing Mono…";
-  return "Install Mono";
-}
-
-function gogMonoButtonTitle(): string {
-  const s = gogMonoStatus.value;
-  if (!s) return "Install Wine Mono";
-  if (s.downloadError) {
-    return `Wine Mono download failed: ${s.downloadError}. Click to retry.`;
-  }
-  if (s.stalled) {
-    return s.lastError
-      ? `Wine Mono installer stalled: ${s.lastError}. Click to retry, or use Reset to clear stuck processes.`
-      : "Wine Mono installer stalled. Click to retry, or use Reset to clear stuck processes.";
-  }
-  const base = `Wine Mono ${s.installedVersion ?? "not installed"} → ${s.latestVersion}`;
-  return s.lastError ? `${base}. ${s.lastError}` : base;
-}
-
-function startGogMonoPoll() {
-  if (gogMonoPollHandle.value) return;
-  let stalledToastShown = false;
-  gogMonoPollHandle.value = setInterval(async () => {
-    await refreshGogMonoStatus();
-    const status = gogMonoStatus.value;
-    if (!status) return;
-
-    // If the backend reports a hung install, surface a single recovery toast
-    // and let the user decide whether to retry or reset.
-    if (status.stalled === true && !stalledToastShown) {
-      stalledToastShown = true;
-      toast.show(
-        status.lastError
-          ? `Wine Mono installer stalled (${status.lastError}); tap Reset to clear or Install Mono to retry`
-          : "Wine Mono installer stalled; tap Reset to clear or Install Mono to retry",
-        "error",
-        10_000,
-      );
-    }
-    if (!status.stalled) {
-      stalledToastShown = false;
-    }
-
-    // Download completed successfully → trigger the installer.
-    if (status.msiCached && !status.downloading && !status.running && !status.upToDate && !status.stalled) {
-      stopGogMonoPoll();
-      gogLoading.value.mono = true;
-      await installGogMono();
-      return;
-    }
-
-    if (status.upToDate) {
-      stopGogMonoPoll();
-      toast.show(`Wine Mono ${status.latestVersion} installed`, "success");
-    } else if (!status.running && !status.downloading) {
-      // Installer exited without landing the latest version (user cancelled).
-      stopGogMonoPoll();
-      if (status.lastError) {
-        toast.show(status.lastError, "error", 12_000);
-      }
-    }
-  }, 3000);
-}
-
-function stopGogMonoPoll() {
-  if (gogMonoPollHandle.value) {
-    clearInterval(gogMonoPollHandle.value);
-    gogMonoPollHandle.value = null;
-  }
-}
 const engineOptions = [
   { id: "d3dmetal", name: "D3DMetal" },
   { id: "m12", name: "M12" },
@@ -510,7 +324,6 @@ async function load() {
       if (game.status === "downloading") void monitorGogProgress(game.productId);
     }
   }
-  if (gogStatus.value?.prefixInitialized) void refreshGogMonoStatus();
 }
 
 function setGogGames(games: GogGame[]) {
@@ -525,7 +338,6 @@ async function refreshGog() {
     api<{ ok: boolean; games: GogGame[]; status: GogStatus }>("GET", "/sharp-library/gog/games"),
   ]);
   if (statusResult?.ok) gogStatus.value = statusResult.status;
-  if (gogStatus.value?.prefixInitialized) void refreshGogMonoStatus();
   if (gamesResult?.ok) {
     setGogGames(gamesResult.games ?? []);
     gogStatus.value = gamesResult.status;
@@ -575,7 +387,7 @@ async function initializeGogPrefix() {
 async function removeGogPrefix() {
   const message =
     "Remove the GOG Wine prefix? " +
-    "This will permanently delete the isolated Wine prefix and all Wine Mono components. " +
+    "This will permanently delete the isolated Wine prefix and its prefix-specific runtime state. " +
     "Downloaded GOG games will stay on disk but cannot launch until the prefix is re-created.";
   if (!confirm(message)) return;
   gogLoading.value.removing = true;
@@ -1448,7 +1260,6 @@ function formatBytes(bytes: number): string {
 }
 
 onMounted(load);
-onUnmounted(stopGogMonoPoll);
 </script>
 
 <template>
@@ -1491,29 +1302,6 @@ onUnmounted(stopGogMonoPoll);
           }}</span
           ><span class="btn-label-short">Prefix</span>
         </button>
-        <button
-          v-if="sourceMode === 'gog' && showGogInstallMono"
-          class="btn btn-primary"
-          :disabled="
-            gogLoading.mono ||
-            (gogMonoStatus?.running && !gogMonoStatus?.stalled) ||
-            (gogMonoStatus?.downloading && !gogMonoStatus?.stalled)
-          "
-          :title="gogMonoButtonTitle()"
-          @click="installGogMono"
-        >
-          <span class="btn-label-long">{{ gogMonoButtonLabel() }}</span
-          ><span class="btn-label-short">Mono</span>
-        </button>
-        <button
-          v-if="sourceMode === 'gog' && showGogInstallMono && (gogMonoStatus?.stalled || gogMonoStatus?.running)"
-          class="btn btn-secondary btn-sm"
-          :disabled="gogLoading.mono"
-          title="Kill any stuck Wine Mono processes and reset the install state"
-          @click="resetGogMonoInstall"
-        >
-          <span class="btn-label-long">Reset</span><span class="btn-label-short">Reset</span>
-        </button>
         <button
           v-if="sourceMode === 'gog'"
           class="btn btn-primary"

From 55074d3cb15e2858f7785dd44241756374fe58fb Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 20:14:32 -0600
Subject: [PATCH 13/14] release: complete 0.57 runtime migration

---
 AGENTS.md                                     |  25 +-
 CMakeLists.txt                                |   2 +-
 app/package-lock.json                         |   4 +-
 app/package.json                              |   2 +-
 app/src-rust/Cargo.lock                       |   2 +-
 app/src-rust/Cargo.toml                       |   2 +-
 app/src-rust/src/installer.rs                 |   2 +-
 app/src-rust/src/migrate.rs                   | 337 +++++++++++------
 app/src-rust/src/runtime_prefix.rs            | 355 ++++++++++++++++--
 app/src-rust/src/steam.rs                     |  27 ++
 app/src/renderer/components/MigrationView.vue |  20 +-
 scripts/install-metalsharp-wine-runtime.sh    |  10 +-
 tools/ci/verify-dmg-workflow.py               |   2 +-
 tools/dmg/prepare-complete-runtime-assets.sh  |   2 +-
 14 files changed, 621 insertions(+), 171 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 21133e694..39a7bad1f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   `scripts/install-metalsharp-wine-runtime.sh` from release
   `v0.60.0-dependency-bundles`.
 - The canonical complete-runtime SHA-256 is
-  `93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee`.
+  `e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146`.
 - Runtime completion is gated by `.metalsharp-runtime-install` plus Wine,
   wineserver, fonts/NLS, DXVK i386, vkd3d-proton D3D12, OpenGL-Metal, and
   MoltenVK payloads. Do not restore the old six-archive setup gate.
@@ -155,6 +155,29 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   compatibility metadata. Post-removal validation passes 644/644 Rust tests,
   strict Clippy, all Rust targets, and the Electron production build.
 
+- The 0.57 -> 0.60 migration is an in-place runtime replacement. Preserve and
+  restore setup/configuration, Steam prefix metadata and payloads, bottles,
+  games, Sharp Library data, and dosdevice links; replace the runtime and then
+  run native ARM64 `wineboot --init --update` on every real prefix. Prefix
+  update failure is fatal and must remain retryable in the migration wizard.
+  Cleanup owns only `runtime/`, transient installer progress files, and the
+  cache `downloads/`, `updates/`, `updater-tools/`, and `tmp/` subdirectories;
+  it must not delete configs, cover/API metadata, logs, or shader caches.
+- The custom i386 provider contract is exact: System32 contains `xtajit.dll`
+  and must not contain `wow64cpu.dll` or `xtajit-*-candidate.dll`; the default
+  value of `HKLM\\Software\\Microsoft\\Wow64\\x86` must be `xtajit.dll`.
+  Wineboot can reselect `wow64cpu.dll` when that competing file is staged, so
+  migration removes conflicts and explicitly restores the registry value.
+- Live migration validation used the installed 0.57 Steam prefix at
+  `~/.metalsharp/prefix-steam`, with the immutable safety copy at
+  `/Volumes/AverySSD/MetalSharp-0.57-Live-Safety-2026-07-31`. Migration passed
+  8/8, preserved Steam's executable at SHA-256
+  `eb823470675e0a8f8b91c4f4f1e4bb6148e72b606a518f250a10c598bb1705b8`,
+  and passed ARM64, ARM64EC, x86_64, and i386 execution in that same prefix.
+  Architecture probes must use `apply_complete_runtime_env` equivalence,
+  including the runtime fallback library path and all FEX TSO modes disabled;
+  omitting that environment is not a valid i386 result.
+
 ## What This Project Is
 
 MetalSharp is a macOS app that runs Windows Steam games and Windows programs via Wine + Metal translation. It's an Electron app with a Rust HTTP backend, a C++ native D3D/Metal engine, per-game engine routing, runtime bottles, installer profiles, and Linux `.deb` packaging.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2245bc7f3..1cbe42e31 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.24)
-project(metalsharp VERSION 0.57.0 LANGUAGES C CXX OBJC OBJCXX)
+project(metalsharp VERSION 0.60.0 LANGUAGES C CXX OBJC OBJCXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
diff --git a/app/package-lock.json b/app/package-lock.json
index 31f680b38..9546759cd 100644
--- a/app/package-lock.json
+++ b/app/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "metalsharp",
-  "version": "0.57.0",
+  "version": "0.60.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "metalsharp",
-      "version": "0.57.0",
+      "version": "0.60.0",
       "dependencies": {
         "electron-store": "^10.0.0"
       },
diff --git a/app/package.json b/app/package.json
index 3cfcefa26..9e7fb1403 100644
--- a/app/package.json
+++ b/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "metalsharp",
-  "version": "0.57.0",
+  "version": "0.60.0",
   "description": "MetalSharp — D3D→Metal translation layer frontend",
   "author": "MetalSharp",
   "repository": {
diff --git a/app/src-rust/Cargo.lock b/app/src-rust/Cargo.lock
index b0969dfcd..599e9b239 100644
--- a/app/src-rust/Cargo.lock
+++ b/app/src-rust/Cargo.lock
@@ -554,7 +554,7 @@ checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
 
 [[package]]
 name = "metalsharp-backend"
-version = "0.57.0"
+version = "0.60.0"
 dependencies = [
  "ctrlc",
  "dirs",
diff --git a/app/src-rust/Cargo.toml b/app/src-rust/Cargo.toml
index c24c94c3b..fcb275516 100644
--- a/app/src-rust/Cargo.toml
+++ b/app/src-rust/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "metalsharp-backend"
-version = "0.57.0"
+version = "0.60.0"
 edition = "2021"
 
 [dependencies]
diff --git a/app/src-rust/src/installer.rs b/app/src-rust/src/installer.rs
index e46089ba1..4c3ee0fcd 100644
--- a/app/src-rust/src/installer.rs
+++ b/app/src-rust/src/installer.rs
@@ -33,7 +33,7 @@ const SCRIPTS_TOOLS_BUNDLE: &str = "metalsharp-scripts-tools";
 const STEAM_BUNDLE: &str = "metalsharp-steam";
 const COMPLETE_RUNTIME_INSTALLER: &str = "install-metalsharp-wine-runtime.sh";
 pub(crate) const COMPLETE_RUNTIME_ARCHIVE_SHA256: &str =
-    "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee";
+    "e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146";
 pub(crate) const GOG_SUPPORT_ARCHIVE_SHA256: &str = "f13075f27d5155e84199619410936931b32310c4ec4161de992c1f727ac24155";
 const METALSHARP_NTDLL_HOOK_DLL: &str = "metalsharp_ntdll_hook.dll";
 const DXMT_REQUIRED_PE: &[&str] = &[
diff --git a/app/src-rust/src/migrate.rs b/app/src-rust/src/migrate.rs
index d074027e2..bb6a794f1 100644
--- a/app/src-rust/src/migrate.rs
+++ b/app/src-rust/src/migrate.rs
@@ -325,12 +325,16 @@ pub fn needs_migration() -> serde_json::Value {
 fn runtime_needs_repair(home: &Path, setup_completed: bool) -> bool {
     let ms_dir = crate::platform::metalsharp_home_dir_for(&home);
     if runtime_core_ready(&ms_dir) {
-        return false;
+        return existing_prefixes_need_repair(&ms_dir);
     }
 
     setup_completed || ms_dir.join("prefix-steam").exists()
 }
 
+fn existing_prefixes_need_repair(ms_dir: &Path) -> bool {
+    collect_existing_wine_prefixes(ms_dir).iter().any(|prefix| !crate::runtime_prefix::all_arch_ready(prefix))
+}
+
 fn post_update_marker_path(ms_dir: &Path) -> PathBuf {
     ms_dir.join(".post-update-migration")
 }
@@ -440,7 +444,8 @@ fn run_migration() {
     }
 
     let marker_requested = post_update_marker.as_ref().map(|marker| marker.needed).unwrap_or(false);
-    if runtime_core_ready(&ms_dir) && !marker_requested {
+    let runtime_was_ready = runtime_core_ready(&ms_dir);
+    if runtime_was_ready && !existing_prefixes_need_repair(&ms_dir) && !marker_requested {
         update_migration_metadata(&ms_dir);
         let marker = post_update_marker_path(&ms_dir);
         let _ = fs::remove_file(&marker);
@@ -471,40 +476,66 @@ fn run_migration() {
     let (preserved, mut report) = preserve_user_data(&ms_dir);
 
     step += 1;
-    write_migrate_progress("running", step, total_steps, "Cleaning stale runtime state...", None);
-    remove_old_runtime(&ms_dir);
+    if runtime_was_ready {
+        write_migrate_progress(
+            "running",
+            step,
+            total_steps,
+            "Complete runtime already installed; keeping it in place...",
+            None,
+        );
+    } else {
+        write_migrate_progress("running", step, total_steps, "Cleaning stale runtime state...", None);
+        remove_old_runtime(&ms_dir);
+    }
 
     step += 1;
-    write_migrate_progress("running", step, total_steps, "Installing update...", None);
-    let install_ok = match crate::installer::start_install_all() {
-        Ok(v) if v.get("ok").and_then(|ok| ok.as_bool()).unwrap_or(false) => match wait_for_install_complete() {
-            Ok(()) => true,
+    write_migrate_progress(
+        "running",
+        step,
+        total_steps,
+        if runtime_was_ready { "Using the verified complete runtime..." } else { "Installing update..." },
+        None,
+    );
+    let install_ok = if runtime_was_ready {
+        true
+    } else {
+        match crate::installer::start_install_all() {
+            Ok(v) if v.get("ok").and_then(|ok| ok.as_bool()).unwrap_or(false) => match wait_for_install_complete() {
+                Ok(()) => true,
+                Err(e) => {
+                    write_migrate_progress(
+                        "error",
+                        step,
+                        total_steps,
+                        &format!("Runtime install failed: {}", e),
+                        Some(&e),
+                    );
+                    false
+                },
+            },
+            Ok(v) => {
+                let error = v.get("error").and_then(|e| e.as_str()).unwrap_or("runtime install did not start");
+                write_migrate_progress(
+                    "error",
+                    step,
+                    total_steps,
+                    &format!("Runtime install failed: {}", error),
+                    Some(error),
+                );
+                false
+            },
             Err(e) => {
-                write_migrate_progress("error", step, total_steps, &format!("Runtime install failed: {}", e), Some(&e));
+                write_migrate_progress(
+                    "error",
+                    step,
+                    total_steps,
+                    &format!("Runtime install failed: {}", e),
+                    Some(&e.to_string()),
+                );
                 false
             },
-        },
-        Ok(v) => {
-            let error = v.get("error").and_then(|e| e.as_str()).unwrap_or("runtime install did not start");
-            write_migrate_progress(
-                "error",
-                step,
-                total_steps,
-                &format!("Runtime install failed: {}", error),
-                Some(error),
-            );
-            false
-        },
-        Err(e) => {
-            write_migrate_progress(
-                "error",
-                step,
-                total_steps,
-                &format!("Runtime install failed: {}", e),
-                Some(&e.to_string()),
-            );
-            false
-        },
+        }
     };
 
     step += 1;
@@ -533,8 +564,21 @@ fn run_migration() {
         None,
     );
     match update_existing_wine_prefixes(&ms_dir, step) {
-        Ok(updated) => log_to_file(&format!("Migration: wineboot -u completed for {} prefix(es)", updated)),
-        Err(e) => log_to_file(&format!("Migration: wineboot -u failed (non-fatal): {}", e)),
+        Ok(updated) => log_to_file(&format!(
+            "Migration: all-architecture provider staging and wineboot update completed for {} prefix(es)",
+            updated
+        )),
+        Err(error) => {
+            write_migrate_progress(
+                "error",
+                step,
+                total_steps,
+                &format!("Wine prefix update failed: {error}"),
+                Some(&error),
+            );
+            log_to_file(&format!("Migration blocked by Wine prefix acceptance failure: {error}"));
+            return;
+        },
     }
     register_external_steam_libraries(&ms_dir);
     clear_steam_crash_marker(&ms_dir);
@@ -564,10 +608,10 @@ fn run_migration() {
     let _ = fs::remove_file(&marker);
     let _ = fs::remove_file(migration_steam_config_backup_path(&ms_dir));
 
-    // wineboot -u can fork Steam.exe twice for self-update. Let those updater
-    // windows finish naturally so the next app launch is not left with a
-    // half-completed Steam update.
-    wait_for_steam_update_windows_after_migration(&ms_dir, 15);
+    // Prefix migration uses wineboot's combined init+update contract, which
+    // deliberately suppresses HKCU Run entries. Steam remains installed but
+    // is not launched or updated behind the user's back during migration.
+    log_to_file("Migration: Wine prefix update completed without launching user startup applications");
 
     write_migrate_progress("complete", total_steps, total_steps, "MetalSharp is updated and ready.", None);
     log_to_file(&format!("Migration to v{} finished (install_ok=true)", MIGRATE_VERSION));
@@ -959,20 +1003,9 @@ fn preserve_user_data(ms_dir: &PathBuf) -> (PreservedData, MigrationReport) {
 }
 
 fn update_existing_wine_prefixes(ms_dir: &Path, step: usize) -> Result<usize, String> {
-    let runtime_wine = ms_dir.join("runtime").join("wine");
-    let wine = crate::platform::runtime_wine_binary(&runtime_wine);
-    if !wine.exists() {
-        return Err(format!("MetalSharp Wine not found at {}", wine.display()));
-    }
-
     let mut updated = 0usize;
+    let mut failures = Vec::new();
     for prefix in collect_existing_wine_prefixes(ms_dir) {
-        let steam_library_drive_links = collect_steam_library_drive_links(&prefix);
-        // Snapshot all dosdevice symlinks before wineboot rewrites them.
-        // This covers custom drive mappings (external drives, Z:, etc.) that
-        // wineboot -u may destroy.
-        let all_dosdevice_links = collect_prefix_dosdevice_links(&prefix);
-
         write_migrate_progress(
             "running",
             step,
@@ -991,29 +1024,63 @@ fn update_existing_wine_prefixes(ms_dir: &Path, step: usize) -> Result<usize, St
             continue;
         }
 
-        run_wineboot_update(&wine, &runtime_wine, &prefix)?;
+        if let Err(error) = prune_stale_installer_dosdevices(&prefix) {
+            failures.push(format!("{}: {error}", prefix.display()));
+            continue;
+        }
+
+        let steam_library_drive_links = collect_steam_library_drive_links(&prefix);
+        // Snapshot the surviving dosdevice symlinks only after stale installer
+        // media and its raw-device companion have been pruned. This covers
+        // custom drive mappings that wineboot may rewrite without resurrecting
+        // the 0.57 DMG mapping afterward.
+        let all_dosdevice_links = collect_prefix_dosdevice_links(&prefix);
+
+        if let Err(error) = crate::runtime_prefix::update_existing(&prefix) {
+            failures.push(format!("{}: {error}", prefix.display()));
+            continue;
+        }
 
         restore_steam_library_drive_links(&prefix, &steam_library_drive_links);
         restore_prefix_dosdevice_links(&prefix, &all_dosdevice_links);
 
+        // wineboot re-enumerates currently mounted DMGs and can recreate the
+        // old installer drive even after the pre-update cleanup. Remove that
+        // pair once more after Wine has finished, while leaving user volume
+        // mappings intact.
+        if let Err(error) = prune_stale_installer_dosdevices(&prefix) {
+            failures.push(format!("{}: {error}", prefix.display()));
+            continue;
+        }
+
         // Post-check: verify critical dosdevice links survived wineboot.
         verify_prefix_dosdevices_integrity(&prefix);
 
         updated += 1;
     }
 
-    Ok(updated)
+    if failures.is_empty() {
+        Ok(updated)
+    } else {
+        Err(failures.join("; "))
+    }
 }
 
 fn collect_existing_wine_prefixes(ms_dir: &Path) -> Vec<PathBuf> {
     let mut prefixes = Vec::new();
     push_existing_prefix(&mut prefixes, ms_dir.join("prefix-steam"));
-    push_existing_prefix(&mut prefixes, gog_bottle_prefix_path(ms_dir));
+    push_existing_prefix(&mut prefixes, ms_dir.join("sharp-prefix"));
+    let bottles = ms_dir.join("bottles");
+    if let Ok(entries) = fs::read_dir(&bottles) {
+        for entry in entries.flatten() {
+            push_existing_prefix(&mut prefixes, entry.path().join("prefix"));
+        }
+    }
     prefixes
 }
 
 fn push_existing_prefix(prefixes: &mut Vec<PathBuf>, prefix: PathBuf) {
-    if !prefix.exists() {
+    if !prefix.join("drive_c").is_dir() {
         return;
     }
     if prefixes.iter().any(|existing| existing == &prefix) {
@@ -1169,52 +1236,6 @@ fn restore_gog_bottle_prefix(bottles_tmp: &Path, bottles: &Path, report: &mut Mi
     );
 }
 
-fn run_wineboot_update(wine: &Path, runtime_wine: &Path, prefix: &Path) -> Result<(), String> {
-    let mut cmd = Command::new(wine);
-    cmd.env("WINEPREFIX", prefix.to_string_lossy().to_string())
-        .env("WINEDEBUG", "-all")
-        .env("WINEDEBUGGER", "/usr/bin/true")
-        .env("WINEDLLOVERRIDES", "winedbg=d")
-        .arg("wineboot")
-        .arg("-u")
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null());
-    crate::platform::set_runtime_library_env(&mut cmd, runtime_wine);
-
-    log_to_file(&format!("Starting wineboot -u for prefix: {}", prefix.display()));
-
-    let mut child = cmd.spawn().map_err(|e| {
-        log_to_file(&format!("Failed to spawn wineboot for {}: {}", prefix.display(), e));
-        format!("spawn wineboot for {}: {}", prefix.display(), e)
-    })?;
-
-    for attempt in 0..240 {
-        if let Some(status) = child.try_wait().map_err(|e| {
-            log_to_file(&format!("Failed to wait for wineboot for {}: {}", prefix.display(), e));
-            format!("wait wineboot for {}: {}", prefix.display(), e)
-        })? {
-            if status.success() {
-                log_to_file(&format!("wineboot -u completed successfully for prefix: {}", prefix.display()));
-                return Ok(());
-            }
-            let error_msg = format!("wineboot -u failed for {} with exit code: {:?}", prefix.display(), status.code());
-            log_to_file(&error_msg);
-            return Err(error_msg);
-        }
-        std::thread::sleep(std::time::Duration::from_millis(500));
-
-        if attempt == 120 {
-            log_to_file(&format!("wineboot -u still running after 60 seconds for prefix: {}", prefix.display()));
-        }
-    }
-
-    let error_msg = format!("wineboot -u timed out (120 seconds) for {}", prefix.display());
-    log_to_file(&error_msg);
-    let _ = child.kill();
-    let _ = child.wait();
-    Err(error_msg)
-}
-
 #[derive(Clone, Debug, PartialEq, Eq)]
 struct SteamLibraryDriveLink {
     drive: char,
@@ -1460,6 +1481,51 @@ fn is_dmg_mount_target(target: &Path) -> bool {
     lower.contains("-arm64") || lower.contains("-x86_64") || lower.contains(".dmg") || lower.contains("-intel")
 }
 
+fn prune_stale_installer_dosdevices(prefix: &Path) -> Result<usize, String> {
+    let dosdevices = prefix.join("dosdevices");
+    if !dosdevices.is_dir() {
+        return Ok(0);
+    }
+
+    let mut stale_names = Vec::new();
+    for entry in fs::read_dir(&dosdevices)
+        .map_err(|error| format!("failed to enumerate {}: {error}", dosdevices.display()))?
+        .flatten()
+    {
+        let Some(name) = entry.file_name().to_str().map(str::to_owned) else {
+            continue;
+        };
+        let Ok(target) = fs::read_link(entry.path()) else {
+            continue;
+        };
+        if is_dmg_mount_target(&target) {
+            stale_names.push(name.clone());
+            if name.ends_with(':') && !name.ends_with("::") {
+                stale_names.push(format!("{name}:"));
+            }
+        }
+    }
+
+    stale_names.sort();
+    stale_names.dedup();
+    let mut removed = 0;
+    for name in stale_names {
+        let path = dosdevices.join(&name);
+        match fs::symlink_metadata(&path) {
+            Ok(metadata) if metadata.file_type().is_symlink() || metadata.is_file() => {
+                fs::remove_file(&path)
+                    .map_err(|error| format!("failed to remove stale {}: {error}", path.display()))?;
+                removed += 1;
+                log_to_file(&format!("Migration: removed stale installer dosdevice {}", path.display()));
+            },
+            Ok(_) => return Err(format!("stale installer dosdevice is not a removable link: {}", path.display())),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {},
+            Err(error) => return Err(format!("failed to inspect stale {}: {error}", path.display())),
+        }
+    }
+    Ok(removed)
+}
+
 fn collect_prefix_dosdevice_links(prefix: &Path) -> Vec<(String, PathBuf)> {
     let dosdevices = prefix.join("dosdevices");
     if !dosdevices.is_dir() {
@@ -2050,17 +2116,7 @@ fn ensure_z_drive(dosdevices: &Path) {
 }
 
 fn remove_old_runtime(ms_dir: &PathBuf) {
-    let dirs_to_remove = [
-        "runtime",
-        "configs",
-        "cache",
-        "logs",
-        "shader-cache",
-        "crashes",
-        "SteamSetup.exe",
-        "install_progress.json",
-        "update_progress.json",
-    ];
+    let dirs_to_remove = ["runtime", "SteamSetup.exe", "install_progress.json", "update_progress.json"];
 
     for name in &dirs_to_remove {
         let p = ms_dir.join(name);
@@ -2073,11 +2129,19 @@ fn remove_old_runtime(ms_dir: &PathBuf) {
         }
     }
 
+    // Keep user-facing cache metadata (covers, API configuration), logs, and
+    // compiled shader caches. Only installer/download scratch payloads are
+    // runtime-owned and safe to discard during replacement.
+    for name in ["downloads", "updates", "updater-tools", "tmp"] {
+        let scratch = ms_dir.join("cache").join(name);
+        if fs::symlink_metadata(&scratch).map(|metadata| metadata.is_dir()).unwrap_or(false) {
+            let _ = fs::remove_dir_all(&scratch);
+        } else if fs::symlink_metadata(&scratch).map(|metadata| metadata.is_file()).unwrap_or(false) {
+            let _ = fs::remove_file(&scratch);
+        }
+    }
+
     let _ = fs::create_dir_all(ms_dir.join("runtime"));
-    let _ = fs::create_dir_all(ms_dir.join("configs"));
-    let _ = fs::create_dir_all(ms_dir.join("cache"));
-    let _ = fs::create_dir_all(ms_dir.join("logs"));
-    let _ = fs::create_dir_all(ms_dir.join("shader-cache"));
 }
 
 fn restore_user_data(ms_dir: &PathBuf, preserved: &PreservedData, report: &mut MigrationReport) {
@@ -2365,6 +2429,27 @@ fn unix_days_to_ymd(days_since_epoch: u64) -> (i64, u32, u32) {
 mod tests {
     use super::*;
 
+    #[test]
+    fn migration_removes_only_stale_installer_drive_pair() {
+        let prefix = test_dir("stale-installer-dosdevices");
+        let dosdevices = prefix.join("dosdevices");
+        fs::create_dir_all(&dosdevices).expect("create dosdevices fixture");
+        std::os::unix::fs::symlink("../drive_c", dosdevices.join("c:")).expect("create C fixture");
+        std::os::unix::fs::symlink("/Volumes/MetalSharp 0.57.0-arm64 1", dosdevices.join("d:"))
+            .expect("create stale installer fixture");
+        std::os::unix::fs::symlink("/dev/rdisk8s1", dosdevices.join("d::")).expect("create raw device fixture");
+        std::os::unix::fs::symlink("/Volumes/Games", dosdevices.join("e:")).expect("create user drive fixture");
+
+        assert_eq!(prune_stale_installer_dosdevices(&prefix).expect("prune stale installer mappings"), 2);
+        assert!(fs::symlink_metadata(dosdevices.join("d:")).is_err());
+        assert!(fs::symlink_metadata(dosdevices.join("d::")).is_err());
+        assert_eq!(fs::read_link(dosdevices.join("c:")).expect("preserve C mapping"), Path::new("../drive_c"));
+        assert_eq!(fs::read_link(dosdevices.join("e:")).expect("preserve user mapping"), Path::new("/Volumes/Games"));
+        assert_eq!(collect_prefix_dosdevice_links(&prefix), vec![("e:".to_string(), PathBuf::from("/Volumes/Games"))]);
+
+        let _ = fs::remove_dir_all(prefix);
+    }
+
     #[test]
     fn cleanup_preserved_temp_dirs_removes_only_real_matching_directories() {
         let temp_root = test_dir("cleanup-preserved-temp");
@@ -2562,8 +2647,10 @@ mod tests {
         let steam_prefix = ms_dir.join("prefix-steam");
         let bottle_dir = ms_dir.join("bottles").join("installer_demo");
         let bottle_prefix = bottle_dir.join("prefix");
-        fs::create_dir_all(&steam_prefix).expect("create Steam prefix");
-        fs::create_dir_all(&bottle_prefix).expect("create bottle prefix");
+        let sharp_prefix = ms_dir.join("sharp-prefix");
+        fs::create_dir_all(steam_prefix.join("drive_c")).expect("create Steam prefix");
+        fs::create_dir_all(bottle_prefix.join("drive_c")).expect("create bottle prefix");
+        fs::create_dir_all(sharp_prefix.join("drive_c")).expect("create Sharp prefix");
         fs::write(
             bottle_dir.join("bottle.json"),
             serde_json::to_vec(&json!({
@@ -2577,8 +2664,9 @@ mod tests {
         let prefixes = collect_existing_wine_prefixes(&ms_dir);
 
         assert!(prefixes.contains(&steam_prefix));
-        assert!(!prefixes.contains(&bottle_prefix));
-        assert_eq!(prefixes.len(), 1);
+        assert!(prefixes.contains(&bottle_prefix));
+        assert!(prefixes.contains(&sharp_prefix));
+        assert_eq!(prefixes.len(), 3);
         let _ = fs::remove_dir_all(home);
     }
 
@@ -2588,12 +2676,12 @@ mod tests {
         let ms_dir = crate::platform::metalsharp_home_dir_for(&home);
         let steam_prefix = ms_dir.join("prefix-steam");
         let gog_prefix = ms_dir.join("bottles").join(GOG_PREFIX_BOTTLE_ID).join("prefix");
-        fs::create_dir_all(&steam_prefix).expect("create Steam prefix");
+        fs::create_dir_all(steam_prefix.join("drive_c")).expect("create Steam prefix");
 
         let prefixes_without_gog = collect_existing_wine_prefixes(&ms_dir);
         assert_eq!(prefixes_without_gog, vec![steam_prefix.clone()]);
 
-        fs::create_dir_all(&gog_prefix).expect("create GOG prefix");
+        fs::create_dir_all(gog_prefix.join("drive_c")).expect("create GOG prefix");
         let prefixes_with_gog = collect_existing_wine_prefixes(&ms_dir);
         assert!(prefixes_with_gog.contains(&steam_prefix));
         assert!(prefixes_with_gog.contains(&gog_prefix));
@@ -2921,10 +3009,15 @@ mod tests {
         let ms_dir = crate::platform::metalsharp_home_dir_for(&home);
         fs::create_dir_all(ms_dir.join("cache").join("covers")).expect("create cache metadata dir");
         fs::create_dir_all(ms_dir.join("cache").join("updates")).expect("create update cache dir");
+        fs::create_dir_all(ms_dir.join("configs")).expect("create settings dir");
+        fs::create_dir_all(ms_dir.join("shader-cache")).expect("create shader cache dir");
         fs::write(ms_dir.join("cache").join("steam_config.json"), br#"{"api_key_set":true}"#)
             .expect("write steam config");
         fs::write(ms_dir.join("cache").join("covers").join("620.png"), b"cover").expect("write cover");
         fs::write(ms_dir.join("cache").join("updates").join("MetalSharp.dmg"), b"dmg").expect("write cached dmg");
+        fs::write(ms_dir.join("configs").join("user.json"), b"settings").expect("write settings fixture");
+        fs::write(ms_dir.join("shader-cache").join("pipeline.bin"), b"shader cache")
+            .expect("write shader cache fixture");
 
         let (preserved, mut report) = preserve_user_data(&ms_dir);
         remove_old_runtime(&ms_dir);
@@ -2934,8 +3027,10 @@ mod tests {
             fs::read_to_string(ms_dir.join("cache").join("steam_config.json")).unwrap(),
             r#"{"api_key_set":true}"#
         );
-        assert!(!ms_dir.join("cache").join("covers").join("620.png").exists());
+        assert!(ms_dir.join("cache").join("covers").join("620.png").exists());
         assert!(!ms_dir.join("cache").join("updates").join("MetalSharp.dmg").exists());
+        assert_eq!(fs::read(ms_dir.join("configs").join("user.json")).unwrap(), b"settings");
+        assert_eq!(fs::read(ms_dir.join("shader-cache").join("pipeline.bin")).unwrap(), b"shader cache");
         let _ = fs::remove_dir_all(home);
     }
 
diff --git a/app/src-rust/src/runtime_prefix.rs b/app/src-rust/src/runtime_prefix.rs
index d5a273e11..e60a14813 100644
--- a/app/src-rust/src/runtime_prefix.rs
+++ b/app/src-rust/src/runtime_prefix.rs
@@ -36,39 +36,97 @@ fn copy_file_required(source: &Path, destination: &Path, label: &str) -> Result<
     Ok(())
 }
 
-fn stage_i386_builtins(build: &Path, prefix: &Path) -> Result<usize, String> {
-    let dll_root = build.join("dlls");
-    let syswow64 = prefix.join("drive_c/windows/syswow64");
-    std::fs::create_dir_all(&syswow64).map_err(|error| format!("failed to create {}: {error}", syswow64.display()))?;
+fn stage_pe_lane(build: &Path, lane_name: &str, destination: &Path) -> Result<usize, String> {
+    std::fs::create_dir_all(destination)
+        .map_err(|error| format!("failed to create {}: {error}", destination.display()))?;
     let mut staged = 0usize;
 
-    let components =
-        std::fs::read_dir(&dll_root).map_err(|error| format!("failed to enumerate {}: {error}", dll_root.display()))?;
-    for component in components {
-        let component = component.map_err(|error| format!("failed to read Wine DLL entry: {error}"))?;
-        let lane = component.path().join("i386-windows");
-        if !lane.is_dir() {
-            continue;
-        }
-        let entries =
-            std::fs::read_dir(&lane).map_err(|error| format!("failed to enumerate {}: {error}", lane.display()))?;
-        for entry in entries {
-            let entry = entry.map_err(|error| format!("failed to read i386 Wine DLL entry: {error}"))?;
-            let path = entry.path();
-            if path.extension().and_then(|ext| ext.to_str()).is_some_and(|ext| ext.eq_ignore_ascii_case("dll")) {
-                std::fs::copy(&path, syswow64.join(entry.file_name()))
-                    .map_err(|error| format!("failed to stage {}: {error}", path.display()))?;
-                staged += 1;
+    for (root_name, extension) in [("dlls", "dll"), ("programs", "exe")] {
+        let root = build.join(root_name);
+        let components =
+            std::fs::read_dir(&root).map_err(|error| format!("failed to enumerate {}: {error}", root.display()))?;
+        for component in components {
+            let component = component.map_err(|error| format!("failed to read Wine PE entry: {error}"))?;
+            let lane = component.path().join(lane_name);
+            if !lane.is_dir() {
+                continue;
+            }
+            let entries =
+                std::fs::read_dir(&lane).map_err(|error| format!("failed to enumerate {}: {error}", lane.display()))?;
+            for entry in entries {
+                let entry = entry.map_err(|error| format!("failed to read Wine PE lane entry: {error}"))?;
+                let path = entry.path();
+                if path.extension().and_then(|ext| ext.to_str()).is_some_and(|ext| ext.eq_ignore_ascii_case(extension))
+                    && should_stage_pe_entry(lane_name, &entry.file_name())
+                {
+                    std::fs::copy(&path, destination.join(entry.file_name()))
+                        .map_err(|error| format!("failed to stage {}: {error}", path.display()))?;
+                    staged += 1;
+                }
             }
         }
     }
 
     if staged == 0 {
-        return Err("complete runtime contains no i386 Wine builtins to stage into the prefix".to_string());
+        return Err(format!("complete runtime contains no {lane_name} Wine PE files to stage"));
     }
     Ok(staged)
 }
 
+fn should_stage_pe_entry(lane_name: &str, name: &std::ffi::OsStr) -> bool {
+    let name = name.to_string_lossy();
+    if lane_name != "aarch64-windows" {
+        return true;
+    }
+
+    // The custom ARM64 host uses xtajit.dll for i386. Wine's generic
+    // wow64cpu.dll is a competing provider; if it is present while wineboot
+    // refreshes the prefix, the x86 provider registry value can be rewritten
+    // to wow64cpu.dll and every i386 process fails before reaching its entry
+    // point. Candidate binaries are retained in the source/runtime tree for
+    // development, but are never promoted into a user's System32 directory.
+    let lowercase = name.to_ascii_lowercase();
+    !(name.eq_ignore_ascii_case("wow64cpu.dll")
+        || lowercase.starts_with("xtajit-") && lowercase.ends_with("-candidate.dll"))
+}
+
+fn stage_i386_builtins(build: &Path, prefix: &Path) -> Result<usize, String> {
+    stage_pe_lane(build, "i386-windows", &prefix.join("drive_c/windows/syswow64"))
+}
+
+fn stage_aarch64_builtins(build: &Path, prefix: &Path) -> Result<usize, String> {
+    stage_pe_lane(build, "aarch64-windows", &prefix.join("drive_c/windows/system32"))
+}
+
+fn ensure_unix_root_dosdevice(prefix: &Path) -> Result<(), String> {
+    let dosdevices = prefix.join("dosdevices");
+    std::fs::create_dir_all(&dosdevices)
+        .map_err(|error| format!("failed to create {}: {error}", dosdevices.display()))?;
+    let z_drive = dosdevices.join("z:");
+
+    if std::fs::read_link(&z_drive).ok().as_deref() == Some(Path::new("/")) {
+        return Ok(());
+    }
+
+    match std::fs::symlink_metadata(&z_drive) {
+        Ok(metadata) if metadata.file_type().is_symlink() || metadata.is_file() => std::fs::remove_file(&z_drive)
+            .map_err(|error| format!("failed to replace stale {}: {error}", z_drive.display()))?,
+        Ok(metadata) if metadata.is_dir() => {
+            return Err(format!(
+                "cannot create the required Wine Z: mapping because {} is a directory",
+                z_drive.display()
+            ));
+        },
+        Ok(_) => std::fs::remove_file(&z_drive)
+            .map_err(|error| format!("failed to replace stale {}: {error}", z_drive.display()))?,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {},
+        Err(error) => return Err(format!("failed to inspect {}: {error}", z_drive.display())),
+    }
+
+    std::os::unix::fs::symlink("/", &z_drive)
+        .map_err(|error| format!("failed to create required Wine Z: mapping at {}: {error}", z_drive.display()))
+}
+
 fn run_runtime_provider_stage(prefix: &Path, verify_only: bool) -> Result<(), String> {
     let root = runtime_root();
     let script = root.join("scripts/stage-runtime-providers.sh");
@@ -102,7 +160,7 @@ fn run_runtime_provider_stage(prefix: &Path, verify_only: bool) -> Result<(), St
 }
 
 pub(crate) fn all_arch_ready(prefix: &Path) -> bool {
-    [
+    let required_files_ready = [
         "system.reg",
         "user.reg",
         "drive_c/windows/system32/kernel32.dll",
@@ -116,10 +174,126 @@ pub(crate) fn all_arch_ready(prefix: &Path) -> bool {
         ".vkmt/gstreamer-runtime.sha256",
     ]
     .iter()
-    .all(|relative| prefix.join(relative).is_file())
+    .all(|relative| prefix.join(relative).is_file());
+    required_files_ready
+        && std::fs::read_link(prefix.join("dosdevices/z:")).ok().as_deref() == Some(Path::new("/"))
+        && wow64_x86_provider_ready(prefix)
+        && !prefix.join("drive_c/windows/system32/wow64cpu.dll").exists()
+        && [
+            "drive_c/windows/system32/kernel32.dll",
+            "drive_c/windows/system32/ntdll.dll",
+            "drive_c/windows/system32/wow64.dll",
+            "drive_c/windows/system32/wow64win.dll",
+        ]
+        .iter()
+        .all(|relative| pe_machine(&prefix.join(relative)) == Some(0xaa64))
+        && ["drive_c/windows/syswow64/kernel32.dll", "drive_c/windows/syswow64/ntdll.dll"]
+            .iter()
+            .all(|relative| pe_machine(&prefix.join(relative)) == Some(0x014c))
+}
+
+fn wow64_x86_provider_ready(prefix: &Path) -> bool {
+    let Ok(registry) = std::fs::read_to_string(prefix.join("system.reg")) else {
+        return false;
+    };
+    let section = "[Software\\\\Microsoft\\\\Wow64\\\\x86]";
+    let Some(section_start) = registry.find(section) else {
+        return false;
+    };
+    registry[section_start + section.len()..]
+        .lines()
+        .take_while(|line| !line.starts_with('['))
+        .any(|line| line.trim().eq_ignore_ascii_case("@=\"xtajit.dll\""))
+}
+
+fn remove_conflicting_cpu_providers(prefix: &Path) -> Result<(), String> {
+    let system32 = prefix.join("drive_c/windows/system32");
+    let entries =
+        std::fs::read_dir(&system32).map_err(|error| format!("failed to enumerate {}: {error}", system32.display()))?;
+    for entry in entries {
+        let entry = entry.map_err(|error| format!("failed to inspect System32 provider entry: {error}"))?;
+        let name = entry.file_name();
+        if !should_stage_pe_entry("aarch64-windows", &name) {
+            let path = entry.path();
+            std::fs::remove_file(&path)
+                .map_err(|error| format!("failed to remove conflicting CPU provider {}: {error}", path.display()))?;
+        }
+    }
+    Ok(())
+}
+
+fn configure_wow64_x86_provider(wine: &Path, prefix: &Path) -> Result<(), String> {
+    let reg = prefix.join("drive_c/windows/system32/reg.exe");
+    if !reg.is_file() {
+        return Err(format!("ARM64 registry tool is missing after wineboot: {}", reg.display()));
+    }
+    let mut command = Command::new(wine);
+    command
+        .arg(&reg)
+        .args(["add", r"HKLM\Software\Microsoft\Wow64\x86", "/ve", "/t", "REG_SZ", "/d", "xtajit.dll", "/f"])
+        .env("WINE_NO_EXPLORER", "1")
+        .env("WINEDEBUG", "-all")
+        .env("WINEDEBUGGER", "none")
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+    apply_complete_runtime_env(&mut command, prefix);
+    let status = command.status().map_err(|error| format!("failed to select the i386 xtajit provider: {error}"))?;
+    if !status.success() {
+        return Err(format!("selecting the i386 xtajit provider failed with {status}"));
+    }
+    Ok(())
+}
+
+fn pe_machine(path: &Path) -> Option<u16> {
+    use std::io::{Read, Seek, SeekFrom};
+
+    let mut file = std::fs::File::open(path).ok()?;
+    let mut mz = [0u8; 64];
+    file.read_exact(&mut mz).ok()?;
+    if &mz[..2] != b"MZ" {
+        return None;
+    }
+    let pe_offset = u32::from_le_bytes(mz[0x3c..0x40].try_into().ok()?) as u64;
+    file.seek(SeekFrom::Start(pe_offset)).ok()?;
+    let mut header = [0u8; 6];
+    file.read_exact(&mut header).ok()?;
+    if &header[..4] != b"PE\0\0" {
+        return None;
+    }
+    Some(u16::from_le_bytes([header[4], header[5]]))
 }
 
 pub(crate) fn prepare(prefix: &Path) -> Result<(), String> {
+    prepare_with_mode(prefix, WinebootMode::Initialize)
+}
+
+pub(crate) fn update_existing(prefix: &Path) -> Result<(), String> {
+    if !prefix.join("drive_c").is_dir() {
+        return Err(format!("existing Wine prefix is missing drive_c: {}", prefix.display()));
+    }
+    prepare_with_mode(prefix, WinebootMode::Update)
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum WinebootMode {
+    Initialize,
+    Update,
+}
+
+impl WinebootMode {
+    fn arguments(self) -> &'static [&'static str] {
+        match self {
+            Self::Initialize => &["--init"],
+            // wineboot's update-only path processes HKCU Run and would launch
+            // Steam (or any other user startup application) in the middle of
+            // migration. Combining init and update performs update_wineprefix
+            // while suppressing those user startup entries.
+            Self::Update => &["--init", "--update"],
+        }
+    }
+}
+
+fn prepare_with_mode(prefix: &Path, mode: WinebootMode) -> Result<(), String> {
     let root = runtime_root();
     let build = root.join("wine/build-ec");
     let wine = crate::platform::runtime_wine_binary(&root.join("wine"));
@@ -132,6 +306,13 @@ pub(crate) fn prepare(prefix: &Path) -> Result<(), String> {
     std::fs::create_dir_all(prefix.join("drive_c/windows/syswow64"))
         .map_err(|error| format!("failed to create prefix syswow64: {error}"))?;
 
+    // Wine starts the PE entry point from an absolute Unix path. Its Unix-side
+    // startup conversion requires that path to be reachable through a DOS
+    // drive; without the canonical Z: mapping Wine 11.12 can produce a null NT
+    // image path before wineboot gets control. Migration restores any user's
+    // custom Z: mapping after this update has completed.
+    ensure_unix_root_dosdevice(prefix)?;
+
     copy_file_required(
         &build.join("dlls/wow64/aarch64-windows/wow64.dll"),
         &system32.join("wow64.dll"),
@@ -143,6 +324,9 @@ pub(crate) fn prepare(prefix: &Path) -> Result<(), String> {
         "ARM64 WoW64 windowing provider",
     )?;
     stage_i386_builtins(&build, prefix)?;
+    if mode == WinebootMode::Update {
+        stage_aarch64_builtins(&build, prefix)?;
+    }
     run_runtime_provider_stage(prefix, false)?;
 
     let wineboot = build.join("programs/wineboot/aarch64-windows/wineboot.exe");
@@ -152,13 +336,15 @@ pub(crate) fn prepare(prefix: &Path) -> Result<(), String> {
     let mut wineboot_command = Command::new(&wine);
     wineboot_command
         .arg(&wineboot)
-        .arg("--init")
-        .env("WINEBOOTSTRAPMODE", "1")
+        .args(mode.arguments())
         .env("WINE_NO_EXPLORER", "1")
         .env("WINEDEBUG", "-all")
         .env("WINEDEBUGGER", "none")
         .stdout(Stdio::null())
         .stderr(Stdio::null());
+    if mode == WinebootMode::Initialize {
+        wineboot_command.env("WINEBOOTSTRAPMODE", "1");
+    }
     apply_complete_runtime_env(&mut wineboot_command, prefix);
     let status =
         wineboot_command.status().map_err(|error| format!("failed to run all-architecture wineboot: {error}"))?;
@@ -166,6 +352,9 @@ pub(crate) fn prepare(prefix: &Path) -> Result<(), String> {
         return Err(format!("all-architecture wineboot failed with {status}"));
     }
 
+    remove_conflicting_cpu_providers(prefix)?;
+    configure_wow64_x86_provider(&wine, prefix)?;
+
     let wineserver = crate::platform::runtime_wineserver(&root.join("wine"));
     let wait_status = Command::new(&wineserver)
         .arg("-w")
@@ -201,22 +390,94 @@ mod tests {
         for relative in [
             "system.reg",
             "user.reg",
+            "drive_c/windows/system32/xtajit64.dll",
+            "drive_c/windows/system32/xtajit.dll",
+            ".vkmt/gstreamer-runtime.sha256",
+        ] {
+            let path = prefix.join(relative);
+            std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+            std::fs::write(path, b"fixture").unwrap();
+        }
+        for relative in [
             "drive_c/windows/system32/kernel32.dll",
             "drive_c/windows/system32/ntdll.dll",
             "drive_c/windows/system32/wow64.dll",
             "drive_c/windows/system32/wow64win.dll",
+        ] {
+            write_pe_fixture(&prefix.join(relative), 0xaa64);
+        }
+        for relative in ["drive_c/windows/syswow64/kernel32.dll", "drive_c/windows/syswow64/ntdll.dll"] {
+            write_pe_fixture(&prefix.join(relative), 0x014c);
+        }
+        assert!(!all_arch_ready(&prefix), "a prefix without Wine's Unix-root mapping is not launch-ready");
+        ensure_unix_root_dosdevice(&prefix).expect("create Wine Z mapping fixture");
+        append_xtajit_registry_fixture(&prefix);
+        assert!(all_arch_ready(&prefix));
+
+        std::fs::write(prefix.join("drive_c/windows/system32/wow64cpu.dll"), b"competing provider").unwrap();
+        assert!(!all_arch_ready(&prefix), "generic wow64cpu must not compete with the custom i386 provider");
+        std::fs::remove_file(prefix.join("drive_c/windows/system32/wow64cpu.dll")).unwrap();
+
+        std::fs::write(
+            prefix.join("system.reg"),
+            "WINE REGISTRY Version 2\n\n[Software\\\\Microsoft\\\\Wow64\\\\x86] 1\n@=\"wow64cpu.dll\"\n",
+        )
+        .unwrap();
+        assert!(!all_arch_ready(&prefix), "the i386 registry contract must select xtajit.dll");
+        append_xtajit_registry_fixture(&prefix);
+        assert!(all_arch_ready(&prefix));
+
+        std::fs::remove_file(prefix.join("drive_c/windows/system32/xtajit.dll")).unwrap();
+        assert!(!all_arch_ready(&prefix));
+        let _ = std::fs::remove_dir_all(prefix);
+    }
+
+    fn write_pe_fixture(path: &Path, machine: u16) {
+        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+        let mut bytes = vec![0u8; 0x46];
+        bytes[..2].copy_from_slice(b"MZ");
+        bytes[0x3c..0x40].copy_from_slice(&(0x40u32).to_le_bytes());
+        bytes[0x40..0x44].copy_from_slice(b"PE\0\0");
+        bytes[0x44..0x46].copy_from_slice(&machine.to_le_bytes());
+        std::fs::write(path, bytes).unwrap();
+    }
+
+    fn append_xtajit_registry_fixture(prefix: &Path) {
+        std::fs::write(
+            prefix.join("system.reg"),
+            "WINE REGISTRY Version 2\n\n[Software\\\\Microsoft\\\\Wow64\\\\x86] 1\n@=\"xtajit.dll\"\n",
+        )
+        .unwrap();
+    }
+
+    #[test]
+    fn all_arch_gate_rejects_x86_64_system32_builtins() {
+        let prefix = std::env::temp_dir().join(format!("metalsharp-runtime-prefix-machine-{}", std::process::id()));
+        for relative in [
+            "system.reg",
+            "user.reg",
             "drive_c/windows/system32/xtajit64.dll",
             "drive_c/windows/system32/xtajit.dll",
-            "drive_c/windows/syswow64/kernel32.dll",
-            "drive_c/windows/syswow64/ntdll.dll",
             ".vkmt/gstreamer-runtime.sha256",
         ] {
             let path = prefix.join(relative);
             std::fs::create_dir_all(path.parent().unwrap()).unwrap();
             std::fs::write(path, b"fixture").unwrap();
         }
-        assert!(all_arch_ready(&prefix));
-        std::fs::remove_file(prefix.join("drive_c/windows/system32/xtajit.dll")).unwrap();
+        for relative in [
+            "drive_c/windows/system32/kernel32.dll",
+            "drive_c/windows/system32/ntdll.dll",
+            "drive_c/windows/system32/wow64.dll",
+            "drive_c/windows/system32/wow64win.dll",
+        ] {
+            write_pe_fixture(&prefix.join(relative), 0xaa64);
+        }
+        for relative in ["drive_c/windows/syswow64/kernel32.dll", "drive_c/windows/syswow64/ntdll.dll"] {
+            write_pe_fixture(&prefix.join(relative), 0x014c);
+        }
+        ensure_unix_root_dosdevice(&prefix).expect("create Wine Z mapping fixture");
+        append_xtajit_registry_fixture(&prefix);
+        write_pe_fixture(&prefix.join("drive_c/windows/system32/kernel32.dll"), 0x8664);
         assert!(!all_arch_ready(&prefix));
         let _ = std::fs::remove_dir_all(prefix);
     }
@@ -240,4 +501,38 @@ mod tests {
         assert!(env.contains_key("WINEMSYNC"));
         assert!(env.contains_key("METALSHARP_CONTROLLER_MODE"));
     }
+
+    #[test]
+    fn existing_prefix_updates_use_the_wineboot_update_contract() {
+        assert_eq!(WinebootMode::Initialize.arguments(), &["--init"]);
+        assert_eq!(WinebootMode::Update.arguments(), &["--init", "--update"]);
+    }
+
+    #[test]
+    fn arm64_staging_excludes_competing_and_candidate_cpu_providers() {
+        assert!(!should_stage_pe_entry("aarch64-windows", std::ffi::OsStr::new("wow64cpu.dll")));
+        assert!(!should_stage_pe_entry("aarch64-windows", std::ffi::OsStr::new("xtajit-exception-candidate.dll")));
+        assert!(should_stage_pe_entry("aarch64-windows", std::ffi::OsStr::new("xtajit.dll")));
+        assert!(should_stage_pe_entry("i386-windows", std::ffi::OsStr::new("wow64cpu.dll")));
+    }
+
+    #[test]
+    fn wineboot_prefix_always_has_a_unix_root_mapping() {
+        let prefix = std::env::temp_dir().join(format!(
+            "metalsharp-runtime-prefix-z-drive-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|duration| duration.as_nanos())
+                .unwrap_or_default()
+        ));
+        let dosdevices = prefix.join("dosdevices");
+        std::fs::create_dir_all(&dosdevices).expect("create dosdevices fixture");
+        std::os::unix::fs::symlink("/Volumes/stale", dosdevices.join("z:")).expect("create stale Z fixture");
+
+        ensure_unix_root_dosdevice(&prefix).expect("repair Wine Z mapping");
+        assert_eq!(std::fs::read_link(dosdevices.join("z:")).expect("read Wine Z mapping"), Path::new("/"));
+
+        let _ = std::fs::remove_dir_all(prefix);
+    }
 }
diff --git a/app/src-rust/src/steam.rs b/app/src-rust/src/steam.rs
index 3ffaae01f..3a1bdb55c 100644
--- a/app/src-rust/src/steam.rs
+++ b/app/src-rust/src/steam.rs
@@ -1991,6 +1991,33 @@ mod tests {
             std::fs::create_dir_all(path.parent().expect("fixture parent")).expect("create fixture parent");
             std::fs::write(path, b"fixture").expect("write fixture");
         }
+        let write_pe = |relative: &str, machine: u16| {
+            let mut bytes = vec![0u8; 0x46];
+            bytes[..2].copy_from_slice(b"MZ");
+            bytes[0x3c..0x40].copy_from_slice(&(0x40u32).to_le_bytes());
+            bytes[0x40..0x44].copy_from_slice(b"PE\0\0");
+            bytes[0x44..0x46].copy_from_slice(&machine.to_le_bytes());
+            std::fs::write(prefix.join(relative), bytes).expect("write PE fixture");
+        };
+        for relative in [
+            "drive_c/windows/system32/kernel32.dll",
+            "drive_c/windows/system32/ntdll.dll",
+            "drive_c/windows/system32/wow64.dll",
+            "drive_c/windows/system32/wow64win.dll",
+        ] {
+            write_pe(relative, 0xaa64);
+        }
+        for relative in ["drive_c/windows/syswow64/kernel32.dll", "drive_c/windows/syswow64/ntdll.dll"] {
+            write_pe(relative, 0x014c);
+        }
+        let dosdevices = prefix.join("dosdevices");
+        std::fs::create_dir_all(&dosdevices).expect("create dosdevices fixture");
+        std::os::unix::fs::symlink("/", dosdevices.join("z:")).expect("create Wine Z mapping fixture");
+        std::fs::write(
+            prefix.join("system.reg"),
+            "WINE REGISTRY Version 2\n\n[Software\\\\Microsoft\\\\Wow64\\\\x86] 1\n@=\"xtajit.dll\"\n",
+        )
+        .expect("write i386 provider registry fixture");
 
         assert!(steam_prefix_all_arch_ready(&prefix));
         std::fs::remove_file(prefix.join("drive_c/windows/syswow64/ntdll.dll")).expect("remove i386 fixture");
diff --git a/app/src/renderer/components/MigrationView.vue b/app/src/renderer/components/MigrationView.vue
index fdb65a3c1..ec7757afa 100644
--- a/app/src/renderer/components/MigrationView.vue
+++ b/app/src/renderer/components/MigrationView.vue
@@ -18,10 +18,10 @@ const percent = computed(() => {
 });
 
 const stages = [
-  { name: "[D3D]" },
-  { name: "[DXMT]" },
-  { name: "[x86_64]" },
-  { name: "[Metal]" },
+  { name: "[Data]" },
+  { name: "[Runtime]" },
+  { name: "[Prefixes]" },
+  { name: "[Verify]" },
 ];
 
 const MAX_START_RETRIES = 20;
@@ -100,6 +100,15 @@ function stopPolling() {
   }
 }
 
+async function retryMigration() {
+  error.value = null;
+  complete.value = false;
+  step.value = 0;
+  total.value = 0;
+  message.value = "Retrying migration from the last safe checkpoint...";
+  await startMigration();
+}
+
 async function restartApp() {
   launching.value = true;
   message.value = "Closing old MetalSharp, stopping the backend, and launching the updated app...";
@@ -153,7 +162,8 @@ onUnmounted(() => {
       <button v-if="complete" class="restart-btn" :disabled="launching" @click="restartApp()">
         {{ launching ? "Launching..." : "Launch MetalSharp" }}
       </button>
-      <p v-if="error" class="error-hint">Try restarting the app. If the issue persists, check the logs.</p>
+      <button v-if="error" class="restart-btn" @click="retryMigration()">Retry Migration</button>
+      <p v-if="error" class="error-hint">Your Steam installation and user data remain preserved at the last safe checkpoint.</p>
     </div>
   </div>
 </template>
diff --git a/scripts/install-metalsharp-wine-runtime.sh b/scripts/install-metalsharp-wine-runtime.sh
index 8b09145f9..a61dd0404 100755
--- a/scripts/install-metalsharp-wine-runtime.sh
+++ b/scripts/install-metalsharp-wine-runtime.sh
@@ -5,13 +5,13 @@ set -euo pipefail
 REPO="${METALSHARP_RUNTIME_REPO:-metalsharp/MetalSharp}"
 TAG="${METALSHARP_RUNTIME_TAG:-v0.60.0-dependency-bundles}"
 ARCHIVE_NAME="MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst"
-ARCHIVE_SHA256="93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee"
+ARCHIVE_SHA256="e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146"
 PACKAGE_ROOT="MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31"
 PART_PREFIX="${ARCHIVE_NAME}.part"
-PART01_SHA256="e3ff07bafe27fbf0f4fd7f761e962e7b3203e7e730c82d5d3e26fd5062bb0568"
-PART02_SHA256="5e3c4e96898daa954fbf629819f760aadc3c73481c6200b1ade5e577131aa133"
-PART03_SHA256="cf79389d77f0bd3002894f704948808510860306e0781b556ab91d233290a067"
-PART04_SHA256="cc33cc12386793f47c1bc090f1d55e89c5f6971160ce4c3cbb7372c099b1232b"
+PART01_SHA256="f0eb41df073e6e8baf3a3461cb7b2117a1616b4175e511a710cef27809c8958f"
+PART02_SHA256="d9bba199557e2aec6725ee0f244ad408eaf255fc1ff152f5a45fd6a0b2c1ae7b"
+PART03_SHA256="93e821332d7d0fd89d078179199988f85c5d9e334525f4c438efb342a09395ca"
+PART04_SHA256="6b0deb933155ec046656392a5505173cf8a9edf282f7a3ca8bd156e34fe4908e"
 GOG_ARCHIVE_NAME="MetalSharp-GOG-Support-arm64-1.2.2.tar.zst"
 GOG_ARCHIVE_SHA256="f13075f27d5155e84199619410936931b32310c4ec4161de992c1f727ac24155"
 GOG_PACKAGE_ROOT="MetalSharp-GOG-Support-arm64-1.2.2"
diff --git a/tools/ci/verify-dmg-workflow.py b/tools/ci/verify-dmg-workflow.py
index a3999754c..1d2f0deb1 100755
--- a/tools/ci/verify-dmg-workflow.py
+++ b/tools/ci/verify-dmg-workflow.py
@@ -124,7 +124,7 @@ def check_bundle_scripts() -> None:
     prepare_runtime = read("tools/dmg/prepare-complete-runtime-assets.sh")
     for needle in [
         "v0.60.0-dependency-bundles",
-        "93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee",
+        "e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146",
         "metalsharp-bundle-manifest.tsv",
         "--verify-only",
         "--verify-package",
diff --git a/tools/dmg/prepare-complete-runtime-assets.sh b/tools/dmg/prepare-complete-runtime-assets.sh
index c7327dee4..153357e8d 100755
--- a/tools/dmg/prepare-complete-runtime-assets.sh
+++ b/tools/dmg/prepare-complete-runtime-assets.sh
@@ -7,7 +7,7 @@ DEST_DIR="${METALSHARP_RELEASE_RUNTIME_DIR:-$PROJECT_ROOT/app/release-runtime}"
 REPO="${METALSHARP_RUNTIME_REPO:-metalsharp/MetalSharp}"
 TAG="${METALSHARP_RUNTIME_TAG:-v0.60.0-dependency-bundles}"
 ARCHIVE="MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst"
-ARCHIVE_SHA256="93a456a40a7bf0ad2fecace5c01c58a366f85cc2901f6f8780c056c9e3b256ee"
+ARCHIVE_SHA256="e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146"
 MANIFEST_SHA256="bba8103217dbc72914a8496cb782882af0883fbb18664956ba365dba68fec4eb"
 
 ASSETS=(

From 6b86e606340f43e60d18b2a0abd295abf1930295 Mon Sep 17 00:00:00 2001
From: Avery Felts <averyfelts@Averys-MacBook-Air.local>
Date: Fri, 31 Jul 2026 20:54:53 -0600
Subject: [PATCH 14/14] release: harden complete runtime installer

---
 AGENTS.md                                    | 18 ++++++++++++++
 scripts/install-metalsharp-wine-runtime.sh   | 25 ++++++++++----------
 tools/ci/verify-dmg-workflow.py              | 24 +++++++++++++++++++
 tools/dmg/prepare-complete-runtime-assets.sh |  2 +-
 4 files changed, 56 insertions(+), 13 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 39a7bad1f..74d6f86b6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -177,6 +177,24 @@ Development is isolated on `agent/0.60-preview-release`. The saved phase plan is
   Architecture probes must use `apply_complete_runtime_env` equivalence,
   including the runtime fallback library path and all FEX TSO modes disabled;
   omitting that environment is not a valid i386 result.
+- Final release-path validation used a fresh copy-on-write clone of that
+  immutable 0.57 backup and an empty AverySSD cache. The migration downloaded
+  all four published runtime parts plus GOG support, reassembled and verified
+  the canonical archive, activated the runtime transactionally, and completed
+  all 8 migration steps. Of 6,845 baseline user-payload files, 6,841 remained
+  byte-identical; the only expected differences were deletion of the stale
+  root `SteamSetup.exe` and Steam `.crash` marker plus appends to two logs.
+  The preserved `steam.exe` and `SteamUI.dll` hashes were unchanged.
+- That upgraded prefix passed ARM64 (rc 0), ARM64EC (rc 42), x86_64 (rc 7),
+  and i386/WoW64 (rc 0 plus marker) with Msync enabled and all FEX TSO modes
+  disabled. `POST /steam/launch` then started the preserved Steam executable,
+  kept it alive through the handoff, and produced an on-screen Wine window
+  titled `Sign in to Steam`; `POST /steam/stop` shut down only that prefix.
+- The fresh download exposed two installer-only regressions now covered by
+  `tools/ci/verify-dmg-workflow.py`: a same-line `local` expansion referenced
+  `destination` before assignment under `set -u`, and packaged launch/layout
+  symlinks were recreated with non-idempotent `ln -s`. Download assignment is
+  now ordered explicitly and all expected packaged symlinks use `ln -sfn`.
 
 ## What This Project Is
 
diff --git a/scripts/install-metalsharp-wine-runtime.sh b/scripts/install-metalsharp-wine-runtime.sh
index a61dd0404..f309c17f0 100755
--- a/scripts/install-metalsharp-wine-runtime.sh
+++ b/scripts/install-metalsharp-wine-runtime.sh
@@ -141,7 +141,8 @@ verify_parts_dir() {
 }
 
 download_asset() {
-  local name="$1" destination="$2" partial="${destination}.partial"
+  local name="$1" destination="$2" partial
+  partial="${destination}.partial"
   [ "$LOCAL_ONLY" -eq 0 ] || die "missing local asset: $name"
   mkdir -p "$(dirname "$destination")"
   info "Downloading $name"
@@ -347,10 +348,10 @@ case "$(basename "$0")" in
 esac
 LAUNCHER
   chmod 0755 "$launcher"
-  ln -s metalsharp-runtime-launcher "$bin/wine"
-  ln -s metalsharp-runtime-launcher "$bin/wine64"
-  ln -s metalsharp-runtime-launcher "$bin/metalsharp-wine"
-  ln -s metalsharp-runtime-launcher "$bin/wineserver"
+  ln -sfn metalsharp-runtime-launcher "$bin/wine"
+  ln -sfn metalsharp-runtime-launcher "$bin/wine64"
+  ln -sfn metalsharp-runtime-launcher "$bin/metalsharp-wine"
+  ln -sfn metalsharp-runtime-launcher "$bin/wineserver"
 }
 
 repair_build_tree_links() {
@@ -380,13 +381,13 @@ PY
 write_metalsharp_layout() {
   local root="$1" lib="$1/wine/lib"
   mkdir -p "$lib"
-  ln -s ../build-ec/dxmt-v0.80 "$lib/dxmt"
-  ln -s ../build-ec/dxmt-v0.80 "$lib/dxmt-m12"
-  ln -s ../build-ec/dxmt-v0.80 "$lib/dxmt_m12"
-  ln -s ../../graphics/dxvk "$lib/dxvk"
-  ln -s ../../graphics/vkd3d-proton "$lib/vkd3d-proton"
-  ln -s ../../graphics/opengl-metal "$lib/opengl-metal"
-  ln -s ../../graphics/moltenvk "$lib/moltenvk"
+  ln -sfn ../build-ec/dxmt-v0.80 "$lib/dxmt"
+  ln -sfn ../build-ec/dxmt-v0.80 "$lib/dxmt-m12"
+  ln -sfn ../build-ec/dxmt-v0.80 "$lib/dxmt_m12"
+  ln -sfn ../../graphics/dxvk "$lib/dxvk"
+  ln -sfn ../../graphics/vkd3d-proton "$lib/vkd3d-proton"
+  ln -sfn ../../graphics/opengl-metal "$lib/opengl-metal"
+  ln -sfn ../../graphics/moltenvk "$lib/moltenvk"
 }
 
 stage_gog_support() {
diff --git a/tools/ci/verify-dmg-workflow.py b/tools/ci/verify-dmg-workflow.py
index 1d2f0deb1..0fe41b97b 100755
--- a/tools/ci/verify-dmg-workflow.py
+++ b/tools/ci/verify-dmg-workflow.py
@@ -122,6 +122,7 @@ def check_updater_handoff() -> None:
 
 def check_bundle_scripts() -> None:
     prepare_runtime = read("tools/dmg/prepare-complete-runtime-assets.sh")
+    runtime_installer = read("scripts/install-metalsharp-wine-runtime.sh")
     for needle in [
         "v0.60.0-dependency-bundles",
         "e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146",
@@ -141,6 +142,29 @@ def check_bundle_scripts() -> None:
         if f'"$ARCHIVE.part{part:02d}"' not in prepare_runtime:
             fail(f"complete-runtime preparation omits runtime part {part:02d}")
 
+    if 'local name="$1" destination="$2" partial="${destination}.partial"' in runtime_installer:
+        fail("runtime installer expands the unset download destination under set -u")
+    if 'partial="${destination}.partial"' not in runtime_installer:
+        fail("runtime installer no longer derives its partial download path after destination assignment")
+    for link in [
+        '"$bin/wine"',
+        '"$bin/wine64"',
+        '"$bin/metalsharp-wine"',
+        '"$bin/wineserver"',
+        '"$lib/dxmt"',
+        '"$lib/dxmt-m12"',
+        '"$lib/dxmt_m12"',
+        '"$lib/dxvk"',
+        '"$lib/vkd3d-proton"',
+        '"$lib/opengl-metal"',
+        '"$lib/moltenvk"',
+    ]:
+        if not any(
+            line.strip().startswith("ln -sfn ") and line.strip().endswith(link)
+            for line in runtime_installer.splitlines()
+        ):
+            fail(f"runtime installer no longer replaces the packaged symlink idempotently: {link}")
+
 
 def check_workflows() -> None:
     pr = read(".github/workflows/pr-ci.yml")
diff --git a/tools/dmg/prepare-complete-runtime-assets.sh b/tools/dmg/prepare-complete-runtime-assets.sh
index 153357e8d..1eb54f372 100755
--- a/tools/dmg/prepare-complete-runtime-assets.sh
+++ b/tools/dmg/prepare-complete-runtime-assets.sh
@@ -8,7 +8,7 @@ REPO="${METALSHARP_RUNTIME_REPO:-metalsharp/MetalSharp}"
 TAG="${METALSHARP_RUNTIME_TAG:-v0.60.0-dependency-bundles}"
 ARCHIVE="MetalSharp-Wine-Runtime-COMPLETE-all-arch-2026-07-31.tar.zst"
 ARCHIVE_SHA256="e44a84bceeca62f01fd95a133364ec82467cd8883ff81bcc1bdfdf4a6c3ad146"
-MANIFEST_SHA256="bba8103217dbc72914a8496cb782882af0883fbb18664956ba365dba68fec4eb"
+MANIFEST_SHA256="1832a96f003e1e3ff2f16974c796f1ba315e6aa7d8ca966eea3f811cd189a8b7"
 
 ASSETS=(
   metalsharp-bundle-manifest.tsv