[shader_recompiler] Fix guest image byte count calculation for Vulkan video presenter

* GUI: verify updater releases by commit and SHA-256

* GUI: add updater rollback and version safeguards

.github/pull_request_template.md

@@ -0,0 +1,27 @@
+## Before submitting
+
+Please read our contribution guidelines before opening a pull request:
+
+➡️ [**CONTRIBUTING.md**](https://github.com/sharpemu/sharpemu/blob/main/CONTRIBUTING.md)
+
+By opening this pull request, you confirm that you have read and agree to follow the contribution guidelines.
+
+## Testing
+
+If applicable, list the game(s) you tested and briefly describe the results.
+
+Example:
+
+- Demon's Souls (PPSA01341) – Boots to splash screen.
+- Dreaming Sarah – Save/load works correctly.
+
+If your changes do not affect runtime behavior (e.g. documentation, tooling, CI), write `N/A`.
+
+## Checklist
+
+By submitting this pull request, you confirm that:
+
+- [ ] I have read and followed `CONTRIBUTING.md`.
+- [ ] I tested my changes or marked the testing section as `N/A`.
+- [ ] I wrote this pull request description myself and did not paste AI-generated explanations.
+- [ ] I listed the game(s) I tested (or marked the testing section as `N/A`).

.github/workflows/notify-site.yml

@@ -0,0 +1,31 @@
+# Copyright (C) 2026 SharpEmu Emulator Project
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+# Tells the website repo to rebuild when a release is published, so
+# sharpemu.app/downloads lists the new build within a minute.
+name: Notify website
+
+on:
+  release:
+    types: [published, released, edited, deleted]
+  workflow_dispatch:
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger sharpemu-site rebuild
+        env:
+          TOKEN: ${{ secrets.SITE_DISPATCH_TOKEN }}
+        run: |
+          if [ -z "$TOKEN" ]; then
+            echo "SITE_DISPATCH_TOKEN is not set — skipping website rebuild."
+            exit 0
+          fi
+          curl -fsS -X POST \
+            -H "Authorization: Bearer $TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/sharpemu/sharpemu-site/dispatches \
+            -d '{"event_type":"release-published"}'
+          echo "Website rebuild requested."

.github/workflows/pr-build-links.yml

@@ -0,0 +1,120 @@
+# Copyright (C) 2026 SharpEmu Emulator Project
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+# Posts (and keeps updated) a single PR comment linking the per-platform build
+# artifacts once "Build and Release" finishes.
+#
+# This is a workflow_run workflow on purpose: PRs from forks run "Build and
+# Release" with a read-only GITHUB_TOKEN and cannot comment. workflow_run runs
+# afterwards in the base-repo context with a read-write token and does not check
+# out untrusted fork code, so it can comment safely. Because of that, GitHub only
+# triggers it from the copy on the default branch — it does nothing until merged
+# to main.
+name: PR Build Links
+
+on:
+  workflow_run:
+    workflows: ["Build and Release"]
+    types:
+      - completed
+
+permissions:
+  contents: read
+  actions: read
+  pull-requests: write
+
+jobs:
+  comment:
+    name: Post artifact links
+    runs-on: ubuntu-latest
+    # Only for successful PR builds — artifacts exist only when the build passed.
+    if: >-
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    steps:
+      - name: Post or update the artifact-links comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const run = context.payload.workflow_run;
+            const { owner, repo } = context.repo;
+
+            // Resolve the PR. Same-repo PRs are in workflow_run.pull_requests, but
+            // fork PRs leave it empty AND their head commit is not on a base-repo
+            // branch, so listPullRequestsAssociatedWithCommit misses them too. Match
+            // the open PR by its head "owner:branch" instead, which works for forks.
+            let prNumber;
+            if (run.pull_requests && run.pull_requests.length > 0) {
+              prNumber = run.pull_requests[0].number;
+            } else {
+              let candidates = [];
+              const headOwner = run.head_repository && run.head_repository.owner
+                ? run.head_repository.owner.login
+                : null;
+              if (headOwner && run.head_branch) {
+                const byHead = await github.rest.pulls.list({
+                  owner, repo, state: 'open',
+                  head: `${headOwner}:${run.head_branch}`, per_page: 10,
+                });
+                candidates = byHead.data;
+              }
+              if (candidates.length === 0) {
+                const byCommit = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+                  owner, repo, commit_sha: run.head_sha,
+                });
+                candidates = byCommit.data.filter(pr => pr.state === 'open');
+              }
+              if (candidates.length === 0) {
+                core.info('No open PR for this build; nothing to comment.');
+                return;
+              }
+              prNumber = candidates[0].number;
+            }
+
+            // Collect the per-platform artifacts the build produced.
+            const artifacts = await github.paginate(
+              github.rest.actions.listWorkflowRunArtifacts,
+              { owner, repo, run_id: run.id, per_page: 100 },
+            );
+            const platforms = [
+              { key: 'win-x64', label: 'Windows (win-x64)' },
+              { key: 'linux-x64', label: 'Linux (linux-x64)' },
+              { key: 'osx-x64', label: 'macOS (osx-x64)' },
+            ];
+            const rows = [];
+            for (const platform of platforms) {
+              const artifact = artifacts.find(a => a.name.includes(platform.key));
+              if (!artifact) {
+                continue;
+              }
+              const url = `https://github.com/${owner}/${repo}/actions/runs/${run.id}/artifacts/${artifact.id}`;
+              rows.push(`| ${platform.label} | [\`${artifact.name}\`](${url}) |`);
+            }
+            if (rows.length === 0) {
+              core.info('No platform artifacts on this run; nothing to comment.');
+              return;
+            }
+
+            const marker = '<!-- pr-build-links -->';
+            const body = [
+              marker,
+              `### 📦 Build artifacts — \`${run.head_sha.substring(0, 7)}\``,
+              '',
+              '| Platform | Download |',
+              '| --- | --- |',
+              ...rows,
+              '',
+              `From [build run #${run.run_number}](${run.html_url}). ` +
+                'Downloads require a GitHub login and expire after 90 days.',
+            ].join('\n');
+
+            // Upsert one comment so repeated builds refresh it in place.
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number: prNumber, per_page: 100,
+            });
+            const existing = comments.find(c => c.body && c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number: prNumber, body });
+            }

.github/workflows/workflow.yml

@@ -7,6 +7,8 @@ on:
   push:
     branches:
       - "**"
+    tags:
+      - "v*"
     paths-ignore:
       - "**/*.md"
       - "**/*.png"
@@ -53,6 +55,11 @@ jobs:
           release_tag="v${version}"
           release_name="SharpEmu v${version}"
 
+          if [ "${GITHUB_REF_TYPE}" = "tag" ] && [ "${GITHUB_REF_NAME}" != "${release_tag}" ]; then
+            echo "Release tag ${GITHUB_REF_NAME} does not match project version ${release_tag}." >&2
+            exit 1
+          fi
+
           {
             echo "short-sha=${short_sha}"
             echo "safe-ref=${safe_ref}"
@@ -94,14 +101,20 @@ jobs:
           cache: true
           cache-dependency-path: |
             Directory.Packages.props
-            src/**/packages.lock.json
+            Directory.Build.props
 
       - name: Restore solution
-        run: dotnet restore SharpEmu.slnx --locked-mode
+        run: dotnet restore SharpEmu.slnx
 
       - name: Build solution
         run: dotnet build SharpEmu.slnx -c Release --no-restore
 
+      # Runs every test project in the solution; a test failure fails the build, as
+      # does an aerolib.bin generation failure in the build step above (the MSBuild
+      # task logs an error and returns false).
+      - name: Run tests
+        run: dotnet test SharpEmu.slnx -c Release --no-build --verbosity normal
+
       - name: Validate synthetic shaders
         run: dotnet run --project tools/SharpEmu.Tools.ShaderDump/SharpEmu.Tools.ShaderDump.csproj -c Release -- artifacts/shader-dump
 
@@ -112,7 +125,7 @@ jobs:
         run: |
           New-Item -ItemType Directory -Path $env:RELEASE_DIR -Force | Out-Null
 
-          $archiveName = "sharpemu-${{ needs.init.outputs.version }}-win-x64-${{ needs.init.outputs.short-sha }}.zip"
+          $archiveName = "sharpemu-${{ needs.init.outputs.version }}-win-x64.zip"
           $archivePath = Join-Path $env:RELEASE_DIR $archiveName
           if (Test-Path $archivePath) {
             Remove-Item $archivePath -Force
@@ -124,7 +137,7 @@ jobs:
         uses: actions/upload-artifact@v7
         with:
           name: sharpemu-win-x64-${{ needs.init.outputs.short-sha }}
-          path: ${{ env.RELEASE_DIR }}\sharpemu-${{ needs.init.outputs.version }}-win-x64-${{ needs.init.outputs.short-sha }}.zip
+          path: ${{ env.RELEASE_DIR }}\sharpemu-${{ needs.init.outputs.version }}-win-x64.zip
           if-no-files-found: error
 
   build-posix:
@@ -146,6 +159,11 @@ jobs:
       NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
       PUBLISH_DIR: ${{ github.workspace }}/artifacts/publish/${{ matrix.rid }}
       RELEASE_DIR: ${{ github.workspace }}/artifacts/release
+      SPIRV_HEADERS_COMMIT: ad9184e76a66b1001c29db9b0a3e87f646c64de0
+      # SpirvModuleBuilder emits SPIR-V 1.5 and VulkanVideoPresenter requests Vulkan 1.2.
+      SPIRV_TARGET_ENV: vulkan1.2
+      SPIRV_TOOLS_COMMIT: 0539c81f69a3daeb706fd3477dca61435b475156
+      SPIRV_TOOLS_VERSION: v2026.2
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -157,14 +175,47 @@ jobs:
           cache: true
           cache-dependency-path: |
             Directory.Packages.props
-            src/**/packages.lock.json
+            Directory.Build.props
 
       - name: Restore solution
-        run: dotnet restore SharpEmu.slnx --locked-mode
+        run: dotnet restore SharpEmu.slnx
 
       - name: Build solution
         run: dotnet build SharpEmu.slnx -c Release --no-restore
 
+      # Also runs on Linux/macOS: the aerolib.bin MSBuild task does platform-sensitive
+      # path handling, so a cross-platform generation regression surfaces here.
+      - name: Run tests
+        run: dotnet test SharpEmu.slnx -c Release --no-build --verbosity normal
+
+      - name: Build pinned SPIRV-Tools
+        if: matrix.rid == 'linux-x64'
+        run: |
+          git clone --no-checkout --filter=blob:none https://github.com/KhronosGroup/SPIRV-Tools.git "$RUNNER_TEMP/spirv-tools"
+          git -C "$RUNNER_TEMP/spirv-tools" checkout --detach "$SPIRV_TOOLS_COMMIT"
+          test "$(git -C "$RUNNER_TEMP/spirv-tools" rev-parse HEAD)" = "$SPIRV_TOOLS_COMMIT"
+
+          git clone --no-checkout --filter=blob:none https://github.com/KhronosGroup/SPIRV-Headers.git "$RUNNER_TEMP/spirv-tools/external/spirv-headers"
+          git -C "$RUNNER_TEMP/spirv-tools/external/spirv-headers" checkout --detach "$SPIRV_HEADERS_COMMIT"
+          test "$(git -C "$RUNNER_TEMP/spirv-tools/external/spirv-headers" rev-parse HEAD)" = "$SPIRV_HEADERS_COMMIT"
+
+          cmake -S "$RUNNER_TEMP/spirv-tools" -B "$RUNNER_TEMP/spirv-tools-build" \
+            -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DSPIRV_SKIP_TESTS=ON \
+            -DSPIRV_WERROR=OFF
+          cmake --build "$RUNNER_TEMP/spirv-tools-build" --target spirv-val
+
+      - name: Generate and validate synthetic SPIR-V
+        if: matrix.rid == 'linux-x64'
+        run: |
+          dotnet run --project tools/SharpEmu.Tools.ShaderDump/SharpEmu.Tools.ShaderDump.csproj -c Release -- artifacts/shader-dump
+          scripts/validate-synthetic-spirv.sh \
+            "$RUNNER_TEMP/spirv-tools-build/tools/spirv-val" \
+            "$SPIRV_TOOLS_VERSION" \
+            "$SPIRV_TARGET_ENV" \
+            artifacts/shader-dump
+
       - name: Publish ${{ matrix.rid }} CLI
         run: dotnet publish src/SharpEmu.CLI/SharpEmu.CLI.csproj -c Release -r ${{ matrix.rid }} --self-contained true --no-restore -p:PublishDir="$PUBLISH_DIR"
 
@@ -176,14 +227,14 @@ jobs:
         run: |
           mkdir -p "$RELEASE_DIR"
           # tar keeps the executable bit, which zip would drop.
-          tar -czf "$RELEASE_DIR/sharpemu-${{ needs.init.outputs.version }}-${{ matrix.rid }}-${{ needs.init.outputs.short-sha }}.tar.gz" \
+          tar -czf "$RELEASE_DIR/sharpemu-${{ needs.init.outputs.version }}-${{ matrix.rid }}.tar.gz" \
             -C "$PUBLISH_DIR" .
 
       - name: Upload build artifact
         uses: actions/upload-artifact@v7
         with:
           name: sharpemu-${{ matrix.rid }}-${{ needs.init.outputs.short-sha }}
-          path: ${{ env.RELEASE_DIR }}/sharpemu-${{ needs.init.outputs.version }}-${{ matrix.rid }}-${{ needs.init.outputs.short-sha }}.tar.gz
+          path: ${{ env.RELEASE_DIR }}/sharpemu-${{ needs.init.outputs.version }}-${{ matrix.rid }}.tar.gz
           if-no-files-found: error
 
   release:
@@ -192,7 +243,9 @@ jobs:
       - init
       - build
       - build-posix
-    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
+    # Versioned releases are immutable and tag-driven. Branch and manual runs
+    # still produce Actions artifacts without modifying a published release.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -202,7 +255,7 @@ jobs:
         with:
           path: release
 
-      - name: Create or update release
+      - name: Create release
         shell: bash
         env:
           GH_REPO: ${{ github.repository }}
@@ -220,11 +273,11 @@ jobs:
           notes="Automated SharpEmu v${VERSION} build for commit ${GITHUB_SHA}."
 
           if gh release view "${RELEASE_TAG}" >/dev/null 2>&1; then
-            gh release upload "${RELEASE_TAG}" "${assets[@]}" --clobber
-            gh release edit "${RELEASE_TAG}" --title "${RELEASE_NAME}" --notes "${notes}"
-          else
-            gh release create "${RELEASE_TAG}" "${assets[@]}" \
-              --title "${RELEASE_NAME}" \
-              --notes "${notes}" \
-              --target "${GITHUB_SHA}"
+            echo "Release ${RELEASE_TAG} already exists and will not be modified." >&2
+            exit 1
           fi
+
+          gh release create "${RELEASE_TAG}" "${assets[@]}" \
+            --verify-tag \
+            --title "${RELEASE_NAME}" \
+            --notes "${notes}"

.gitignore

@@ -32,6 +32,8 @@ packages/
 .nuget/
 .dotnet-home/
 .cache/
+__pycache__/
+*.py[cod]
 
 .DS_Store
 Thumbs.db

CONTRIBUTING.md

@@ -5,6 +5,11 @@ SPDX-License-Identifier: GPL-2.0-or-later
 
 # Contributing
 
+> [!IMPORTANT]
+> The pull request template is mandatory.
+>
+> Pull requests that do not follow the template or leave the required checklist incomplete will be closed without review, even if the proposed code is technically correct or beneficial. Please review these contribution guidelines before submitting a pull request.
+
 Contributions are always welcome!
 
 Before opening a pull request, please keep the following in mind:

Directory.Build.props

@@ -9,8 +9,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
-    <SharpEmuVersion>0.0.1</SharpEmuVersion>
+    <SharpEmuVersion>0.0.2-beta.3</SharpEmuVersion>
     <Version>$(SharpEmuVersion)</Version>
 
     <RepoRoot>$([MSBuild]::NormalizeDirectory('$(MSBuildThisFileDirectory)'))</RepoRoot>

Directory.Packages.props

@@ -12,6 +12,9 @@ SPDX-License-Identifier: GPL-2.0-or-later
     <PackageVersion Include="Avalonia.Fonts.Inter" Version="11.3.18" />
     <PackageVersion Include="Avalonia.Themes.Fluent" Version="11.3.18" />
     <PackageVersion Include="Iced" Version="1.21.0" />
+    <PackageVersion Include="Microsoft.Build.Framework" Version="17.14.8" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
     <PackageVersion Include="Silk.NET.Input" Version="2.23.0" />
     <PackageVersion Include="Silk.NET.Vulkan" Version="2.23.0" />

README.md

@@ -23,11 +23,13 @@ SPDX-License-Identifier: GPL-2.0-or-later
   <strong>Join our Discord for development updates, compatibility discussions, support, and community chat.</strong>
 </p>
 
----
-
-> [!NOTE]  
-> SharpEmu supports Windows x64, Linux x64, and macOS x64. Apple Silicon Macs
-> can run the macOS x64 build through Rosetta 2.
+---
+
+> [!NOTE]  
+> SharpEmu supports Windows x64, Linux x64, and macOS x64. Apple Silicon Macs
+> can run the macOS x64 build through Rosetta 2, and Windows on ARM devices
+> (e.g. Snapdragon) can run the Windows x64 build through Windows' built-in
+> x64 emulation.
 
 > [!WARNING]  
 > SharpEmu is an experimental PS5 emulator developed from scratch in C#. The current focus is on accuracy and infrastructure setup rather than game-specific compatibility.
@@ -41,6 +43,16 @@ This project is developed purely for research and educational purposes. There ar
 SharpEmu focuses exclusively on the PlayStation 5.  
 Our goal is **not** to emulate PS4 games, as there is already an excellent emulator dedicated to that platform: **ShadPS4**.
 
+## Games Tested
+
+|               Demons Souls Remake                   |                     Dreaming Sarah                         |
+| :-----------------------------------------------------------: | :--------------------------------------------------------------------------------------------: |
+| ![Bloodborne screenshot](./.github/images/demons-souls.jpg) | ![Dreaming Sarah](./.github/images/dreaming-sarah.jpg) |
+
+|                  Void Terrarium                     |                 Dead Cells                    |
+| :------------------------------------------------------------------------: | :------------------------------------------------------------------: |
+| ![Void Terrarium](./.github/images/void-terrarium.jpg) | ![Dead Cells](./.github/images/dead-cells.jpg) |
+
 ## Status
 
 The emulator can currently load the `eboot.bin` of real games, execute native CPU instructions, and partially handle kernel-related functionality. However, several critical components are still missing.
@@ -60,52 +72,33 @@ Current capabilities include:
 
 Some games have reached like `sceVideoOut` and AGC stages.
 
-SharpEmu supports Windows, Linux, and macOS hosts. Video output uses Vulkan on
-Windows and Linux, and MoltenVK on macOS. Platform support is still experimental,
-so compatibility and performance vary by game, operating system, and GPU driver.
-
-## Using
-
-Download the release archive for your operating system, extract it, and launch
-SharpEmu with the path to a legally obtained game's `eboot.bin`.
-
-Windows PowerShell:
-
-```powershell
-.\SharpEmu.exe "C:\path\to\game\eboot.bin" 2>&1 |
-  Tee-Object -FilePath "SharpEmu.log"
-```
-
-Linux and macOS:
-
-```bash
-chmod +x ./SharpEmu
-
-./SharpEmu "/path/to/game/eboot.bin" 2>&1 |
-  tee SharpEmu.log
-```
-
-A Vulkan-capable GPU and current graphics driver are required. The macOS
-release includes the MoltenVK Vulkan implementation.
+SharpEmu supports Windows, Linux, and macOS hosts. Video output uses Vulkan on
+Windows and Linux, and MoltenVK on macOS. Platform support is still experimental,
+so compatibility and performance vary by game, operating system, and GPU driver.
 
-## Games Tested
+## Using
 
-* **Demon's Souls Remake**
-  * [Demon's Souls [PPSA01341]](https://github.com/par274/sharpemu/issues/2)
-  * Demon's Souls is now video loop. Shaders are ready to be converted to SPIR-V/Vulkan. We are continuing our work on this.
-  ![DeS videoOut submit first frame](./.github/images/des-videoout-shaders.jpg)
+Download the release archive for your operating system, extract it, and launch
+SharpEmu with the path to a legally obtained game's `eboot.bin`.
 
-* **Poppy Playtime Chapter 1**
-  * [Poppy Playtime Chapter 1 [PPSA20591]](https://github.com/par274/sharpemu/issues/3)
+Windows PowerShell:
 
-* **SILENT HILL: The Short Message**
-  * [SILENT HILL: The Short Message [PPSA10112]](https://github.com/par274/sharpemu/issues/4)
+```powershell
+.\SharpEmu.exe "C:\path\to\game\eboot.bin" 2>&1 |
+  Tee-Object -FilePath "SharpEmu.log"
+```
 
-* **Dreaming Sarah**
-  * [Dreaming Sarah [PPSA02929]](https://github.com/par274/sharpemu/issues/9)
-  * Real texture rendering for this game;
-  ![Splash texture](./.github/images/dreaming-sarah.jpg)
+Linux and macOS:
 
+```bash
+chmod +x ./SharpEmu
+
+./SharpEmu "/path/to/game/eboot.bin" 2>&1 |
+  tee SharpEmu.log
+```
+
+A Vulkan-capable GPU and current graphics driver are required. The macOS
+release includes the MoltenVK Vulkan implementation.
 
 > [!IMPORTANT]  
 > This project does **not** support or condone piracy.  
@@ -114,8 +107,8 @@ release includes the MoltenVK Vulkan implementation.
 
 ## Build
 
-1. Install the .NET SDK version specified in [`global.json`](./global.json).
-2. Clone the repository: `git clone https://github.com/par274/sharpemu.git`
+1. Install the .NET SDK version specified in [`global.json`](./global.json).
+2. Clone the repository: `git clone https://github.com/sharpemu/sharpemu.git`
 3. Open the solution file (`SharpEmu.slnx`) in **VSCode**.
 4. Build the project: `dotnet build` or `dotnet publish`
 5. Build artifacts will be located in the `artifacts` directory.
@@ -141,7 +134,7 @@ Provided valuable references for filesystem handling and low-level C# implementa
 
 # License
 
-- [**GPL-2.0 license**](https://github.com/par274/sharpemu/blob/main/LICENSE)
+- [**GPL-2.0 license**](https://github.com/sharpemu/sharpemu/blob/main/LICENSE)
 
 ## Contributing
 

REUSE.toml

@@ -7,10 +7,10 @@ path = [
     "global.json",
     "**/packages.lock.json",
     "scripts/ps5_names.txt",
-    "src/SharpEmu.HLE/Aerolib/aerolib.bin",
     "src/SharpEmu.GUI/Languages/**",
     "_logs/**",
     ".github/images/**",
+    ".github/pull_request_template.md",
     "assets/images/**"
 ]
 precedence = "aggregate"

SharpEmu.slnx

@@ -7,12 +7,18 @@ SPDX-License-Identifier: GPL-2.0-or-later
   <Folder Name="/src/">
     <Project Path="src/SharpEmu.CLI/SharpEmu.CLI.csproj" />
     <Project Path="src/SharpEmu.Core/SharpEmu.Core.csproj" />
+    <Project Path="src/SharpEmu.DebugClient/SharpEmu.DebugClient.csproj" />
+    <Project Path="src/SharpEmu.Debugger/SharpEmu.Debugger.csproj" />
     <Project Path="src/SharpEmu.GUI/SharpEmu.GUI.csproj" />
     <Project Path="src/SharpEmu.HLE/SharpEmu.HLE.csproj" />
     <Project Path="src/SharpEmu.Libs/SharpEmu.Libs.csproj" />
     <Project Path="src/SharpEmu.Logging/SharpEmu.Logging.csproj" />
+    <Project Path="src/SharpEmu.ShaderCompiler/SharpEmu.ShaderCompiler.csproj" />
+    <Project Path="src/SharpEmu.ShaderCompiler.Vulkan/SharpEmu.ShaderCompiler.Vulkan.csproj" />
+    <Project Path="src/SharpEmu.SourceGenerators/SharpEmu.SourceGenerators.csproj" />
   </Folder>
   <Folder Name="/tests/">
     <Project Path="tests/SharpEmu.Libs.Tests/SharpEmu.Libs.Tests.csproj" />
+    <Project Path="tests/SharpEmu.SourceGenerators.Tests/SharpEmu.SourceGenerators.Tests.csproj" />
   </Folder>
 </Solution>

docs/bink2-bridge.md

@@ -0,0 +1,46 @@
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# Bink 2 bridge
+
+Demon's Souls plays Bink 2 (.bk2) files through a Bink implementation linked
+directly into eboot.bin. It does not use libSceVideodec, therefore an HLE video
+decoder cannot observe or replace those frames.
+
+SharpEmu observes successful guest .bk2 opens and, when a Bink bridge is
+available, presents its decoded BGRA frames at the normal guest-flip boundary.
+This preserves the game's own timing and lets the host Vulkan presenter display
+the movie without trying to execute the PS5-specific Bink GPU decode path.
+
+Without an adapter, Bink movies are skipped by default: their open call returns
+not-found so games that mark cinematics as optional progress to their next
+state instead of waiting on an empty Bink GPU texture.
+
+Set SHARPEMU_BINK_MODE=dummy to retain the open and show a built-in,
+non-decoded placeholder frame. This requires no SDK, but is a visual diagnostic
+only; it does not decode the movie or alter its game logic. Set
+SHARPEMU_BINK_MODE=native to force native bridge mode.
+
+## Supplying the adapter
+
+Bink 2 is proprietary. Obtain a compatible Mac Bink 2 SDK from RAD Game Tools,
+then compile sharpemu_bink2_bridge.c against the SDK's bink.h and Mac library.
+The adapter deliberately contains only a three-function C ABI so the managed
+emulator never depends on RAD's private binary ABI.
+
+Place the resulting libsharpemu_bink2_bridge.dylib next to the SharpEmu
+executable, or point to it explicitly:
+
+    SHARPEMU_BINK2_BRIDGE=/absolute/path/libsharpemu_bink2_bridge.dylib \
+      ./SharpEmu /path/to/eboot.bin
+
+The expected exports are sharpemu_bink2_open_utf8,
+sharpemu_bink2_decode_next_bgra, and sharpemu_bink2_close. The supplied
+adapter opens one movie, exposes BGRA pixels, and advances after each decoded
+frame. The managed side validates dimensions and retains ownership of the
+destination buffer.
+
+If the bridge is absent in native mode, SharpEmu logs one informational line
+and retains the existing guest rendering path.

docs/debugger-server.md

@@ -0,0 +1,177 @@
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# Live debug server
+
+SharpEmu can expose a **live debug server** so an external process can inspect
+and control a running guest over TCP. The server lives in the emulator; the
+companion `SharpEmu.DebugClient` executable is one client, and the wire protocol
+is simple enough to script against directly.
+
+This document describes the moving parts and the wire protocol. For day-to-day
+client usage, see
+[`src/SharpEmu.DebugClient/DEVELOPER_READ.md`](../src/SharpEmu.DebugClient/DEVELOPER_READ.md).
+
+## Layering
+
+| Assembly | Role |
+| -------- | ---- |
+| `SharpEmu.Core` | Defines the dispatcher seam `ICpuDebugHook` / `ICpuDebugFrame` (namespace `SharpEmu.Core.Cpu.Debug`) and the `CpuExecutionOptions.DebugHook` slot. Core has **no** reference to the debugger. |
+| `SharpEmu.Debugger` | The debugger: `DebuggerSession` (implements the hook), `BreakpointStore`, the TCP `DebuggerServer`, the pluggable `IDebugProtocol` with a JSON-lines implementation, and the `DebuggerServerHost` one-call wiring. |
+| `SharpEmu.CLI` | Parses `--debug-server`, builds a `DebuggerServerHost`, hands its `Hook` to `SharpEmuRuntimeOptions.DebugHook`, and manages its lifetime. |
+| `SharpEmu.DebugClient` | A standalone client executable. Depends only on the BCL. |
+
+The dependency direction is important: Core stays debugger-agnostic and only
+publishes the seam. Anything that observes execution implements
+`ICpuDebugHook` and is injected through the options, so the debugger can evolve
+without touching the CPU core.
+
+## Execution model
+
+`CpuDispatcher` enters a fresh frame for the process entry point and for each
+module initializer. When a `DebugHook` is attached it is notified at those
+boundaries:
+
+- `OnFrameEnter(frame)` — before the native backend runs the frame. The
+  `DebuggerSession` decides whether to stop (pause request, breakpoint on the
+  entry address, single-step, or stop-at-entry). To stop, it **parks the
+  emulation thread** inside this call on a gate; the frame stays live, so a
+  client can read and write registers and memory while parked. `continue` /
+  `step` release the gate.
+- `OnFrameExit(frame, result)` — after the frame completes.
+
+Because pausing parks the one thread that owns the guest context, register and
+memory accessors are only served while the session reports `Paused`; otherwise
+they return "not paused" so a client never observes torn state.
+
+### What is and isn't live yet
+
+- **Live:** attach/handshake, run-state tracking, register read/write, memory
+  read/write, breakpoint management, execution breakpoints at frame entry,
+  pause, frame-level step, continue, and stop/resume/terminate events.
+- **Surface only (armed as the backend grows hooks):** per-instruction
+  stepping and data watchpoints (`readwatch` / `writewatch` / `accesswatch`).
+  The verbs and types exist so clients and tooling can be written now.
+
+## Enabling the server
+
+```bash
+SharpEmu --debug-server "/path/to/eboot.bin"            # 127.0.0.1:5714
+SharpEmu --debug-server=0.0.0.0:5714 "/path/to/eboot.bin"
+```
+
+The bind address defaults to loopback; a routable address must be given
+explicitly. With stop-at-entry (the default `DebuggerSessionOptions.StopAtEntry`),
+the guest parks at its first frame until a client connects and issues
+`continue`, giving you a window to set breakpoints before any guest code runs.
+
+## Browser frontend
+
+The dependency-free Python frontend can choose and launch an `eboot.bin`, attach
+to its debugger automatically, and provides execution controls, registers,
+memory inspection, breakpoint management, process output, and a live protocol
+activity stream:
+
+```bash
+./tools/SharpEmu.DebuggerFrontend/run.sh
+```
+
+It connects to `127.0.0.1:5714` and opens `http://127.0.0.1:8765/` by default.
+See [`tools/SharpEmu.DebuggerFrontend/README.md`](../tools/SharpEmu.DebuggerFrontend/README.md)
+for configuration and testing options.
+
+## Wire protocol (json-lines/1)
+
+One JSON object per line, UTF-8, `\n`-terminated, in both directions.
+
+### Requests
+
+A `command` string plus command-specific fields. Numeric fields accept a JSON
+number or a `0x`-prefixed hex string.
+
+| `command` | Fields | Reply `data` |
+| --------- | ------ | ------------ |
+| `ping` | — | — |
+| `status` (`info`) | — | `state`, `breakpoints`, `lastStop?` |
+| `state` | — | `state` |
+| `registers` (`regs`) | — | `registers` (rax..r15, rip, rflags, fs_base, gs_base) |
+| `set-register` | `register`, `value` | — |
+| `read-memory` | `address`, `length` (≤ 65536) | `address`, `length`, `bytes` (hex) |
+| `write-memory` | `address`, `bytes` (hex) | `written` |
+| `list-breakpoints` (`breakpoints`) | — | `breakpoints[]` |
+| `add-breakpoint` (`break`) | `address`, `kind?`, `length?` | `breakpoint` |
+| `remove-breakpoint` (`delete-breakpoint`) | `id` | — |
+| `enable-breakpoint` | `id`, `enabled?` (default true) | — |
+| `continue` (`cont`, `c`) | — | — |
+| `step` (`s`) | — | — |
+| `pause` | — | — |
+
+### Replies
+
+```json
+{"ok":true,"command":"registers","data":{ "registers": { "rax":"0x…", … } }}
+{"ok":false,"command":"read-memory","error":"Target is not paused."}
+```
+
+### Events (unsolicited)
+
+```json
+{"event":"hello","protocol":"json-lines/1","state":"Paused"}
+{"event":"stopped","reason":"Breakpoint","address":"0x…","frameKind":"ProcessEntry","frameLabel":"eboot.bin","registers":{…},"breakpoint":{…}}
+{"event":"resumed"}
+{"event":"terminated"}
+```
+
+`reason` is one of `EntryPoint`, `Breakpoint`, `Watchpoint`, `Step`, `Pause`,
+`Fault`, or `Stall`.
+
+Stall stops include structured evidence in addition to the human-readable
+detail. Import-loop evidence identifies the NID, resolved HLE export, repeating
+guest return site, dispatch count, and first two ABI arguments:
+
+```json
+{
+  "event": "stopped",
+  "reason": "Stall",
+  "stall": {
+    "kind": "ImportLoop",
+    "nid": "9UK1vLZQft4",
+    "instructionPointer": "0x0000000801CE2418",
+    "dispatchIndex": 40667904,
+    "argument0": "0x0000000812345000",
+    "argument1": "0x0000000000000000",
+    "resolved": true,
+    "library": "libKernel",
+    "function": "scePthreadMutexLock"
+  }
+}
+```
+
+The Python frontend uses this evidence to explain the likely failure class and
+rank concrete checks/fixes. Its diagnosis is intentionally labelled heuristic:
+it helps locate the responsible HLE/scheduler path but does not replace tracing.
+
+## Swapping the protocol
+
+`DebuggerServer` takes an `IDebugProtocol` factory. The default is
+`JsonLineDebugProtocol`; a GDB remote serial stub (or any other framing) can be
+dropped in without changing the session or command semantics, which live in
+`DebugCommandDispatcher`.
+
+## Embedding the server
+
+```csharp
+using SharpEmu.Debugger;
+using SharpEmu.Core.Runtime;
+
+await using var host = new DebuggerServerHost();
+host.Start();
+
+var options = new SharpEmuRuntimeOptions { DebugHook = host.Hook };
+using var runtime = SharpEmuRuntime.CreateDefault(options);
+var result = runtime.Run(ebootPath);
+
+host.NotifyRunCompleted();
+```

native/bink2-bridge/sharpemu_bink2_bridge.c

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2026 SharpEmu Emulator Project
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ *
+ * Build this small adapter with a licensed RAD Bink 2 SDK. The SDK and its
+ * headers are not distributed by SharpEmu. See docs/bink2-bridge.md.
+ */
+#include <stdint.h>
+#include "bink.h"
+
+typedef struct sharpemu_bink2_info {
+   uint32_t width;
+   uint32_t height;
+   uint32_t frames_per_second_numerator;
+   uint32_t frames_per_second_denominator;
+} sharpemu_bink2_info;
+
+int sharpemu_bink2_open_utf8(const char *path, HBINK *movie, sharpemu_bink2_info *info) {
+    HBINK bink;
+    if (!path || !movie || !info) return 0;
+
+    *movie = NULL;
+
+    bink = BinkOpen(path, 0);
+    if (!bink) return 0;
+
+    if (bink->Width == 0 || bink->Height == 0) {
+        BinkClose(bink);
+        return 0;
+    }
+
+    *movie = bink;
+    info->width = bink->Width;
+    info->height = bink->Height;
+    info->frames_per_second_numerator = bink->FrameRate;
+    info->frames_per_second_denominator = bink->FrameRateDiv;
+    return 1;
+}
+
+int sharpemu_bink2_decode_next_bgra(HBINK movie, uint8_t *destination,
+                                    uint32_t stride, uint32_t destination_bytes) {
+    uint64_t needed;
+    uint64_t min_stride;
+
+    if (!movie || !destination) return 0;
+
+    min_stride = (uint64_t)movie->Width * 4;
+    if ((uint64_t)stride < min_stride) return 0;
+
+    needed = (uint64_t)stride * movie->Height;
+    if (needed > destination_bytes) return 0;
+
+    /* Async Bink I/O has not filled the next frame yet; retry on the next host present. */
+    if (BinkWait(movie)) return 0;
+
+    if (!BinkDoFrame(movie)) return 0;
+
+    if (!BinkCopyToBuffer(movie, destination, stride, movie->Height, 0, 0, BINKSURFACE32RA)) return 0;
+
+    BinkNextFrame(movie);
+    return 1;
+}
+
+void sharpemu_bink2_close(HBINK movie) {
+   if (movie) BinkClose(movie);
+}

scripts/RELEASE-USE.md

@@ -0,0 +1,90 @@
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+## Release Script
+
+SharpEmu releases are prepared and published using `scripts/release.py`.
+
+The release process consists of two steps:
+
+1. Prepare the version bump through a pull request.
+2. Create and push the release tag after the pull request has been merged.
+
+### Preparing a Release
+
+Run:
+
+```bash
+python scripts/release.py prepare 0.0.2-beta.2
+```
+
+This command will:
+
+- Verify that the working tree is clean.
+- Update the local `main` branch.
+- Create a new branch named `release/0.0.2-beta.2`.
+- Update `SharpEmuVersion` in `Directory.Build.props`.
+- Create a version bump commit.
+- Push the release branch to the remote repository.
+
+Afterwards, open a pull request from:
+
+```text
+release/0.0.2-beta.2
+```
+
+into:
+
+```text
+main
+```
+
+### Publishing a Release
+
+Once the pull request has been merged, update your local repository:
+
+```bash
+git switch main
+git pull --ff-only
+```
+
+Then create and push the release tag:
+
+```bash
+python scripts/release.py tag 0.0.2-beta.2
+```
+
+This command will:
+
+- Verify that the working tree is clean.
+- Confirm that `Directory.Build.props` contains the requested version.
+- Create an annotated Git tag (`v0.0.2-beta.2`).
+- Push the tag to the remote repository.
+
+Pushing the tag automatically triggers the GitHub Release workflow.
+
+### Version Format
+
+Specify the version **without** the `v` prefix.
+
+Examples:
+
+```text
+0.0.2
+0.0.2-alpha.1
+0.0.2-beta.1
+0.0.2-beta.2
+0.0.2-rc.1
+```
+
+The script automatically prefixes the Git tag with `v`.
+
+### Notes
+
+- Run `prepare` only from the `main` branch.
+- Run `tag` only after the version bump pull request has been merged.
+- Do not create release tags manually before merging the version bump.
+- Both commands require a clean working tree.
+- The version in `Directory.Build.props` must exactly match the version passed to the `tag` command.

scripts/check_sysabi_aerolib.py

@@ -1,172 +0,0 @@
-# Copyright (C) 2026 SharpEmu Emulator Project
-# SPDX-License-Identifier: GPL-2.0-or-later
-
-#!/usr/bin/env python3
-
-"""Offline check: SysAbiExport ExportName must hash to its Nid (name2nid).
-
-NIDs absent from aerolib.bin are skipped (unknown/unresolved symbols).
-Known historic mislabels may be allowlisted with a one-line reason.
-
-Run from the repository root:
-  python scripts/check_sysabi_aerolib.py
-  python scripts/check_sysabi_aerolib.py --strict
-"""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import re
-import struct
-import sys
-from base64 import b64encode as base64enc
-from binascii import unhexlify as uhx
-from pathlib import Path
-
-SRC_ROOT = Path("src")
-AEROLIB_BIN = Path("src/SharpEmu.HLE/Aerolib/aerolib.bin")
-SYSABI_EXPORT_RE = re.compile(r"\[SysAbiExport\((.*?)\)\]", re.DOTALL)
-NID_RE = re.compile(r'Nid\s*=\s*"([^"]+)"')
-EXPORT_NAME_RE = re.compile(r'ExportName\s*=\s*"([^"]+)"')
-
-# NID -> reason. Keep minimal; fix ExportName when safe instead of growing this list.
-ALLOWLISTED_NIDS: dict[str, str] = {
-    "KMcEa+rHsIo": "Historic kernel MapMemory stub bound to sceAvPlayerAddSource NID; API rewrite deferred.",
-    "WV1GwM32NgY": "Historic WebApi2 init alias for PushEventCreateHandle NID; ABI rewrite deferred.",
-}
-
-
-def name2nid(name: str) -> str:
-    symbol = hashlib.sha1(name.encode() + uhx("518D64A635DED8C1E6B039B1C3E55230")).digest()
-    id_val = struct.unpack("<Q", symbol[:8])[0]
-    nid = base64enc(uhx("%016x" % id_val), b"+-").rstrip(b"=")
-    return nid.decode("utf-8")
-
-
-def find_repo_root() -> Path:
-    cwd = Path.cwd()
-    if (cwd / SRC_ROOT).is_dir() and (cwd / "scripts").is_dir():
-        return cwd
-    script_root = Path(__file__).resolve().parent.parent
-    if (script_root / SRC_ROOT).is_dir():
-        return script_root
-    raise SystemExit("Run from the repository root (src/ and scripts/ expected).")
-
-
-def load_aerolib_nids(aerolib_path: Path) -> set[str]:
-    data = aerolib_path.read_bytes()
-    if len(data) < 4:
-        raise SystemExit(f"Aerolib binary too small: {aerolib_path}")
-
-    count = struct.unpack_from("<I", data, 0)[0]
-    offset = 4
-    nids: set[str] = set()
-    for _ in range(count):
-        if offset >= len(data):
-            raise SystemExit(f"Truncated aerolib.bin while reading NIDs: {aerolib_path}")
-        nid_len = data[offset]
-        offset += 1
-        nid = data[offset : offset + nid_len].decode("utf-8")
-        offset += nid_len
-        if offset + 2 > len(data):
-            raise SystemExit(f"Truncated aerolib.bin name length: {aerolib_path}")
-        name_len = struct.unpack_from("<H", data, offset)[0]
-        offset += 2 + name_len
-        nids.add(nid)
-    return nids
-
-
-def iter_sysabi_exports(cs_path: Path, text: str):
-    for match in SYSABI_EXPORT_RE.finditer(text):
-        block = match.group(1)
-        nid_match = NID_RE.search(block)
-        export_match = EXPORT_NAME_RE.search(block)
-        if nid_match is None or export_match is None:
-            continue
-
-        nid = nid_match.group(1)
-        export_name = export_match.group(1)
-        nid_attr = f'Nid = "{nid}"'
-        abs_pos = text.find(nid_attr, match.start(), match.end())
-        if abs_pos < 0:
-            abs_pos = match.start()
-        line = text.count("\n", 0, abs_pos) + 1
-        yield cs_path, line, nid, export_name
-
-
-def scan(src_root: Path, catalog_nids: set[str]):
-    checked = 0
-    mismatches = []
-    skipped_no_catalog = 0
-    allowlisted = 0
-
-    for cs_path in sorted(src_root.rglob("*.cs")):
-        text = cs_path.read_text(encoding="utf-8")
-        for path, line, nid, export_name in iter_sysabi_exports(cs_path, text):
-            checked += 1
-            computed = name2nid(export_name)
-            if computed == nid:
-                continue
-
-            if nid not in catalog_nids:
-                skipped_no_catalog += 1
-                continue
-
-            if nid in ALLOWLISTED_NIDS:
-                allowlisted += 1
-                continue
-
-            mismatches.append((path, line, nid, export_name, computed))
-
-    return checked, mismatches, skipped_no_catalog, allowlisted
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description="Check that SysAbiExport ExportName values hash to their Nid via name2nid."
-    )
-    parser.add_argument(
-        "--strict",
-        action="store_true",
-        help="Exit 1 when any non-skipped/non-allowlisted ExportName does not hash to its Nid.",
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Print only the summary line.",
-    )
-    args = parser.parse_args()
-
-    repo_root = find_repo_root()
-    aerolib_path = repo_root / AEROLIB_BIN
-    if not aerolib_path.is_file():
-        raise SystemExit(f"Missing Aerolib catalog: {aerolib_path.as_posix()}")
-
-    catalog_nids = load_aerolib_nids(aerolib_path)
-    checked, mismatches, skipped_no_catalog, allowlisted = scan(
-        repo_root / SRC_ROOT, catalog_nids
-    )
-    ok = checked - len(mismatches) - skipped_no_catalog - allowlisted
-
-    if not args.quiet:
-        for path, line, nid, export_name, computed in mismatches:
-            rel = path.relative_to(repo_root).as_posix()
-            print(
-                f"{rel}:{line}: NID={nid} ExportName={export_name!r} "
-                f"computed={computed}"
-            )
-
-    print(
-        f"checked={checked} ok={ok} fail={len(mismatches)} "
-        f"skipped_no_catalog={skipped_no_catalog} allowlisted={allowlisted} "
-        f"allowlist_size={len(ALLOWLISTED_NIDS)}"
-    )
-
-    if args.strict and mismatches:
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/generate_aerolib_binary.py

@@ -1,54 +0,0 @@
-# Copyright (C) 2026 SharpEmu Emulator Project
-# SPDX-License-Identifier: GPL-2.0-or-later
-
-#!/usr/bin/env python3
-
-import hashlib
-import struct
-from base64 import b64encode as base64enc
-from binascii import unhexlify as uhx
-from pathlib import Path
-
-NAMES = 'scripts/ps5_names.txt'
-OUTPUT = 'src/SharpEmu.HLE/Aerolib/aerolib.bin'
-
-def name2nid(name):
-    symbol = hashlib.sha1(name.encode() + uhx('518D64A635DED8C1E6B039B1C3E55230')).digest()
-    id_val = struct.unpack('<Q', symbol[:8])[0]
-    nid = base64enc(uhx('%016x' % id_val), b'+-').rstrip(b'=')
-    return nid.decode('utf-8')
-
-def generate():
-    names_path = Path(NAMES)
-    output_path = Path(OUTPUT)
-
-    entries = []
-    with open(names_path, 'r', encoding='utf-8') as f:
-        for line in f:
-            name = line.strip()
-            if name:
-                nid = name2nid(name)
-                entries.append((nid, name))
-
-    print(f"Found {len(entries)} entries")
-
-    data = bytearray()
-    data.extend(struct.pack('<I', len(entries)))
-
-    for nid, name in entries:
-        nid_bytes = nid.encode('utf-8')
-        name_bytes = name.encode('utf-8')
-        data.append(len(nid_bytes))
-        data.extend(nid_bytes)
-        data.extend(struct.pack('<H', len(name_bytes)))
-        data.extend(name_bytes)
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(output_path, 'wb') as f:
-        f.write(data)
-
-    print(f"Generated: {output_path} ({len(data):,} bytes)")
-    print(f"Total entries: {len(entries)}")
-
-if __name__ == "__main__":
-    generate()

scripts/release.py

@@ -0,0 +1,408 @@
+#!/usr/bin/env python3
+
+# Copyright (C) 2026 SharpEmu Emulator Project
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+VERSION_PATTERN = re.compile(r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$")
+VERSION_ELEMENT_PATTERN = re.compile(
+    r"(<SharpEmuVersion>)([^<]+)(</SharpEmuVersion>)"
+)
+
+
+class ReleaseError(RuntimeError):
+    pass
+
+
+def run_git(
+    *args: str,
+    cwd: Path,
+    capture_output: bool = False,
+) -> str:
+    command = ["git", *args]
+
+    try:
+        result = subprocess.run(
+            command,
+            cwd=cwd,
+            check=True,
+            text=True,
+            capture_output=capture_output,
+        )
+    except FileNotFoundError:
+        raise ReleaseError("Git was not found in PATH.") from None
+    except subprocess.CalledProcessError as error:
+        stderr = error.stderr.strip() if error.stderr else ""
+        detail = f"\n{stderr}" if stderr else ""
+
+        raise ReleaseError(
+            f"Git command failed: {' '.join(command)}{detail}"
+        ) from error
+
+    return result.stdout.strip() if capture_output else ""
+
+
+def find_repository_root(script_path: Path) -> Path:
+    root = run_git(
+        "rev-parse",
+        "--show-toplevel",
+        cwd=script_path.resolve().parent,
+        capture_output=True,
+    )
+
+    return Path(root)
+
+
+def get_status(repository_root: Path) -> str:
+    return run_git(
+        "status",
+        "--porcelain",
+        cwd=repository_root,
+        capture_output=True,
+    )
+
+
+def ensure_clean_worktree(repository_root: Path) -> None:
+    status = get_status(repository_root)
+
+    if status:
+        raise ReleaseError(
+            "The working tree is not clean.\n\n"
+            f"{status}\n\n"
+            "Commit, stash, or remove these changes first."
+        )
+
+
+def get_current_branch(repository_root: Path) -> str:
+    branch = run_git(
+        "branch",
+        "--show-current",
+        cwd=repository_root,
+        capture_output=True,
+    )
+
+    if not branch:
+        raise ReleaseError(
+            "HEAD is detached. Switch to a branch before continuing."
+        )
+
+    return branch
+
+
+def ensure_branch_does_not_exist(
+    repository_root: Path,
+    branch: str,
+    remote: str,
+) -> None:
+    local_branch = run_git(
+        "branch",
+        "--list",
+        branch,
+        cwd=repository_root,
+        capture_output=True,
+    )
+
+    if local_branch:
+        raise ReleaseError(f"Branch {branch} already exists locally.")
+
+    remote_branch = run_git(
+        "ls-remote",
+        "--heads",
+        remote,
+        branch,
+        cwd=repository_root,
+        capture_output=True,
+    )
+
+    if remote_branch:
+        raise ReleaseError(
+            f"Branch {branch} already exists on {remote}."
+        )
+
+
+def ensure_tag_does_not_exist(
+    repository_root: Path,
+    tag: str,
+    remote: str,
+) -> None:
+    local_tag = run_git(
+        "tag",
+        "--list",
+        tag,
+        cwd=repository_root,
+        capture_output=True,
+    )
+
+    if local_tag:
+        raise ReleaseError(f"Tag {tag} already exists locally.")
+
+    remote_tag = run_git(
+        "ls-remote",
+        "--tags",
+        remote,
+        f"refs/tags/{tag}",
+        cwd=repository_root,
+        capture_output=True,
+    )
+
+    if remote_tag:
+        raise ReleaseError(f"Tag {tag} already exists on {remote}.")
+
+
+def read_version(props_path: Path) -> str:
+    if not props_path.exists():
+        raise ReleaseError(f"Version file not found: {props_path}")
+
+    content = props_path.read_text(encoding="utf-8")
+    match = VERSION_ELEMENT_PATTERN.search(content)
+
+    if match is None:
+        raise ReleaseError(
+            f"SharpEmuVersion was not found in {props_path.name}."
+        )
+
+    return match.group(2).strip()
+
+
+def update_version(props_path: Path, version: str) -> str:
+    content = props_path.read_text(encoding="utf-8")
+    current_version = read_version(props_path)
+
+    if current_version == version:
+        raise ReleaseError(
+            f"SharpEmuVersion is already set to {version}."
+        )
+
+    updated_content, replacement_count = VERSION_ELEMENT_PATTERN.subn(
+        rf"\g<1>{version}\g<3>",
+        content,
+        count=1,
+    )
+
+    if replacement_count != 1:
+        raise ReleaseError(
+            "Expected exactly one SharpEmuVersion element."
+        )
+
+    props_path.write_text(
+        updated_content,
+        encoding="utf-8",
+        newline="\n",
+    )
+
+    return current_version
+
+
+def prepare_release(
+    repository_root: Path,
+    props_path: Path,
+    version: str,
+    remote: str,
+) -> None:
+    ensure_clean_worktree(repository_root)
+
+    current_branch = get_current_branch(repository_root)
+
+    if current_branch != "main":
+        raise ReleaseError(
+            f"Prepare must be run from main, not {current_branch}."
+        )
+
+    run_git(
+        "pull",
+        "--ff-only",
+        remote,
+        "main",
+        cwd=repository_root,
+    )
+
+    branch = f"release/{version}"
+    ensure_branch_does_not_exist(
+        repository_root,
+        branch,
+        remote,
+    )
+
+    previous_version = read_version(props_path)
+
+    run_git(
+        "switch",
+        "-c",
+        branch,
+        cwd=repository_root,
+    )
+
+    try:
+        update_version(props_path, version)
+
+        relative_props_path = props_path.relative_to(repository_root)
+
+        run_git(
+            "add",
+            relative_props_path.as_posix(),
+            cwd=repository_root,
+        )
+        run_git(
+            "commit",
+            "-m",
+            f"chore: bump version to {version}",
+            cwd=repository_root,
+        )
+        run_git(
+            "push",
+            "-u",
+            remote,
+            branch,
+            cwd=repository_root,
+        )
+    except Exception:
+        print(
+            "\nPrepare failed. The release branch may still exist locally.",
+            file=sys.stderr,
+        )
+        raise
+
+    print()
+    print(f"Prepared release {previous_version} -> {version}")
+    print(f"Branch pushed: {branch}")
+    print()
+    print("Open a pull request from:")
+    print(f"  {branch}")
+    print("into:")
+    print("  main")
+    print()
+    print("After merging the PR, run:")
+    print(f"  python scripts/release.py tag {version}")
+
+
+def create_release_tag(
+    repository_root: Path,
+    props_path: Path,
+    version: str,
+    remote: str,
+) -> None:
+    ensure_clean_worktree(repository_root)
+
+    current_branch = get_current_branch(repository_root)
+
+    if current_branch != "main":
+        raise ReleaseError(
+            f"Tagging must be run from main, not {current_branch}."
+        )
+
+    run_git(
+        "pull",
+        "--ff-only",
+        remote,
+        "main",
+        cwd=repository_root,
+    )
+
+    current_version = read_version(props_path)
+
+    if current_version != version:
+        raise ReleaseError(
+            "Version mismatch:\n"
+            f"  Directory.Build.props: {current_version}\n"
+            f"  Requested tag:         {version}"
+        )
+
+    tag = f"v{version}"
+
+    ensure_tag_does_not_exist(
+        repository_root,
+        tag,
+        remote,
+    )
+
+    run_git(
+        "tag",
+        "-a",
+        tag,
+        "-m",
+        f"SharpEmu {version}",
+        cwd=repository_root,
+    )
+    run_git(
+        "push",
+        remote,
+        tag,
+        cwd=repository_root,
+    )
+
+    print()
+    print(f"Successfully pushed tag {tag}.")
+    print("The release workflow should start automatically.")
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Prepare or tag a SharpEmu release."
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        required=True,
+    )
+
+    for command in ("prepare", "tag"):
+        subparser = subparsers.add_parser(command)
+        subparser.add_argument(
+            "version",
+            help="Version without the v prefix, e.g. 0.0.2-beta.2.",
+        )
+        subparser.add_argument(
+            "--remote",
+            default="origin",
+            help="Git remote. Default: origin.",
+        )
+
+    arguments = parser.parse_args()
+
+    if not VERSION_PATTERN.fullmatch(arguments.version):
+        parser.error(
+            "Version must look like 0.0.2, "
+            "0.0.2-beta.2, or 0.0.2-rc.1."
+        )
+
+    return arguments
+
+
+def main() -> int:
+    arguments = parse_arguments()
+
+    try:
+        repository_root = find_repository_root(Path(__file__))
+        props_path = repository_root / "Directory.Build.props"
+
+        if arguments.command == "prepare":
+            prepare_release(
+                repository_root,
+                props_path,
+                arguments.version,
+                arguments.remote,
+            )
+        else:
+            create_release_tag(
+                repository_root,
+                props_path,
+                arguments.version,
+                arguments.remote,
+            )
+    except ReleaseError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/validate-synthetic-spirv.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Copyright (C) 2026 SharpEmu Emulator Project
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+set -euo pipefail
+
+if [ "$#" -ne 4 ]; then
+  echo "usage: $0 <spirv-val> <expected-version> <target-env> <module-directory>" >&2
+  exit 2
+fi
+
+validator=$1
+expected_version=$2
+target_env=$3
+module_directory=$4
+
+if [ ! -x "$validator" ]; then
+  echo "SPIR-V validator is not executable: $validator" >&2
+  exit 2
+fi
+
+if [ ! -d "$module_directory" ]; then
+  echo "SPIR-V module directory does not exist: $module_directory" >&2
+  exit 2
+fi
+
+validator_version="$("$validator" --version | head -n 1)"
+if [[ "$validator_version" != *"SPIRV-Tools $expected_version"* ]]; then
+  echo "unexpected SPIRV-Tools version: $validator_version (expected $expected_version)" >&2
+  exit 2
+fi
+
+echo "Validator: $validator_version"
+echo "Target environment: $target_env"
+
+mapfile -d '' modules < <(find "$module_directory" -type f -name '*.spv' -print0 | sort -z)
+if [ "${#modules[@]}" -eq 0 ]; then
+  echo "no SPIR-V modules found in $module_directory" >&2
+  exit 1
+fi
+
+failures=0
+for module in "${modules[@]}"; do
+  echo "Validating module: $module"
+  if ! "$validator" --target-env "$target_env" "$module"; then
+    echo "SPIR-V validation failed: $module" >&2
+    failures=1
+  fi
+done
+
+if [ "$failures" -ne 0 ]; then
+  exit 1
+fi
+
+echo "Validated ${#modules[@]} synthetic SPIR-V modules."

src/SharpEmu.CLI/Program.cs

@@ -45,6 +45,11 @@ internal static partial class Program
     [STAThread]
     private static int Main(string[] args)
     {
+        // Avoid blocking full collections while guest and render threads are
+        // running, and establish the GC mode before the runtime reserves the
+        // fixed guest address-space window.
+        System.Runtime.GCSettings.LatencyMode = System.Runtime.GCLatencyMode.SustainedLowLatency;
+
         try
         {
             return Run(args);
@@ -58,11 +63,15 @@ internal static partial class Program
 
     private static int Run(string[] args)
     {
-        args = NormalizeInternalArguments(args, out var isMitigatedChild);
-        if (args.Length == 0 && !isMitigatedChild)
+        if (Updater.TryApply(args, out var updateExitCode))
+        {
+            return updateExitCode;
+        }
+
+        args = NormalizeInternalArguments(args, out var isMitigatedChild);
+
+        if (args.Length == 0)
         {
-            // No arguments: open the desktop frontend. Any argument selects
-            // the classic CLI behavior below.
             return GuiLauncher.Run();
         }
 
@@ -84,6 +93,7 @@ internal static partial class Program
         {
             if (OperatingSystem.IsMacOS())
             {
+                ConfigureMoltenVkDefaults();
                 PreloadMacVulkanLoader();
             }
 
@@ -151,6 +161,26 @@ internal static partial class Program
         return false;
     }
 
+    /// <summary>
+    /// Applies MoltenVK performance defaults before the Vulkan loader is
+    /// loaded. Existing user-provided values always take precedence.
+    /// </summary>
+    private static void ConfigureMoltenVkDefaults()
+    {
+        try
+        {
+            _ = MacSetEnv("MVK_CONFIG_SYNCHRONOUS_QUEUE_SUBMITS", "0", 0);
+            _ = MacSetEnv("MVK_CONFIG_SHOULD_MAXIMIZE_CONCURRENT_COMPILATION", "1", 0);
+            _ = MacSetEnv("MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS", "1", 0);
+            _ = MacSetEnv("MVK_CONFIG_RESUME_LOST_DEVICE", "1", 0);
+        }
+        catch (Exception exception)
+        {
+            Console.Error.WriteLine(
+                $"[LOADER][WARN] Failed to set MoltenVK defaults: {exception.Message}");
+        }
+    }
+
     /// <summary>
     /// Makes a Vulkan loader visible to GLFW's dlopen("libvulkan.1.dylib").
     /// Homebrew's Vulkan libraries are arm64-only and cannot load into this
@@ -197,7 +227,17 @@ internal static partial class Program
             return childExitCode;
         }
 
-        if (!TryParseArguments(args, out var ebootPath, out var runtimeOptions, out var logLevel, out var logFilePath))
+        if (!TryExtractHostSurfaceArgument(args, out var emulatorArgs, out var hostSurface, out var hostSurfaceError))
+        {
+            Console.Error.WriteLine($"[LOADER][ERROR] {hostSurfaceError}");
+            return 1;
+        }
+
+        HostSessionControl.SetEmbeddedHostSurface(
+            hostSurface?.WindowHandle ?? 0,
+            hostSurface?.DisplayHandle ?? 0);
+
+        if (!TryParseArguments(emulatorArgs, out var ebootPath, out var runtimeOptions, out var logLevel, out var logFilePath))
         {
             PrintUsage();
             return 1;
@@ -222,68 +262,156 @@ internal static partial class Program
             return 2;
         }
 
-        Console.Error.WriteLine("[DEBUG] Creating runtime...");
-
-        using var runtime = SharpEmuRuntime.CreateDefault(runtimeOptions);
-
-        OrbisGen2Result result;
-        ConsoleCancelEventHandler? cancelHandler = null;
-        try
+        if (!TryGetDebugServerOptions(args, out var debugServerEnabled, out var debugServerOptions, out var debugServerError))
         {
-            cancelHandler = (_, eventArgs) =>
-            {
-                eventArgs.Cancel = true;
-                VideoOutExports.NotifyHostInterrupt();
-            };
-            Console.CancelKeyPress += cancelHandler;
-
-            Console.Error.WriteLine($"[DEBUG] Running: {ebootPath}");
-            result = runtime.Run(ebootPath);
-            Console.Error.WriteLine($"[DEBUG] Result: {result}");
+            Log.Error($"Invalid --debug-server endpoint: {debugServerError}");
+            return 1;
         }
-        catch (Exception ex)
+
+        SharpEmu.Debugger.DebuggerServerHost? debugHost = null;
+        if (debugServerEnabled)
         {
-            Console.Error.WriteLine($"[DEBUG] Exception: {ex}");
-            Log.Error("SharpEmu failed to run.", ex);
-            return 3;
-        }
-        finally
-        {
-            if (cancelHandler is not null)
+            debugHost = new SharpEmu.Debugger.DebuggerServerHost(debugServerOptions);
+            try
             {
-                Console.CancelKeyPress -= cancelHandler;
+                debugHost.Start();
+                Log.Info($"Live debug server listening on {debugHost.Endpoint}. Attach with SharpEmu.DebugClient.");
+                // With StopAtEntry, the guest parks at its first frame until a
+                // client connects and continues.
+                runtimeOptions = runtimeOptions with { DebugHook = debugHost.Hook };
+            }
+            catch (Exception ex)
+            {
+                Log.Error("Failed to start the debug server.", ex);
+                debugHost.DisposeAsync().AsTask().GetAwaiter().GetResult();
+                return 6;
             }
         }
 
-        Log.Info($"SharpEmu execution completed. Result={result} (0x{(int)result:X8})");
-        if (!string.IsNullOrWhiteSpace(runtime.LastSessionSummary))
+        Console.Error.WriteLine("[DEBUG] Creating runtime...");
+
+        try
         {
-            Log.Info(runtime.LastSessionSummary);
+            if (hostSurface is not null && !VulkanVideoHost.TryAttachSurface(hostSurface))
+            {
+                Console.Error.WriteLine("[LOADER][ERROR] The requested GUI host surface is already active.");
+                return 3;
+            }
+
+            using var runtime = SharpEmuRuntime.CreateDefault(runtimeOptions);
+
+            OrbisGen2Result result;
+            ConsoleCancelEventHandler? cancelHandler = null;
+            try
+            {
+                cancelHandler = (_, eventArgs) =>
+                {
+                    eventArgs.Cancel = true;
+                    VideoOutExports.NotifyHostInterrupt();
+                };
+                Console.CancelKeyPress += cancelHandler;
+
+                Console.Error.WriteLine($"[DEBUG] Running: {ebootPath}");
+                result = runtime.Run(ebootPath);
+                Console.Error.WriteLine($"[DEBUG] Result: {result}");
+            }
+            catch (Exception ex)
+            {
+                Console.Error.WriteLine($"[DEBUG] Exception: {ex}");
+                Log.Error("SharpEmu failed to run.", ex);
+                return 3;
+            }
+            finally
+            {
+                if (cancelHandler is not null)
+                {
+                    Console.CancelKeyPress -= cancelHandler;
+                }
+            }
+
+            Log.Info($"SharpEmu execution completed. Result={result} (0x{(int)result:X8})");
+            if (!string.IsNullOrWhiteSpace(runtime.LastSessionSummary))
+            {
+                Log.Info(runtime.LastSessionSummary);
+            }
+
+            if (!string.IsNullOrWhiteSpace(runtime.LastBasicBlockTrace))
+            {
+                Log.Info("BB trace:");
+                Log.Info(runtime.LastBasicBlockTrace);
+            }
+
+            if (!string.IsNullOrWhiteSpace(runtime.LastMilestoneLog))
+            {
+                Log.Info(runtime.LastMilestoneLog);
+            }
+
+            if (result != OrbisGen2Result.ORBIS_GEN2_OK && !string.IsNullOrWhiteSpace(runtime.LastExecutionDiagnostics))
+            {
+                Log.Warn(runtime.LastExecutionDiagnostics);
+            }
+
+            if (runtimeOptions.ImportTraceLimit > 0 && !string.IsNullOrWhiteSpace(runtime.LastExecutionTrace))
+            {
+                Log.Info("Import trace:");
+                Log.Info(runtime.LastExecutionTrace);
+            }
+
+            return result == OrbisGen2Result.ORBIS_GEN2_OK ? 0 : 4;
+        }
+        finally
+        {
+            if (debugHost is not null)
+            {
+                debugHost.NotifyRunCompleted();
+                debugHost.DisposeAsync().AsTask().GetAwaiter().GetResult();
+            }
+
+            HostSessionControl.SetEmbeddedHostSurface(0);
+            if (hostSurface is not null)
+            {
+                VulkanVideoHost.RequestClose();
+                VulkanVideoHost.DetachSurface(hostSurface);
+                hostSurface.Dispose();
+            }
+        }
+    }
+
+    private static bool TryExtractHostSurfaceArgument(
+        IReadOnlyList<string> args,
+        out string[] emulatorArgs,
+        out VulkanHostSurface? hostSurface,
+        out string? error)
+    {
+        const string hostSurfacePrefix = "--host-surface=";
+        var remaining = new List<string>(args.Count);
+        hostSurface = null;
+        error = null;
+        foreach (var argument in args)
+        {
+            if (!argument.StartsWith(hostSurfacePrefix, StringComparison.OrdinalIgnoreCase))
+            {
+                remaining.Add(argument);
+                continue;
+            }
+
+            if (hostSurface is not null)
+            {
+                emulatorArgs = [];
+                error = "more than one GUI host surface was specified";
+                return false;
+            }
+
+            var descriptor = argument[hostSurfacePrefix.Length..];
+            if (!VulkanHostSurface.TryCreateChildProcessSurface(descriptor, out hostSurface, out error))
+            {
+                emulatorArgs = [];
+                return false;
+            }
         }
 
-        if (!string.IsNullOrWhiteSpace(runtime.LastBasicBlockTrace))
-        {
-            Log.Info("BB trace:");
-            Log.Info(runtime.LastBasicBlockTrace);
-        }
-
-        if (!string.IsNullOrWhiteSpace(runtime.LastMilestoneLog))
-        {
-            Log.Info(runtime.LastMilestoneLog);
-        }
-
-        if (result != OrbisGen2Result.ORBIS_GEN2_OK && !string.IsNullOrWhiteSpace(runtime.LastExecutionDiagnostics))
-        {
-            Log.Warn(runtime.LastExecutionDiagnostics);
-        }
-
-        if (runtimeOptions.ImportTraceLimit > 0 && !string.IsNullOrWhiteSpace(runtime.LastExecutionTrace))
-        {
-            Log.Info("Import trace:");
-            Log.Info(runtime.LastExecutionTrace);
-        }
-
-        return result == OrbisGen2Result.ORBIS_GEN2_OK ? 0 : 4;
+        emulatorArgs = remaining.ToArray();
+        return true;
     }
 
     private static void EnsureCliConsole()
@@ -380,7 +508,9 @@ internal static partial class Program
         return handle != 0 && handle != -1;
     }
 
-    private static string[] NormalizeInternalArguments(string[] args, out bool isMitigatedChild)
+    private static string[] NormalizeInternalArguments(
+        string[] args,
+        out bool isMitigatedChild)
     {
         isMitigatedChild = false;
         var trustedMitigatedChild = string.Equals(
@@ -900,8 +1030,45 @@ internal static partial class Program
 
     private static void PrintUsage()
     {
-        Log.Info("Usage: SharpEmu.CLI [--strict] [--trace-imports[=N]] [--cpu-engine=<native>] [--log-level=<level>] [--log-file[=<path>]] <path-to-eboot.bin>");
+        Log.Info("Usage: SharpEmu.CLI [--strict] [--trace-imports[=N]] [--cpu-engine=<native>] [--log-level=<level>] [--log-file[=<path>]] [--debug-server[=host:port]] <path-to-eboot.bin>");
         Log.Info(@"Example: SharpEmu.CLI --cpu-engine=native --trace-imports=64 --log-level=debug --log-file ""E:\Games\...\eboot.bin""");
+        Log.Info("Debug server: --debug-server starts a live debug listener (default 127.0.0.1:5714); connect with SharpEmu.DebugClient.");
+    }
+
+    /// <summary>
+    /// Detects the <c>--debug-server</c> flag and parses its optional
+    /// <c>host:port</c> endpoint. Returns false only when the flag is present but
+    /// its endpoint is malformed, so the caller can abort with a clear error.
+    /// </summary>
+    private static bool TryGetDebugServerOptions(
+        string[] args,
+        out bool enabled,
+        out SharpEmu.Debugger.Server.DebuggerServerOptions options,
+        out string error)
+    {
+        enabled = false;
+        options = new SharpEmu.Debugger.Server.DebuggerServerOptions();
+        error = string.Empty;
+        foreach (var argument in args)
+        {
+            if (string.Equals(argument, "--debug-server", StringComparison.OrdinalIgnoreCase))
+            {
+                enabled = true;
+                continue;
+            }
+
+            const string prefix = "--debug-server=";
+            if (argument.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            {
+                enabled = true;
+                if (!SharpEmu.Debugger.Server.DebuggerServerOptions.TryParseEndpoint(argument[prefix.Length..], out options, out error))
+                {
+                    return false;
+                }
+            }
+        }
+
+        return true;
     }
 
     private static bool TryParseArguments(
@@ -935,6 +1102,15 @@ internal static partial class Program
                 continue;
             }
 
+            // The debug-server endpoint is parsed separately (see
+            // TryGetDebugServerOptions); accept the flag here so it is not
+            // rejected as an unknown option or mistaken for the eboot path.
+            if (string.Equals(argument, "--debug-server", StringComparison.OrdinalIgnoreCase) ||
+                argument.StartsWith("--debug-server=", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
             if (string.Equals(argument, "--trace-imports", StringComparison.OrdinalIgnoreCase))
             {
                 importTraceLimit = DefaultImportTraceLimit;
@@ -1319,4 +1495,7 @@ internal static partial class Program
         uint creationDisposition,
         uint flagsAndAttributes,
         nint templateFile);
+
+    [DllImport("libSystem", EntryPoint = "setenv")]
+    private static extern int MacSetEnv(string name, string value, int overwrite);
 }

src/SharpEmu.CLI/SharpEmu.CLI.csproj

@@ -7,6 +7,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
 
   <ItemGroup>
     <ProjectReference Include="..\SharpEmu.Core\SharpEmu.Core.csproj" />
+    <ProjectReference Include="..\SharpEmu.Debugger\SharpEmu.Debugger.csproj" />
     <ProjectReference Include="..\SharpEmu.GUI\SharpEmu.GUI.csproj" />
     <ProjectReference Include="..\SharpEmu.Logging\SharpEmu.Logging.csproj" />
   </ItemGroup>
@@ -25,7 +26,11 @@ SPDX-License-Identifier: GPL-2.0-or-later
     <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
     <ImplicitUsings>enable</ImplicitUsings>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-    <ServerGarbageCollection>true</ServerGarbageCollection>
+    <!-- Server GC reserves one large heap range per logical processor. On
+         high-core-count hosts those ranges can overlap fixed PS5 image bases
+         before the guest address space is established. Workstation GC avoids
+         that collision and keeps the emulator's required mappings available. -->
+    <ServerGarbageCollection>false</ServerGarbageCollection>
     <ConcurrentGarbageCollection>true</ConcurrentGarbageCollection>
     <TieredPGO>true</TieredPGO>
   </PropertyGroup>
@@ -50,6 +55,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
   <PropertyGroup Condition="'$(RuntimeIdentifier)' == 'win-x64' Or '$(RuntimeIdentifier)' == ''">
     <ApplicationIcon>..\..\assets\images\SharpEmu.ico</ApplicationIcon>
     <Win32Icon>..\..\assets\images\SharpEmu.ico</Win32Icon>
+    <ApplicationManifest>app.manifest</ApplicationManifest>
   </PropertyGroup>
 
   <PropertyGroup>

src/SharpEmu.CLI/app.manifest

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
+  <assemblyIdentity version="1.0.0.0" name="SharpEmu" />
+  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+    <application>
+      <!-- Required by Avalonia NativeControlHost on Windows 10 and 11. -->
+      <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
+    </application>
+  </compatibility>
+</assembly>

src/SharpEmu.CLI/packages.lock.json

@@ -216,9 +216,17 @@
         "type": "Project",
         "dependencies": {
           "Iced": "[1.21.0, )",
-          "SharpEmu.HLE": "[1.0.0, )",
-          "SharpEmu.Libs": "[1.0.0, )",
-          "SharpEmu.Logging": "[1.0.0, )"
+          "SharpEmu.HLE": "[0.0.2-beta.3, )",
+          "SharpEmu.Libs": "[0.0.2-beta.3, )",
+          "SharpEmu.Logging": "[0.0.2-beta.3, )"
+        }
+      },
+      "sharpemu.debugger": {
+        "type": "Project",
+        "dependencies": {
+          "SharpEmu.Core": "[0.0.2-beta.3, )",
+          "SharpEmu.HLE": "[0.0.2-beta.3, )",
+          "SharpEmu.Logging": "[0.0.2-beta.3, )"
         }
       },
       "sharpemu.gui": {
@@ -228,20 +236,24 @@
           "Avalonia.Desktop": "[11.3.18, )",
           "Avalonia.Fonts.Inter": "[11.3.18, )",
           "Avalonia.Themes.Fluent": "[11.3.18, )",
-          "SharpEmu.Logging": "[1.0.0, )",
+          "SharpEmu.Core": "[0.0.2-beta.3, )",
+          "SharpEmu.Libs": "[0.0.2-beta.3, )",
+          "SharpEmu.Logging": "[0.0.2-beta.3, )",
           "Tmds.DBus.Protocol": "[0.21.3, )"
         }
       },
       "sharpemu.hle": {
         "type": "Project",
         "dependencies": {
-          "SharpEmu.Logging": "[1.0.0, )"
+          "SharpEmu.Logging": "[0.0.2-beta.3, )"
         }
       },
       "sharpemu.libs": {
         "type": "Project",
         "dependencies": {
-          "SharpEmu.HLE": "[1.0.0, )",
+          "SharpEmu.HLE": "[0.0.2-beta.3, )",
+          "SharpEmu.ShaderCompiler": "[0.0.2-beta.3, )",
+          "SharpEmu.ShaderCompiler.Vulkan": "[0.0.2-beta.3, )",
           "Silk.NET.Input": "[2.23.0, )",
           "Silk.NET.Vulkan": "[2.23.0, )",
           "Silk.NET.Vulkan.Extensions.EXT": "[2.23.0, )",
@@ -252,6 +264,18 @@
       "sharpemu.logging": {
         "type": "Project"
       },
+      "sharpemu.shadercompiler": {
+        "type": "Project",
+        "dependencies": {
+          "SharpEmu.HLE": "[0.0.2-beta.3, )"
+        }
+      },
+      "sharpemu.shadercompiler.vulkan": {
+        "type": "Project",
+        "dependencies": {
+          "SharpEmu.ShaderCompiler": "[0.0.2-beta.3, )"
+        }
+      },
       "Avalonia": {
         "type": "CentralTransitive",
         "requested": "[11.3.18, )",

src/SharpEmu.Core/Cpu/CpuDispatcher.cs

@@ -3,19 +3,16 @@
 
 using System.Buffers.Binary;
 using System.Text;
+using SharpEmu.Core.Cpu.Debugging;
 using SharpEmu.Core.Cpu.Native;
 using SharpEmu.Core.Loader;
 using SharpEmu.Core.Memory;
 using SharpEmu.HLE;
-using SharpEmu.HLE.Host;
-using SharpEmu.Logging;
 
 namespace SharpEmu.Core.Cpu;
 
 public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
 {
-    private static readonly SharpEmuLogger Log = SharpEmuLog.For("Dispatcher");
-
     private enum EntryFrameKind
     {
         ProcessEntry,
@@ -31,9 +28,9 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
     private static readonly ulong TlsBaseAddress = OperatingSystem.IsWindows() ? 0x7FFE_0000_0000UL : 0x6FFE_0000_0000UL;
     private const ulong TlsSize = 0x0001_0000UL;
     // The static TLS blocks live at negative offsets from the TCB (FreeBSD
-    // amd64 variant II); libc.prx alone reaches beyond -0x1700, so give the
-    // prefix a full 64KB on POSIX. Windows keeps its historical 4KB prefix.
-    private static readonly ulong TlsPrefixSize = OperatingSystem.IsWindows() ? 0x0000_1000UL : 0x0001_0000UL;
+    // amd64 variant II). Keep every host in sync with GuestTlsTemplate's
+    // startup reservation; PS5 modules routinely reach beyond one host page.
+    private const ulong TlsPrefixSize = GuestTlsTemplate.StartupStaticTlsReservation;
     private static readonly ulong BootstrapStubBaseAddress = OperatingSystem.IsWindows() ? 0x7FFD_F000_0000UL : 0x6FFD_F000_0000UL;
     private static readonly ulong BootstrapPayloadBaseAddress = OperatingSystem.IsWindows() ? 0x7FFD_E000_0000UL : 0x6FFD_E000_0000UL;
     private static readonly ulong DynlibFallbackStubBaseAddress = OperatingSystem.IsWindows() ? 0x7FFD_D000_0000UL : 0x6FFD_D000_0000UL;
@@ -49,19 +46,16 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
     ];
     private readonly IVirtualMemory _virtualMemory;
     private readonly IModuleManager _moduleManager;
-    private readonly IHostPlatform? _hostPlatform;
     private INativeCpuBackend? _nativeCpuBackend;
 
     public CpuDispatcher(
         IVirtualMemory virtualMemory,
         IModuleManager moduleManager,
-        INativeCpuBackend? nativeCpuBackend = null,
-        IHostPlatform? hostPlatform = null)
+        INativeCpuBackend? nativeCpuBackend = null)
     {
         _virtualMemory = virtualMemory ?? throw new ArgumentNullException(nameof(virtualMemory));
         _moduleManager = moduleManager ?? throw new ArgumentNullException(nameof(moduleManager));
         _nativeCpuBackend = nativeCpuBackend;
-        _hostPlatform = hostPlatform;
     }
 
     public ulong? LastEntryPoint { get; private set; }
@@ -94,8 +88,8 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         string processImageName = "eboot.bin",
         CpuExecutionOptions executionOptions = default)
     {
-        Log.Debug("=== DispatchEntry START ===");
-        Log.Debug($"entryPoint=0x{entryPoint:X16}, generation={generation}");
+        Console.Error.WriteLine("[DISPATCHER] === DispatchEntry START ===");
+        Console.Error.WriteLine($"[DISPATCHER] entryPoint=0x{entryPoint:X16}, generation={generation}");
 
         try
         {
@@ -103,7 +97,8 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         }
         catch (Exception ex)
         {
-            Log.Critical($"FATAL EXCEPTION in DispatchEntry: {ex.GetType().Name}: {ex.Message}", ex);
+            Console.Error.WriteLine($"[DISPATCHER] FATAL EXCEPTION in DispatchEntry: {ex.GetType().Name}: {ex.Message}");
+            Console.Error.WriteLine($"[DISPATCHER] Stack trace: {ex.StackTrace}");
             throw;
         }
     }
@@ -116,8 +111,8 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         string moduleName = "module",
         CpuExecutionOptions executionOptions = default)
     {
-        Log.Debug("=== DispatchModuleInitializer START ===");
-        Log.Debug($"moduleInit=0x{entryPoint:X16}, generation={generation}, module={moduleName}");
+        Console.Error.WriteLine("[DISPATCHER] === DispatchModuleInitializer START ===");
+        Console.Error.WriteLine($"[DISPATCHER] moduleInit=0x{entryPoint:X16}, generation={generation}, module={moduleName}");
 
         try
         {
@@ -132,7 +127,8 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         }
         catch (Exception ex)
         {
-            Log.Critical($"FATAL EXCEPTION in DispatchModuleInitializer: {ex.GetType().Name}: {ex.Message}", ex);
+            Console.Error.WriteLine($"[DISPATCHER] FATAL EXCEPTION in DispatchModuleInitializer: {ex.GetType().Name}: {ex.Message}");
+            Console.Error.WriteLine($"[DISPATCHER] Stack trace: {ex.StackTrace}");
             throw;
         }
     }
@@ -146,7 +142,7 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         CpuExecutionOptions executionOptions = default,
         EntryFrameKind frameKind = EntryFrameKind.ProcessEntry)
     {
-        Log.Debug("DispatchEntryCore STARTING...");
+        Console.Error.WriteLine("[DISPATCHER] DispatchEntryCore STARTING...");
 
         LastEntryPoint = entryPoint;
         LastTrapInfo = null;
@@ -277,7 +273,23 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
             entryFrameDiagnostic,
             Environment.NewLine,
             "CpuEngine: native-only");
-        _nativeCpuBackend ??= new DirectExecutionBackend(_moduleManager, _hostPlatform);
+        // Frame boundaries an attached debugger observes; null hook = a branch.
+        var debugHook = executionOptions.DebugHook;
+        var debugFrame = debugHook is null
+            ? null
+            : new CpuContextDebugFrame(
+                frameKind == EntryFrameKind.ProcessEntry
+                    ? CpuDebugFrameKind.ProcessEntry
+                    : CpuDebugFrameKind.ModuleInitializer,
+                entryPoint,
+                processImageName,
+                context,
+                effectiveImportStubs);
+        debugHook?.OnFrameEnter(debugFrame!);
+
+        _nativeCpuBackend ??= new DirectExecutionBackend(_moduleManager);
+        // Let backend stall reports reference the same frame as entry.
+        (_nativeCpuBackend as DirectExecutionBackend)?.SetActiveDebugFrame(debugFrame);
         if (_nativeCpuBackend.TryExecute(
                 context,
                 entryPoint,
@@ -287,6 +299,7 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
                 executionOptions,
                 out var nativeResult))
         {
+            debugHook?.OnFrameExit(debugFrame!, nativeResult);
             LastSessionSummary = new CpuSessionSummary(
                 nativeResult,
                 nativeResult == OrbisGen2Result.ORBIS_GEN2_OK
@@ -301,6 +314,8 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
             return nativeResult;
         }
 
+        debugHook?.OnFrameExit(debugFrame!, OrbisGen2Result.ORBIS_GEN2_ERROR_NOT_IMPLEMENTED);
+
         var backendName = string.IsNullOrWhiteSpace(_nativeCpuBackend.BackendName)
             ? "native-backend"
             : _nativeCpuBackend.BackendName;
@@ -318,7 +333,7 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
             LastMilestoneLog,
             Environment.NewLine,
             $"CpuEngine native-only failed: {backendError}");
-        Log.Error($"Native backend FAILED: {backendError}");
+        Console.Error.WriteLine($"[DISPATCHER] Native backend FAILED: {backendError}");
         return FailEarly(
             OrbisGen2Result.ORBIS_GEN2_ERROR_NOT_IMPLEMENTED,
             CpuExitReason.NativeBackendUnavailable);
@@ -377,11 +392,19 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
 
     private static bool InitializeTls(CpuContext context, ulong tlsBase)
     {
-        return context.TryWriteUInt64(tlsBase - 0xF0, 0) &&
-               context.TryWriteUInt64(tlsBase + 0x00, tlsBase) &&
-               context.TryWriteUInt64(tlsBase + 0x10, tlsBase) &&
-               context.TryWriteUInt64(tlsBase + 0x28, 0xC0DEC0DECAFEBABEUL) &&
-               context.TryWriteUInt64(tlsBase + 0x60, tlsBase);
+        if (!context.TryWriteUInt64(tlsBase - 0xF0, 0) ||
+            !context.TryWriteUInt64(tlsBase + 0x00, tlsBase) ||
+            !context.TryWriteUInt64(tlsBase + 0x10, tlsBase) ||
+            !context.TryWriteUInt64(tlsBase + 0x28, 0xC0DEC0DECAFEBA00UL) ||
+            !context.TryWriteUInt64(tlsBase + 0x60, tlsBase))
+        {
+            return false;
+        }
+
+        // Seed the static TLS block below the thread pointer with the main
+        // module's initialized thread-locals (variant II layout).
+        SharpEmu.HLE.GuestTlsTemplate.SeedThreadBlock(context, tlsBase);
+        return true;
     }
 
     private static bool InitializeGuestFrameChainSentinel(CpuContext context)
@@ -407,35 +430,54 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         ulong programExitHandlerAddress)
     {
         var imageName = string.IsNullOrWhiteSpace(processImageName) ? "eboot.bin" : processImageName;
-        var encodedNameLength = Encoding.UTF8.GetByteCount(imageName);
-        Span<byte> argv0Buffer = encodedNameLength + 1 <= 512
-            ? stackalloc byte[encodedNameLength + 1]
-            : new byte[encodedNameLength + 1];
-        if (Encoding.UTF8.GetBytes(imageName.AsSpan(), argv0Buffer) != encodedNameLength)
+        var arguments = new List<string>(3) { imageName };
+        var configuredArguments = Environment.GetEnvironmentVariable("SHARPEMU_GUEST_ARGS");
+        if (!string.IsNullOrWhiteSpace(configuredArguments))
         {
-            return false;
+            // The PS5 entry-parameter ABI exposes three inline argv pointers.
+            // Two compatibility arguments are therefore safe without changing
+            // the fixed 0x20-byte structure expected by existing titles.
+            var compatibilityArguments = configuredArguments.Split(
+                (char[]?)null,
+                StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+            arguments.AddRange(compatibilityArguments.Take(2));
         }
 
-        argv0Buffer[encodedNameLength] = 0;
         var cursor = context[CpuRegister.Rsp];
-
-        var argv0Address = AlignDown(cursor - (ulong)argv0Buffer.Length, 16);
-        if (!context.Memory.TryWrite(argv0Address, argv0Buffer))
+        var argumentAddresses = new ulong[arguments.Count];
+        for (var index = arguments.Count - 1; index >= 0; index--)
         {
-            return false;
+            var encoded = Encoding.UTF8.GetBytes(arguments[index] + '\0');
+            cursor = AlignDown(cursor - (ulong)encoded.Length, 16);
+            if (!context.Memory.TryWrite(cursor, encoded))
+            {
+                return false;
+            }
+
+            argumentAddresses[index] = cursor;
         }
 
         const ulong entryParamsSize = 0x20;
-        var entryParamsAddress = AlignDown(argv0Address - entryParamsSize, 16);
-        if (!context.TryWriteUInt32(entryParamsAddress + 0x00, 1) ||
-            !context.TryWriteUInt32(entryParamsAddress + 0x04, 0) ||
-            !context.TryWriteUInt64(entryParamsAddress + 0x08, argv0Address) ||
-            !context.TryWriteUInt64(entryParamsAddress + 0x10, 0) ||
-            !context.TryWriteUInt64(entryParamsAddress + 0x18, 0))
+        var entryParamsAddress = AlignDown(cursor - entryParamsSize, 16);
+        if (!TryWriteUInt32(context, entryParamsAddress + 0x00, (uint)arguments.Count) ||
+            !TryWriteUInt32(context, entryParamsAddress + 0x04, 0) ||
+            !context.TryWriteUInt64(entryParamsAddress + 0x08, argumentAddresses[0]) ||
+            !context.TryWriteUInt64(
+                entryParamsAddress + 0x10,
+                argumentAddresses.Length > 1 ? argumentAddresses[1] : 0) ||
+            !context.TryWriteUInt64(
+                entryParamsAddress + 0x18,
+                argumentAddresses.Length > 2 ? argumentAddresses[2] : 0))
         {
             return false;
         }
 
+        if (arguments.Count > 1)
+        {
+            Console.Error.WriteLine(
+                $"[DISPATCHER] Guest arguments: {string.Join(' ', arguments.Skip(1))}");
+        }
+
         var entryStackPointer = entryParamsAddress - sizeof(ulong);
         if (!context.TryWriteUInt64(entryStackPointer, 0))
         {
@@ -468,6 +510,13 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         return value & ~(alignment - 1);
     }
 
+    private static bool TryWriteUInt32(CpuContext context, ulong address, uint value)
+    {
+        Span<byte> buffer = stackalloc byte[sizeof(uint)];
+        BinaryPrimitives.WriteUInt32LittleEndian(buffer, value);
+        return context.Memory.TryWrite(address, buffer);
+    }
+
     private static string BuildEntryFrameDiagnostic(
         ulong entryPoint,
         CpuContext context,
@@ -664,6 +713,13 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
         return _virtualMemory.TryWrite(address, buffer);
     }
 
+    /// <summary>
+    /// True when the disposed native backend left its session state alive
+    /// because guest workers were still executing guest code. The guest
+    /// address space must then stay mapped as well.
+    /// </summary>
+    internal bool NativeSessionLeaked { get; private set; }
+
     public void Dispose()
     {
         if (_nativeCpuBackend is IDisposable disposableBackend)
@@ -671,6 +727,7 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
             disposableBackend.Dispose();
         }
 
+        NativeSessionLeaked = _nativeCpuBackend is DirectExecutionBackend { GuestSessionLeaked: true };
         _nativeCpuBackend = null;
     }
 }

src/SharpEmu.Core/Cpu/CpuExecutionOptions.cs

@@ -1,15 +1,26 @@
 // Copyright (C) 2026 SharpEmu Emulator Project
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+using SharpEmu.Core.Cpu.Debugging;
+
 namespace SharpEmu.Core.Cpu;
 
 public readonly struct CpuExecutionOptions
 {
     public bool EnableDisasmDiagnostics { get; init; }
-    
+
     public CpuExecutionEngine CpuEngine { get; init; }
 
     public bool StrictDynlibResolution { get; init; }
 
     public int ImportTraceLimit { get; init; }
+
+    /// <summary>
+    /// An optional debugger attached to this execution session. When set, the
+    /// dispatcher notifies it at each frame boundary via
+    /// <see cref="ICpuDebugHook.OnFrameEnter"/> / <see cref="ICpuDebugHook.OnFrameExit"/>.
+    /// Null when no debugger is attached, which is the default and imposes no
+    /// runtime cost.
+    /// </summary>
+    public ICpuDebugHook? DebugHook { get; init; }
 }

src/SharpEmu.Core/Cpu/Debugging/CpuContextDebugFrame.cs

@@ -0,0 +1,66 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.HLE;
+
+namespace SharpEmu.Core.Cpu.Debugging;
+
+/// <summary>
+/// Adapts a live <see cref="CpuContext"/> to <see cref="ICpuDebugFrame"/>. The
+/// dispatcher creates one of these around the guest context it is about to run
+/// and passes it to the attached <see cref="ICpuDebugHook"/>; every accessor
+/// forwards directly to the underlying context.
+/// </summary>
+internal sealed class CpuContextDebugFrame : ICpuDebugFrame
+{
+    private readonly CpuContext _context;
+
+    internal CpuContextDebugFrame(
+        CpuDebugFrameKind kind,
+        ulong entryPoint,
+        string label,
+        CpuContext context,
+        IReadOnlyDictionary<ulong, string> importStubs)
+    {
+        Kind = kind;
+        EntryPoint = entryPoint;
+        Label = label ?? string.Empty;
+        _context = context ?? throw new ArgumentNullException(nameof(context));
+        ImportStubs = importStubs ?? new Dictionary<ulong, string>();
+    }
+
+    public CpuDebugFrameKind Kind { get; }
+
+    public Generation Generation => _context.TargetGeneration;
+
+    public ulong EntryPoint { get; }
+
+    public string Label { get; }
+
+    public ICpuMemory Memory => _context.Memory;
+
+    public ulong GetRegister(CpuRegister register) => _context[register];
+
+    public void SetRegister(CpuRegister register, ulong value) => _context[register] = value;
+
+    public ulong Rip
+    {
+        get => _context.Rip;
+        set => _context.Rip = value;
+    }
+
+    public ulong Rflags
+    {
+        get => _context.Rflags;
+        set => _context.Rflags = value;
+    }
+
+    public ulong FsBase => _context.FsBase;
+
+    public ulong GsBase => _context.GsBase;
+
+    public void GetXmm(int registerIndex, out ulong low, out ulong high)
+        => _context.GetXmmRegister(registerIndex, out low, out high);
+
+    public IReadOnlyDictionary<ulong, string> ImportStubs { get; }
+}

src/SharpEmu.Core/Cpu/Debugging/CpuDebugFrameKind.cs

@@ -0,0 +1,18 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Core.Cpu.Debugging;
+
+/// <summary>
+/// Identifies the kind of guest entry frame a debugger is observing. The
+/// dispatcher enters a fresh frame for the process entry point and for every
+/// module initializer, so the debug layer can label stops accordingly.
+/// </summary>
+public enum CpuDebugFrameKind
+{
+    /// <summary>The guest process entry point (<c>eboot.bin</c> start).</summary>
+    ProcessEntry,
+
+    /// <summary>A module DT_INIT / initializer routine.</summary>
+    ModuleInitializer,
+}

src/SharpEmu.Core/Cpu/Debugging/CpuStallInfo.cs

@@ -0,0 +1,70 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Core.Cpu.Debugging;
+
+/// <summary>The kind of execution stall the backend detected.</summary>
+public enum CpuStallKind
+{
+    /// <summary>
+    /// The guest is repeatedly re-dispatching the same import with no forward
+    /// progress — most commonly a spin on a mutex lock/unlock pair.
+    /// </summary>
+    ImportLoop,
+}
+
+/// <summary>
+/// Details of a detected stall handed to <see cref="ICpuDebugHook.OnStall"/>.
+/// Reported from the emulation thread at the point the backend recognises the
+/// livelock, before it forces the guest out of the loop.
+/// </summary>
+public readonly struct CpuStallInfo
+{
+    public CpuStallInfo(
+        CpuStallKind kind,
+        string? nid,
+        ulong instructionPointer,
+        long dispatchIndex,
+        ulong argument0,
+        ulong argument1,
+        string detail,
+        string? libraryName = null,
+        string? functionName = null)
+    {
+        Kind = kind;
+        Nid = nid;
+        InstructionPointer = instructionPointer;
+        DispatchIndex = dispatchIndex;
+        Argument0 = argument0;
+        Argument1 = argument1;
+        Detail = detail ?? string.Empty;
+        LibraryName = libraryName;
+        FunctionName = functionName;
+    }
+
+    public CpuStallKind Kind { get; }
+
+    /// <summary>The NID of the import being spun on, when known.</summary>
+    public string? Nid { get; }
+
+    /// <summary>The guest return address of the looping import dispatch.</summary>
+    public ulong InstructionPointer { get; }
+
+    /// <summary>The import dispatch counter at detection time.</summary>
+    public long DispatchIndex { get; }
+
+    /// <summary>The first two guest ABI arguments at stall detection.</summary>
+    public ulong Argument0 { get; }
+
+    public ulong Argument1 { get; }
+
+    /// <summary>The resolved HLE export, when the NID is registered.</summary>
+    public string? LibraryName { get; }
+
+    public string? FunctionName { get; }
+
+    public bool IsResolved => !string.IsNullOrWhiteSpace(FunctionName);
+
+    /// <summary>A human-readable one-line summary of the stall.</summary>
+    public string Detail { get; }
+}

src/SharpEmu.Core/Cpu/Debugging/ICpuDebugFrame.cs

@@ -0,0 +1,66 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.HLE;
+
+namespace SharpEmu.Core.Cpu.Debugging;
+
+/// <summary>
+/// A live view of the guest CPU state at a dispatch boundary, handed to an
+/// <see cref="ICpuDebugHook"/> so a debugger can read and mutate registers and
+/// guest memory without taking a dependency on the concrete
+/// <c>CpuContext</c>/<c>CpuDispatcher</c> types.
+/// </summary>
+/// <remarks>
+/// The frame instance is only valid for the duration of the hook call that
+/// receives it (between <see cref="ICpuDebugHook.OnFrameEnter"/> and the
+/// matching <see cref="ICpuDebugHook.OnFrameExit"/>). Reads and writes are
+/// forwarded straight to the underlying guest context, so mutations made from
+/// a hook are observed by the CPU backend when it resumes the frame.
+/// </remarks>
+public interface ICpuDebugFrame
+{
+    /// <summary>The kind of frame being executed.</summary>
+    CpuDebugFrameKind Kind { get; }
+
+    /// <summary>The guest ABI generation this frame targets.</summary>
+    Generation Generation { get; }
+
+    /// <summary>The guest virtual address the frame begins executing at.</summary>
+    ulong EntryPoint { get; }
+
+    /// <summary>
+    /// A human-readable label for the frame (process image name or module name).
+    /// </summary>
+    string Label { get; }
+
+    /// <summary>Guest-addressable memory for this frame.</summary>
+    ICpuMemory Memory { get; }
+
+    /// <summary>Reads a general-purpose register.</summary>
+    ulong GetRegister(CpuRegister register);
+
+    /// <summary>Overwrites a general-purpose register.</summary>
+    void SetRegister(CpuRegister register, ulong value);
+
+    /// <summary>The instruction pointer.</summary>
+    ulong Rip { get; set; }
+
+    /// <summary>The flags register.</summary>
+    ulong Rflags { get; set; }
+
+    /// <summary>The FS segment base (guest TLS pointer).</summary>
+    ulong FsBase { get; }
+
+    /// <summary>The GS segment base.</summary>
+    ulong GsBase { get; }
+
+    /// <summary>Reads the 128-bit value of an XMM register.</summary>
+    void GetXmm(int registerIndex, out ulong low, out ulong high);
+
+    /// <summary>
+    /// The import stubs (guest address to NID) resolved for this frame, so a
+    /// debugger can annotate calls into HLE exports.
+    /// </summary>
+    IReadOnlyDictionary<ulong, string> ImportStubs { get; }
+}

src/SharpEmu.Core/Cpu/Debugging/ICpuDebugHook.cs

@@ -0,0 +1,49 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.HLE;
+
+namespace SharpEmu.Core.Cpu.Debugging;
+
+/// <summary>
+/// The seam the CPU dispatcher uses to notify an attached debugger when guest
+/// execution crosses a frame boundary. Implemented outside of Core (for
+/// example by <c>SharpEmu.Debugger</c>) and supplied through
+/// <see cref="CpuExecutionOptions.DebugHook"/>.
+/// </summary>
+/// <remarks>
+/// This is intentionally coarse-grained: it exposes the entry and exit of each
+/// dispatched frame rather than per-instruction stepping. Per-instruction
+/// control requires cooperation from the native execution backend and is layered
+/// on top of this seam as the backend gains support; keeping the dispatcher-level
+/// contract stable lets the debugger infrastructure exist independently of that
+/// work. Implementations must be thread-safe: frames may be dispatched from the
+/// dedicated emulation thread while a debug server services clients on its own
+/// threads.
+/// </remarks>
+public interface ICpuDebugHook
+{
+    /// <summary>
+    /// Invoked immediately before the native backend begins executing a frame.
+    /// The debugger may inspect or mutate <paramref name="frame"/> and may block
+    /// the calling thread (for example, to honour a pause request) before
+    /// returning to allow execution to proceed.
+    /// </summary>
+    void OnFrameEnter(ICpuDebugFrame frame);
+
+    /// <summary>
+    /// Invoked after a frame completes, whether it returned to the host or
+    /// terminated with an error. <paramref name="frame"/> reflects the final
+    /// guest state.
+    /// </summary>
+    void OnFrameExit(ICpuDebugFrame frame, OrbisGen2Result result);
+
+    /// <summary>
+    /// Invoked from the emulation thread when the backend detects an execution
+    /// stall (for example a mutex spin loop) in the running frame, before it
+    /// forces the guest out of the loop. As with <see cref="OnFrameEnter"/>, the
+    /// implementation may inspect <paramref name="frame"/> and block to honour a
+    /// break before returning to let the backend proceed.
+    /// </summary>
+    void OnStall(ICpuDebugFrame frame, CpuStallInfo info);
+}

src/SharpEmu.Core/Cpu/Emulation/BmiInstructionEmulator.cs

@@ -0,0 +1,305 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Numerics;
+
+namespace SharpEmu.Core.Cpu.Emulation;
+
+/// <summary>
+/// Pure software implementations of the BMI1, BMI2 and ABM general-purpose-register
+/// bit-manipulation instructions.
+///
+/// The direct-execution backend runs guest PS5 code natively on the host CPU. The PS5's
+/// Zen 2 cores implement BMI1/BMI2/ABM, but a host CPU that predates those extensions raises
+/// #UD (STATUS_ILLEGAL_INSTRUCTION) when it meets one of these opcodes. This class provides the
+/// register-only arithmetic so the exception handler can finish the instruction in software and
+/// resume, instead of aborting the title.
+///
+/// The methods deliberately operate on plain integers rather than on the OS CONTEXT record so the
+/// semantics can be unit-tested in isolation; the unsafe register/memory plumbing lives in the
+/// backend adapter. Each method returns the result already masked to the operand width and, where
+/// the instruction is defined to touch flags, updates <paramref name="eflags"/> in place. Flags
+/// documented as "undefined" by the vendor manuals are left untouched so behaviour stays
+/// deterministic across hosts.
+/// </summary>
+public static class BmiInstructionEmulator
+{
+    private const uint FlagCarry = 1u << 0;
+    private const uint FlagZero = 1u << 6;
+    private const uint FlagSign = 1u << 7;
+    private const uint FlagOverflow = 1u << 11;
+
+    private static ulong WidthMask(GprOperandSize size) =>
+        size == GprOperandSize.Bits64 ? ulong.MaxValue : 0xFFFF_FFFFUL;
+
+    private static int WidthBits(GprOperandSize size) => (int)size;
+
+    private static bool SignSet(ulong value, GprOperandSize size) =>
+        size == GprOperandSize.Bits64 ? (value >> 63) != 0 : (value & 0x8000_0000UL) != 0;
+
+    private static uint WithFlag(uint eflags, uint flag, bool set) =>
+        set ? eflags | flag : eflags & ~flag;
+
+    // Applies the CF/ZF/SF/OF set shared by ANDN/BLS*/BZHI: OF is always cleared, ZF and SF follow
+    // the result, and the caller supplies CF because each instruction defines it differently.
+    private static uint ApplyLogicFlags(uint eflags, ulong result, GprOperandSize size, bool carry)
+    {
+        eflags = WithFlag(eflags, FlagCarry, carry);
+        eflags = WithFlag(eflags, FlagZero, result == 0);
+        eflags = WithFlag(eflags, FlagSign, SignSet(result, size));
+        eflags = WithFlag(eflags, FlagOverflow, false);
+        return eflags;
+    }
+
+    /// <summary>ANDN: <c>dest = (~src1) &amp; src2</c>. CF and OF are cleared.</summary>
+    public static ulong Andn(ulong src1, ulong src2, GprOperandSize size, ref uint eflags)
+    {
+        var result = (~src1 & src2) & WidthMask(size);
+        eflags = ApplyLogicFlags(eflags, result, size, carry: false);
+        return result;
+    }
+
+    /// <summary>BLSI: isolate the lowest set bit, <c>dest = (-src) &amp; src</c>. CF = (src != 0).</summary>
+    public static ulong Blsi(ulong src, GprOperandSize size, ref uint eflags)
+    {
+        var mask = WidthMask(size);
+        var s = src & mask;
+        var result = ((0UL - s) & s) & mask;
+        eflags = ApplyLogicFlags(eflags, result, size, carry: s != 0);
+        return result;
+    }
+
+    /// <summary>BLSMSK: mask up to and including the lowest set bit, <c>dest = (src - 1) ^ src</c>. CF = (src == 0).</summary>
+    public static ulong Blsmsk(ulong src, GprOperandSize size, ref uint eflags)
+    {
+        var mask = WidthMask(size);
+        var s = src & mask;
+        var result = ((s - 1) ^ s) & mask;
+        eflags = ApplyLogicFlags(eflags, result, size, carry: s == 0);
+        return result;
+    }
+
+    /// <summary>BLSR: reset the lowest set bit, <c>dest = (src - 1) &amp; src</c>. CF = (src == 0).</summary>
+    public static ulong Blsr(ulong src, GprOperandSize size, ref uint eflags)
+    {
+        var mask = WidthMask(size);
+        var s = src & mask;
+        var result = ((s - 1) & s) & mask;
+        eflags = ApplyLogicFlags(eflags, result, size, carry: s == 0);
+        return result;
+    }
+
+    /// <summary>
+    /// BEXTR: extract <c>len</c> bits of <paramref name="src"/> starting at bit <c>start</c>, where
+    /// start = control[7:0] and len = control[15:8]. Only ZF (per result) and cleared CF/OF are defined.
+    /// </summary>
+    public static ulong Bextr(ulong src, ulong control, GprOperandSize size, ref uint eflags)
+    {
+        var bits = WidthBits(size);
+        var start = (int)(control & 0xFF);
+        var length = (int)((control >> 8) & 0xFF);
+
+        ulong result;
+        if (start >= bits)
+        {
+            result = 0;
+        }
+        else
+        {
+            var shifted = (src & WidthMask(size)) >> start;
+            if (length == 0)
+            {
+                result = 0;
+            }
+            else if (length >= bits)
+            {
+                result = shifted;
+            }
+            else
+            {
+                result = shifted & ((1UL << length) - 1);
+            }
+        }
+
+        result &= WidthMask(size);
+        eflags = WithFlag(eflags, FlagZero, result == 0);
+        eflags = WithFlag(eflags, FlagCarry, false);
+        eflags = WithFlag(eflags, FlagOverflow, false);
+        return result;
+    }
+
+    /// <summary>
+    /// BZHI: zero the bits of <paramref name="src"/> from bit position <c>index[7:0]</c> upward.
+    /// CF is set when the requested position is at or beyond the operand width.
+    /// </summary>
+    public static ulong Bzhi(ulong src, ulong index, GprOperandSize size, ref uint eflags)
+    {
+        var bits = WidthBits(size);
+        var mask = WidthMask(size);
+        var s = src & mask;
+        var n = (int)(index & 0xFF);
+
+        ulong result;
+        bool carry;
+        if (n >= bits)
+        {
+            result = s;
+            carry = true;
+        }
+        else
+        {
+            result = s & ((1UL << n) - 1);
+            carry = false;
+        }
+
+        eflags = ApplyLogicFlags(eflags, result, size, carry);
+        return result;
+    }
+
+    /// <summary>TZCNT: count trailing zero bits. If src == 0 the result is the operand width and CF is set.</summary>
+    public static ulong Tzcnt(ulong src, GprOperandSize size, ref uint eflags)
+    {
+        var bits = WidthBits(size);
+        var s = src & WidthMask(size);
+
+        ulong result;
+        bool carry;
+        if (s == 0)
+        {
+            result = (ulong)bits;
+            carry = true;
+        }
+        else
+        {
+            result = (ulong)(size == GprOperandSize.Bits64
+                ? BitOperations.TrailingZeroCount(s)
+                : BitOperations.TrailingZeroCount((uint)s));
+            carry = false;
+        }
+
+        eflags = WithFlag(eflags, FlagCarry, carry);
+        eflags = WithFlag(eflags, FlagZero, result == 0);
+        return result;
+    }
+
+    /// <summary>LZCNT: count leading zero bits. If src == 0 the result is the operand width and CF is set.</summary>
+    public static ulong Lzcnt(ulong src, GprOperandSize size, ref uint eflags)
+    {
+        var bits = WidthBits(size);
+        var s = src & WidthMask(size);
+
+        ulong result;
+        bool carry;
+        if (s == 0)
+        {
+            result = (ulong)bits;
+            carry = true;
+        }
+        else
+        {
+            result = (ulong)(size == GprOperandSize.Bits64
+                ? BitOperations.LeadingZeroCount(s)
+                : BitOperations.LeadingZeroCount((uint)s));
+            carry = false;
+        }
+
+        eflags = WithFlag(eflags, FlagCarry, carry);
+        eflags = WithFlag(eflags, FlagZero, result == 0);
+        return result;
+    }
+
+    /// <summary>RORX: rotate <paramref name="src"/> right by <paramref name="count"/> (masked to the operand width). No flags.</summary>
+    public static ulong Rorx(ulong src, int count, GprOperandSize size)
+    {
+        var bits = WidthBits(size);
+        var mask = WidthMask(size);
+        var s = src & mask;
+        var rotate = count & (bits - 1);
+        if (rotate == 0)
+        {
+            return s;
+        }
+
+        return ((s >> rotate) | (s << (bits - rotate))) & mask;
+    }
+
+    /// <summary>SARX: arithmetic shift right by <paramref name="count"/> (masked to the operand width). No flags.</summary>
+    public static ulong Sarx(ulong src, int count, GprOperandSize size)
+    {
+        var bits = WidthBits(size);
+        var mask = WidthMask(size);
+        var shift = count & (bits - 1);
+        if (size == GprOperandSize.Bits64)
+        {
+            return (ulong)((long)src >> shift);
+        }
+
+        return (ulong)(uint)((int)(uint)src >> shift) & mask;
+    }
+
+    /// <summary>SHLX: logical shift left by <paramref name="count"/> (masked to the operand width). No flags.</summary>
+    public static ulong Shlx(ulong src, int count, GprOperandSize size)
+    {
+        var bits = WidthBits(size);
+        var mask = WidthMask(size);
+        var shift = count & (bits - 1);
+        return (src << shift) & mask;
+    }
+
+    /// <summary>SHRX: logical shift right by <paramref name="count"/> (masked to the operand width). No flags.</summary>
+    public static ulong Shrx(ulong src, int count, GprOperandSize size)
+    {
+        var bits = WidthBits(size);
+        var mask = WidthMask(size);
+        var s = src & mask;
+        var shift = count & (bits - 1);
+        return s >> shift;
+    }
+
+    /// <summary>PDEP: deposit contiguous low bits of <paramref name="src"/> into the positions selected by <paramref name="mask"/>. No flags.</summary>
+    public static ulong Pdep(ulong src, ulong mask, GprOperandSize size)
+    {
+        var bits = WidthBits(size);
+        var selector = mask & WidthMask(size);
+        ulong result = 0;
+        var bit = 0;
+        for (var i = 0; i < bits; i++)
+        {
+            var position = 1UL << i;
+            if ((selector & position) != 0)
+            {
+                if (((src >> bit) & 1UL) != 0)
+                {
+                    result |= position;
+                }
+
+                bit++;
+            }
+        }
+
+        return result & WidthMask(size);
+    }
+
+    /// <summary>PEXT: gather the bits of <paramref name="src"/> selected by <paramref name="mask"/> into contiguous low bits. No flags.</summary>
+    public static ulong Pext(ulong src, ulong mask, GprOperandSize size)
+    {
+        var bits = WidthBits(size);
+        var selector = mask & WidthMask(size);
+        ulong result = 0;
+        var bit = 0;
+        for (var i = 0; i < bits; i++)
+        {
+            if ((selector & (1UL << i)) != 0)
+            {
+                if (((src >> i) & 1UL) != 0)
+                {
+                    result |= 1UL << bit;
+                }
+
+                bit++;
+            }
+        }
+
+        return result & WidthMask(size);
+    }
+}

src/SharpEmu.Core/Cpu/Emulation/GprOperandSize.cs

@@ -0,0 +1,14 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Core.Cpu.Emulation;
+
+/// <summary>
+/// Operand width for the emulated general-purpose-register instructions. The numeric value is the
+/// bit width, so it can double as the "count leading/trailing zeros of an all-zero source" result.
+/// </summary>
+public enum GprOperandSize
+{
+    Bits32 = 32,
+    Bits64 = 64,
+}

src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Diagnostics.cs

@@ -7,8 +7,8 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Runtime.InteropServices;
 using System.Threading;
+using SharpEmu.Core.Cpu.Disasm;
 using SharpEmu.HLE;
-using SharpEmu.HLE.Host;
 using SharpEmu.Logging;
 
 namespace SharpEmu.Core.Cpu.Native;
@@ -17,6 +17,55 @@ public sealed partial class DirectExecutionBackend
 {
 	private static readonly ConcurrentDictionary<ulong, byte> _knownExecutablePages = new();
 
+	private static readonly bool _perfHleHistogram =
+		string.Equals(System.Environment.GetEnvironmentVariable("SHARPEMU_PERF_HLE"), "1", System.StringComparison.Ordinal);
+	private static readonly System.Collections.Concurrent.ConcurrentDictionary<string, long> _perfHleCounts = new();
+	private static long _perfHleTotal;
+	private static long _perfHleDispatchTicks;
+
+	private static void RecordPerfHleDispatchTime(long ticks)
+	{
+		var total = System.Threading.Interlocked.Add(ref _perfHleDispatchTicks, ticks);
+		var calls = System.Threading.Interlocked.Read(ref _perfHleTotal);
+		if (calls > 0 && calls % 500000 == 0)
+		{
+			var avgUs = (double)total / System.Diagnostics.Stopwatch.Frequency * 1_000_000.0 / calls;
+			System.Console.Error.WriteLine($"[PERF][HLE] managed_dispatch_avg={avgUs:F3}us total_managed_s={(double)total / System.Diagnostics.Stopwatch.Frequency:F2}");
+		}
+	}
+
+	private static readonly bool _perfHleNoDict =
+		string.Equals(System.Environment.GetEnvironmentVariable("SHARPEMU_PERF_HLE_NODICT"), "1", System.StringComparison.Ordinal);
+
+	private static void RecordPerfHleCall(string name)
+	{
+		var total = System.Threading.Interlocked.Increment(ref _perfHleTotal);
+		if (!_perfHleNoDict)
+		{
+			_perfHleCounts.AddOrUpdate(name, 1, static (_, v) => v + 1);
+		}
+
+		if (total % 500000 == 0 && !_perfHleNoDict)
+		{
+			// Snapshot via foreach (a safe moving enumerator) before sorting.
+			// LINQ over a ConcurrentDictionary uses ICollection.CopyTo, which
+			// throws ArgumentException if another thread adds a key between the
+			// Count read and the copy — that exception was being swallowed into
+			// a CPU_TRAP return and crashing the guest.
+			var snapshot = new System.Collections.Generic.List<System.Collections.Generic.KeyValuePair<string, long>>(_perfHleCounts.Count + 16);
+			foreach (var kvp in _perfHleCounts)
+			{
+				snapshot.Add(kvp);
+			}
+
+			var top = snapshot
+				.OrderByDescending(kvp => kvp.Value)
+				.Take(20)
+				.Select(kvp => $"{kvp.Key}={kvp.Value}");
+			System.Console.Error.WriteLine($"[PERF][HLE] total={total} top: {string.Join(", ", top)}");
+		}
+	}
+
 	private void RecordRecentImportTrace(
 		long dispatchIndex,
 		string nid,
@@ -25,101 +74,40 @@ public sealed partial class DirectExecutionBackend
 		ulong arg1,
 		ulong arg2)
 	{
-		_recentImportTrace[_recentImportTraceWriteIndex] = new RecentImportTraceEntry(
+		var trace = _recentImportTrace;
+		trace[_recentImportTraceWriteIndex] = new RecentImportTraceEntry(
 			dispatchIndex,
 			nid,
 			returnRip,
 			arg0,
 			arg1,
-			arg2);
-		_recentImportTraceWriteIndex = (_recentImportTraceWriteIndex + 1) % _recentImportTrace.Length;
-		if (_recentImportTraceCount < _recentImportTrace.Length)
+			arg2,
+			GuestThreadExecution.CurrentGuestThreadHandle,
+			Environment.CurrentManagedThreadId);
+		_recentImportTraceWriteIndex = (_recentImportTraceWriteIndex + 1) % trace.Length;
+		if (_recentImportTraceCount < trace.Length)
 		{
 			_recentImportTraceCount++;
 		}
 	}
 
-	private void RecordDeferredBootstrapTrace(
-		long dispatchIndex,
-		ulong op,
-		ulong symbolPointer,
-		ulong outputPointer,
-		ulong returnRip)
-	{
-		lock (_deferredBootstrapTraceGate)
-		{
-			_deferredBootstrapTrace[_deferredBootstrapTraceWriteIndex] = new DeferredBootstrapTraceEntry(
-				dispatchIndex,
-				op,
-				symbolPointer,
-				outputPointer,
-				returnRip);
-			_deferredBootstrapTraceWriteIndex =
-				(_deferredBootstrapTraceWriteIndex + 1) % _deferredBootstrapTrace.Length;
-			if (_deferredBootstrapTraceCount < _deferredBootstrapTrace.Length)
-			{
-				_deferredBootstrapTraceCount++;
-			}
-		}
-	}
-
-	private void DrainDeferredBootstrapTraces()
-	{
-		if (!_logBootstrap)
-		{
-			return;
-		}
-
-		DeferredBootstrapTraceEntry[] pending;
-		lock (_deferredBootstrapTraceGate)
-		{
-			if (_deferredBootstrapTraceCount == 0)
-			{
-				return;
-			}
-
-			pending = new DeferredBootstrapTraceEntry[_deferredBootstrapTraceCount];
-			var readIndex = (_deferredBootstrapTraceWriteIndex - _deferredBootstrapTraceCount +
-				_deferredBootstrapTrace.Length) % _deferredBootstrapTrace.Length;
-			for (var i = 0; i < _deferredBootstrapTraceCount; i++)
-			{
-				pending[i] = _deferredBootstrapTrace[(readIndex + i) % _deferredBootstrapTrace.Length];
-			}
-
-			_deferredBootstrapTraceCount = 0;
-		}
-
-		foreach (var entry in pending)
-		{
-			var symbolText = "<unreadable>";
-			if (TryReadAsciiZ(entry.SymbolPointer, 256, out var sym))
-			{
-				symbolText = sym;
-			}
-
-			Console.Error.WriteLine(
-				$"[LOADER][TRACE] bootstrap_call#{entry.DispatchIndex}: op=0x{entry.Op:X16} " +
-				$"sym_ptr=0x{entry.SymbolPointer:X16} sym='{symbolText}' " +
-				$"out_ptr=0x{entry.OutputPointer:X16} ret=0x{entry.ReturnRip:X16}");
-		}
-	}
-
 	private void DumpRecentImportTrace()
 	{
-		if (_recentImportTraceCount == 0)
+		var trace = _recentImportTrace;
+		if (trace is null || _recentImportTraceCount == 0)
 		{
 			return;
 		}
-		Log.Info($"   Recent import calls ({_recentImportTraceCount}):");
-		int num = (_recentImportTraceWriteIndex - _recentImportTraceCount + _recentImportTrace.Length) % _recentImportTrace.Length;
+		Log.Info($"   Recent import calls for managed={Environment.CurrentManagedThreadId} guest=0x{GuestThreadExecution.CurrentGuestThreadHandle:X16} ({_recentImportTraceCount}):");
+		int num = (_recentImportTraceWriteIndex - _recentImportTraceCount + trace.Length) % trace.Length;
 		for (int i = 0; i < _recentImportTraceCount; i++)
 		{
-			int num2 = (num + i) % _recentImportTrace.Length;
-			var entry = _recentImportTrace[num2];
+			int num2 = (num + i) % trace.Length;
+			var entry = trace[num2];
 			if (!string.IsNullOrEmpty(entry.Nid))
 			{
 				Log.Info(
-					$"     #{entry.DispatchIndex} nid={entry.Nid} ret=0x{entry.ReturnRip:X16} " +
+					$"     #{entry.DispatchIndex} managed={entry.ManagedThreadId} guest=0x{entry.GuestThreadHandle:X16} nid={entry.Nid} ret=0x{entry.ReturnRip:X16} " +
 					$"rdi=0x{entry.Arg0:X16} rsi=0x{entry.Arg1:X16} rdx=0x{entry.Arg2:X16}");
 			}
 		}
@@ -135,9 +123,8 @@ public sealed partial class DirectExecutionBackend
 		int num2 = 0;
 		List<ulong> list = new List<ulong>(16);
 		ulong num3 = scanStart;
-		var hostMemory = ResolveDiagnosticsHostMemory();
-		HostRegionInfo lpBuffer;
-		while (num3 < scanEnd && hostMemory.Query(num3, out lpBuffer))
+		MEMORY_BASIC_INFORMATION64 lpBuffer;
+		while (num3 < scanEnd && VirtualQuery((void*)num3, out lpBuffer, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) != 0)
 		{
 			ulong baseAddress = lpBuffer.BaseAddress;
 			ulong num4 = baseAddress + lpBuffer.RegionSize;
@@ -147,7 +134,7 @@ public sealed partial class DirectExecutionBackend
 			}
 			ulong value = Math.Max(num3, baseAddress);
 			ulong num5 = Math.Min(num4, scanEnd);
-			if (lpBuffer.State == HostRegionState.Committed && IsReadableProtection(lpBuffer.RawProtection) && !IsExecutableProtection(lpBuffer.RawProtection))
+			if (lpBuffer.State == 4096 && IsReadableProtection(lpBuffer.Protect) && !IsExecutableProtection(lpBuffer.Protect))
 			{
 				ulong num6 = AlignUp(value, 8uL);
 				for (ulong num7 = num6; num7 + 8 <= num5; num7 += 8)
@@ -186,6 +173,50 @@ public sealed partial class DirectExecutionBackend
 		{
 			return;
 		}
+		const int preludeSize = 192;
+		Span<byte> prelude = stackalloc byte[preludeSize];
+		if (returnRip >= preludeSize && cpuContext.Memory.TryRead(returnRip - preludeSize, prelude))
+		{
+			Console.Error.WriteLine(
+				$"[LOADER][TRACE] Import#{dispatchIndex} pre-return bytes @0x{returnRip - preludeSize:X16}: " +
+				BitConverter.ToString(prelude.ToArray()).Replace("-", " "));
+
+			List<DecodedInst>? bestCallChain = null;
+			var preludeAddress = returnRip - preludeSize;
+			for (var startOffset = 0; startOffset < preludeSize; startOffset++)
+			{
+				var cursor = preludeAddress + (ulong)startOffset;
+				var candidate = new List<DecodedInst>();
+				while (cursor < returnRip && candidate.Count < 96 &&
+					IcedDecoder.TryReadGuestBytes(cpuContext.Memory, cursor, 15, out var instructionBytes) &&
+					IcedDecoder.TryDecode(cursor, instructionBytes, out var instruction) &&
+					instruction.Length > 0 &&
+					cursor + (ulong)instruction.Length <= returnRip)
+				{
+					candidate.Add(instruction);
+					cursor += (ulong)instruction.Length;
+				}
+
+				if (cursor == returnRip &&
+					candidate.Count > 0 &&
+					string.Equals(candidate[^1].Mnemonic, "Call", StringComparison.OrdinalIgnoreCase) &&
+					(bestCallChain is null || candidate.Count > bestCallChain.Count))
+				{
+					bestCallChain = candidate;
+				}
+			}
+
+			if (bestCallChain is not null)
+			{
+				Console.Error.WriteLine($"[LOADER][TRACE] Import#{dispatchIndex} pre-return disassembly:");
+				foreach (var instruction in bestCallChain.TakeLast(32))
+				{
+					Console.Error.WriteLine(
+						$"[LOADER][TRACE]   0x{instruction.Rip:X16}: {instruction.Text} " +
+						$"bytes={IcedDecoder.FormatBytes(instruction.Bytes)}");
+				}
+			}
+		}
 		Span<byte> destination = stackalloc byte[128];
 		if (!cpuContext.Memory.TryRead(returnRip, destination))
 		{
@@ -237,15 +268,14 @@ public sealed partial class DirectExecutionBackend
 			ulong callRip = returnRip + (ulong)i;
 			ulong target = unchecked((ulong)((long)(callRip + 5) + rel32));
 			Log.Debug($"Import#{dispatchIndex} near-call @{callRip:X16}: target=0x{target:X16}");
-			var importEntries = _importEntries;
-			for (int importIndex = 0; importIndex < importEntries.Length; importIndex++)
+			for (int importIndex = 0; importIndex < _importEntries.Length; importIndex++)
 			{
-				if (importEntries[importIndex].Address != target)
+				if (_importEntries[importIndex].Address != target)
 				{
 					continue;
 				}
 
-				string nid = importEntries[importIndex].Nid;
+				string nid = _importEntries[importIndex].Nid;
 				if (_moduleManager.TryGetExport(nid, out var export))
 				{
 					Log.Debug(
@@ -272,14 +302,14 @@ public sealed partial class DirectExecutionBackend
 					{
 						Log.Debug(
 							$"Import#{dispatchIndex} near-call PLT slot: [0x{slot:X16}] = 0x{slotTarget:X16}");
-						for (int importIndex = 0; importIndex < importEntries.Length; importIndex++)
+						for (int importIndex = 0; importIndex < _importEntries.Length; importIndex++)
 						{
-							if (importEntries[importIndex].Address != slotTarget)
+							if (_importEntries[importIndex].Address != slotTarget)
 							{
 								continue;
 							}
 
-							string nid = importEntries[importIndex].Nid;
+							string nid = _importEntries[importIndex].Nid;
 							if (_moduleManager.TryGetExport(nid, out var export))
 							{
 								Log.Debug(
@@ -303,6 +333,28 @@ public sealed partial class DirectExecutionBackend
 		return value == 65534 || value == 4294967294u || value == 18446744073709551614uL;
 	}
 
+	private static ulong ParseOptionalHexAddress(string? value)
+	{
+		if (string.IsNullOrWhiteSpace(value))
+		{
+			return 0;
+		}
+
+		var text = value.Trim();
+		if (text.StartsWith("0x", StringComparison.OrdinalIgnoreCase))
+		{
+			text = text[2..];
+		}
+
+		return ulong.TryParse(
+			text,
+			System.Globalization.NumberStyles.HexNumber,
+			System.Globalization.CultureInfo.InvariantCulture,
+			out var address)
+			? address
+			: 0;
+	}
+
 	private static bool IsPlausibleReturnAddress(ulong address)
 	{
 		return address >= 12884901888L && address < 17592186044416L && !IsUnresolvedSentinel(address);
@@ -352,7 +404,7 @@ public sealed partial class DirectExecutionBackend
 		{
 			return false;
 		}
-		if (!ResolveDiagnosticsHostMemory().Query(address, out var lpBuffer))
+		if (VirtualQuery((void*)address, out var lpBuffer, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) == 0)
 		{
 			return false;
 		}
@@ -361,7 +413,7 @@ public sealed partial class DirectExecutionBackend
 		{
 			return false;
 		}
-		if (lpBuffer.State != HostRegionState.Committed || !IsReadableProtection(lpBuffer.RawProtection))
+		if (lpBuffer.State != 4096 || !IsReadableProtection(lpBuffer.Protect))
 		{
 			return false;
 		}
@@ -393,12 +445,12 @@ public sealed partial class DirectExecutionBackend
 			return true;
 		}
 
-		if (!ResolveDiagnosticsHostMemory().Query(address, out var lpBuffer))
+		if (VirtualQuery((void*)address, out var lpBuffer, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) == 0)
 		{
 			return false;
 		}
 
-		var executable = lpBuffer.State == HostRegionState.Committed && IsExecutableProtection(lpBuffer.RawProtection);
+		var executable = lpBuffer.State == 4096 && IsExecutableProtection(lpBuffer.Protect);
 		if (executable)
 		{
 			_knownExecutablePages.TryAdd(pageAddress, 0);
@@ -417,14 +469,6 @@ public sealed partial class DirectExecutionBackend
 		return (value + num) & ~num;
 	}
 
-	// Diagnostics helpers are static (reachable from static handler paths), so
-	// they use the platform injected into the backend active on this thread and
-	// fall back to the process-wide singleton only when no run is bound.
-	private static IHostMemory ResolveDiagnosticsHostMemory()
-	{
-		return _activeExecutionBackend?._hostMemory ?? HostPlatform.Current.Memory;
-	}
-
 	private static bool IsReadableProtection(uint protect)
 	{
 		if ((protect & 0x100) != 0 || (protect & 1) != 0)

src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Exceptions.cs

@@ -9,9 +9,7 @@ using System.Reflection;
 using System.Runtime.InteropServices;
 using System.Threading;
 using SharpEmu.Core.Cpu.Disasm;
-using SharpEmu.Core.Cpu.Native.Windows;
 using SharpEmu.HLE;
-using SharpEmu.HLE.Host;
 
 namespace SharpEmu.Core.Cpu.Native;
 
@@ -19,6 +17,8 @@ public sealed partial class DirectExecutionBackend
 {
 	private const ulong LazyCommitWindowBytes = 0x0200_0000UL;
 	private static int _lazyCommitTraceCount;
+	private static int _guestAllocatorHoleRecoveries;
+	private static int _auxiliaryThreadExecuteFaultRecoveries;
 
 	private unsafe void SetupExceptionHandler()
 	{
@@ -30,12 +30,12 @@ public sealed partial class DirectExecutionBackend
 
 		if (!string.Equals(Environment.GetEnvironmentVariable("SHARPEMU_DISABLE_RAW_HANDLER"), "1", StringComparison.Ordinal))
 		{
-			_rawExceptionHandlerStub = _faultHandling.CreateHandlerThunk(RawVectoredHandlerPtrManaged, _hostRspSlotTlsIndex, _tlsGetValueAddress);
+			_rawExceptionHandlerStub = CreateExceptionHandlerTrampoline(RawVectoredHandlerPtrManaged);
 			if (_rawExceptionHandlerStub == 0)
 			{
 				throw new InvalidOperationException("Failed to create raw exception handler trampoline");
 			}
-			_rawExceptionHandler = _faultHandling.AddFirstChanceHandler(_rawExceptionHandlerStub);
+			_rawExceptionHandler = (nint)AddVectoredExceptionHandler(1u, _rawExceptionHandlerStub);
 			Console.Error.WriteLine($"[LOADER][INFO] Raw exception handler installed: 0x{_rawExceptionHandler:X16}");
 		}
 		else
@@ -45,22 +45,22 @@ public sealed partial class DirectExecutionBackend
 
 		_handlerDelegate = VectoredHandler;
 		_handlerHandle = GCHandle.Alloc(_handlerDelegate);
-		_exceptionHandlerStub = _faultHandling.CreateHandlerThunk(Marshal.GetFunctionPointerForDelegate(_handlerDelegate), _hostRspSlotTlsIndex, _tlsGetValueAddress);
+		_exceptionHandlerStub = CreateExceptionHandlerTrampoline(Marshal.GetFunctionPointerForDelegate(_handlerDelegate));
 		if (_exceptionHandlerStub == 0)
 		{
 			throw new InvalidOperationException("Failed to create exception handler trampoline");
 		}
-		_exceptionHandler = _faultHandling.AddFirstChanceHandler(_exceptionHandlerStub);
+		_exceptionHandler = (nint)AddVectoredExceptionHandler(1u, _exceptionHandlerStub);
 		Console.Error.WriteLine($"[LOADER][INFO] Exception handler installed: 0x{_exceptionHandler:X16}");
 
 		_unhandledFilterDelegate = UnhandledExceptionFilter;
 		_unhandledFilterHandle = GCHandle.Alloc(_unhandledFilterDelegate);
-		_unhandledFilterStub = _faultHandling.CreateHandlerThunk(Marshal.GetFunctionPointerForDelegate(_unhandledFilterDelegate), _hostRspSlotTlsIndex, _tlsGetValueAddress);
+		_unhandledFilterStub = CreateExceptionHandlerTrampoline(Marshal.GetFunctionPointerForDelegate(_unhandledFilterDelegate));
 		if (_unhandledFilterStub == 0)
 		{
 			throw new InvalidOperationException("Failed to create unhandled exception filter trampoline");
 		}
-		_faultHandling.SetUnhandledFilter(_unhandledFilterStub);
+		SetUnhandledExceptionFilter(_unhandledFilterStub);
 	}
 
 	private unsafe int UnhandledExceptionFilter(void* exceptionInfo)
@@ -68,8 +68,8 @@ public sealed partial class DirectExecutionBackend
 		try
 		{
 			EXCEPTION_RECORD* exceptionRecord = ((EXCEPTION_POINTERS*)exceptionInfo)->ExceptionRecord;
-			ulong rip = ReadCtxU64(((EXCEPTION_POINTERS*)exceptionInfo)->ContextRecord, CTX_RIP);
-			ulong rsp = ReadCtxU64(((EXCEPTION_POINTERS*)exceptionInfo)->ContextRecord, CTX_RSP);
+			ulong rip = ReadCtxU64(((EXCEPTION_POINTERS*)exceptionInfo)->ContextRecord, 248);
+			ulong rsp = ReadCtxU64(((EXCEPTION_POINTERS*)exceptionInfo)->ContextRecord, 152);
 			Console.Error.WriteLine("[LOADER][FATAL] Unhandled exception filter fired.");
 			Console.Error.WriteLine($"[LOADER][FATAL]   Code: 0x{exceptionRecord->ExceptionCode:X8}");
 			Console.Error.WriteLine($"[LOADER][FATAL]   Exception Address: 0x{(ulong)(nint)exceptionRecord->ExceptionAddress:X16}");
@@ -108,19 +108,28 @@ public sealed partial class DirectExecutionBackend
 				return 0;
 			}
 
-			ulong rip = ReadCtxU64(contextRecord, CTX_RIP);
-			ulong rsp = ReadCtxU64(contextRecord, CTX_RSP);
-
-			// Thread-mode probe: a hardware exception raised while this thread is inside
-			// the managed import gateway means the VEH->managed reentry happened from
-			// cooperative GC mode — a ReversePInvokeBadTransition candidate.
-			if (LogThreadMode && _threadModeGatewayDepth > 0)
+			ulong rip = ReadCtxU64(contextRecord, 248);
+			ulong rsp = ReadCtxU64(contextRecord, 152);
+			if (TryRecoverGuestInt41(exceptionCode, contextRecord, rip))
 			{
-				TraceThreadMode(
-					$"veh_in_gateway code=0x{exceptionCode:X8} rip=0x{rip:X16} gateway_depth={_threadModeGatewayDepth}");
+				return -1;
+			}
+			if (TryRecoverAuxiliaryThreadExecuteFault(exceptionRecord, contextRecord, rip))
+			{
+				return -1;
 			}
 
-			if (exceptionCode == WindowsFaultCodes.AccessViolation && TryHandleLazyCommittedPage(exceptionRecord, rip, rsp))
+			if (exceptionCode == 3221225477u && TryHandleLazyCommittedPage(exceptionRecord, rip, rsp))
+			{
+				return -1;
+			}
+			if (exceptionCode == 3221225477u &&
+				TryRecoverGuestAllocatorHole(exceptionRecord, contextRecord, rip))
+			{
+				return -1;
+			}
+			if (exceptionCode == StatusIllegalInstruction &&
+				TryRecoverIllegalInstruction(contextRecord, rip))
 			{
 				return -1;
 			}
@@ -135,10 +144,10 @@ public sealed partial class DirectExecutionBackend
 
 			switch (exceptionCode)
 			{
-				case WindowsFaultCodes.AccessViolation:
+				case 3221225477u:
 					LogAccessViolationTrace(exceptionAddress, exceptionRecord);
 					break;
-				case WindowsFaultCodes.FastFail:
+				case 3221226505u:
 					{
 						ulong p0 = exceptionRecord->NumberParameters >= 1 ? (*exceptionRecord->ExceptionInformation) : 0;
 						ulong p1 = exceptionRecord->NumberParameters >= 2 ? exceptionRecord->ExceptionInformation[1] : 0;
@@ -148,27 +157,56 @@ public sealed partial class DirectExecutionBackend
 					}
 			}
 
-			ulong rax = ReadCtxU64(contextRecord, CTX_RAX);
-			ulong rbx = ReadCtxU64(contextRecord, CTX_RBX);
-			ulong rcx = ReadCtxU64(contextRecord, CTX_RCX);
-			ulong rdx = ReadCtxU64(contextRecord, CTX_RDX);
-			ulong rsi = ReadCtxU64(contextRecord, CTX_RSI);
-			ulong rdi = ReadCtxU64(contextRecord, CTX_RDI);
-			ulong rbp = ReadCtxU64(contextRecord, CTX_RBP);
-			ulong r8 = ReadCtxU64(contextRecord, CTX_R8);
-			ulong r9 = ReadCtxU64(contextRecord, CTX_R9);
-			ulong r10 = ReadCtxU64(contextRecord, CTX_R10);
-			ulong r11 = ReadCtxU64(contextRecord, CTX_R11);
-			ulong r12 = ReadCtxU64(contextRecord, CTX_R12);
-			ulong r13 = ReadCtxU64(contextRecord, CTX_R13);
-			ulong r14 = ReadCtxU64(contextRecord, CTX_R14);
-			ulong r15 = ReadCtxU64(contextRecord, CTX_R15);
+			ulong rax = ReadCtxU64(contextRecord, 120);
+			ulong rbx = ReadCtxU64(contextRecord, 144);
+			ulong rcx = ReadCtxU64(contextRecord, 128);
+			ulong rdx = ReadCtxU64(contextRecord, 136);
+			ulong rsi = ReadCtxU64(contextRecord, 168);
+			ulong rdi = ReadCtxU64(contextRecord, 176);
+			ulong rbp = ReadCtxU64(contextRecord, 160);
+			ulong r8 = ReadCtxU64(contextRecord, 184);
+			ulong r9 = ReadCtxU64(contextRecord, 192);
+			ulong r10 = ReadCtxU64(contextRecord, 200);
+			ulong r11 = ReadCtxU64(contextRecord, 208);
+			ulong r12 = ReadCtxU64(contextRecord, 216);
+			ulong r13 = ReadCtxU64(contextRecord, 224);
+			ulong r14 = ReadCtxU64(contextRecord, 232);
+			ulong r15 = ReadCtxU64(contextRecord, 240);
 
 			Console.Error.WriteLine("[LOADER][INFO] =========================================");
 			Console.Error.WriteLine("[LOADER][INFO] NATIVE EXCEPTION CAUGHT!");
 			Console.Error.WriteLine($"[LOADER][INFO]   Code: 0x{exceptionCode:X8}");
 			Console.Error.WriteLine($"[LOADER][INFO]   Exception Address: 0x{exceptionAddress:X16}");
 			Console.Error.WriteLine($"[LOADER][INFO]   RIP: 0x{rip:X16}");
+			Console.Error.WriteLine(
+				$"[LOADER][INFO]   Host thread: managed={Environment.CurrentManagedThreadId} " +
+				$"name='{Thread.CurrentThread.Name ?? "<unnamed>"}'");
+			if (_activeGuestThreadState is { } activeGuestThread)
+			{
+				Console.Error.WriteLine(
+					$"[LOADER][INFO]   Guest thread: handle=0x{activeGuestThread.ThreadHandle:X16} " +
+					$"name='{activeGuestThread.Name}' state={activeGuestThread.State} " +
+					$"last_import={activeGuestThread.LastImportNid ?? "<none>"} " +
+					$"last_ret=0x{activeGuestThread.LastReturnRip:X16}");
+				Console.Error.WriteLine(
+					$"[LOADER][INFO]   Last import registers: " +
+					$"rax=0x{Volatile.Read(ref activeGuestThread.LastImportRax):X16} " +
+					$"result_valid={Volatile.Read(ref activeGuestThread.LastImportResultValid) != 0} " +
+					$"rdi=0x{activeGuestThread.LastImportRdi:X16} " +
+					$"rsi=0x{activeGuestThread.LastImportRsi:X16} " +
+					$"rdx=0x{activeGuestThread.LastImportRdx:X16} " +
+					$"rcx=0x{activeGuestThread.LastImportRcx:X16} " +
+					$"r8=0x{activeGuestThread.LastImportR8:X16} " +
+					$"r9=0x{activeGuestThread.LastImportR9:X16}");
+				Console.Error.WriteLine(
+					$"[LOADER][INFO]   Last import stack args: " +
+					$"0=0x{activeGuestThread.LastImportStack0:X16} " +
+					$"1=0x{activeGuestThread.LastImportStack1:X16} " +
+					$"2=0x{activeGuestThread.LastImportStack2:X16} " +
+					$"3=0x{activeGuestThread.LastImportStack3:X16} " +
+					$"4=0x{activeGuestThread.LastImportStack4:X16} " +
+					$"5=0x{activeGuestThread.LastImportStack5:X16}");
+			}
 			if (TryFormatNearestRuntimeSymbol(rip, out string symbol))
 			{
 				Console.Error.WriteLine("[LOADER][INFO]   RIP symbol: " + symbol);
@@ -193,7 +231,7 @@ public sealed partial class DirectExecutionBackend
 
 			ulong accessType = 0;
 			ulong target = 0;
-			if (exceptionCode == WindowsFaultCodes.AccessViolation && exceptionRecord->NumberParameters >= 2)
+			if (exceptionCode == 3221225477u && exceptionRecord->NumberParameters >= 2)
 			{
 				accessType = *exceptionRecord->ExceptionInformation;
 				target = exceptionRecord->ExceptionInformation[1];
@@ -206,9 +244,9 @@ public sealed partial class DirectExecutionBackend
 				};
 				Console.Error.WriteLine("[LOADER][INFO]   AV access: " + accessText);
 				Console.Error.WriteLine($"[LOADER][INFO]   AV target: 0x{target:X16}");
-				if (_hostMemory.Query(target, out var mbi))
+				if (VirtualQuery((void*)target, out var mbi, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) != 0)
 				{
-					Console.Error.WriteLine($"[LOADER][INFO]   AV target region: base=0x{mbi.BaseAddress:X16} size=0x{mbi.RegionSize:X16} state=0x{mbi.RawState:X08} protect=0x{mbi.RawProtection:X08}");
+					Console.Error.WriteLine($"[LOADER][INFO]   AV target region: base=0x{mbi.BaseAddress:X16} size=0x{mbi.RegionSize:X16} state=0x{mbi.State:X08} protect=0x{mbi.Protect:X08}");
 				}
 
 			}
@@ -225,13 +263,46 @@ public sealed partial class DirectExecutionBackend
 				Console.Error.WriteLine($"[LOADER][INFO]     [rsp+0x{i * 8:X2}] @0x{stackAddr:X16} = 0x{value:X16}");
 			}
 
+			if (string.Equals(
+					Environment.GetEnvironmentVariable("SHARPEMU_DUMP_FAULT_STACK_WINDOW"),
+					"1",
+					StringComparison.Ordinal))
+			{
+				Console.Error.WriteLine("[LOADER][INFO]   Full fault stack window (RSP-0x300..RSP+0x100):");
+				var windowStart = rsp >= 0x300 ? rsp - 0x300 : 0;
+				for (var stackAddr = windowStart; stackAddr < rsp + 0x100; stackAddr += 8)
+				{
+					if (!TryReadHostQword(stackAddr, out var value))
+					{
+						continue;
+					}
+
+					var relative = unchecked((long)(stackAddr - rsp));
+					var relativeText = relative >= 0
+						? $"+0x{relative:X}"
+						: $"-0x{-relative:X}";
+					var symbolText = TryFormatNearestRuntimeSymbol(value, out var stackSymbol)
+						? $" [{stackSymbol}]"
+						: string.Empty;
+					Console.Error.WriteLine(
+						$"[LOADER][INFO]     [rsp{relativeText}] " +
+						$"@0x{stackAddr:X16} = 0x{value:X16}{symbolText}");
+				}
+			}
+
+			DumpPointerWindow("fault-register-rbx", rbx, 0x60);
+			DumpPointerWindow("fault-register-rsi", rsi, 0x60);
+			DumpPointerWindow("fault-register-rdi", rdi, 0x60);
+			DumpPointerWindow("fault-register-r13", r13, 0x60);
+			DumpPointerWindow("fault-register-r14", r14, 0x60);
+
 			try
 			{
 				Console.Error.WriteLine("[LOADER][INFO]   Frame chain (RBP walk):");
 				ulong frame = rbp;
 				for (int i = 0; i < 12; i++)
 				{
-					if (frame < 140733193388032L || frame > 140737488355327L)
+					if (frame < 0x10000)
 					{
 						break;
 					}
@@ -256,7 +327,7 @@ public sealed partial class DirectExecutionBackend
 
 			switch (exceptionCode)
 			{
-				case WindowsFaultCodes.AccessViolation:
+				case 3221225477u:
 					Console.Error.WriteLine("[LOADER][ERROR]   Type: Access Violation");
 					Console.Error.WriteLine("[LOADER][ERROR]   This usually means:");
 					Console.Error.WriteLine("[LOADER][ERROR]     - Guest code called an unmapped import");
@@ -290,22 +361,57 @@ public sealed partial class DirectExecutionBackend
 						{
 							Console.Error.WriteLine("[LOADER][INFO]   Code window [RIP-0x20..]: " + BitConverter.ToString(window).Replace("-", " "));
 						}
+						for (var stackIndex = 0; stackIndex < 16; stackIndex++)
+						{
+							byte[] stackSlot = new byte[8];
+							if (!TryReadHostBytes(rsp + (ulong)(stackIndex * 8), stackSlot))
+							{
+								continue;
+							}
+							var candidate = BitConverter.ToUInt64(stackSlot);
+							if (candidate < _entryPoint || candidate >= _entryPoint + 0x10000000 || candidate < 24)
+							{
+								continue;
+							}
+							byte[] callSiteWindow = new byte[48];
+							if (TryReadHostBytes(candidate - 24, callSiteWindow))
+							{
+								Console.Error.WriteLine(
+									$"[LOADER][INFO]   Stack guest-code candidate [rsp+0x{stackIndex * 8:X2}]=0x{candidate:X16}, bytes [-0x18..]: " +
+									BitConverter.ToString(callSiteWindow).Replace("-", " "));
+							}
+						}
 					}
 					else
 					{
 						Console.Error.WriteLine("[LOADER][ERROR]   Could not read code at RIP");
 					}
 					DumpRecentImportTrace();
-					DumpGuestDisasmDiagnostics(rip, rbp);
+					DumpGuestDisasmDiagnostics(rip, rbp, rsp);
+					DumpGuestRegisterWindowDiagnostics(
+						rax, rbx, rcx, rdx, rsi, rdi, rbp, rsp,
+						r8, r9, r10, r11, r12, r13, r14, r15);
 					DumpGuestReferenceDiagnostics();
 					DumpGuestPointerWindowDiagnostics();
 					break;
-				case WindowsFaultCodes.Breakpoint:
+				case 2147483651u:
 					Console.Error.WriteLine("[LOADER][WARNING]   Type: Breakpoint (int3)");
 					Console.Error.WriteLine("[LOADER][WARNING]   Unexpected breakpoint in direct-bridge mode");
 					break;
-				case WindowsFaultCodes.IllegalInstruction:
+				case 1073741845u:
+					Console.Error.WriteLine("[LOADER][ERROR]   Type: Abort (SIGABRT)");
+					DumpRecentImportTrace();
+					DumpGuestDisasmDiagnostics(rip, rbp, rsp);
+					break;
+				case 3221225501u:
 					Console.Error.WriteLine("[LOADER][INFO]   Type: Illegal Instruction");
+					byte[] illegalCode = new byte[16];
+					if (TryReadHostBytes(rip, illegalCode))
+					{
+						Console.Error.WriteLine("[LOADER][INFO]   Code at RIP: " + BitConverter.ToString(illegalCode).Replace("-", " "));
+					}
+					DumpRecentImportTrace();
+					DumpGuestDisasmDiagnostics(rip, rbp, rsp);
 					break;
 			}
 
@@ -319,6 +425,108 @@ public sealed partial class DirectExecutionBackend
 		}
 	}
 
+	private unsafe bool TryRecoverAuxiliaryThreadExecuteFault(
+		EXCEPTION_RECORD* exceptionRecord,
+		void* contextRecord,
+		ulong rip)
+	{
+		if (exceptionRecord->ExceptionCode != 3221225477u ||
+			rip >= 0x0000000800000000UL ||
+			_activeGuestThreadState is not { Name: "tbb_thead" } activeThread)
+		{
+			return false;
+		}
+
+		var hostExit = ActiveEntryReturnSentinelRip;
+		if (hostExit < 0x10000)
+		{
+			hostExit = unchecked((ulong)_guestReturnStub);
+		}
+		if (hostExit < 0x10000)
+		{
+			Console.Error.WriteLine(
+				$"[LOADER][WARN] Could not recover auxiliary TBB execute fault: target=0x{rip:X16} " +
+				$"active_exit=0x{ActiveEntryReturnSentinelRip:X16} guest_return_stub=0x{unchecked((ulong)_guestReturnStub):X16}");
+			return false;
+		}
+
+		_ = TryPatchActiveGuestReturnSlot(hostExit);
+		WriteCtxU64(contextRecord, 120, 0);
+		WriteCtxU64(contextRecord, 248, hostExit);
+		var recovery = Interlocked.Increment(ref _auxiliaryThreadExecuteFaultRecoveries);
+		Console.Error.WriteLine(
+			$"[LOADER][WARN] Recovered auxiliary TBB execute fault #{recovery}: " +
+			$"thread=0x{activeThread.ThreadHandle:X16} target=0x{rip:X16} -> host_exit=0x{hostExit:X16}");
+		return true;
+	}
+
+	private unsafe bool TryRecoverGuestInt41(uint exceptionCode, void* contextRecord, ulong rip)
+	{
+		if (!_ignoreGuestInt41 || exceptionCode != 3221225477u || rip < 0x10000)
+		{
+			return false;
+		}
+
+		byte[] opcode = new byte[2];
+		if (!TryReadHostBytes(rip, opcode) || opcode[0] != 0xCD || opcode[1] != 0x41)
+		{
+			return false;
+		}
+
+		var count = Interlocked.Increment(ref _ignoredGuestInt41Count);
+		WriteCtxU64(contextRecord, 248, rip + 2);
+		if (count <= 16 || count % 65536 == 0)
+		{
+			Console.Error.WriteLine(
+				$"[LOADER][WARN] Ignored guest int 0x41 trap #{count} at 0x{rip:X16} (SHARPEMU_IGNORE_INT41=1)");
+			Console.Error.Flush();
+		}
+		return true;
+	}
+
+	private unsafe static bool TryRecoverGuestAllocatorHole(
+		EXCEPTION_RECORD* exceptionRecord,
+		void* contextRecord,
+		ulong rip)
+	{
+		if (string.Equals(
+				Environment.GetEnvironmentVariable("SHARPEMU_DISABLE_GUEST_ALLOCATOR_HOLE_RECOVERY"),
+				"1",
+				StringComparison.Ordinal) ||
+			exceptionRecord->NumberParameters < 2 ||
+			exceptionRecord->ExceptionInformation[0] != 0 ||
+			exceptionRecord->ExceptionInformation[1] != 8 ||
+			ReadCtxU64(contextRecord, CTX_RDI) != 0 ||
+			rip < 0x10000)
+		{
+			return false;
+		}
+
+		// Demon's Souls occasionally leaves an empty payload in a locked pool
+		// tree node. The allocator dereferences payload+8 before reaching its
+		// existing empty-pool fallback. Match the instruction stream instead of
+		// a title-specific absolute address, then resume at that fallback so the
+		// lock is released and the allocator can try its next backing pool.
+		const ulong allocatorHoleSignature = 0x634CFF568D08778BUL;
+		if (*(ulong*)rip != allocatorHoleSignature || *((byte*)rip + 8) != 0xF2)
+		{
+			return false;
+		}
+
+		const ulong emptyPoolFallbackDelta = 0x8E;
+		WriteCtxU64(contextRecord, CTX_RIP, rip + emptyPoolFallbackDelta);
+		var recovery = Interlocked.Increment(ref _guestAllocatorHoleRecoveries);
+		if (recovery <= 16 || (recovery & (recovery - 1)) == 0)
+		{
+			Console.Error.WriteLine(
+				$"[LOADER][WARN] Guest allocator empty-node adapter recovery #{recovery}: " +
+				$"rip=0x{rip:X16} -> 0x{rip + emptyPoolFallbackDelta:X16}");
+			Console.Error.Flush();
+		}
+
+		return true;
+	}
+
 	private static bool IsBenignHostDebugException(uint exceptionCode)
 	{
 		return exceptionCode is DBG_PRINTEXCEPTION_C or DBG_PRINTEXCEPTION_WIDE_C or MS_VC_THREADNAME_EXCEPTION;
@@ -337,8 +545,8 @@ public sealed partial class DirectExecutionBackend
 			EXCEPTION_POINTERS* pointers = (EXCEPTION_POINTERS*)exceptionInfo;
 			EXCEPTION_RECORD* record = pointers->ExceptionRecord;
 			void* contextRecord = pointers->ContextRecord;
-			ulong rip = contextRecord != null ? ReadCtxU64(contextRecord, CTX_RIP) : 0;
-			ulong rsp = contextRecord != null ? ReadCtxU64(contextRecord, CTX_RSP) : 0;
+			ulong rip = contextRecord != null ? ReadCtxU64(contextRecord, 248) : 0;
+			ulong rsp = contextRecord != null ? ReadCtxU64(contextRecord, 152) : 0;
 			ulong accessType = record->NumberParameters >= 1 ? *record->ExceptionInformation : 0;
 			ulong target = record->NumberParameters >= 2 ? record->ExceptionInformation[1] : 0;
 			Console.Error.WriteLine(
@@ -398,7 +606,7 @@ public sealed partial class DirectExecutionBackend
 		}
 	}
 
-	private void DumpGuestDisasmDiagnostics(ulong rip, ulong rbp)
+	private void DumpGuestDisasmDiagnostics(ulong rip, ulong rbp, ulong rsp)
 	{
 		if (!string.Equals(Environment.GetEnvironmentVariable("SHARPEMU_LOG_DISASM"), "1", StringComparison.Ordinal))
 		{
@@ -410,12 +618,20 @@ public sealed partial class DirectExecutionBackend
 			DumpGuestInstructionStream("fault-prelude", rip - 0x20, 24);
 		}
 
+		// Optimized guest code frequently omits frame pointers. The return
+		// address at RSP is then more useful than an RBP walk and identifies the
+		// exact call site that supplied the faulting arguments.
+		if (TryReadHostQword(rsp, out var stackReturn) && stackReturn >= 0x60)
+		{
+			DumpGuestInstructionStream("stack-return-prelude", stackReturn - 0x60, 40);
+		}
+
 		try
 		{
 			ulong frame = rbp;
 			for (int i = 0; i < 3; i++)
 			{
-				if (frame < 140733193388032L || frame > 140737488355327L)
+				if (frame < 0x10000)
 				{
 					break;
 				}
@@ -484,7 +700,7 @@ public sealed partial class DirectExecutionBackend
 		ulong address = scanBase;
 		while (address < scanEnd)
 		{
-			if (!_hostMemory.Query(address, out var mbi))
+			if (VirtualQuery((void*)address, out var mbi, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) == 0)
 			{
 				break;
 			}
@@ -496,9 +712,9 @@ public sealed partial class DirectExecutionBackend
 				break;
 			}
 
-			if (mbi.State == HostRegionState.Committed &&
-				IsReadableProtection(mbi.RawProtection) &&
-				IsExecutableProtection(mbi.RawProtection))
+			if (mbi.State == MEM_COMMIT &&
+				IsReadableProtection(mbi.Protect) &&
+				IsExecutableProtection(mbi.Protect))
 			{
 				ScanExecutableRegionForTargetReferences(regionBase, regionEnd, targetList, hitCounts, maxHitsPerTarget);
 			}
@@ -559,6 +775,55 @@ public sealed partial class DirectExecutionBackend
 		}
 	}
 
+	private void DumpGuestRegisterWindowDiagnostics(
+		ulong rax,
+		ulong rbx,
+		ulong rcx,
+		ulong rdx,
+		ulong rsi,
+		ulong rdi,
+		ulong rbp,
+		ulong rsp,
+		ulong r8,
+		ulong r9,
+		ulong r10,
+		ulong r11,
+		ulong r12,
+		ulong r13,
+		ulong r14,
+		ulong r15)
+	{
+		if (!string.Equals(
+				Environment.GetEnvironmentVariable("SHARPEMU_LOG_REGISTER_WINDOWS"),
+				"1",
+				StringComparison.Ordinal))
+		{
+			return;
+		}
+
+		// A register can be the only surviving reference to the object or
+		// argument array that caused a native guest fault. Capture a compact
+		// window while the process is alive so the post-mortem log can
+		// distinguish an absent object from a partially initialized one.
+		var registers = new (string Name, ulong Value)[]
+		{
+			("rax", rax), ("rbx", rbx), ("rcx", rcx), ("rdx", rdx),
+			("rsi", rsi), ("rdi", rdi), ("rbp", rbp), ("rsp", rsp),
+			("r8", r8), ("r9", r9), ("r10", r10), ("r11", r11),
+			("r12", r12), ("r13", r13), ("r14", r14), ("r15", r15),
+		};
+		var seen = new HashSet<ulong>();
+		foreach (var (name, value) in registers)
+		{
+			if (value < 0x10000 || !seen.Add(value))
+			{
+				continue;
+			}
+
+			DumpPointerWindow($"register-{name}", value, 0x80);
+		}
+	}
+
 	private void ScanExecutableRegionForTargetReferences(
 		ulong regionBase,
 		ulong regionEnd,
@@ -803,13 +1068,13 @@ public sealed partial class DirectExecutionBackend
 			return false;
 		}
 
-		if (!_hostMemory.Query(address, out var mbi))
+		if (VirtualQuery((void*)address, out var mbi, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) == 0)
 		{
 			return false;
 		}
 
 		ulong regionEnd = mbi.BaseAddress + mbi.RegionSize;
-		if (mbi.State != HostRegionState.Committed || !IsReadableProtection(mbi.RawProtection) || regionEnd <= address || address > regionEnd - 8)
+		if (mbi.State != MEM_COMMIT || !IsReadableProtection(mbi.Protect) || regionEnd <= address || address > regionEnd - 8)
 		{
 			return false;
 		}
@@ -848,7 +1113,7 @@ public sealed partial class DirectExecutionBackend
 		}
 	}
 
-	private unsafe bool TryReadHostBytes(ulong address, byte[] buffer)
+	private unsafe static bool TryReadHostBytes(ulong address, byte[] buffer)
 	{
 		if (address < 65536)
 		{
@@ -861,9 +1126,9 @@ public sealed partial class DirectExecutionBackend
 			ulong end = address + (ulong)buffer.Length;
 			for (ulong page = address & 0xFFFFFFFFFFFFF000uL; page < end; page += 4096)
 			{
-				if (!_hostMemory.Query(page, out var mbi) ||
-					mbi.State != HostRegionState.Committed ||
-					!IsReadableProtection(mbi.RawProtection))
+				if (VirtualQuery((void*)page, out var mbi, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) == 0 ||
+					mbi.State != MEM_COMMIT ||
+					!IsReadableProtection(mbi.Protect))
 				{
 					return false;
 				}
@@ -976,25 +1241,25 @@ public sealed partial class DirectExecutionBackend
 		{
 			return false;
 		}
-		if (!_hostMemory.Query(faultAddress, out var mbi))
+		if (VirtualQuery((void*)faultAddress, out var mbi, (nuint)sizeof(MEMORY_BASIC_INFORMATION64)) == 0)
 		{
 			return false;
 		}
 
 		ulong pageBase = faultAddress & 0xFFFFFFFFFFFFF000uL;
-		uint commitProtect = ResolveLazyCommitProtection(accessType, mbi.RawAllocationProtection);
+		uint commitProtect = ResolveLazyCommitProtection(accessType, mbi.AllocationProtect);
 		int traceIndex = Interlocked.Increment(ref _lazyCommitTraceCount);
 		bool traceLazyCommit = ShouldTraceLazyCommit(traceIndex);
 		if (traceLazyCommit)
 		{
-			Console.Error.WriteLine($"[LOADER][TRACE] lazy-query#{traceIndex}: fault=0x{faultAddress:X16} owner={owner} rip=0x{rip:X16} rsp=0x{rsp:X16} state=0x{mbi.RawState:X08} base=0x{mbi.BaseAddress:X16} size=0x{mbi.RegionSize:X16} alloc=0x{mbi.RawAllocationProtection:X08} prot=0x{mbi.RawProtection:X08}");
+			Console.Error.WriteLine($"[LOADER][TRACE] lazy-query#{traceIndex}: fault=0x{faultAddress:X16} owner={owner} rip=0x{rip:X16} rsp=0x{rsp:X16} state=0x{mbi.State:X08} base=0x{mbi.BaseAddress:X16} size=0x{mbi.RegionSize:X16} alloc=0x{mbi.AllocationProtect:X08} prot=0x{mbi.Protect:X08}");
 		}
 
-		if (mbi.State == HostRegionState.Committed && IsAccessCompatible(accessType, mbi.RawProtection))
+		if (mbi.State == 4096 && IsAccessCompatible(accessType, mbi.Protect))
 		{
 			if (traceLazyCommit)
 			{
-				Console.Error.WriteLine($"[LOADER][TRACE] lazy-commit-race#{traceIndex}: fault=0x{faultAddress:X16} protect=0x{mbi.RawProtection:X08}");
+				Console.Error.WriteLine($"[LOADER][TRACE] lazy-commit-race#{traceIndex}: fault=0x{faultAddress:X16} protect=0x{mbi.Protect:X08}");
 			}
 			return true;
 		}
@@ -1003,10 +1268,10 @@ public sealed partial class DirectExecutionBackend
 		ulong committedBase = 0;
 		ulong committedSize = 0;
 
-		if (mbi.State == HostRegionState.Free)
+		if (mbi.State == 65536)
 		{
 			if (TryGetLazyCommitWindow(faultAddress, mbi.BaseAddress, mbi.RegionSize, out var windowBase, out var windowSize) &&
-				TryReserveThenCommit(_hostMemory, windowBase, windowSize, windowBase, windowSize, commitProtect))
+				TryReserveThenCommit(windowBase, windowSize, windowBase, windowSize, commitProtect))
 			{
 				committed = true;
 				committedBase = windowBase;
@@ -1015,7 +1280,7 @@ public sealed partial class DirectExecutionBackend
 			else
 			{
 				ulong largeBase = faultAddress & 0xFFFFFFFFFFE00000uL;
-				if (TryReserveThenCommit(_hostMemory, largeBase, 2097152uL, largeBase, 2097152uL, commitProtect))
+				if (TryReserveThenCommit(largeBase, 2097152uL, largeBase, 2097152uL, commitProtect))
 				{
 					committed = true;
 					committedBase = largeBase;
@@ -1026,13 +1291,13 @@ public sealed partial class DirectExecutionBackend
 			if (!committed)
 			{
 				ulong region64kBase = faultAddress & 0xFFFFFFFFFFFF0000uL;
-				if (TryReserveThenCommit(_hostMemory, region64kBase, 65536uL, region64kBase, 65536uL, commitProtect))
+				if (TryReserveThenCommit(region64kBase, 65536uL, region64kBase, 65536uL, commitProtect))
 				{
 					committed = true;
 					committedBase = region64kBase;
 					committedSize = 65536uL;
 				}
-				else if (TryReserveThenCommit(_hostMemory, pageBase, 4096uL, pageBase, 4096uL, commitProtect))
+				else if (TryReserveThenCommit(pageBase, 4096uL, pageBase, 4096uL, commitProtect))
 				{
 					committed = true;
 					committedBase = pageBase;
@@ -1045,7 +1310,7 @@ public sealed partial class DirectExecutionBackend
 				return false;
 			}
 
-			TryCommitRange(_hostMemory, pageBase + 4096, 4096uL, commitProtect);
+			TryCommitRange(pageBase + 4096, 4096uL, commitProtect);
 			if (traceLazyCommit)
 			{
 				Console.Error.WriteLine($"[LOADER][TRACE] lazy-reserve-commit#{traceIndex}: addr=0x{committedBase:X16} size=0x{committedSize:X16} access={accessType} protect=0x{commitProtect:X8}");
@@ -1053,13 +1318,13 @@ public sealed partial class DirectExecutionBackend
 			return true;
 		}
 
-		if (mbi.State != HostRegionState.Reserved)
+		if (mbi.State != 8192)
 		{
 			return false;
 		}
 
 		if (TryGetLazyCommitWindow(faultAddress, mbi.BaseAddress, mbi.RegionSize, out var commitWindowBase, out var commitWindowSize) &&
-			TryCommitRange(_hostMemory, commitWindowBase, commitWindowSize, commitProtect))
+			TryCommitRange(commitWindowBase, commitWindowSize, commitProtect))
 		{
 			committed = true;
 			committedBase = commitWindowBase;
@@ -1068,7 +1333,7 @@ public sealed partial class DirectExecutionBackend
 		else
 		{
 			ulong largeCommitBase = faultAddress & 0xFFFFFFFFFFE00000uL;
-			if (TryCommitRange(_hostMemory, largeCommitBase, 2097152uL, commitProtect))
+			if (TryCommitRange(largeCommitBase, 2097152uL, commitProtect))
 			{
 				committed = true;
 				committedBase = largeCommitBase;
@@ -1079,19 +1344,19 @@ public sealed partial class DirectExecutionBackend
 		if (!committed)
 		{
 			ulong region64kBase = faultAddress & 0xFFFFFFFFFFFF0000uL;
-			if (TryCommitRange(_hostMemory, region64kBase, 65536uL, commitProtect))
+			if (TryCommitRange(region64kBase, 65536uL, commitProtect))
 			{
 				committed = true;
 				committedBase = region64kBase;
 				committedSize = 65536uL;
 			}
-			else if (TryCommitRange(_hostMemory, pageBase, 8192uL, commitProtect))
+			else if (TryCommitRange(pageBase, 8192uL, commitProtect))
 			{
 				committed = true;
 				committedBase = pageBase;
 				committedSize = 8192uL;
 			}
-			else if (TryCommitRange(_hostMemory, pageBase, 4096uL, commitProtect))
+			else if (TryCommitRange(pageBase, 4096uL, commitProtect))
 			{
 				committed = true;
 				committedBase = pageBase;
@@ -1104,7 +1369,7 @@ public sealed partial class DirectExecutionBackend
 			return false;
 		}
 
-		TryCommitRange(_hostMemory, pageBase + 4096, 4096uL, commitProtect);
+		TryCommitRange(pageBase + 4096, 4096uL, commitProtect);
 		if (traceLazyCommit)
 		{
 			Console.Error.WriteLine($"[LOADER][TRACE] lazy-commit#{traceIndex}: addr=0x{committedBase:X16} size=0x{committedSize:X16} access={accessType} protect=0x{commitProtect:X8}");
@@ -1145,33 +1410,31 @@ public sealed partial class DirectExecutionBackend
 			return true;
 		}
 
-		// The commit protection is one of the two raw values ResolveLazyCommitProtection
-		// produces (0x40 RWX / 0x04 RW); the enum mapping reproduces those exactly.
-		static bool TryCommitRange(IHostMemory hostMemory, ulong baseAddress, ulong length, uint protection)
+		static unsafe bool TryCommitRange(ulong baseAddress, ulong length, uint protection)
 		{
 			if (length == 0)
 			{
 				return false;
 			}
-			return hostMemory.Commit(baseAddress, length, protection == 64u ? HostPageProtection.ReadWriteExecute : HostPageProtection.ReadWrite);
+			return VirtualAlloc((void*)baseAddress, (nuint)length, 4096u, protection) != null;
 		}
 
-		static bool TryReserveRange(IHostMemory hostMemory, ulong baseAddress, ulong length)
+		static unsafe bool TryReserveRange(ulong baseAddress, ulong length)
 		{
 			if (length == 0)
 			{
 				return false;
 			}
-			return hostMemory.Reserve(baseAddress, length, HostPageProtection.ReadWrite) != 0;
+			return VirtualAlloc((void*)baseAddress, (nuint)length, 8192u, 4u) != null;
 		}
 
-		static bool TryReserveThenCommit(IHostMemory hostMemory, ulong reserveAddress, ulong reserveSize, ulong commitAddress, ulong commitSize, uint protection)
+		static bool TryReserveThenCommit(ulong reserveAddress, ulong reserveSize, ulong commitAddress, ulong commitSize, uint protection)
 		{
-			if (!TryReserveRange(hostMemory, reserveAddress, reserveSize))
+			if (!TryReserveRange(reserveAddress, reserveSize))
 			{
 				return false;
 			}
-			return TryCommitRange(hostMemory, commitAddress, commitSize, protection);
+			return TryCommitRange(commitAddress, commitSize, protection);
 		}
 
 		static bool IsAccessCompatible(ulong accessType, uint protection)

src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.IllegalInstruction.cs

@@ -0,0 +1,362 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Buffers.Binary;
+using System.Threading;
+using Iced.Intel;
+using SharpEmu.Core.Cpu.Emulation;
+
+namespace SharpEmu.Core.Cpu.Native;
+
+// Software fallback for the BMI1/BMI2/ABM general-purpose-register instructions.
+//
+// Guest code runs natively, so the guest and host share the same virtual address space and the
+// same registers (the OS delivers them in the CONTEXT record on a fault). When the host CPU lacks
+// one of these extensions it raises #UD instead of executing the opcode; without this the title
+// simply aborts. Here we decode the faulting instruction, evaluate it against the trapped register
+// and memory state, write the result back into the CONTEXT, step RIP past the instruction and ask
+// the OS to continue. Only the register-only BMI/ABM forms are handled; anything else returns false
+// and falls through to the existing diagnostics unchanged, so this can never mis-handle an opcode it
+// does not fully model.
+public sealed partial class DirectExecutionBackend
+{
+    // Windows x64 CONTEXT.EFlags lives just past the segment selectors. The GPR offsets it shares
+    // with the rest of the backend are the CTX_* constants declared in DirectExecutionBackend.cs.
+    private const int CTX_EFLAGS = 68;
+
+    // STATUS_ILLEGAL_INSTRUCTION (#UD surfaced by the Windows vectored handler).
+    private const uint StatusIllegalInstruction = 0xC000001Du;
+
+    private const int MaxInstructionBytes = 15;
+
+    // Instruction-window sizes tried in turn so a fault near a page boundary still decodes.
+    private static readonly int[] DecodeWindowSizes = { MaxInstructionBytes, 11, 8, 4, 2 };
+
+    private static int _bmiSoftwareFallbackAnnounced;
+    private static long _bmiInstructionsEmulated;
+
+    private unsafe bool TryRecoverIllegalInstruction(void* contextRecord, ulong rip)
+    {
+        if (!TryReadFaultingInstruction(rip, out var instruction))
+        {
+            return false;
+        }
+
+        if (instruction.Op0Kind != OpKind.Register ||
+            !TryGetGprSlot(instruction.Op0Register, out var destOffset, out var size))
+        {
+            return false;
+        }
+
+        if (!TryEvaluate(contextRecord, in instruction, size, out var result, out var flagsChanged, out var eflags))
+        {
+            return false;
+        }
+
+        WriteCtxU64(contextRecord, destOffset, result);
+        if (flagsChanged)
+        {
+            WriteCtxU32(contextRecord, CTX_EFLAGS, eflags);
+        }
+
+        WriteCtxU64(contextRecord, CTX_RIP, rip + (ulong)instruction.Length);
+
+        Interlocked.Increment(ref _bmiInstructionsEmulated);
+        if (Interlocked.Exchange(ref _bmiSoftwareFallbackAnnounced, 1) == 0)
+        {
+            Console.Error.WriteLine(
+                "[LOADER][INFO] Host lacks a BMI/ABM extension used by the guest; " +
+                "emulating those instructions in software.");
+        }
+
+        return true;
+    }
+
+    private unsafe bool TryEvaluate(
+        void* contextRecord,
+        in Instruction instruction,
+        GprOperandSize size,
+        out ulong result,
+        out bool flagsChanged,
+        out uint eflags)
+    {
+        result = 0;
+        flagsChanged = false;
+        eflags = ReadCtxU32(contextRecord, CTX_EFLAGS);
+
+        switch (instruction.Mnemonic)
+        {
+            case Mnemonic.Andn:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var andnSrc1) ||
+                    !TryReadOperand(contextRecord, in instruction, 2, size, out var andnSrc2))
+                {
+                    return false;
+                }
+
+                result = BmiInstructionEmulator.Andn(andnSrc1, andnSrc2, size, ref eflags);
+                flagsChanged = true;
+                return true;
+
+            case Mnemonic.Blsi:
+            case Mnemonic.Blsmsk:
+            case Mnemonic.Blsr:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var blsSrc))
+                {
+                    return false;
+                }
+
+                result = instruction.Mnemonic switch
+                {
+                    Mnemonic.Blsi => BmiInstructionEmulator.Blsi(blsSrc, size, ref eflags),
+                    Mnemonic.Blsmsk => BmiInstructionEmulator.Blsmsk(blsSrc, size, ref eflags),
+                    _ => BmiInstructionEmulator.Blsr(blsSrc, size, ref eflags),
+                };
+                flagsChanged = true;
+                return true;
+
+            case Mnemonic.Bextr:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var bextrSrc) ||
+                    !TryReadOperand(contextRecord, in instruction, 2, size, out var bextrControl))
+                {
+                    return false;
+                }
+
+                result = BmiInstructionEmulator.Bextr(bextrSrc, bextrControl, size, ref eflags);
+                flagsChanged = true;
+                return true;
+
+            case Mnemonic.Bzhi:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var bzhiSrc) ||
+                    !TryReadOperand(contextRecord, in instruction, 2, size, out var bzhiIndex))
+                {
+                    return false;
+                }
+
+                result = BmiInstructionEmulator.Bzhi(bzhiSrc, bzhiIndex, size, ref eflags);
+                flagsChanged = true;
+                return true;
+
+            case Mnemonic.Tzcnt:
+            case Mnemonic.Lzcnt:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var cntSrc))
+                {
+                    return false;
+                }
+
+                result = instruction.Mnemonic == Mnemonic.Tzcnt
+                    ? BmiInstructionEmulator.Tzcnt(cntSrc, size, ref eflags)
+                    : BmiInstructionEmulator.Lzcnt(cntSrc, size, ref eflags);
+                flagsChanged = true;
+                return true;
+
+            case Mnemonic.Rorx:
+                if (instruction.Op2Kind != OpKind.Immediate8 ||
+                    !TryReadOperand(contextRecord, in instruction, 1, size, out var rorxSrc))
+                {
+                    return false;
+                }
+
+                result = BmiInstructionEmulator.Rorx(rorxSrc, instruction.Immediate8, size);
+                return true;
+
+            case Mnemonic.Sarx:
+            case Mnemonic.Shlx:
+            case Mnemonic.Shrx:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var shiftSrc) ||
+                    !TryReadOperand(contextRecord, in instruction, 2, size, out var shiftCount))
+                {
+                    return false;
+                }
+
+                result = instruction.Mnemonic switch
+                {
+                    Mnemonic.Sarx => BmiInstructionEmulator.Sarx(shiftSrc, (int)shiftCount, size),
+                    Mnemonic.Shlx => BmiInstructionEmulator.Shlx(shiftSrc, (int)shiftCount, size),
+                    _ => BmiInstructionEmulator.Shrx(shiftSrc, (int)shiftCount, size),
+                };
+                return true;
+
+            case Mnemonic.Pdep:
+            case Mnemonic.Pext:
+                if (!TryReadOperand(contextRecord, in instruction, 1, size, out var packSrc) ||
+                    !TryReadOperand(contextRecord, in instruction, 2, size, out var packMask))
+                {
+                    return false;
+                }
+
+                result = instruction.Mnemonic == Mnemonic.Pdep
+                    ? BmiInstructionEmulator.Pdep(packSrc, packMask, size)
+                    : BmiInstructionEmulator.Pext(packSrc, packMask, size);
+                return true;
+
+            default:
+                return false;
+        }
+    }
+
+    private unsafe bool TryReadFaultingInstruction(ulong rip, out Instruction instruction)
+    {
+        // Try the full instruction window first, then shrink so a fault near the end of a mapped
+        // page (where fewer than 15 bytes are readable) still decodes.
+        foreach (var attempt in DecodeWindowSizes)
+        {
+            var buffer = new byte[attempt];
+            if (!TryReadHostBytes(rip, buffer))
+            {
+                continue;
+            }
+
+            var decoder = Decoder.Create(64, new ByteArrayCodeReader(buffer));
+            decoder.IP = rip;
+            decoder.Decode(out instruction);
+            if (instruction.Code != Code.INVALID && instruction.Length > 0 && instruction.Length <= attempt)
+            {
+                return true;
+            }
+        }
+
+        instruction = default;
+        return false;
+    }
+
+    private unsafe bool TryReadOperand(
+        void* contextRecord,
+        in Instruction instruction,
+        int operandIndex,
+        GprOperandSize size,
+        out ulong value)
+    {
+        value = 0;
+        switch (instruction.GetOpKind(operandIndex))
+        {
+            case OpKind.Register:
+                if (!TryGetGprSlot(instruction.GetOpRegister(operandIndex), out var offset, out _))
+                {
+                    return false;
+                }
+
+                var raw = ReadCtxU64(contextRecord, offset);
+                value = size == GprOperandSize.Bits64 ? raw : raw & 0xFFFF_FFFFUL;
+                return true;
+
+            case OpKind.Memory:
+                if (!TryComputeMemoryAddress(contextRecord, in instruction, out var address))
+                {
+                    return false;
+                }
+
+                var byteCount = size == GprOperandSize.Bits64 ? 8 : 4;
+                var buffer = new byte[byteCount];
+                if (!TryReadHostBytes(address, buffer))
+                {
+                    return false;
+                }
+
+                value = byteCount == 8
+                    ? BinaryPrimitives.ReadUInt64LittleEndian(buffer)
+                    : BinaryPrimitives.ReadUInt32LittleEndian(buffer);
+                return true;
+
+            default:
+                return false;
+        }
+    }
+
+    private unsafe bool TryComputeMemoryAddress(void* contextRecord, in Instruction instruction, out ulong address)
+    {
+        address = 0;
+
+        // FS/GS-relative operands need the guest segment base, which is not modelled here.
+        if (instruction.SegmentPrefix != Register.None)
+        {
+            return false;
+        }
+
+        if (instruction.IsIPRelativeMemoryOperand)
+        {
+            address = instruction.IPRelativeMemoryAddress;
+            return true;
+        }
+
+        var effective = instruction.MemoryDisplacement64;
+        if (instruction.MemoryBase != Register.None)
+        {
+            if (!TryGetGpr64Offset(instruction.MemoryBase, out var baseOffset))
+            {
+                return false;
+            }
+
+            effective += ReadCtxU64(contextRecord, baseOffset);
+        }
+
+        if (instruction.MemoryIndex != Register.None)
+        {
+            if (!TryGetGpr64Offset(instruction.MemoryIndex, out var indexOffset))
+            {
+                return false;
+            }
+
+            effective += ReadCtxU64(contextRecord, indexOffset) * (ulong)instruction.MemoryIndexScale;
+        }
+
+        address = effective;
+        return true;
+    }
+
+    // Maps a 32- or 64-bit GPR to its CONTEXT offset and reports the operand width it implies.
+    private static bool TryGetGprSlot(Register register, out int offset, out GprOperandSize size)
+    {
+        switch (register)
+        {
+            case Register.EAX: offset = CTX_RAX; size = GprOperandSize.Bits32; return true;
+            case Register.ECX: offset = CTX_RCX; size = GprOperandSize.Bits32; return true;
+            case Register.EDX: offset = CTX_RDX; size = GprOperandSize.Bits32; return true;
+            case Register.EBX: offset = CTX_RBX; size = GprOperandSize.Bits32; return true;
+            case Register.ESP: offset = CTX_RSP; size = GprOperandSize.Bits32; return true;
+            case Register.EBP: offset = CTX_RBP; size = GprOperandSize.Bits32; return true;
+            case Register.ESI: offset = CTX_RSI; size = GprOperandSize.Bits32; return true;
+            case Register.EDI: offset = CTX_RDI; size = GprOperandSize.Bits32; return true;
+            case Register.R8D: offset = CTX_R8; size = GprOperandSize.Bits32; return true;
+            case Register.R9D: offset = CTX_R9; size = GprOperandSize.Bits32; return true;
+            case Register.R10D: offset = CTX_R10; size = GprOperandSize.Bits32; return true;
+            case Register.R11D: offset = CTX_R11; size = GprOperandSize.Bits32; return true;
+            case Register.R12D: offset = CTX_R12; size = GprOperandSize.Bits32; return true;
+            case Register.R13D: offset = CTX_R13; size = GprOperandSize.Bits32; return true;
+            case Register.R14D: offset = CTX_R14; size = GprOperandSize.Bits32; return true;
+            case Register.R15D: offset = CTX_R15; size = GprOperandSize.Bits32; return true;
+            default:
+                if (TryGetGpr64Offset(register, out offset))
+                {
+                    size = GprOperandSize.Bits64;
+                    return true;
+                }
+
+                size = GprOperandSize.Bits32;
+                return false;
+        }
+    }
+
+    private static bool TryGetGpr64Offset(Register register, out int offset)
+    {
+        switch (register)
+        {
+            case Register.RAX: offset = CTX_RAX; return true;
+            case Register.RCX: offset = CTX_RCX; return true;
+            case Register.RDX: offset = CTX_RDX; return true;
+            case Register.RBX: offset = CTX_RBX; return true;
+            case Register.RSP: offset = CTX_RSP; return true;
+            case Register.RBP: offset = CTX_RBP; return true;
+            case Register.RSI: offset = CTX_RSI; return true;
+            case Register.RDI: offset = CTX_RDI; return true;
+            case Register.R8: offset = CTX_R8; return true;
+            case Register.R9: offset = CTX_R9; return true;
+            case Register.R10: offset = CTX_R10; return true;
+            case Register.R11: offset = CTX_R11; return true;
+            case Register.R12: offset = CTX_R12; return true;
+            case Register.R13: offset = CTX_R13; return true;
+            case Register.R14: offset = CTX_R14; return true;
+            case Register.R15: offset = CTX_R15; return true;
+            default: offset = 0; return false;
+        }
+    }
+}

src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.NativeWorker.cs

@@ -6,8 +6,6 @@ using System.Collections.Generic;
 using System.Runtime.InteropServices;
 using System.Threading;
 using SharpEmu.HLE;
-using SharpEmu.HLE.Host;
-using SharpEmu.HLE.Host.Posix;
 
 namespace SharpEmu.Core.Cpu.Native;
 
@@ -37,6 +35,20 @@ public sealed partial class DirectExecutionBackend
 	private bool _nativeWorkersDisposed;
 	private int _nativeWorkerCreationFailedLogged;
 
+	private const uint StackSizeParamIsAReservation = 0x00010000u;
+
+	[DllImport("kernel32.dll", SetLastError = true)]
+	private static extern nint CreateThread(
+		nint lpThreadAttributes,
+		nuint dwStackSize,
+		nint lpStartAddress,
+		nint lpParameter,
+		uint dwCreationFlags,
+		out uint lpThreadId);
+
+	[DllImport("kernel32.dll", SetLastError = true)]
+	private static extern uint WaitForSingleObject(nint hHandle, uint dwMilliseconds);
+
 	// Runs an emitted guest entry stub. Preferred path is a pooled native worker
 	// thread; falls back to the historical inline calli (guest frames above this
 	// thread's managed frames) when workers are disabled or unavailable.
@@ -49,7 +61,7 @@ public sealed partial class DirectExecutionBackend
 		var worker = RentNativeGuestExecutor();
 		if (worker is null)
 		{
-			_hostThreading.SetTlsValue(_hostRspSlotTlsIndex, (nint)hostRspSlot);
+			TlsSetValue(_hostRspSlotTlsIndex, (nint)hostRspSlot);
 			return CallNativeEntry(entryStub);
 		}
 		try
@@ -80,7 +92,10 @@ public sealed partial class DirectExecutionBackend
 
 	private NativeGuestExecutor? RentNativeGuestExecutor()
 	{
-		if (NativeGuestWorkersDisabled)
+		// NativeGuestExecutor emits a Win32 wait loop and creates it with
+		// kernel32!CreateThread. POSIX hosts use the established inline entry
+		// path until the worker loop has a pthread/eventfd implementation.
+		if (!OperatingSystem.IsWindows() || NativeGuestWorkersDisabled)
 		{
 			return null;
 		}
@@ -234,7 +249,7 @@ public sealed partial class DirectExecutionBackend
 
 		public static NativeGuestExecutor? TryCreate(DirectExecutionBackend backend)
 		{
-			if (!EnsureHostRuntimeExports(backend._hostSymbols))
+			if (!EnsureKernel32Exports())
 			{
 				return null;
 			}
@@ -247,27 +262,32 @@ public sealed partial class DirectExecutionBackend
 			return executor;
 		}
 
-		private static bool EnsureHostRuntimeExports(IHostSymbolResolver symbols)
+		private static bool EnsureKernel32Exports()
 		{
 			if (_exitThreadAddress != 0)
 			{
 				return _waitForSingleObjectAddress != 0 && _setEventAddress != 0;
 			}
-			_waitForSingleObjectAddress = symbols.GetAddress(HostRuntimeFunction.WaitForSingleObject);
-			_setEventAddress = symbols.GetAddress(HostRuntimeFunction.SetEvent);
-			_exitThreadAddress = symbols.GetAddress(HostRuntimeFunction.ExitThread);
+			nint kernel32 = GetModuleHandle("kernel32.dll");
+			if (kernel32 == 0)
+			{
+				return false;
+			}
+			_waitForSingleObjectAddress = GetProcAddress(kernel32, "WaitForSingleObject");
+			_setEventAddress = GetProcAddress(kernel32, "SetEvent");
+			_exitThreadAddress = GetProcAddress(kernel32, "ExitThread");
 			return _waitForSingleObjectAddress != 0 && _setEventAddress != 0 && _exitThreadAddress != 0;
 		}
 
 		private bool Initialize()
 		{
 			_selfHandle = GCHandle.Alloc(this);
-			_controlBlock = (void*)_backend._hostMemory.Allocate(0, 4096u, HostPageProtection.ReadWrite);
+			_controlBlock = VirtualAlloc(null, 4096u, 12288u, 4u);
 			if (_controlBlock == null)
 			{
 				return false;
 			}
-			_loopStub = (void*)_backend._hostMemory.Allocate(0, LoopStubSize, HostPageProtection.ReadWriteExecute);
+			_loopStub = VirtualAlloc(null, LoopStubSize, 12288u, 64u);
 			if (_loopStub == null)
 			{
 				return false;
@@ -375,15 +395,17 @@ public sealed partial class DirectExecutionBackend
 			*(int*)(code + skipJump) = skipEntryOffset - (skipJump + sizeof(int));
 
 			uint oldProtect = 0;
-			if (!_backend._hostMemory.Protect((ulong)_loopStub, LoopStubSize, HostPageProtection.ReadExecute, out oldProtect))
+			if (!VirtualProtect(_loopStub, LoopStubSize, 32u, &oldProtect))
 			{
 				return false;
 			}
-			_backend._hostMemory.FlushInstructionCache((ulong)_loopStub, LoopStubSize);
-			_threadHandle = _backend._hostThreading.CreateNativeThread(
-				(nint)_loopStub,
+			FlushInstructionCache(GetCurrentProcess(), _loopStub, LoopStubSize);
+			_threadHandle = CreateThread(
 				0,
 				WorkerStackReservation,
+				(nint)_loopStub,
+				0,
+				StackSizeParamIsAReservation,
 				out _nativeThreadId);
 			if (_threadHandle == 0)
 			{
@@ -511,7 +533,7 @@ public sealed partial class DirectExecutionBackend
 			_prevYieldRequested = _activeGuestThreadYieldRequested;
 			_prevYieldReason = _activeGuestThreadYieldReason;
 			_prevState = _activeGuestThreadState;
-			_prevHostRspSlot = backend._hostThreading.GetTlsValue(backend._hostRspSlotTlsIndex);
+			_prevHostRspSlot = TlsGetValue(backend._hostRspSlotTlsIndex);
 			_prevGuestThreadHandle = GuestThreadExecution.EnterGuestThread(_runGuestThreadHandle);
 			_entered = true;
 			_activeExecutionBackend = backend;
@@ -523,11 +545,11 @@ public sealed partial class DirectExecutionBackend
 			_activeGuestThreadYieldReason = null;
 			_activeGuestThreadState = _runState;
 			backend.BindTlsBase(_runContext!);
-			backend._hostThreading.SetTlsValue(backend._hostRspSlotTlsIndex, _runHostRspSlot);
+			TlsSetValue(backend._hostRspSlotTlsIndex, _runHostRspSlot);
 			if (_runState is { } state)
 			{
 				_prevHostThreadId = Volatile.Read(ref state.HostThreadId);
-				Volatile.Write(ref state.HostThreadId, unchecked((int)backend._hostThreading.CurrentThreadId));
+				Volatile.Write(ref state.HostThreadId, unchecked((int)GetCurrentThreadId()));
 			}
 			if (_runAffinityMask != 0)
 			{
@@ -557,7 +579,7 @@ public sealed partial class DirectExecutionBackend
 			{
 				Volatile.Write(ref state.HostThreadId, _prevHostThreadId);
 			}
-			_backend._hostThreading.SetTlsValue(_backend._hostRspSlotTlsIndex, _prevHostRspSlot);
+			TlsSetValue(_backend._hostRspSlotTlsIndex, _prevHostRspSlot);
 			GuestThreadExecution.RestoreGuestThread(_prevGuestThreadHandle);
 			_activeExecutionBackend = _prevBackend;
 			_activeCpuContext = _prevContext;
@@ -594,8 +616,8 @@ public sealed partial class DirectExecutionBackend
 			var exited = _threadHandle == 0;
 			if (_threadHandle != 0)
 			{
-				exited = _backend._hostThreading.WaitForThreadExit(_threadHandle, 1000u);
-				_backend._hostThreading.CloseThreadHandle(_threadHandle);
+				exited = WaitForSingleObject(_threadHandle, 1000u) == 0u;
+				CloseHandle(_threadHandle);
 				_threadHandle = 0;
 			}
 			if (!exited)
@@ -609,12 +631,12 @@ public sealed partial class DirectExecutionBackend
 			}
 			if (_loopStub != null)
 			{
-				_backend._hostMemory.Free((ulong)_loopStub);
+				VirtualFree(_loopStub, 0u, 32768u);
 				_loopStub = null;
 			}
 			if (_controlBlock != null)
 			{
-				_backend._hostMemory.Free((ulong)_controlBlock);
+				VirtualFree(_controlBlock, 0u, 32768u);
 				_controlBlock = null;
 			}
 			if (_selfHandle.IsAllocated)

src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.PosixSignals.cs

@@ -4,7 +4,7 @@
 using System;
 using System.Runtime.InteropServices;
 using System.Threading;
-using SharpEmu.Core.Cpu.Native.Windows;
+using SharpEmu.HLE;
 
 namespace SharpEmu.Core.Cpu.Native;
 
@@ -21,6 +21,8 @@ public sealed unsafe partial class DirectExecutionBackend
 	// runtime keeps turning its own faults into managed exceptions.
 
 	private const int PosixSigIll = 4;
+	private const int PosixSigTrap = 5;
+	private const int PosixSigAbort = 6;
 	private const int PosixSigSegv = 11;
 	private static readonly int PosixSigBus = OperatingSystem.IsMacOS() ? 10 : 7;
 
@@ -62,6 +64,9 @@ public sealed unsafe partial class DirectExecutionBackend
 	private static bool _posixSignalWarmup;
 	private static readonly nint[] _posixPreviousActions = new nint[32];
 	private static int _posixSignalTraceCount;
+	private static long _perfSignalCount;
+	private static readonly bool _perfSignalCounter =
+		string.Equals(Environment.GetEnvironmentVariable("SHARPEMU_PERF_MEM"), "1", StringComparison.Ordinal);
 
 	[ThreadStatic]
 	private static int _posixSignalHandlerDepth;
@@ -88,10 +93,13 @@ public sealed unsafe partial class DirectExecutionBackend
 		}
 
 		WarmUpPosixSignalPath();
+		SharpEmu.HLE.GuestImageWriteTracker.WarmUp();
 
 		if (!InstallPosixSignalHandler(PosixSigSegv) ||
 			!InstallPosixSignalHandler(PosixSigBus) ||
-			!InstallPosixSignalHandler(PosixSigIll))
+			!InstallPosixSignalHandler(PosixSigIll) ||
+			!InstallPosixSignalHandler(PosixSigTrap) ||
+			!InstallPosixSignalHandler(PosixSigAbort))
 		{
 			throw new InvalidOperationException("Failed to install POSIX fault signal handlers");
 		}
@@ -132,8 +140,8 @@ public sealed unsafe partial class DirectExecutionBackend
 			// action and sigaction(0, ...) fails with EINVAL).
 			EXCEPTION_RECORD record = default;
 			record.ExceptionCode = DBG_PRINTEXCEPTION_C;
-			byte* contextRecord = stackalloc byte[Win64ContextOffsets.Size];
-			new Span<byte>(contextRecord, Win64ContextOffsets.Size).Clear();
+			byte* contextRecord = stackalloc byte[Win64ContextSize];
+			new Span<byte>(contextRecord, Win64ContextSize).Clear();
 			EXCEPTION_POINTERS pointers;
 			pointers.ExceptionRecord = &record;
 			pointers.ContextRecord = contextRecord;
@@ -190,8 +198,27 @@ public sealed unsafe partial class DirectExecutionBackend
 		}
 
 		_posixSignalHandlerDepth++;
+		if (_perfSignalCounter)
+		{
+			var n = Interlocked.Increment(ref _perfSignalCount);
+			if (n % 100000 == 0)
+			{
+				Console.Error.WriteLine($"[PERF][MEM] posix_faults={n}");
+			}
+		}
 		try
 		{
+			// Guest-image write tracking runs first: it only needs the fault
+			// address (safe for host and guest threads alike) and must resume
+			// the faulting write immediately after restoring write access.
+			if (signal != PosixSigIll &&
+				siginfo != 0 &&
+				SharpEmu.HLE.GuestImageWriteTracker.TryHandleWriteFault(
+					*(ulong*)((byte*)siginfo + PosixSigInfoAddressOffset)))
+			{
+				return;
+			}
+
 			if (TryHandlePosixFault(signal, siginfo, ucontext))
 			{
 				return;
@@ -217,8 +244,8 @@ public sealed unsafe partial class DirectExecutionBackend
 			return false;
 		}
 
-		byte* contextRecord = stackalloc byte[Win64ContextOffsets.Size];
-		new Span<byte>(contextRecord, Win64ContextOffsets.Size).Clear();
+		byte* contextRecord = stackalloc byte[Win64ContextSize];
+		new Span<byte>(contextRecord, Win64ContextSize).Clear();
 		int[] offsets = PosixRegisterOffsets;
 		for (int i = 0; i < offsets.Length; i++)
 		{
@@ -231,6 +258,14 @@ public sealed unsafe partial class DirectExecutionBackend
 		{
 			record.ExceptionCode = 3221225501u;
 		}
+		else if (signal == PosixSigTrap)
+		{
+			record.ExceptionCode = 2147483651u;
+		}
+		else if (signal == PosixSigAbort)
+		{
+			record.ExceptionCode = 1073741845u;
+		}
 		else
 		{
 			ulong faultAddress = GetPosixFaultAddress(siginfo, registers);

src/SharpEmu.Core/Cpu/Native/PosixHostStubs.cs

@@ -0,0 +1,425 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Runtime.InteropServices;
+using SharpEmu.HLE;
+
+namespace SharpEmu.Core.Cpu.Native;
+
+/// <summary>
+/// POSIX replacements for the kernel32 helpers the native backend embeds in
+/// emitted x86-64 code. Every stub exposed here follows the Win64 calling
+/// convention the emitted call sites were written for (first argument in
+/// ECX, result in RAX, Win64 non-volatile registers preserved), so the
+/// emission code stays identical across platforms.
+/// </summary>
+internal static unsafe class PosixHostStubs
+{
+    private static readonly object Gate = new();
+    private static bool _initialized;
+    private static nint _tlsGetValueStub;
+    private static nint _queryPerformanceCounterStub;
+    private static nint _switchToThreadStub;
+    private static nint _sleepStub;
+
+    public static nint TlsGetValueStubAddress
+    {
+        get { EnsureInitialized(); return _tlsGetValueStub; }
+    }
+
+    public static nint QueryPerformanceCounterStubAddress
+    {
+        get { EnsureInitialized(); return _queryPerformanceCounterStub; }
+    }
+
+    public static nint SwitchToThreadStubAddress
+    {
+        get { EnsureInitialized(); return _switchToThreadStub; }
+    }
+
+    public static nint SleepStubAddress
+    {
+        get { EnsureInitialized(); return _sleepStub; }
+    }
+
+    public static nint CreateWorkerEvent()
+    {
+        if (OperatingSystem.IsMacOS())
+        {
+            return dispatch_semaphore_create(0);
+        }
+
+        var semaphore = Marshal.AllocHGlobal(64);
+        if (sem_init(semaphore, 0, 0) != 0)
+        {
+            Marshal.FreeHGlobal(semaphore);
+            return 0;
+        }
+
+        return semaphore;
+    }
+
+    public static bool SignalWorkerEvent(nint handle)
+    {
+        if (OperatingSystem.IsMacOS())
+        {
+            _ = dispatch_semaphore_signal(handle);
+            return true;
+        }
+
+        return sem_post(handle) == 0;
+    }
+
+    public static bool WaitWorkerEvent(nint handle, int timeoutMilliseconds)
+    {
+        if (OperatingSystem.IsMacOS())
+        {
+            if (timeoutMilliseconds < 0)
+            {
+                return dispatch_semaphore_wait(handle, ulong.MaxValue) == 0;
+            }
+
+            var deadline = dispatch_time(0, timeoutMilliseconds * 1_000_000L);
+            return dispatch_semaphore_wait(handle, deadline) == 0;
+        }
+
+        if (timeoutMilliseconds < 0)
+        {
+            while (sem_wait(handle) != 0)
+            {
+            }
+
+            return true;
+        }
+
+        var deadlineTicks = Environment.TickCount64 + timeoutMilliseconds;
+        while (sem_trywait(handle) != 0)
+        {
+            if (Environment.TickCount64 >= deadlineTicks)
+            {
+                return false;
+            }
+
+            Thread.Sleep(1);
+        }
+
+        return true;
+    }
+
+    public static void DestroyWorkerEvent(nint handle)
+    {
+        if (handle == 0)
+        {
+            return;
+        }
+
+        if (OperatingSystem.IsMacOS())
+        {
+            dispatch_release(handle);
+            return;
+        }
+
+        _ = sem_destroy(handle);
+        Marshal.FreeHGlobal(handle);
+    }
+
+    /// <summary>Allocates a pthread TLS key, mirroring kernel32!TlsAlloc.</summary>
+    public static uint TlsAlloc()
+    {
+        if (OperatingSystem.IsMacOS())
+        {
+            nuint key;
+            return pthread_key_create_mac(&key, 0) == 0 ? (uint)key : uint.MaxValue;
+        }
+
+        uint key32;
+        return pthread_key_create_linux(&key32, 0) == 0 ? key32 : uint.MaxValue;
+    }
+
+    public static bool TlsFree(uint key)
+    {
+        return OperatingSystem.IsMacOS()
+            ? pthread_key_delete_mac((nuint)key) == 0
+            : pthread_key_delete_linux(key) == 0;
+    }
+
+    public static bool TlsSetValue(uint key, nint value)
+    {
+        return OperatingSystem.IsMacOS()
+            ? pthread_setspecific_mac((nuint)key, value) == 0
+            : pthread_setspecific_linux(key, value) == 0;
+    }
+
+    public static nint TlsGetValue(uint key)
+    {
+        return OperatingSystem.IsMacOS()
+            ? pthread_getspecific_mac((nuint)key)
+            : pthread_getspecific_linux(key);
+    }
+
+    /// <summary>Stable numeric id of the calling thread (kernel32!GetCurrentThreadId).</summary>
+    public static uint GetCurrentThreadId()
+    {
+        if (OperatingSystem.IsMacOS())
+        {
+            ulong tid;
+            return pthread_threadid_np(0, &tid) == 0 ? unchecked((uint)tid) : 0u;
+        }
+
+        return unchecked((uint)gettid());
+    }
+
+    /// <summary>
+    /// Wraps a managed callback (compiled for the SysV ABI on POSIX .NET) in a
+    /// thunk that accepts up to four integer arguments in the Win64 ABI the
+    /// emitted x86-64 call sites use. Win64 passes args in rcx/rdx/r8/r9 and
+    /// treats rdi/rsi as non-volatile; SysV expects rdi/rsi/rdx/rcx and
+    /// clobbers them, so the thunk saves rdi/rsi, shuffles the registers, keeps
+    /// the stack 16-byte aligned for the call, and forwards the rax result.
+    /// </summary>
+    public static nint CreateWin64ToSysVThunk(nint sysvTarget)
+    {
+        var page = (byte*)HostMemory.Alloc(
+            null,
+            4096,
+            HostMemory.MEM_COMMIT | HostMemory.MEM_RESERVE,
+            HostMemory.PAGE_EXECUTE_READWRITE);
+        if (page == null)
+        {
+            throw new OutOfMemoryException("Failed to allocate Win64->SysV thunk page");
+        }
+
+        var offset = 0;
+        Emit(page, ref offset, 0x57);                   // push rdi
+        Emit(page, ref offset, 0x56);                   // push rsi
+        Emit(page, ref offset, 0x48, 0x89, 0xCF);       // mov rdi, rcx
+        Emit(page, ref offset, 0x48, 0x89, 0xD6);       // mov rsi, rdx
+        Emit(page, ref offset, 0x4C, 0x89, 0xC2);       // mov rdx, r8
+        Emit(page, ref offset, 0x4C, 0x89, 0xC9);       // mov rcx, r9
+        Emit(page, ref offset, 0x48, 0x83, 0xEC, 0x08); // sub rsp, 8 (realign to 16)
+        EmitMovRaxImm64(page, ref offset, sysvTarget);  // mov rax, target
+        Emit(page, ref offset, 0xFF, 0xD0);             // call rax
+        Emit(page, ref offset, 0x48, 0x83, 0xC4, 0x08); // add rsp, 8
+        Emit(page, ref offset, 0x5E);                   // pop rsi
+        Emit(page, ref offset, 0x5F);                   // pop rdi
+        Emit(page, ref offset, 0xC3);                   // ret
+
+        if (!HostMemory.Protect(page, 4096, HostMemory.PAGE_EXECUTE_READ, out _))
+        {
+            throw new InvalidOperationException("Failed to protect Win64->SysV thunk page");
+        }
+
+        HostMemory.FlushInstructionCache(page, (nuint)offset);
+        return (nint)page;
+    }
+
+    private static void EnsureInitialized()
+    {
+        if (_initialized)
+        {
+            return;
+        }
+
+        lock (Gate)
+        {
+            if (_initialized)
+            {
+                return;
+            }
+
+            BuildStubs();
+            _initialized = true;
+        }
+    }
+
+    private static void BuildStubs()
+    {
+        var page = (byte*)HostMemory.Alloc(
+            null,
+            4096,
+            HostMemory.MEM_COMMIT | HostMemory.MEM_RESERVE,
+            HostMemory.PAGE_EXECUTE_READWRITE);
+        if (page == null)
+        {
+            throw new OutOfMemoryException("Failed to allocate POSIX host helper stub page");
+        }
+
+        var offset = 0;
+        _tlsGetValueStub = EmitTlsGetValue(page, ref offset);
+        _queryPerformanceCounterStub = EmitQueryPerformanceCounter(page, ref offset);
+        _switchToThreadStub = EmitSwitchToThread(page, ref offset);
+        _sleepStub = EmitSleep(page, ref offset);
+
+        if (!HostMemory.Protect(page, 4096, HostMemory.PAGE_EXECUTE_READ, out _))
+        {
+            throw new InvalidOperationException("Failed to protect POSIX host helper stub page");
+        }
+
+        HostMemory.FlushInstructionCache(page, (nuint)offset);
+    }
+
+    private static nint EmitTlsGetValue(byte* page, ref int offset)
+    {
+        var start = (nint)(page + offset);
+        if (OperatingSystem.IsMacOS())
+        {
+            // On macOS x86-64 pthread keys index the gs-based thread specific
+            // data array directly, so TlsGetValue(index in ecx) collapses to a
+            // single load that clobbers nothing but RAX.
+            Emit(page, ref offset, 0x89, 0xC8);                                     // mov eax, ecx
+            Emit(page, ref offset, 0x65, 0x48, 0x8B, 0x04, 0xC5, 0, 0, 0, 0);       // mov rax, gs:[rax*8]
+            Emit(page, ref offset, 0xC3);                                           // ret
+            return start;
+        }
+
+        // Linux: call pthread_getspecific, preserving the registers that are
+        // volatile in SysV but non-volatile in Win64 (rsi, rdi).
+        var pthreadGetSpecific = ResolveLibcExport("pthread_getspecific");
+        Emit(page, ref offset, 0x56);                                               // push rsi
+        Emit(page, ref offset, 0x57);                                               // push rdi
+        Emit(page, ref offset, 0x48, 0x83, 0xEC, 0x08);                             // sub rsp, 8
+        Emit(page, ref offset, 0x89, 0xCF);                                         // mov edi, ecx
+        EmitMovRaxImm64(page, ref offset, pthreadGetSpecific);                      // mov rax, imm64
+        Emit(page, ref offset, 0xFF, 0xD0);                                         // call rax
+        Emit(page, ref offset, 0x48, 0x83, 0xC4, 0x08);                             // add rsp, 8
+        Emit(page, ref offset, 0x5F);                                               // pop rdi
+        Emit(page, ref offset, 0x5E);                                               // pop rsi
+        Emit(page, ref offset, 0xC3);                                               // ret
+        return start;
+    }
+
+    private static nint EmitQueryPerformanceCounter(byte* page, ref int offset)
+    {
+        // BOOL QueryPerformanceCounter(LARGE_INTEGER* out in rcx): the emitted
+        // consumers only need a monotonically increasing counter, which rdtsc
+        // provides without leaving Win64-safe registers.
+        var start = (nint)(page + offset);
+        Emit(page, ref offset, 0x0F, 0x31);                                         // rdtsc
+        Emit(page, ref offset, 0x48, 0xC1, 0xE2, 0x20);                             // shl rdx, 32
+        Emit(page, ref offset, 0x48, 0x09, 0xD0);                                   // or rax, rdx
+        Emit(page, ref offset, 0x48, 0x89, 0x01);                                   // mov [rcx], rax
+        Emit(page, ref offset, 0xB8, 0x01, 0x00, 0x00, 0x00);                       // mov eax, 1
+        Emit(page, ref offset, 0xC3);                                               // ret
+        return start;
+    }
+
+    private static nint EmitSwitchToThread(byte* page, ref int offset)
+    {
+        var schedYield = ResolveLibcExport("sched_yield");
+        var start = (nint)(page + offset);
+        Emit(page, ref offset, 0x56);                                               // push rsi
+        Emit(page, ref offset, 0x57);                                               // push rdi
+        Emit(page, ref offset, 0x48, 0x83, 0xEC, 0x08);                             // sub rsp, 8
+        EmitMovRaxImm64(page, ref offset, schedYield);                              // mov rax, imm64
+        Emit(page, ref offset, 0xFF, 0xD0);                                         // call rax
+        Emit(page, ref offset, 0x48, 0x83, 0xC4, 0x08);                             // add rsp, 8
+        Emit(page, ref offset, 0x5F);                                               // pop rdi
+        Emit(page, ref offset, 0x5E);                                               // pop rsi
+        Emit(page, ref offset, 0xB8, 0x01, 0x00, 0x00, 0x00);                       // mov eax, 1
+        Emit(page, ref offset, 0xC3);                                               // ret
+        return start;
+    }
+
+    private static nint EmitSleep(byte* page, ref int offset)
+    {
+        // void Sleep(DWORD milliseconds in ecx) -> usleep(microseconds in edi).
+        var usleep = ResolveLibcExport("usleep");
+        var start = (nint)(page + offset);
+        Emit(page, ref offset, 0x56);                                               // push rsi
+        Emit(page, ref offset, 0x57);                                               // push rdi
+        Emit(page, ref offset, 0x48, 0x83, 0xEC, 0x08);                             // sub rsp, 8
+        Emit(page, ref offset, 0x89, 0xCF);                                         // mov edi, ecx
+        Emit(page, ref offset, 0x81, 0xFF, 0xFF, 0x0F, 0x00, 0x00);                 // cmp edi, 0xFFF
+        Emit(page, ref offset, 0x76, 0x05);                                         // jbe +5
+        Emit(page, ref offset, 0xBF, 0xFF, 0x0F, 0x00, 0x00);                       // mov edi, 0xFFF (cap at ~4s)
+        Emit(page, ref offset, 0x69, 0xFF, 0xE8, 0x03, 0x00, 0x00);                 // imul edi, edi, 1000
+        EmitMovRaxImm64(page, ref offset, usleep);                                  // mov rax, imm64
+        Emit(page, ref offset, 0xFF, 0xD0);                                         // call rax
+        Emit(page, ref offset, 0x48, 0x83, 0xC4, 0x08);                             // add rsp, 8
+        Emit(page, ref offset, 0x5F);                                               // pop rdi
+        Emit(page, ref offset, 0x5E);                                               // pop rsi
+        Emit(page, ref offset, 0xC3);                                               // ret
+        return start;
+    }
+
+    private static nint ResolveLibcExport(string name)
+    {
+        var libc = NativeLibrary.Load(OperatingSystem.IsMacOS() ? "libSystem.dylib" : "libc.so.6");
+        return NativeLibrary.GetExport(libc, name);
+    }
+
+    private static void Emit(byte* page, ref int offset, params byte[] bytes)
+    {
+        foreach (var value in bytes)
+        {
+            page[offset++] = value;
+        }
+    }
+
+    private static void EmitMovRaxImm64(byte* page, ref int offset, nint value)
+    {
+        Emit(page, ref offset, 0x48, 0xB8);
+        *(long*)(page + offset) = value;
+        offset += sizeof(long);
+    }
+
+    [DllImport("libc", EntryPoint = "pthread_key_create", SetLastError = true)]
+    private static extern int pthread_key_create_mac(nuint* key, nint destructor);
+
+    [DllImport("libc", EntryPoint = "pthread_key_create", SetLastError = true)]
+    private static extern int pthread_key_create_linux(uint* key, nint destructor);
+
+    [DllImport("libc", EntryPoint = "pthread_key_delete")]
+    private static extern int pthread_key_delete_mac(nuint key);
+
+    [DllImport("libc", EntryPoint = "pthread_key_delete")]
+    private static extern int pthread_key_delete_linux(uint key);
+
+    [DllImport("libc", EntryPoint = "pthread_setspecific")]
+    private static extern int pthread_setspecific_mac(nuint key, nint value);
+
+    [DllImport("libc", EntryPoint = "pthread_setspecific")]
+    private static extern int pthread_setspecific_linux(uint key, nint value);
+
+    [DllImport("libc", EntryPoint = "pthread_getspecific")]
+    private static extern nint pthread_getspecific_mac(nuint key);
+
+    [DllImport("libc", EntryPoint = "pthread_getspecific")]
+    private static extern nint pthread_getspecific_linux(uint key);
+
+    [DllImport("libc")]
+    private static extern int pthread_threadid_np(nint thread, ulong* threadId);
+
+    [DllImport("libc")]
+    private static extern int gettid();
+
+    [DllImport("libc")]
+    private static extern nint dispatch_semaphore_create(long value);
+
+    [DllImport("libc")]
+    private static extern nint dispatch_semaphore_signal(nint semaphore);
+
+    [DllImport("libc")]
+    private static extern nint dispatch_semaphore_wait(nint semaphore, ulong timeout);
+
+    [DllImport("libc")]
+    private static extern ulong dispatch_time(ulong when, long deltaNanoseconds);
+
+    [DllImport("libc")]
+    private static extern void dispatch_release(nint handle);
+
+    [DllImport("libc")]
+    private static extern int sem_init(nint semaphore, int shared, uint value);
+
+    [DllImport("libc")]
+    private static extern int sem_post(nint semaphore);
+
+    [DllImport("libc")]
+    private static extern int sem_wait(nint semaphore);
+
+    [DllImport("libc")]
+    private static extern int sem_trywait(nint semaphore);
+
+    [DllImport("libc")]
+    private static extern int sem_destroy(nint semaphore);
+}

src/SharpEmu.Core/Cpu/Native/StubManager.cs

@@ -3,7 +3,6 @@
 
 using System.Runtime.InteropServices;
 using SharpEmu.HLE;
-using SharpEmu.HLE.Host;
 
 namespace SharpEmu.Core.Cpu.Native;
 
@@ -12,15 +11,17 @@ public sealed unsafe class StubManager : IDisposable
     private readonly List<nint> _allocatedStubs = new();
     private readonly Dictionary<string, nint> _importHandlers = new();
     private readonly Dictionary<ulong, nint> _stubAddresses = new();
-    private readonly IHostMemory _hostMemory;
     private byte* _pltMemory;
     private int _pltOffset;
     private const int PltMemorySize = 1024 * 1024; // 1MB for stubs
 
-    public StubManager(IHostMemory? hostMemory = null)
+    public StubManager()
     {
-        _hostMemory = hostMemory ?? HostPlatform.Current.Memory;
-        _pltMemory = (byte*)_hostMemory.Allocate(0, PltMemorySize, HostPageProtection.ReadWriteExecute);
+        _pltMemory = (byte*)VirtualAlloc(
+            null,
+            (nuint)PltMemorySize,
+            AllocationType.Reserve | AllocationType.Commit,
+            MemoryProtection.ExecuteReadWrite);
 
         if (_pltMemory == null)
         {
@@ -184,7 +185,7 @@ public sealed unsafe class StubManager : IDisposable
     {
         if (_pltMemory != null)
         {
-            _hostMemory.Free((ulong)_pltMemory);
+            VirtualFree(_pltMemory, 0, FreeType.Release);
             _pltMemory = null;
         }
 
@@ -193,5 +194,29 @@ public sealed unsafe class StubManager : IDisposable
         _stubAddresses.Clear();
     }
 
+    private static void* VirtualAlloc(void* lpAddress, nuint dwSize, AllocationType flAllocationType, MemoryProtection flProtect) =>
+        HostMemory.Alloc(lpAddress, dwSize, (uint)flAllocationType, (uint)flProtect);
+
+    private static bool VirtualFree(void* lpAddress, nuint dwSize, FreeType dwFreeType) =>
+        HostMemory.Free(lpAddress, dwSize, (uint)dwFreeType);
+
+    [Flags]
+    private enum AllocationType : uint
+    {
+        Commit = 0x1000,
+        Reserve = 0x2000,
+    }
+
+    [Flags]
+    private enum MemoryProtection : uint
+    {
+        ExecuteReadWrite = 0x40,
+    }
+
+    private enum FreeType : uint
+    {
+        Release = 0x8000,
+    }
+
     public delegate void ImportHandler(CpuContext context);
 }

src/SharpEmu.Core/Loader/ProgramHeader.cs

@@ -48,6 +48,8 @@ public enum ProgramHeaderType : uint
 
     Tls = 7,
 
+    GnuEhFrame = 0x6474E550,
+
     SceRela = 0x60000000,
 
     SceProcParam = 0x61000001,

src/SharpEmu.Core/Loader/SelfImage.cs

@@ -24,7 +24,10 @@ public sealed class SelfImage
         ulong procParamAddress = 0,
         string? title = null,
         string? titleId = null,
-        string? version = null)
+        string? version = null,
+        uint tlsModuleId = 0,
+        ulong tlsMemorySize = 0,
+        ulong tlsStaticOffset = 0)
     {
         ArgumentNullException.ThrowIfNull(programHeaders);
         ArgumentNullException.ThrowIfNull(mappedRegions);
@@ -44,6 +47,9 @@ public sealed class SelfImage
         Title = title;
         TitleId = titleId;
         Version = version;
+        TlsModuleId = tlsModuleId;
+        TlsMemorySize = tlsMemorySize;
+        TlsStaticOffset = tlsStaticOffset;
     }
 
     public bool IsSelf { get; }
@@ -75,4 +81,11 @@ public sealed class SelfImage
     public string? TitleId { get; }
 
     public string? Version { get; }
+
+    public uint TlsModuleId { get; }
+
+    public ulong TlsMemorySize { get; }
+
+    /// <summary>Variant II distance from the thread pointer to this module's static TLS base.</summary>
+    public ulong TlsStaticOffset { get; }
 }

src/SharpEmu.Core/Loader/SelfLoader.cs

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 
 using System.Buffers.Binary;
+using System.Diagnostics;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using System.Text;
@@ -10,16 +11,14 @@ using SharpEmu.Core;
 using SharpEmu.Core.Cpu;
 using SharpEmu.Core.Memory;
 using SharpEmu.HLE;
-using SharpEmu.Logging;
 
 namespace SharpEmu.Core.Loader;
 
 public sealed class SelfLoader : ISelfLoader
 {
-    private static readonly SharpEmuLogger Log = SharpEmuLog.For("Loader");
     private const uint ElfMagic = 0x7F454C46;
-    private const uint Ps4SelfMagic  = 0x4F153D1D;
-    private const uint Ps5SelfMagic  = 0x5414F5EE;
+    private const uint Ps4SelfMagic = 0x4F153D1D;
+    private const uint Ps5SelfMagic = 0x5414F5EE;
     private const ulong SelfSegmentFlag = 0x800;
     private const int PageSize = 0x1000;
     private const ulong ImportStubBaseAddress = 0x0000_7000_0000_0000UL;
@@ -58,11 +57,22 @@ public sealed class SelfLoader : ISelfLoader
     private const long DtSceSymTab = 0x61000039;
     private const long DtSceSymTabSize = 0x6100003F;
 
+    private const uint RelocationTypeNone = 0;
     private const uint RelocationTypeAbsolute64 = 1;
+    private const uint RelocationTypePc32 = 2;
+    private const uint RelocationTypePlt32 = 4;
     private const uint RelocationTypeGlobalData = 6;
     private const uint RelocationTypeJumpSlot = 7;
     private const uint RelocationTypeRelative = 8;
-    private const uint RelocationTypeTlsModuleId = 16;
+    private const uint RelocationTypeUnsigned32 = 10;
+    private const uint RelocationTypeSigned32 = 11;
+    private const uint RelocationTypeTlsModuleId = 16;   // R_X86_64_DTPMOD64
+    private const uint RelocationTypeTlsDtpOff64 = 17;    // R_X86_64_DTPOFF64
+    private const uint RelocationTypeTlsTpOff64 = 18;     // R_X86_64_TPOFF64
+    private const uint RelocationTypePc64 = 24;
+    private const uint RelocationTypeSize32 = 32;
+    private const uint RelocationTypeSize64 = 33;
+    private const uint RelocationTypeRelative64 = 38;
     private const ulong Ps5MainImageBase = 0x0000000800000000UL;
     private const ulong Ps4MainImageBase = 0x0000000000400000UL;
     private const ulong Ps5ModuleSearchStart = 0x0000000804000000UL;
@@ -88,6 +98,11 @@ public sealed class SelfLoader : ISelfLoader
     private static readonly int SelfSegmentSize = Unsafe.SizeOf<SelfSegment>();
     private static readonly int ProgramHeaderSize = Unsafe.SizeOf<ProgramHeader>();
 
+    static SelfLoader()
+    {
+        RunRelocationSelfChecks();
+    }
+
     public SelfImage Load(ReadOnlySpan<byte> imageData, IVirtualMemory virtualMemory)
     {
         return Load(imageData, virtualMemory, fs: null, mountRoot: null);
@@ -156,16 +171,22 @@ public sealed class SelfLoader : ISelfLoader
         {
             virtualMemory.Clear();
             _nextTlsModuleId = 1;
+            GuestTlsTemplate.Reset();
         }
 
-        var tlsModuleId = _nextTlsModuleId == 0 ? 1u : _nextTlsModuleId;
-        Log.Debug($"TLS load_start clear={clearVirtualMemory} next={_nextTlsModuleId} assigned={tlsModuleId}");
-
         var loadContext = ParseLayout(imageData);
         var elfHeader = ReadUnmanaged<ElfHeader>(imageData, loadContext.ElfOffset);
         ValidateElfHeader(elfHeader);
 
         var programHeaders = ParseProgramHeaders(imageData, loadContext, elfHeader);
+        var hasTlsSegment = TryGetProgramHeader(programHeaders, ProgramHeaderType.Tls, out var processTlsHeader, out _) &&
+            processTlsHeader.MemorySize != 0;
+        var tlsModuleId = hasTlsSegment
+            ? (_nextTlsModuleId == 0 ? 1u : _nextTlsModuleId)
+            : 0u;
+        Console.Error.WriteLine(
+            $"[LOADER][TLS] load_start clear={clearVirtualMemory} next={_nextTlsModuleId} " +
+            $"assigned={tlsModuleId} has_pt_tls={hasTlsSegment}");
 
         var totalImageSize = CalculateTotalImageSize(programHeaders);
         Console.WriteLine($"Total image size needed: 0x{totalImageSize:X} ({totalImageSize} bytes)");
@@ -178,8 +199,9 @@ public sealed class SelfLoader : ISelfLoader
             {
                 if (!physicalVm.TryAllocateAtExact(imageBase, totalImageSize, executable: true, out var allocatedBase))
                 {
+                    var reason = physicalVm.DescribeAddressForDiagnostics(imageBase);
                     throw new InvalidOperationException(
-                        $"Could not allocate main image at required base 0x{imageBase:X16} (size=0x{totalImageSize:X}).");
+                        $"Could not allocate main image at required base 0x{imageBase:X16} (size=0x{totalImageSize:X}): {reason}.");
                 }
 
                 imageBase = allocatedBase;
@@ -198,6 +220,13 @@ public sealed class SelfLoader : ISelfLoader
         }
 
         MapLoadSegments(imageData, loadContext, programHeaders, virtualMemory, imageBase);
+        // Register every module before relocations so DTPMOD/DTPOFF/TPOFF use
+        // the module's real PT_TLS identity and Variant II static offset.
+        var tlsInfo = RegisterModuleTlsTemplate(
+            programHeaders,
+            virtualMemory,
+            imageBase,
+            tlsModuleId);
         var importStubs = ResolveAndPatchImportStubs(
             imageData,
             loadContext,
@@ -255,11 +284,11 @@ public sealed class SelfLoader : ISelfLoader
             Console.WriteLine($"[LOADER] PH[{i}]: type={ph.HeaderType}, vaddr=0x{ph.VirtualAddress:X16} -> 0x{ph.VirtualAddress + imageBase:X16}, memsz=0x{ph.MemorySize:X}");
         }
 
-        if (_nextTlsModuleId == tlsModuleId && _nextTlsModuleId < uint.MaxValue)
+        if (tlsModuleId != 0 && _nextTlsModuleId == tlsModuleId && _nextTlsModuleId < uint.MaxValue)
         {
             _nextTlsModuleId++;
         }
-        Log.Debug($"TLS load_done assigned={tlsModuleId} next={_nextTlsModuleId}");
+        Console.Error.WriteLine($"[LOADER][TLS] load_done assigned={tlsModuleId} next={_nextTlsModuleId}");
 
         return new SelfImage(
             loadContext.IsSelf,
@@ -276,7 +305,10 @@ public sealed class SelfLoader : ISelfLoader
             procParamAddress,
             applicationInfo.Title,
             applicationInfo.TitleId,
-            applicationInfo.Version);
+            applicationInfo.Version,
+            tlsModuleId,
+            tlsInfo.MemorySize,
+            tlsInfo.StaticOffset);
     }
 
     private static (string? Title, string? TitleId, string? Version) TryLoadParamJson(
@@ -329,7 +361,7 @@ public sealed class SelfLoader : ISelfLoader
         if (magic is Ps4SelfMagic or Ps5SelfMagic)
         {
             var selfHeader = ReadUnmanaged<SelfHeader>(imageData, 0);
-            if (!selfHeader.HasKnownLayout || selfHeader.Unknown != 0x22)
+            if (!selfHeader.HasKnownLayout)
             {
                 throw new InvalidDataException("SELF header signature is not recognized.");
             }
@@ -348,10 +380,17 @@ public sealed class SelfLoader : ISelfLoader
             return new LoadContext(IsSelf: true, elfOffset, selfHeader.FileSize, segments);
         }
 
+        // Not a recognized (fake-signed) SELF. Only a bare, decrypted ELF is
+        // acceptable here; anything else — most commonly a still-encrypted
+        // retail eboot — must be reported clearly rather than failing later
+        // with an opaque "not a valid ELF header" message.
         if (magic != ElfMagic)
         {
             throw new InvalidDataException(
-                $"Unsupported executable signature 0x{magic:X8}");
+                $"Image is neither a decrypted ELF nor a recognized fake-signed SELF " +
+                $"(leading bytes 0x{magic:X8}). This is almost certainly a still-encrypted " +
+                $"retail eboot — SharpEmu has no decryption keys and requires a decrypted / " +
+                $"fake-signed (fSELF) image.");
         }
 
         return new LoadContext(IsSelf: false, ElfOffset: 0, SelfFileSize: 0, Array.Empty<SelfSegment>());
@@ -414,15 +453,15 @@ public sealed class SelfLoader : ISelfLoader
 
             var virtualAddress = header.VirtualAddress + imageBase;
 
-            Log.Debug($"Segment {index}: VAddr=0x{virtualAddress:X16}, FileSize=0x{header.FileSize:X}, MemSize=0x{header.MemorySize:X}, Align=0x{header.Alignment:X}");
+            Console.Error.WriteLine($"[LOADER] Segment {index}: VAddr=0x{virtualAddress:X16}, FileSize=0x{header.FileSize:X}, MemSize=0x{header.MemorySize:X}, Align=0x{header.Alignment:X}");
             if (header.Alignment > 1)
             {
                 var vaddrMod = virtualAddress % header.Alignment;
                 var offsetMod = header.Offset % header.Alignment;
                 if (vaddrMod != offsetMod)
                 {
-                    Log.Warning(
-                        $"Segment {index} ELF alignment mismatch! " +
+                    Console.Error.WriteLine(
+                        $"[LOADER] WARNING: Segment {index} ELF alignment mismatch! " +
                         $"VAddr=0x{virtualAddress:X}, Offset=0x{header.Offset:X}, Align=0x{header.Alignment:X}, " +
                         $"VAddr%Align=0x{vaddrMod:X}, Offset%Align=0x{offsetMod:X}");
                 }
@@ -465,6 +504,43 @@ public sealed class SelfLoader : ISelfLoader
         return 0;
     }
 
+    private static ModuleTlsInfo RegisterModuleTlsTemplate(
+        IReadOnlyList<ProgramHeader> programHeaders,
+        IVirtualMemory virtualMemory,
+        ulong imageBase,
+        uint tlsModuleId)
+    {
+        if (!TryGetProgramHeader(programHeaders, ProgramHeaderType.Tls, out var tlsHeader, out _) ||
+            tlsHeader.MemorySize == 0)
+        {
+            return default;
+        }
+
+        // tdata (initialized) bytes come from the mapped segment; tbss is the
+        // implicitly-zero remainder up to MemorySize.
+        var fileSize = (int)Math.Min(tlsHeader.FileSize, tlsHeader.MemorySize);
+        var initImage = fileSize > 0 ? new byte[fileSize] : [];
+        if (fileSize > 0 &&
+            !virtualMemory.TryRead(imageBase + tlsHeader.VirtualAddress, initImage))
+        {
+            Console.Error.WriteLine(
+                $"[LOADER][TLS] Failed to read TLS init image at 0x{imageBase + tlsHeader.VirtualAddress:X}; seeding zeros.");
+            initImage = [];
+        }
+
+        var staticOffset = GuestTlsTemplate.RegisterModule(
+            tlsModuleId,
+            initImage,
+            tlsHeader.MemorySize,
+            tlsHeader.Alignment,
+            tlsHeader.VirtualAddress);
+        Console.Error.WriteLine(
+            $"[LOADER][TLS] Module {tlsModuleId} TLS template: memsz=0x{tlsHeader.MemorySize:X} " +
+            $"filesz=0x{tlsHeader.FileSize:X} align=0x{tlsHeader.Alignment:X} " +
+            $"static_offset=0x{staticOffset:X} total_static=0x{GuestTlsTemplate.StaticTlsSize:X}");
+        return new ModuleTlsInfo(tlsHeader.MemorySize, staticOffset);
+    }
+
     private static IReadOnlyDictionary<ulong, string> ResolveAndPatchImportStubs(
         ReadOnlySpan<byte> imageData,
         LoadContext loadContext,
@@ -544,12 +620,17 @@ public sealed class SelfLoader : ISelfLoader
         uint maxSymbolIndex = 0;
         foreach (var relocation in relocations)
         {
+            if (relocation.Type == RelocationTypeNone)
+            {
+                continue;
+            }
+
             if (!IsSupportedRelocationType(relocation.Type))
             {
                 continue;
             }
 
-            if (relocation.Type is RelocationTypeRelative or RelocationTypeTlsModuleId)
+            if (relocation.Type is RelocationTypeNone or RelocationTypeRelative or RelocationTypeRelative64 or RelocationTypeTlsModuleId)
             {
                 continue;
             }
@@ -633,13 +714,16 @@ public sealed class SelfLoader : ISelfLoader
 
         importedRelocations = BuildImportedRelocations(descriptors);
 
-        var stubsByAddress = CreateImportStubMapping(virtualMemory, orderedImportNids);
+        var stubImportNids = orderedImportNids
+            .Where(nid => ShouldCreateImportStub(nid, descriptors, moduleManager))
+            .ToArray();
+        var stubsByAddress = CreateImportStubMapping(virtualMemory, stubImportNids);
         Console.WriteLine($"[LOADER] Created {stubsByAddress.Count} import stubs");
 
-        int printCount = Math.Min(10, orderedImportNids.Count);
+        int printCount = Math.Min(10, stubImportNids.Length);
         for (int i = 0; i < printCount; i++)
         {
-            var nid = orderedImportNids[i];
+            var nid = stubImportNids[i];
             var addr = stubsByAddress.First(x => x.Value == nid).Key;
         }
 
@@ -663,45 +747,65 @@ public sealed class SelfLoader : ISelfLoader
 
         foreach (var descriptor in descriptors)
         {
-            ulong targetValue;
+            ulong symbolValue;
             if (descriptor.ImportNid is null)
             {
-                targetValue = AddSigned(descriptor.SymbolValue, descriptor.Addend);
+                symbolValue = descriptor.SymbolValue;
             }
             else
             {
-                if (!addressesByNid.TryGetValue(descriptor.ImportNid, out var stubAddress))
+                if (addressesByNid.TryGetValue(descriptor.ImportNid, out var stubAddress))
                 {
-                    throw new InvalidOperationException($"Import stub not found for NID '{descriptor.ImportNid}'.");
+                    symbolValue = stubAddress;
                 }
-
-                targetValue = AddSigned(stubAddress, descriptor.Addend);
-            }
-
-            if (targetValue < 0x1000)
-            {
-                if (descriptor.ValueKind == RelocationValueKind.TlsModuleId)
+                else if (descriptor.IsWeak)
                 {
-                    Log.Debug(
-                        $"Patching DTPMOD64 at 0x{descriptor.TargetAddress:X} with module id 0x{targetValue:X}");
+                    // ELF unresolved weak definitions use S=0. They must not
+                    // receive a trap import stub, which would turn a permitted
+                    // null test into a call to an unresolved-import handler.
+                    symbolValue = 0;
                 }
                 else
                 {
-                    Log.Warning($"!!! CRITICAL !!! Patching address 0x{descriptor.TargetAddress:X} with INVALID value 0x{targetValue:X} for NID {descriptor.ImportNid ?? "(null)"}");
-                    Log.Warning($"  SymbolValue=0x{descriptor.SymbolValue:X}, Addend=0x{descriptor.Addend:X}, StubAddress=0x{(addressesByNid.TryGetValue(descriptor.ImportNid ?? "", out var sa) ? sa : 0):X}");
+                    throw new InvalidOperationException($"Import stub not found for NID '{descriptor.ImportNid}'.");
                 }
             }
 
-            if (!TryWriteUInt64(virtualMemory, descriptor.TargetAddress, targetValue))
+            var targetValue = ComputeRelocationValue(descriptor, symbolValue);
+
+            if (targetValue < 0x1000 && descriptor.ValueKind is
+                RelocationValueKind.TlsOffset or
+                RelocationValueKind.PcRelative or
+                RelocationValueKind.SymbolSize)
             {
-                throw new InvalidDataException($"Failed to patch relocation at 0x{descriptor.TargetAddress:X16}.");
+                // A TLS offset (TPOFF64/DTPOFF64) is a signed displacement, not a
+                // mapped address, so a small or negative value here is expected.
+            }
+            else if (targetValue < 0x1000 && !descriptor.IsWeak)
+            {
+                if (descriptor.ValueKind == RelocationValueKind.TlsModuleId)
+                {
+                    Console.Error.WriteLine(
+                        $"[LOADER][TLS] Patching DTPMOD64 at 0x{descriptor.TargetAddress:X} with module id 0x{targetValue:X}");
+                }
+                else
+                {
+                    Console.Error.WriteLine($"[LOADER] !!! CRITICAL !!! Patching address 0x{descriptor.TargetAddress:X} with INVALID value 0x{targetValue:X} for NID {descriptor.ImportNid ?? "(null)"}");
+                    Console.Error.WriteLine($"[LOADER]   SymbolValue=0x{descriptor.SymbolValue:X}, Addend=0x{descriptor.Addend:X}, StubAddress=0x{(addressesByNid.TryGetValue(descriptor.ImportNid ?? "", out var sa) ? sa : 0):X}");
+                }
+            }
+
+            if (!TryWriteRelocationValue(virtualMemory, descriptor, targetValue, out var writeError))
+            {
+                throw new InvalidDataException(
+                    $"Failed to patch relocation at 0x{descriptor.TargetAddress:X16}: {writeError}");
             }
 
             if (descriptor.TargetAddress >= 0x00000008030FC300UL &&
                 descriptor.TargetAddress <= 0x00000008030FC3F0UL)
             {
-                Log.Debug(
-                    $"[RELOC] target=0x{descriptor.TargetAddress:X16} value=0x{targetValue:X16} addend=0x{descriptor.Addend:X} nid={(descriptor.ImportNid ?? "<sym>")}");
+                Console.Error.WriteLine(
+                    $"[LOADER][RELOC] target=0x{descriptor.TargetAddress:X16} value=0x{targetValue:X16} addend=0x{descriptor.Addend:X} nid={(descriptor.ImportNid ?? "<sym>")}");
             }
         }
 
@@ -794,29 +898,36 @@ public sealed class SelfLoader : ISelfLoader
         {
             if (IsFocusRelocationOffset(relocation.Offset, imageBase))
             {
-                Log.Debug(
-                    $"[FOCUS][SCAN] off=0x{relocation.Offset:X16} type={relocation.Type} sym={relocation.SymbolIndex} addend=0x{relocation.Addend:X}");
+                Console.Error.WriteLine(
+                    $"[LOADER][FOCUS][SCAN] off=0x{relocation.Offset:X16} type={relocation.Type} sym={relocation.SymbolIndex} addend=0x{relocation.Addend:X}");
             }
 
             if (!IsSupportedRelocationType(relocation.Type))
             {
-                if (IsFocusRelocationOffset(relocation.Offset, imageBase))
+                // Surface unsupported relocation types loudly instead of
+                // skipping silently: TLS-relative (17/18), COPY (5), and
+                // IRELATIVE/ifunc (37) leave their targets unrelocated, which
+                // manifests later as reads of zero or calls into address 0.
+                ReportUnsupportedRelocation(relocation.Type, relocation.Offset, imageBase);
+                if (relocation.Type is 5 or 37)
                 {
-                    Log.Debug($"[FOCUS][SKIP] unsupported type={relocation.Type}");
+                    throw new NotSupportedException(
+                        $"Relocation type {relocation.Type} requires deferred runtime-linker processing.");
                 }
                 continue;
             }
 
-            if (!TryResolveMappedAddress(virtualMemory, relocation.Offset, imageBase, sizeof(ulong), out var targetAddress))
+            var relocationWriteSize = GetRelocationWriteSize(relocation.Type);
+            if (!TryResolveMappedAddress(virtualMemory, relocation.Offset, imageBase, relocationWriteSize, out var targetAddress))
             {
                 if (IsFocusRelocationOffset(relocation.Offset, imageBase))
                 {
-                    Log.Debug("[FOCUS][SKIP] target address not mapped");
+                    Console.Error.WriteLine("[LOADER][FOCUS][SKIP] target address not mapped");
                 }
                 continue;
             }
 
-            if (relocation.Type == RelocationTypeRelative)
+            if (relocation.Type is RelocationTypeRelative or RelocationTypeRelative64)
             {
                 descriptors.Add(new RelocationDescriptor(
                     targetAddress,
@@ -830,7 +941,12 @@ public sealed class SelfLoader : ISelfLoader
 
             if (relocation.Type == RelocationTypeTlsModuleId)
             {
-                var dtpmodValue = tlsModuleId == 0 ? 1u : tlsModuleId;
+                if (tlsModuleId == 0)
+                {
+                    throw new InvalidDataException(
+                        $"R_X86_64_DTPMOD64 at 0x{targetAddress:X16} references a module without PT_TLS.");
+                }
+                var dtpmodValue = tlsModuleId;
                 descriptors.Add(new RelocationDescriptor(
                     targetAddress,
                     0,
@@ -851,50 +967,100 @@ public sealed class SelfLoader : ISelfLoader
             {
                 if (targetAddress >= FocusRelocGuestStart && targetAddress <= FocusRelocGuestEnd)
                 {
-                    Log.Debug($"[FOCUS][SKIP] symbol read failed index={symbolIndex}");
+                    Console.Error.WriteLine($"[LOADER][FOCUS][SKIP] symbol read failed index={symbolIndex}");
                 }
                 continue;
             }
 
-            var addend = relocation.Type is RelocationTypeGlobalData or RelocationTypeJumpSlot ? 0 : relocation.Addend;
-            var symbolBind = GetSymbolBind(symbol.Info);
-            if (symbolBind == SymbolBindLocal)
+            if (relocation.Type is RelocationTypeTlsDtpOff64 or RelocationTypeTlsTpOff64)
             {
-                var symbolAddress = ResolveMappedAddressOrFallback(virtualMemory, symbol.Value, imageBase);
-                if (symbolAddress == 0)
+                // Variant II static TLS: the module block sits at
+                // [tp - blockSize, tp). DTPOFF64 is the module-relative offset
+                // (st_value + addend); TPOFF64 is that offset expressed relative
+                // to the thread pointer, i.e. minus the aligned block size.
+                var tlsSymbolOffset = AddSigned(symbol.Value, relocation.Addend);
+                if (!GuestTlsTemplate.TryGetStaticOffset(tlsModuleId, out var moduleStaticOffset))
                 {
-                    Log.Warning(
-                        $"Skipping local relocation with invalid symbol value 0x{symbol.Value:X} " +
-                        $"at target 0x{targetAddress:X16}, type={relocation.Type}, sym={symbolIndex}");
+                    Console.Error.WriteLine(
+                        $"[LOADER][TLS] Missing PT_TLS registration for module {tlsModuleId}; " +
+                        $"cannot apply relocation {relocation.Type} at 0x{targetAddress:X16}.");
+                    continue;
                 }
-
+                var tlsValue = relocation.Type == RelocationTypeTlsTpOff64
+                    ? unchecked(tlsSymbolOffset - moduleStaticOffset)
+                    : tlsSymbolOffset;
                 descriptors.Add(new RelocationDescriptor(
                     targetAddress,
-                    addend,
+                    0,
                     null,
-                    symbolAddress,
-                    RelocationValueKind.Pointer,
+                    tlsValue,
+                    RelocationValueKind.TlsOffset,
                     IsDataImport: false));
                 continue;
             }
 
+            var symbolBind = GetSymbolBind(symbol.Info);
+            if (symbolIndex == 0)
+            {
+                descriptors.Add(CreateSymbolRelocationDescriptor(
+                    relocation,
+                    targetAddress,
+                    symbol,
+                    symbolAddress: 0,
+                    importNid: null,
+                    isWeak: false));
+                continue;
+            }
+
+            if (symbolBind == SymbolBindLocal)
+            {
+                var symbolAddress = relocation.Type is RelocationTypeSize32 or RelocationTypeSize64
+                    ? 0
+                    : ResolveMappedAddressOrFallback(virtualMemory, symbol.Value, imageBase);
+                if (symbolAddress == 0)
+                {
+                    if (relocation.Type is not (RelocationTypeSize32 or RelocationTypeSize64))
+                    {
+                        Console.Error.WriteLine(
+                            $"[LOADER] Skipping local relocation with invalid symbol value 0x{symbol.Value:X} " +
+                            $"at target 0x{targetAddress:X16}, type={relocation.Type}, sym={symbolIndex}");
+                        continue;
+                    }
+                }
+
+                descriptors.Add(CreateSymbolRelocationDescriptor(
+                    relocation,
+                    targetAddress,
+                    symbol,
+                    symbolAddress,
+                    importNid: null,
+                    isWeak: false));
+                continue;
+            }
+
             if (symbol.Value != 0)
             {
-                var symbolAddress = ResolveMappedAddressOrFallback(virtualMemory, symbol.Value, imageBase);
+                var symbolAddress = relocation.Type is RelocationTypeSize32 or RelocationTypeSize64
+                    ? 0
+                    : ResolveMappedAddressOrFallback(virtualMemory, symbol.Value, imageBase);
                 if (symbolAddress == 0)
                 {
-                    Log.Warning(
-                        $"Skipping relocation with invalid symbol value 0x{symbol.Value:X} " +
-                        $"at target 0x{targetAddress:X16}, type={relocation.Type}, sym={symbolIndex}");
+                    if (relocation.Type is not (RelocationTypeSize32 or RelocationTypeSize64))
+                    {
+                        Console.Error.WriteLine(
+                            $"[LOADER] Skipping relocation with invalid symbol value 0x{symbol.Value:X} " +
+                            $"at target 0x{targetAddress:X16}, type={relocation.Type}, sym={symbolIndex}");
+                        continue;
+                    }
                 }
 
-                descriptors.Add(new RelocationDescriptor(
+                descriptors.Add(CreateSymbolRelocationDescriptor(
+                    relocation,
                     targetAddress,
-                    addend,
-                    null,
+                    symbol,
                     symbolAddress,
-                    RelocationValueKind.Pointer,
-                    IsDataImport: false));
+                    importNid: null,
+                    isWeak: false));
                 continue;
             }
 
@@ -902,16 +1068,26 @@ public sealed class SelfLoader : ISelfLoader
             {
                 if (targetAddress >= FocusRelocGuestStart && targetAddress <= FocusRelocGuestEnd)
                 {
-                    Log.Debug($"[FOCUS][SKIP] bind={symbolBind} not importable");
+                    Console.Error.WriteLine($"[LOADER][FOCUS][SKIP] bind={symbolBind} not importable");
                 }
                 continue;
             }
 
             if (!TryReadNullTerminatedAscii(stringTable, symbol.NameOffset, out var symbolName))
             {
+                if (symbolBind == SymbolBindWeak)
+                {
+                    descriptors.Add(CreateSymbolRelocationDescriptor(
+                        relocation,
+                        targetAddress,
+                        symbol,
+                        symbolAddress: 0,
+                        importNid: null,
+                        isWeak: true));
+                }
                 if (targetAddress >= FocusRelocGuestStart && targetAddress <= FocusRelocGuestEnd)
                 {
-                    Log.Debug($"[FOCUS][SKIP] symbol name read failed offset={symbol.NameOffset}");
+                    Console.Error.WriteLine($"[LOADER][FOCUS][SKIP] symbol name read failed offset={symbol.NameOffset}");
                 }
                 continue;
             }
@@ -919,6 +1095,16 @@ public sealed class SelfLoader : ISelfLoader
             var nid = ExtractNid(symbolName);
             if (string.IsNullOrWhiteSpace(nid))
             {
+                if (symbolBind == SymbolBindWeak)
+                {
+                    descriptors.Add(CreateSymbolRelocationDescriptor(
+                        relocation,
+                        targetAddress,
+                        symbol,
+                        symbolAddress: 0,
+                        importNid: null,
+                        isWeak: true));
+                }
                 continue;
             }
 
@@ -927,16 +1113,74 @@ public sealed class SelfLoader : ISelfLoader
                 orderedImportNids.Add(nid);
             }
 
-            descriptors.Add(new RelocationDescriptor(
+            descriptors.Add(CreateSymbolRelocationDescriptor(
+                relocation,
                 targetAddress,
-                addend,
-                nid,
-                0,
-                RelocationValueKind.Pointer,
-                IsDataImport: GetSymbolType(symbol.Info) == SymbolTypeObject));
+                symbol,
+                symbolAddress: 0,
+                importNid: nid,
+                isWeak: symbolBind == SymbolBindWeak));
         }
     }
 
+    private static RelocationDescriptor CreateSymbolRelocationDescriptor(
+        ElfRelocation relocation,
+        ulong targetAddress,
+        ElfSymbol symbol,
+        ulong symbolAddress,
+        string? importNid,
+        bool isWeak)
+    {
+        var valueKind = relocation.Type switch
+        {
+            RelocationTypePc32 or RelocationTypePlt32 or RelocationTypePc64 => RelocationValueKind.PcRelative,
+            RelocationTypeSize32 or RelocationTypeSize64 => RelocationValueKind.SymbolSize,
+            _ => RelocationValueKind.Pointer,
+        };
+        var writeKind = relocation.Type switch
+        {
+            RelocationTypePc32 or RelocationTypePlt32 or RelocationTypeSigned32 => RelocationWriteKind.Int32,
+            RelocationTypeUnsigned32 or RelocationTypeSize32 => RelocationWriteKind.UInt32,
+            _ => RelocationWriteKind.UInt64,
+        };
+        var symbolValue = valueKind == RelocationValueKind.SymbolSize
+            ? symbol.Size
+            : symbolAddress;
+        var addend = relocation.Type is RelocationTypeGlobalData or RelocationTypeJumpSlot
+            ? 0
+            : relocation.Addend;
+        return new RelocationDescriptor(
+            targetAddress,
+            addend,
+            importNid,
+            symbolValue,
+            valueKind,
+            IsDataImport: GetSymbolType(symbol.Info) == SymbolTypeObject,
+            writeKind,
+            isWeak);
+    }
+
+    private static bool ShouldCreateImportStub(
+        string nid,
+        IReadOnlyList<RelocationDescriptor> descriptors,
+        IModuleManager? moduleManager)
+    {
+        for (var i = 0; i < descriptors.Count; i++)
+        {
+            var descriptor = descriptors[i];
+            if (!string.Equals(descriptor.ImportNid, nid, StringComparison.Ordinal))
+            {
+                continue;
+            }
+            if (!descriptor.IsWeak || moduleManager?.TryGetExport(nid, out _) == true)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private static void RegisterRuntimeSymbolsAndHooks(
         ReadOnlySpan<byte> imageData,
         LoadContext loadContext,
@@ -959,8 +1203,8 @@ public sealed class SelfLoader : ISelfLoader
 
         if (sectionSymbols > 0 || dynamicSymbols > 0)
         {
-            Log.Info(
-                $"Runtime symbol index populated: section={sectionSymbols}, dynamic={dynamicSymbols}, total={runtimeSymbols.Count}");
+            Console.Error.WriteLine(
+                $"[LOADER] Runtime symbol index populated: section={sectionSymbols}, dynamic={dynamicSymbols}, total={runtimeSymbols.Count}");
         }
     }
 
@@ -1034,8 +1278,8 @@ public sealed class SelfLoader : ISelfLoader
 
         if (preInitializers.Count != 0 || initializers.Count != 0)
         {
-            Log.Info(
-                $"Initializers discovered: preinit={preInitializers.Count}, init={initializers.Count}");
+            Console.Error.WriteLine(
+                $"[LOADER] Initializers discovered: preinit={preInitializers.Count}, init={initializers.Count}");
         }
     }
 
@@ -1418,8 +1662,8 @@ public sealed class SelfLoader : ISelfLoader
 
         var requiredBytes = checked((ulong)orderedImportNids.Count * ImportStubSlotSize);
         var mapSize = AlignUp(Math.Max(requiredBytes, (ulong)PageSize), PageSize);
-        Log.Debug(
-            $"CreateImportStubMapping: nids={orderedImportNids.Count}, required=0x{requiredBytes:X}, map_size=0x{mapSize:X}");
+        Console.Error.WriteLine(
+            $"[LOADER] CreateImportStubMapping: nids={orderedImportNids.Count}, required=0x{requiredBytes:X}, map_size=0x{mapSize:X}");
         if (mapSize > int.MaxValue)
         {
             throw new NotSupportedException("Import stub mapping exceeds 2 GB and is not supported.");
@@ -1691,11 +1935,51 @@ public sealed class SelfLoader : ISelfLoader
     private static bool IsSupportedRelocationType(uint relocationType)
     {
         return relocationType is
+            RelocationTypeNone or
             RelocationTypeAbsolute64 or
+            RelocationTypePc32 or
+            RelocationTypePlt32 or
             RelocationTypeGlobalData or
             RelocationTypeJumpSlot or
             RelocationTypeRelative or
-            RelocationTypeTlsModuleId;
+            RelocationTypeUnsigned32 or
+            RelocationTypeSigned32 or
+            RelocationTypeTlsModuleId or
+            RelocationTypeTlsDtpOff64 or
+            RelocationTypeTlsTpOff64 or
+            RelocationTypePc64 or
+            RelocationTypeSize32 or
+            RelocationTypeSize64 or
+            RelocationTypeRelative64;
+    }
+
+    private static readonly HashSet<uint> _reportedUnsupportedRelocationTypes = new();
+
+    private static void ReportUnsupportedRelocation(uint relocationType, ulong offset, ulong imageBase)
+    {
+        // Report each distinct unsupported type once to keep the log useful.
+        lock (_reportedUnsupportedRelocationTypes)
+        {
+            if (!_reportedUnsupportedRelocationTypes.Add(relocationType))
+            {
+                if (IsFocusRelocationOffset(offset, imageBase))
+                {
+                    Console.Error.WriteLine($"[LOADER][FOCUS][SKIP] unsupported type={relocationType}");
+                }
+
+                return;
+            }
+        }
+
+        var name = relocationType switch
+        {
+            5 => "R_X86_64_COPY",
+            37 => "R_X86_64_IRELATIVE (ifunc)",
+            _ => "unknown",
+        };
+        Console.Error.WriteLine(
+            $"[LOADER][ERROR] Unsupported relocation type {relocationType} ({name}) rejected " +
+            $"(first at off=0x{offset:X16}); COPY requires dependency symbol storage and IRELATIVE requires resolver execution.");
     }
 
     private static ulong DetermineRequestedImageBase(
@@ -1851,16 +2135,16 @@ public sealed class SelfLoader : ISelfLoader
         tableBytes = GC.AllocateUninitializedArray<byte>((int)size);
 
         var guestAddr = location + imageBase;
-        Log.Debug($"TryLoadTableBytes: trying guest address 0x{guestAddr:X}");
+        Console.Error.WriteLine($"[LOADER] TryLoadTableBytes: trying guest address 0x{guestAddr:X}");
         if (virtualMemory.TryRead(guestAddr, tableBytes))
         {
-            Log.Debug($"TryLoadTableBytes: loaded from guest memory at 0x{guestAddr:X}");
+            Console.Error.WriteLine($"[LOADER] TryLoadTableBytes: loaded from guest memory at 0x{guestAddr:X}");
             return true;
         }
 
         if (virtualMemory.TryRead(location, tableBytes))
         {
-            Log.Debug($"TryLoadTableBytes: loaded from absolute guest address 0x{location:X}");
+            Console.Error.WriteLine($"[LOADER] TryLoadTableBytes: loaded from absolute guest address 0x{location:X}");
             return true;
         }
 
@@ -1868,11 +2152,11 @@ public sealed class SelfLoader : ISelfLoader
         {
             var slice = elfData.Slice((int)location, (int)size);
             tableBytes = slice.ToArray();
-            Log.Debug($"TryLoadTableBytes: loaded from elfData as file offset at 0x{location:X}");
+            Console.Error.WriteLine($"[LOADER] TryLoadTableBytes: loaded from elfData as file offset at 0x{location:X}");
             return true;
         }
 
-        Log.Warning($"TryLoadTableBytes: FAILED for location 0x{location:X}");
+        Console.Error.WriteLine($"[LOADER] TryLoadTableBytes: FAILED for location 0x{location:X}");
         tableBytes = Array.Empty<byte>();
         return false;
     }
@@ -1929,17 +2213,17 @@ public sealed class SelfLoader : ISelfLoader
 
     private static ulong ResolveMappedAddressOrFallback(IVirtualMemory virtualMemory, ulong address, ulong imageBase)
     {
-        Log.Debug($"ResolveMappedAddressOrFallback addr=0x{address:X} imageBase=0x{imageBase:X16}");
+        Console.Error.WriteLine($"[LOADER][TEST] ResolveMappedAddressOrFallback addr=0x{address:X} imageBase=0x{imageBase:X16}");
 
         if (address == 0)
         {
-            Log.Debug("-> return 0 (null)");
+            Console.Error.WriteLine("[LOADER][TEST] -> return 0 (null)");
             return 0;
         }
 
         if (TryResolveMappedAddress(virtualMemory, address, imageBase, 1, out var resolved))
         {
-            Log.Debug($"-> resolved raw 0x{resolved:X16}");
+            Console.Error.WriteLine($"[LOADER][TEST] -> resolved raw 0x{resolved:X16}");
             return resolved;
         }
 
@@ -1948,18 +2232,18 @@ public sealed class SelfLoader : ISelfLoader
             var rebased = address + imageBase;
             if (TryResolveMappedAddress(virtualMemory, rebased, imageBase, 1, out var resolvedRebased))
             {
-                Log.Debug($"-> resolved rebased 0x{resolvedRebased:X16}");
+                Console.Error.WriteLine($"[LOADER][TEST] -> resolved rebased 0x{resolvedRebased:X16}");
                 return resolvedRebased;
             }
         }
 
         if (address < 0x10000)
         {
-            Log.Debug($"-> reject small 0x{address:X}");
+            Console.Error.WriteLine($"[LOADER][TEST] -> reject small 0x{address:X}");
             return 0;
         }
 
-        Log.Debug($"-> fallback raw 0x{address:X}");
+        Console.Error.WriteLine($"[LOADER][TEST] -> fallback raw 0x{address:X}");
         return address;
     }
 
@@ -2049,6 +2333,106 @@ public sealed class SelfLoader : ISelfLoader
         return virtualMemory.TryWrite(address, buffer);
     }
 
+    private static ulong ComputeRelocationValue(RelocationDescriptor descriptor, ulong resolvedSymbolValue)
+    {
+        var baseValue = descriptor.ValueKind == RelocationValueKind.SymbolSize
+            ? descriptor.SymbolValue
+            : resolvedSymbolValue;
+        var value = AddSigned(baseValue, descriptor.Addend);
+        return descriptor.ValueKind == RelocationValueKind.PcRelative
+            ? unchecked(value - descriptor.TargetAddress)
+            : value;
+    }
+
+    private static bool TryWriteRelocationValue(
+        IVirtualMemory virtualMemory,
+        RelocationDescriptor descriptor,
+        ulong value,
+        out string? error)
+    {
+        Span<byte> buffer = stackalloc byte[sizeof(ulong)];
+        var length = sizeof(ulong);
+        switch (descriptor.WriteKind)
+        {
+            case RelocationWriteKind.UInt64:
+                BinaryPrimitives.WriteUInt64LittleEndian(buffer, value);
+                break;
+
+            case RelocationWriteKind.UInt32:
+                if (value > uint.MaxValue)
+                {
+                    error = $"value 0x{value:X16} overflows an unsigned 32-bit relocation";
+                    return false;
+                }
+                BinaryPrimitives.WriteUInt32LittleEndian(buffer, (uint)value);
+                length = sizeof(uint);
+                break;
+
+            case RelocationWriteKind.Int32:
+                var signedValue = unchecked((long)value);
+                if (signedValue is < int.MinValue or > int.MaxValue)
+                {
+                    error = $"value {signedValue} overflows a signed 32-bit relocation";
+                    return false;
+                }
+                BinaryPrimitives.WriteInt32LittleEndian(buffer, (int)signedValue);
+                length = sizeof(int);
+                break;
+
+            default:
+                error = $"unknown relocation write kind {descriptor.WriteKind}";
+                return false;
+        }
+
+        error = virtualMemory.TryWrite(descriptor.TargetAddress, buffer[..length])
+            ? null
+            : "target memory is not writable";
+        return error is null;
+    }
+
+    private static int GetRelocationWriteSize(uint relocationType)
+    {
+        return relocationType is
+            RelocationTypePc32 or
+            RelocationTypePlt32 or
+            RelocationTypeUnsigned32 or
+            RelocationTypeSigned32 or
+            RelocationTypeSize32
+                ? sizeof(uint)
+                : sizeof(ulong);
+    }
+
+    [Conditional("DEBUG")]
+    private static void RunRelocationSelfChecks()
+    {
+        var pc32 = new RelocationDescriptor(
+            TargetAddress: 0x1000,
+            Addend: -4,
+            ImportNid: null,
+            SymbolValue: 0x1800,
+            RelocationValueKind.PcRelative,
+            IsDataImport: false,
+            RelocationWriteKind.Int32);
+        Debug.Assert(
+            unchecked((long)ComputeRelocationValue(pc32, pc32.SymbolValue)) == 0x7FC,
+            "R_X86_64_PC32 did not apply S + A - P.");
+
+        var weak = new RelocationDescriptor(
+            TargetAddress: 0x2000,
+            Addend: 7,
+            ImportNid: "weak",
+            SymbolValue: 0,
+            RelocationValueKind.Pointer,
+            IsDataImport: false,
+            IsWeak: true);
+        Debug.Assert(
+            ComputeRelocationValue(weak, resolvedSymbolValue: 0) == 7,
+            "An unresolved weak relocation did not use S=0.");
+        Debug.Assert(
+            !ShouldCreateImportStub("weak", [weak], moduleManager: null),
+            "An unresolved weak symbol incorrectly received a trap import stub.");
+    }
+
     private static ulong AlignUp(ulong value, ulong alignment)
     {
         var mask = alignment - 1;
@@ -2257,6 +2641,16 @@ public sealed class SelfLoader : ISelfLoader
         {
             throw new InvalidDataException($"Unsupported ELF program header entry size: {header.ProgramHeaderEntrySize}.");
         }
+
+        // The CPU backend executes guest instructions natively, so a non
+        // x86-64 image can only fail deep in execution with an opaque SIGILL.
+        // Catch it here with an actionable message. (EM_X86_64 == 62.)
+        const ushort ElfMachineX86_64 = 62;
+        if (header.Machine != ElfMachineX86_64)
+        {
+            throw new InvalidDataException(
+                $"Unsupported ELF machine type 0x{header.Machine:X4}; SharpEmu only runs x86-64 (EM_X86_64) images.");
+        }
     }
 
     private static unsafe T ReadUnmanaged<T>(ReadOnlySpan<byte> source, int offset)
@@ -2337,10 +2731,25 @@ public sealed class SelfLoader : ISelfLoader
         public uint Type => (uint)(Info & uint.MaxValue);
     }
 
+    private readonly record struct ModuleTlsInfo(ulong MemorySize, ulong StaticOffset);
+
     private enum RelocationValueKind : byte
     {
         Pointer = 0,
-        TlsModuleId = 1
+        TlsModuleId = 1,
+        // A pre-computed TLS offset written verbatim (TPOFF64/DTPOFF64). Unlike
+        // Pointer it is a signed displacement, not a mapped address, so it is
+        // patched as-is without the low-address validity warning.
+        TlsOffset = 2,
+        PcRelative = 3,
+        SymbolSize = 4,
+    }
+
+    private enum RelocationWriteKind : byte
+    {
+        UInt64 = 0,
+        UInt32 = 1,
+        Int32 = 2,
     }
 
     private readonly record struct RelocationDescriptor(
@@ -2349,7 +2758,9 @@ public sealed class SelfLoader : ISelfLoader
         string? ImportNid,
         ulong SymbolValue,
         RelocationValueKind ValueKind,
-        bool IsDataImport);
+        bool IsDataImport,
+        RelocationWriteKind WriteKind = RelocationWriteKind.UInt64,
+        bool IsWeak = false);
 
     private enum SelfSegmentResolveStatus
     {
@@ -2379,15 +2790,15 @@ public sealed class SelfLoader : ISelfLoader
         private readonly ushort _size2;
         private readonly ulong _fileSize;
         private readonly ushort _segmentCount;
-        private readonly ushort _unknown;
+        private readonly ushort _flags;
         private readonly uint _padding;
 
         public ushort SegmentCount => _segmentCount;
 
-        public ushort Unknown => _unknown;
-
         public ulong FileSize => _fileSize;
 
+        // Version, key type, and flags are signing metadata and vary across
+        // valid SELF images. They do not change the fixed header layout.
         public bool HasKnownLayout =>
             ((_ident0 == 0x4F &&
               _ident1 == 0x15 &&
@@ -2397,14 +2808,9 @@ public sealed class SelfLoader : ISelfLoader
               _ident1 == 0x14 &&
               _ident2 == 0xF5 &&
               _ident3 == 0xEE)) &&
-            _ident4 == 0x00 &&
             _ident5 == 0x01 &&
             _ident6 == 0x01 &&
-            _ident7 == 0x12 &&
-            _ident8 == 0x01 &&
-            _ident9 == 0x01 &&
-            _ident10 == 0x00 &&
-            _ident11 == 0x00;
+            _ident7 == 0x12;
     }
 
     [StructLayout(LayoutKind.Sequential, Pack = 1)]

src/SharpEmu.Core/Memory/PhysicalVirtualMemory.cs

@@ -48,7 +48,107 @@ public sealed unsafe class PhysicalVirtualMemory : IVirtualMemory, IGuestMemoryA
 
     public PhysicalVirtualMemory(IHostMemory? hostMemory = null)
     {
-        _hostMemory = hostMemory ?? HostPlatform.Current.Memory;
+        _hostMemory = hostMemory ?? CrossPlatformHostMemory.Instance;
+    }
+
+    private sealed class CrossPlatformHostMemory : IHostMemory
+    {
+        public static readonly CrossPlatformHostMemory Instance = new();
+
+        public ulong Allocate(ulong desiredAddress, ulong size, HostPageProtection protection) =>
+            unchecked((ulong)HostMemory.Alloc(
+                (void*)desiredAddress,
+                (nuint)size,
+                HostMemory.MEM_RESERVE | HostMemory.MEM_COMMIT,
+                ToRawProtection(protection)));
+
+        public ulong Reserve(ulong desiredAddress, ulong size, HostPageProtection protection) =>
+            unchecked((ulong)HostMemory.Alloc(
+                (void*)desiredAddress,
+                (nuint)size,
+                HostMemory.MEM_RESERVE,
+                ToRawProtection(protection)));
+
+        public bool Commit(ulong address, ulong size, HostPageProtection protection) =>
+            HostMemory.Alloc(
+                (void*)address,
+                (nuint)size,
+                HostMemory.MEM_COMMIT,
+                ToRawProtection(protection)) != null;
+
+        public bool Free(ulong address) =>
+            HostMemory.Free((void*)address, 0, HostMemory.MEM_RELEASE);
+
+        public bool Protect(
+            ulong address,
+            ulong size,
+            HostPageProtection protection,
+            out uint rawOldProtection) =>
+            HostMemory.Protect(
+                (void*)address,
+                (nuint)size,
+                ToRawProtection(protection),
+                out rawOldProtection);
+
+        public bool ProtectRaw(
+            ulong address,
+            ulong size,
+            uint rawProtection,
+            out uint rawOldProtection) =>
+            HostMemory.Protect((void*)address, (nuint)size, rawProtection, out rawOldProtection);
+
+        public bool Query(ulong address, out HostRegionInfo info)
+        {
+            if (HostMemory.Query((void*)address, out var raw) == 0)
+            {
+                info = default;
+                return false;
+            }
+
+            var state = raw.State switch
+            {
+                HostMemory.MEM_FREE_STATE => HostRegionState.Free,
+                HostMemory.MEM_RESERVE => HostRegionState.Reserved,
+                _ => HostRegionState.Committed,
+            };
+
+            info = new HostRegionInfo(
+                raw.BaseAddress,
+                raw.AllocationBase,
+                raw.RegionSize,
+                state,
+                raw.State,
+                FromRawProtection(raw.Protect),
+                raw.Protect,
+                raw.AllocationProtect);
+            return true;
+        }
+
+        public void FlushInstructionCache(ulong address, ulong size) =>
+            HostMemory.FlushInstructionCache((void*)address, (nuint)size);
+
+        private static uint ToRawProtection(HostPageProtection protection) => protection switch
+        {
+            HostPageProtection.NoAccess => HostMemory.PAGE_NOACCESS,
+            HostPageProtection.ReadOnly => HostMemory.PAGE_READONLY,
+            HostPageProtection.ReadWrite => HostMemory.PAGE_READWRITE,
+            HostPageProtection.Execute => HostMemory.PAGE_EXECUTE,
+            HostPageProtection.ReadExecute => HostMemory.PAGE_EXECUTE_READ,
+            HostPageProtection.ReadWriteExecute => HostMemory.PAGE_EXECUTE_READWRITE,
+            HostPageProtection.ExecuteWriteCopy => 0x80,
+            _ => HostMemory.PAGE_NOACCESS,
+        };
+
+        private static HostPageProtection FromRawProtection(uint protection) => protection switch
+        {
+            HostMemory.PAGE_READONLY => HostPageProtection.ReadOnly,
+            HostMemory.PAGE_READWRITE => HostPageProtection.ReadWrite,
+            HostMemory.PAGE_EXECUTE => HostPageProtection.Execute,
+            HostMemory.PAGE_EXECUTE_READ => HostPageProtection.ReadExecute,
+            HostMemory.PAGE_EXECUTE_READWRITE => HostPageProtection.ReadWriteExecute,
+            0x80 => HostPageProtection.ExecuteWriteCopy,
+            _ => HostPageProtection.NoAccess,
+        };
     }
 
     public bool TryAllocateAtExact(ulong desiredAddress, ulong size, bool executable, out ulong actualAddress)
@@ -98,6 +198,24 @@ public sealed unsafe class PhysicalVirtualMemory : IVirtualMemory, IGuestMemoryA
         return true;
     }
 
+    public string DescribeAddressForDiagnostics(ulong address)
+    {
+        if (!_hostMemory.Query(address, out var info))
+        {
+            return "unable to query host memory at this address";
+        }
+
+        return info.State switch
+        {
+            HostRegionState.Free => "address reports free, but the exact-address reservation still failed",
+            HostRegionState.Reserved =>
+                $"already reserved by another host allocation (base=0x{info.AllocationBase:X16}, size=0x{info.RegionSize:X})",
+            HostRegionState.Committed =>
+                $"already committed by another host allocation (base=0x{info.AllocationBase:X16}, size=0x{info.RegionSize:X}, protect=0x{info.RawProtection:X})",
+            _ => $"in an unexpected host state (raw=0x{info.RawState:X})",
+        };
+    }
+
     public ulong AllocateAt(ulong desiredAddress, ulong size, bool executable = true, bool allowAlternative = true)
     {
         if (size == 0)
@@ -249,42 +367,9 @@ public sealed unsafe class PhysicalVirtualMemory : IVirtualMemory, IGuestMemoryA
         var requestedCursor = AlignUp(desiredAddress, effectiveAlignment);
         var cursor = GetAllocationSearchCursor(desiredAddress, requestedCursor, effectiveAlignment, executable);
 
-        // Under Rosetta 2 the kernel can ignore placement hints for whole
-        // windows, so page-stepped exact probes are pathological on macOS.
-        // Linux must keep using the exact-address search below: PS5 resource
-        // descriptors cannot represent ordinary 0x7F... host mappings. Linux
-        // HostMemory uses MAP_FIXED_NOREPLACE, making those low-address probes
-        // safe without clobbering existing host mappings.
+        // macOS needs alignment over-allocation; Linux uses exact-address search.
         if (OperatingSystem.IsMacOS())
         {
-            // Prefer the requested low address.  Besides matching the guest
-            // address model, this keeps the allocation representable by every
-            // PS5 GPU descriptor (the strictest ones carry 40 address bits).
-            try
-            {
-                var exactAddress = AllocateAt(
-                    cursor,
-                    alignedSize,
-                    executable,
-                    allowAlternative: false);
-                if (exactAddress == cursor)
-                {
-                    actualAddress = exactAddress;
-                    UpdateAllocationSearchCursor(
-                        desiredAddress,
-                        effectiveAlignment,
-                        executable,
-                        exactAddress + alignedSize);
-                    return true;
-                }
-            }
-            catch
-            {
-            }
-
-            // Over-allocate by the alignment so a kernel-chosen placement
-            // always contains an aligned start; the unused head/tail stays
-            // part of the tracked region and is simply never handed out.
             var reserveSize = effectiveAlignment > PageSize
                 ? alignedSize + effectiveAlignment
                 : alignedSize;
@@ -294,10 +379,7 @@ public sealed unsafe class PhysicalVirtualMemory : IVirtualMemory, IGuestMemoryA
                 if (posixAddress != 0)
                 {
                     var alignedBase = AlignUp(posixAddress, effectiveAlignment);
-                    const ulong gpuAddressLimit = 1UL << 40;
-                    if (alignedBase < gpuAddressLimit &&
-                        alignedSize <= gpuAddressLimit - alignedBase &&
-                        alignedBase + alignedSize <= posixAddress + reserveSize)
+                    if (alignedBase + alignedSize <= posixAddress + reserveSize)
                     {
                         actualAddress = alignedBase;
                         UpdateAllocationSearchCursor(desiredAddress, effectiveAlignment, executable, alignedBase + alignedSize);
@@ -327,19 +409,10 @@ public sealed unsafe class PhysicalVirtualMemory : IVirtualMemory, IGuestMemoryA
                 continue;
             }
 
-            try
-            {
-                actualAddress = AllocateAt(cursor, alignedSize, executable, allowAlternative: false);
-                if (actualAddress == cursor)
-                {
-                    UpdateAllocationSearchCursor(desiredAddress, effectiveAlignment, executable, actualAddress + alignedSize);
-                    return true;
-                }
-
-                actualAddress = 0;
-            }
-            catch
+            if (TryAllocateAtExact(cursor, alignedSize, executable, out actualAddress))
             {
+                UpdateAllocationSearchCursor(desiredAddress, effectiveAlignment, executable, actualAddress + alignedSize);
+                return true;
             }
 
             cursor = AlignUp(cursor + effectiveAlignment, effectiveAlignment);

src/SharpEmu.Core/Runtime/SharpEmuRuntime.cs

@@ -7,25 +7,22 @@ using SharpEmu.Core.Cpu.Disasm;
 using SharpEmu.Core.Loader;
 using SharpEmu.Core.Memory;
 using SharpEmu.HLE;
-using SharpEmu.HLE.Host;
 using SharpEmu.Libs.VideoOut;
 using SharpEmu.Libs.Kernel;
 using SharpEmu.Libs.AppContent;
 using SharpEmu.Libs.SaveData;
-using SharpEmu.Logging;
+using SharpEmu.Libs.Fiber;
+using SharpEmu.Libs.SystemService;
 using System.Buffers.Binary;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
-using System.IO;
 
 namespace SharpEmu.Core.Runtime;
 
 public sealed class SharpEmuRuntime : ISharpEmuRuntime
 {
-    private static readonly SharpEmuLogger Log = SharpEmuLog.For("Runtime");
-
-    private readonly record struct LoadedModuleImage(string Path, SelfImage Image);
+    private readonly record struct LoadedModuleImage(string Path, SelfImage Image, int Handle, bool StartAtBoot);
 
     private static readonly HashSet<string> PreloadSkipModules = new(StringComparer.OrdinalIgnoreCase)
     {
@@ -71,6 +68,7 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             CpuEngine = cpuExecutionOptions.CpuEngine,
             StrictDynlibResolution = cpuExecutionOptions.StrictDynlibResolution,
             ImportTraceLimit = Math.Max(0, cpuExecutionOptions.ImportTraceLimit),
+            DebugHook = cpuExecutionOptions.DebugHook,
         };
         _fileSystem = fileSystem ?? new PhysicalFileSystem();
     }
@@ -82,24 +80,22 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             CpuEngine = options.CpuEngine,
             StrictDynlibResolution = options.StrictDynlibResolution,
             ImportTraceLimit = Math.Max(0, options.ImportTraceLimit),
+            DebugHook = options.DebugHook,
         };
         var moduleManager = new ModuleManager();
-        moduleManager.RegisterFromAssembly(typeof(KernelExports).Assembly, Generation.Gen4 | Generation.Gen5, Aerolib.Instance);
+        // The compile-time generated registry (SharpEmu.SourceGenerators) is the sole
+        // registration source; content tests in SharpEmu.Libs.Tests pin its invariants.
+        moduleManager.RegisterExports(SharpEmu.Generated.SysAbiExportRegistry.CreateExports(Generation.Gen4 | Generation.Gen5));
         moduleManager.Freeze();
 
-        // Resolve the host platform once at the composition root; on unsupported
-        // OSes this throws PlatformNotSupportedException with a clear message
-        // instead of failing on the first native call.
-        var hostPlatform = HostPlatform.Current;
-
-        var virtualMemory = new PhysicalVirtualMemory(hostPlatform.Memory);
+        var virtualMemory = new PhysicalVirtualMemory();
 
         var fileSystem = new PhysicalFileSystem();
 
         return new SharpEmuRuntime(
             new SelfLoader(),
             virtualMemory,
-            new CpuDispatcher(virtualMemory, moduleManager, hostPlatform: hostPlatform),
+            new CpuDispatcher(virtualMemory, moduleManager),
             moduleManager,
             Aerolib.Instance,
             cpuExecutionOptions,
@@ -137,20 +133,21 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
     {
         var normalizedEbootPath = Path.GetFullPath(ebootPath);
         using var app0Binding = BindApp0Root(normalizedEbootPath);
-        Log.Info($"Loading: {ebootPath}");
+        Console.Error.WriteLine($"[RUNTIME] Loading: {ebootPath}");
         LastExecutionDiagnostics = null;
         LastExecutionTrace = null;
         LastSessionSummary = null;
         LastBasicBlockTrace = null;
         LastMilestoneLog = null;
+        FiberExports.ResetRuntimeState();
         KernelModuleRegistry.Reset();
         var image = LoadImage(normalizedEbootPath);
-        VideoOutExports.ConfigureApplicationInfo(image.Title, image.TitleId, image.Version, BuildInfo.CommitSha);
+        VideoOutExports.ConfigureApplicationInfo(image.Title, image.TitleId, image.Version);
         SaveDataExports.ConfigureApplicationInfo(image.TitleId);
-        LogAppBundleInfo(normalizedEbootPath, image);
-        RegisterLoadedModule(normalizedEbootPath, image, isMain: true, isSystemModule: false);
+        SystemServiceExports.ConfigureApplicationInfo(image.TitleId);
+        _ = RegisterLoadedModule(normalizedEbootPath, image, isMain: true, isSystemModule: false);
         KernelRuntimeCompatExports.ConfigureProcessProcParamAddress(image.ProcParamAddress);
-        Log.Info($"Entry: 0x{image.EntryPoint:X16}");
+        Console.Error.WriteLine($"[RUNTIME] Entry: 0x{image.EntryPoint:X16}");
         var generation = image.ElfHeader.AbiVersion == 2 ? Generation.Gen5 : Generation.Gen4;
         var activeImportStubs = new Dictionary<ulong, string>(image.ImportStubs);
         var activeRuntimeSymbols = new Dictionary<string, ulong>(image.RuntimeSymbols, StringComparer.Ordinal);
@@ -173,7 +170,7 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             processImageName);
         if (initializerResult is { } failedInitializerResult)
         {
-            Log.Error($"Initializer dispatch failed: {failedInitializerResult}");
+            Console.Error.WriteLine($"[RUNTIME] Initializer dispatch failed: {failedInitializerResult}");
             LastExecutionTrace = _cpuDispatcher.LastImportResolutionTrace;
             LastMilestoneLog = _cpuDispatcher.LastMilestoneLog;
             LastSessionSummary = BuildSessionSummary(_cpuDispatcher.LastSessionSummary);
@@ -181,8 +178,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             return failedInitializerResult;
         }
 
-        Log.Info($"Dispatching, gen: {generation}");
-        Log.Debug($"About to call DispatchEntry with entryPoint=0x{image.EntryPoint:X16}");
+        Console.Error.WriteLine($"[RUNTIME] Dispatching, gen: {generation}");
+        Console.Error.WriteLine($"[RUNTIME] About to call DispatchEntry with entryPoint=0x{image.EntryPoint:X16}");
 
         var result = _cpuDispatcher.DispatchEntry(
             image.EntryPoint,
@@ -192,8 +189,18 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             processImageName,
             _cpuExecutionOptions);
 
-        Log.Info($"DispatchEntry returned: {result}");
-        Log.Info($"Dispatch result: {result}");
+        Console.Error.WriteLine($"[RUNTIME] DispatchEntry returned: {result}");
+        Console.Error.WriteLine($"[RUNTIME] Dispatch result: {result}");
+
+        // Stop is a host operation, not an emulation failure. The detailed
+        // trace and session-summary builders can traverse a partially torn
+        // down native backend, delaying the GUI exit callback indefinitely.
+        if (HostSessionControl.IsShutdownRequested)
+        {
+            Console.Error.WriteLine("[RUNTIME] Skipping post-exit diagnostics for host shutdown.");
+            return result;
+        }
+
         LastExecutionTrace = _cpuDispatcher.LastImportResolutionTrace;
         LastMilestoneLog = _cpuDispatcher.LastMilestoneLog;
         LastSessionSummary = BuildSessionSummary(_cpuDispatcher.LastSessionSummary);
@@ -364,66 +371,6 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
         return result;
     }
 
-    private static void LogAppBundleInfo(string ebootPath, SelfImage image)
-    {
-        var executableName = Path.GetFileName(ebootPath);
-        if (string.IsNullOrWhiteSpace(executableName))
-        {
-            executableName = "eboot.bin";
-        }
-
-        var displayName = string.IsNullOrWhiteSpace(image.Title) ? "(unknown)" : image.Title!.Trim();
-        var titleId = string.IsNullOrWhiteSpace(image.TitleId) ? "(unknown)" : image.TitleId!.Trim();
-        var version = string.IsNullOrWhiteSpace(image.Version) ? "(unknown)" : image.Version!.Trim();
-        var contentId = ResolveContentId(Path.GetDirectoryName(ebootPath)) ?? "(unknown)";
-
-        var builder = new StringBuilder();
-        builder.AppendLine("App bundle info:");
-        builder.AppendLine($"- Display name: {displayName}");
-        builder.AppendLine($"- Version: {version}");
-        builder.AppendLine($"- Title ID: {titleId}");
-        builder.AppendLine($"- Content ID: {contentId}");
-        builder.AppendLine($"- Executable: {executableName}");
-        builder.Append("- Platform: PlayStation 5");
-        Log.Info(builder.ToString());
-    }
-
-    private static string? ResolveContentId(string? bundleRoot)
-    {
-        if (string.IsNullOrEmpty(bundleRoot))
-        {
-            return null;
-        }
-
-        foreach (var candidate in new[]
-        {
-            Path.Combine(bundleRoot, "sce_sys", "param.json"),
-            Path.Combine(bundleRoot, "param.json"),
-        })
-        {
-            if (!File.Exists(candidate))
-            {
-                continue;
-            }
-
-            try
-            {
-                using var doc = System.Text.Json.JsonDocument.Parse(File.ReadAllBytes(candidate));
-                if (doc.RootElement.TryGetProperty("contentId", out var contentId))
-                {
-                    return contentId.GetString();
-                }
-            }
-            catch (Exception ex) when (ex is IOException or System.Text.Json.JsonException)
-            {
-            }
-
-            break;
-        }
-
-        return null;
-    }
-
     private static App0BindingScope? BindApp0Root(string normalizedEbootPath)
     {
         const string app0VariableName = "SHARPEMU_APP0_DIR";
@@ -438,6 +385,20 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             return null;
         }
 
+        // Dump tools commonly place decrypted executables in an app0/decrypted
+        // sidecar while leaving Unity data in the parent app0 directory. Keep
+        // loading code/modules beside the decrypted eboot, but mount /app0 at
+        // the content-bearing parent so boot.config, metadata and assets resolve.
+        if (string.Equals(Path.GetFileName(app0Root), "decrypted", StringComparison.OrdinalIgnoreCase))
+        {
+            var parentRoot = Path.GetDirectoryName(app0Root);
+            if (!string.IsNullOrWhiteSpace(parentRoot) &&
+                Directory.Exists(Path.Combine(parentRoot, "Media")))
+            {
+                app0Root = parentRoot;
+            }
+        }
+
         Environment.SetEnvironmentVariable(app0VariableName, app0Root);
         return new App0BindingScope(app0VariableName);
     }
@@ -483,6 +444,56 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
         return null;
     }
 
+    private bool TryGetEhFrameInfo(
+        SelfImage image,
+        ulong imageSize,
+        out ulong ehFrameHeaderAddress,
+        out ulong ehFrameAddress,
+        out ulong ehFrameSize)
+    {
+        ehFrameHeaderAddress = 0;
+        ehFrameAddress = 0;
+        ehFrameSize = 0;
+        var imageBase = image.EntryPoint >= image.ElfHeader.EntryPoint
+            ? image.EntryPoint - image.ElfHeader.EntryPoint
+            : 0UL;
+        for (var i = 0; i < image.ProgramHeaders.Count; i++)
+        {
+            var header = image.ProgramHeaders[i];
+            if (header.HeaderType != ProgramHeaderType.GnuEhFrame || header.MemorySize < 8)
+            {
+                continue;
+            }
+
+            var headerAddress = imageBase + header.VirtualAddress;
+            Span<byte> ehHeader = stackalloc byte[8];
+            if (!_virtualMemory.TryRead(headerAddress, ehHeader) ||
+                ehHeader[0] != 1 ||
+                ehHeader[1] != 0x1B)
+            {
+                continue;
+            }
+
+            var relativeOffset = BinaryPrimitives.ReadInt32LittleEndian(ehHeader[4..]);
+            ehFrameHeaderAddress = headerAddress;
+            ehFrameAddress = unchecked((ulong)((long)headerAddress + 4 + relativeOffset));
+            if (ehFrameAddress < 0x10000)
+            {
+                continue;
+            }
+
+            var relativeEhFrameAddress = ehFrameAddress - imageBase;
+            ehFrameSize = header.VirtualAddress > relativeEhFrameAddress
+                ? header.VirtualAddress - relativeEhFrameAddress
+                : imageSize > header.VirtualAddress
+                    ? imageSize - header.VirtualAddress
+                    : 0;
+            return true;
+        }
+
+        return false;
+    }
+
     private OrbisGen2Result? RunPreloadedModuleInitializers(
         IReadOnlyList<LoadedModuleImage> loadedModuleImages,
         Generation generation,
@@ -492,20 +503,30 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
         for (var i = 0; i < loadedModuleImages.Count; i++)
         {
             var loadedModule = loadedModuleImages[i];
+            if (!loadedModule.StartAtBoot)
+            {
+                continue;
+            }
+
             var initEntryPoint = loadedModule.Image.InitFunctionEntryPoint;
             if (initEntryPoint < 0x10000)
             {
                 continue;
             }
 
+            if (!KernelModuleRegistry.TryBeginModuleStart(loadedModule.Handle, out _))
+            {
+                continue;
+            }
+
             var moduleName = Path.GetFileName(loadedModule.Path);
             if (string.IsNullOrWhiteSpace(moduleName))
             {
                 moduleName = $"module#{i}";
             }
 
-            Log.Info(
-                $"Starting module {moduleName}: dt_init=0x{initEntryPoint:X16}");
+            Console.Error.WriteLine(
+                $"[RUNTIME] Starting module {moduleName}: dt_init=0x{initEntryPoint:X16}");
 
             var result = _cpuDispatcher.DispatchModuleInitializer(
                 initEntryPoint,
@@ -514,10 +535,13 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
                 activeRuntimeSymbols,
                 moduleName,
                 _cpuExecutionOptions);
+            KernelModuleRegistry.CompleteModuleStart(
+                loadedModule.Handle,
+                result == OrbisGen2Result.ORBIS_GEN2_OK);
             if (result != OrbisGen2Result.ORBIS_GEN2_OK)
             {
-                Log.Error(
-                    $"Module start failed: {moduleName} -> {result}");
+                Console.Error.WriteLine(
+                    $"[RUNTIME] Module start failed: {moduleName} -> {result}");
                 return result;
             }
         }
@@ -538,8 +562,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             return null;
         }
 
-        Log.Info(
-            $"Running initializers for {label}: preinit={image.PreInitializerFunctions.Count}, init={image.InitializerFunctions.Count}");
+        Console.Error.WriteLine(
+            $"[RUNTIME] Running initializers for {label}: preinit={image.PreInitializerFunctions.Count}, init={image.InitializerFunctions.Count}");
 
         var result = RunInitializerList(
             $"{label}:preinit",
@@ -578,8 +602,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
                 continue;
             }
 
-            Log.Debug(
-                $"  Initializer {label}[{i}] -> 0x{initializerAddress:X16}");
+            Console.Error.WriteLine(
+                $"[RUNTIME]   Initializer {label}[{i}] -> 0x{initializerAddress:X16}");
 
             var result = _cpuDispatcher.DispatchEntry(
                 initializerAddress,
@@ -611,12 +635,17 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
 
         var moduleDirectories = new[]
         {
-            Path.Combine(ebootDirectory, "sce_module"),
-            Path.Combine(ebootDirectory, "sce_modules"),
-            Path.Combine(ebootDirectory, "Media", "Modules"),
+            (Path: Path.Combine(ebootDirectory, "sce_module"), StartAtBoot: true),
+            (Path: Path.Combine(ebootDirectory, "sce_modules"), StartAtBoot: true),
+            (Path: Path.Combine(ebootDirectory, "Media", "Modules"), StartAtBoot: true),
+            // Unity native plugins are loaded later through sceKernelLoadStartModule. Map
+            // them up front so the HLE loader can return a real module handle and dlsym
+            // can resolve their exports, but defer DT_INIT until the guest requests them.
+            (Path: Path.Combine(ebootDirectory, "Media", "Plugins"), StartAtBoot: false),
         }
-        .Distinct(StringComparer.OrdinalIgnoreCase)
-        .Where(Directory.Exists)
+        .GroupBy(entry => entry.Path, StringComparer.OrdinalIgnoreCase)
+        .Select(group => group.First())
+        .Where(entry => Directory.Exists(entry.Path))
         .ToArray();
 
         if (moduleDirectories.Length == 0)
@@ -626,28 +655,30 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
 
         var allModulePaths = moduleDirectories
             .SelectMany(directory => Directory
-                .EnumerateFiles(directory)
-                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase))
-            .Where(path =>
+                .EnumerateFiles(directory.Path)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
+                .Select(path => (Path: path, directory.StartAtBoot)))
+            .Where(entry =>
             {
-                var extension = Path.GetExtension(path);
+                var extension = Path.GetExtension(entry.Path);
                 return string.Equals(extension, ".prx", StringComparison.OrdinalIgnoreCase) ||
                        string.Equals(extension, ".sprx", StringComparison.OrdinalIgnoreCase);
             })
-            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .GroupBy(entry => entry.Path, StringComparer.OrdinalIgnoreCase)
+            .Select(group => group.First())
             .ToArray();
 
         var modulePaths = allModulePaths
-            .Where(ShouldPreloadModule)
+            .Where(entry => ShouldPreloadModule(entry.Path))
             .ToArray();
         var skippedModules = allModulePaths
-            .Where(path => !ShouldPreloadModule(path))
-            .Select(Path.GetFileName)
+            .Where(entry => !ShouldPreloadModule(entry.Path))
+            .Select(entry => Path.GetFileName(entry.Path))
             .Where(name => !string.IsNullOrWhiteSpace(name))
             .ToArray();
         if (skippedModules.Length > 0)
         {
-            Log.Info($"Skipping {skippedModules.Length} core module(s): {string.Join(", ", skippedModules)}");
+            Console.Error.WriteLine($"[RUNTIME] Skipping {skippedModules.Length} core module(s): {string.Join(", ", skippedModules)}");
         }
 
         if (modulePaths.Length == 0)
@@ -655,14 +686,15 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             return loadedImages;
         }
 
-        Log.Debug($"Module search directories: {string.Join(", ", moduleDirectories)}");
-        Log.Info($"Loading {modulePaths.Length} module(s)...");
+        Console.Error.WriteLine($"[RUNTIME] Module search directories: {string.Join(", ", moduleDirectories.Select(entry => entry.Path))}");
+        Console.Error.WriteLine($"[RUNTIME] Loading {modulePaths.Length} module(s)...");
         var loadedModules = 0;
         var failedModules = 0;
         var mergedImportCount = 0;
         var mergedSymbolCount = 0;
-        foreach (var modulePath in modulePaths)
+        foreach (var moduleEntry in modulePaths)
         {
+            var modulePath = moduleEntry.Path;
             try
             {
                 var fileInfo = new FileInfo(modulePath);
@@ -687,25 +719,52 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
 
                 mergedImportCount += MergeImportStubs(importStubs, moduleImage.ImportStubs, modulePath);
                 mergedSymbolCount += MergeRuntimeSymbols(runtimeSymbols, moduleImage.RuntimeSymbols);
-                RegisterLoadedModule(modulePath, moduleImage, isMain: false, isSystemModule: false);
-                loadedImages.Add(new LoadedModuleImage(modulePath, moduleImage));
+                InstallNativePluginCompatibilityHooks(importStubs, moduleImage, modulePath);
+                var moduleHandle = RegisterLoadedModule(modulePath, moduleImage, isMain: false, isSystemModule: false);
+                var moduleName = Path.GetFileName(modulePath);
+                var startAtBoot = moduleEntry.StartAtBoot ||
+                    string.Equals(moduleName, "libfmod.prx", StringComparison.OrdinalIgnoreCase) ||
+                    string.Equals(moduleName, "libfmodstudio.prx", StringComparison.OrdinalIgnoreCase);
+                loadedImages.Add(new LoadedModuleImage(modulePath, moduleImage, moduleHandle, startAtBoot));
                 loadedModules++;
 
-                Log.Info(
-                    $"Loaded module {Path.GetFileName(modulePath)}: entry=0x{moduleImage.EntryPoint:X16}, imports={moduleImage.ImportStubs.Count}, symbols={moduleImage.RuntimeSymbols.Count}");
+                Console.Error.WriteLine(
+                    $"[RUNTIME] Loaded module {Path.GetFileName(modulePath)}: entry=0x{moduleImage.EntryPoint:X16}, imports={moduleImage.ImportStubs.Count}, symbols={moduleImage.RuntimeSymbols.Count}");
             }
             catch (Exception ex)
             {
                 failedModules++;
-                Log.Error($"Module load failed: {modulePath} ({ex.GetType().Name}: {ex.Message})", ex);
+                Console.Error.WriteLine($"[RUNTIME] Module load failed: {modulePath} ({ex.GetType().Name}: {ex.Message})");
             }
         }
 
-        Log.Info(
-            $"Module preload summary: loaded={loadedModules}, failed={failedModules}, merged_imports={mergedImportCount}, merged_symbols={mergedSymbolCount}");
+        Console.Error.WriteLine(
+            $"[RUNTIME] Module preload summary: loaded={loadedModules}, failed={failedModules}, merged_imports={mergedImportCount}, merged_symbols={mergedSymbolCount}");
         return loadedImages;
     }
 
+    private static void InstallNativePluginCompatibilityHooks(
+        IDictionary<ulong, string> importStubs,
+        SelfImage moduleImage,
+        string modulePath)
+    {
+        if (!string.Equals(Path.GetFileName(modulePath), "libfmod.prx", StringComparison.OrdinalIgnoreCase))
+        {
+            return;
+        }
+
+        ReadOnlySpan<string> compatibilityNids = ["uPLTdl3psGk"];
+        foreach (var nid in compatibilityNids)
+        {
+            if (moduleImage.RuntimeSymbols.TryGetValue(nid, out var address) && address >= 0x10000)
+            {
+                importStubs[address] = nid;
+                Console.Error.WriteLine(
+                    $"[RUNTIME] Installed FMOD compatibility hook: {nid} -> 0x{address:X16}");
+            }
+        }
+    }
+
     private void RebindImportedDataSymbols(
         SelfImage mainImage,
         IReadOnlyList<LoadedModuleImage> loadedModuleImages,
@@ -722,8 +781,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
 
         if (rebound != 0 || unresolved != 0)
         {
-            Log.Info(
-                $"Imported data rebind: rebound={rebound}, unresolved={unresolved}");
+            Console.Error.WriteLine(
+                $"[RUNTIME] Imported data rebind: rebound={rebound}, unresolved={unresolved}");
         }
     }
 
@@ -755,8 +814,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             {
                 if (logRebind)
                 {
-                    Log.Warning(
-                        $"Imported data unresolved: nid={relocation.Nid} target=0x{relocation.TargetAddress:X16} addend=0x{unchecked((ulong)relocation.Addend):X16}");
+                    Console.Error.WriteLine(
+                        $"[RUNTIME] Imported data unresolved: nid={relocation.Nid} target=0x{relocation.TargetAddress:X16} addend=0x{unchecked((ulong)relocation.Addend):X16}");
                 }
 
                 unresolved++;
@@ -768,8 +827,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             {
                 if (logRebind)
                 {
-                    Log.Error(
-                        $"Imported data write-failed: nid={relocation.Nid} target=0x{relocation.TargetAddress:X16} value=0x{reboundValue:X16}");
+                    Console.Error.WriteLine(
+                        $"[RUNTIME] Imported data write-failed: nid={relocation.Nid} target=0x{relocation.TargetAddress:X16} value=0x{reboundValue:X16}");
                 }
 
                 unresolved++;
@@ -778,8 +837,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
 
             if (logRebind)
             {
-                Log.Debug(
-                    $"Imported data rebound: nid={relocation.Nid} target=0x{relocation.TargetAddress:X16} value=0x{reboundValue:X16}");
+                Console.Error.WriteLine(
+                    $"[RUNTIME] Imported data rebound: nid={relocation.Nid} target=0x{relocation.TargetAddress:X16} value=0x{reboundValue:X16}");
             }
 
             rebound++;
@@ -815,8 +874,8 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             {
                 if (!string.Equals(existingNid, nid, StringComparison.Ordinal))
                 {
-                    Log.Warning(
-                        $"Import stub conflict at 0x{address:X16}: keep={existingNid}, skip={nid} ({Path.GetFileName(modulePath)})");
+                    Console.Error.WriteLine(
+                        $"[RUNTIME] Import stub conflict at 0x{address:X16}: keep={existingNid}, skip={nid} ({Path.GetFileName(modulePath)})");
                 }
 
                 continue;
@@ -910,7 +969,7 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
         return !PreloadSkipModules.Contains(fileName);
     }
 
-    private static void RegisterLoadedModule(string modulePath, SelfImage image, bool isMain, bool isSystemModule)
+    private int RegisterLoadedModule(string modulePath, SelfImage image, bool isMain, bool isSystemModule)
     {
         if (!TryComputeImageRange(image, out var baseAddress, out var size))
         {
@@ -918,15 +977,27 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             size = 0;
         }
 
+        _ = TryGetEhFrameInfo(
+            image,
+            size,
+            out var ehFrameHeaderAddress,
+            out var ehFrameAddress,
+            out var ehFrameSize);
         var handle = KernelModuleRegistry.RegisterModule(
             modulePath,
             baseAddress,
             size,
             image.EntryPoint,
+            image.InitFunctionEntryPoint,
+            ehFrameHeaderAddress,
+            ehFrameAddress,
+            ehFrameSize,
             isMain,
             isSystemModule);
-        Log.Info(
-            $"Registered module handle={handle} name={Path.GetFileName(modulePath)} base=0x{baseAddress:X16} size=0x{size:X16}");
+        KernelModuleRegistry.RegisterModuleSymbols(handle, image.RuntimeSymbols);
+        Console.Error.WriteLine(
+            $"[RUNTIME] Registered module handle={handle} name={Path.GetFileName(modulePath)} base=0x{baseAddress:X16} size=0x{size:X16}");
+        return handle;
     }
 
     private static bool TryComputeImageRange(SelfImage image, out ulong baseAddress, out ulong size)
@@ -1093,6 +1164,16 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
             disposableDispatcher.Dispose();
         }
 
+        if (_cpuDispatcher is CpuDispatcher { NativeSessionLeaked: true })
+        {
+            // A guest worker is still inside guest code; unmapping the guest
+            // address space under it would fault the whole process, which
+            // hosts the GUI launcher in embedded sessions.
+            Console.Error.WriteLine(
+                "[RUNTIME] Guest workers were still active at teardown; keeping the guest address space mapped.");
+            return;
+        }
+
         if (_virtualMemory is IDisposable disposableMemory)
         {
             disposableMemory.Dispose();

src/SharpEmu.Core/Runtime/SharpEmuRuntimeOptions.cs

@@ -4,6 +4,7 @@
 namespace SharpEmu.Core.Runtime;
 
 using SharpEmu.Core.Cpu;
+using SharpEmu.Core.Cpu.Debugging;
 
 public readonly struct SharpEmuRuntimeOptions
 {
@@ -12,4 +13,11 @@ public readonly struct SharpEmuRuntimeOptions
     public bool StrictDynlibResolution { get; init; }
 
     public int ImportTraceLimit { get; init; }
+
+    /// <summary>
+    /// An optional debugger to attach to guest execution. Flows through to
+    /// <see cref="CpuExecutionOptions.DebugHook"/>. Null (the default) runs with
+    /// no debugger attached.
+    /// </summary>
+    public ICpuDebugHook? DebugHook { get; init; }
 }

src/SharpEmu.Core/SharpEmu.Core.csproj

@@ -14,6 +14,10 @@ SPDX-License-Identifier: GPL-2.0-or-later
     <PackageReference Include="Iced" />
   </ItemGroup>
 
+  <ItemGroup>
+    <InternalsVisibleTo Include="SharpEmu.Libs.Tests" />
+  </ItemGroup>
+
   <PropertyGroup>
     <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>

src/SharpEmu.Core/packages.lock.json

@@ -1,155 +0,0 @@
-{
-  "version": 2,
-  "dependencies": {
-    "net10.0": {
-      "Iced": {
-        "type": "Direct",
-        "requested": "[1.21.0, )",
-        "resolved": "1.21.0",
-        "contentHash": "dv5+81Q1TBQvVMSOOOmRcjJmvWcX3BZPZsIq31+RLc5cNft0IHAyNlkdb7ZarOWG913PyBoFDsDXoCIlKmLclg=="
-      },
-      "Microsoft.DotNet.PlatformAbstractions": {
-        "type": "Transitive",
-        "resolved": "3.1.6",
-        "contentHash": "jek4XYaQ/PGUwDKKhwR8K47Uh1189PFzMeLqO83mXrXQVIpARZCcfuDedH50YDTepBkfijCZN5U/vZi++erxtg=="
-      },
-      "Microsoft.Extensions.DependencyModel": {
-        "type": "Transitive",
-        "resolved": "9.0.9",
-        "contentHash": "fNGvKct2De8ghm0Bpfq0iWthtzIWabgOTi+gJhNOPhNJIowXNEUE2eZNW/zNCzrHVA3PXg2yZ+3cWZndC2IqYA=="
-      },
-      "Silk.NET.Core": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "D7AT/nnwlB+4RZ84XY8QNGBZMJI5z9l4CSSETIJ1wCfRJzRt/341y3MRZ4HbnFz4r/IGaWOEZr86iE+0/65yyQ==",
-        "dependencies": {
-          "Microsoft.DotNet.PlatformAbstractions": "3.1.6",
-          "Microsoft.Extensions.DependencyModel": "9.0.9"
-        }
-      },
-      "Silk.NET.GLFW": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "UIs4sH57xlPUNHQ/1bt9rymPWlGy8IMDCNv86h0iM4TOA1CkIx0XM/n/tA4AReh1zQkNrvkxPEdZ3Blvy1dyXg==",
-        "dependencies": {
-          "Silk.NET.Core": "2.23.0",
-          "Ultz.Native.GLFW": "3.4.0"
-        }
-      },
-      "Silk.NET.Input.Common": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "QbJVV7kFBHEByayXCYdJtXXI9Sp4a+QAf0IdGV6uCWkFYcEmqBYW3aaNGvFOdSwTBDbHL5T/OtOCrGh4qYhk7A==",
-        "dependencies": {
-          "Silk.NET.Windowing.Common": "2.23.0"
-        }
-      },
-      "Silk.NET.Input.Glfw": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "KGHYqsv/IQRJtD6dloYh2tN4CkaM40vxM2kj0cGKBoCQiBDYHHhJiyDTyMPx0W7Fz5IgnhnG42ELmIAa0DH69A==",
-        "dependencies": {
-          "Silk.NET.Input.Common": "2.23.0",
-          "Silk.NET.Windowing.Glfw": "2.23.0"
-        }
-      },
-      "Silk.NET.Maths": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "r8PdIVzME8EH0qAgbmRPO87I4GfgR2j8TofT7EMuRJDf1QluoQwnVypDoFJjQ2ZBSRsGYk5unYxxogI05Ogsmw=="
-      },
-      "Silk.NET.Windowing.Common": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "ThStSinmY9KQI8DGiF5XEhkLJVnBcgRTBTzL9ijg1wMZAYuckz7ykrNw04fjRm2Gryh6tCNGbvz2XaY0efeFzg==",
-        "dependencies": {
-          "Silk.NET.Core": "2.23.0",
-          "Silk.NET.Maths": "2.23.0"
-        }
-      },
-      "Silk.NET.Windowing.Glfw": {
-        "type": "Transitive",
-        "resolved": "2.23.0",
-        "contentHash": "aYBudKmENmvLRn9p15HbdvlQTnnXskcDfTfbYwSb/4fr263rGLwYuDw/txUEc2jihHJiWCp5+75Y7z5wTJWl7g==",
-        "dependencies": {
-          "Silk.NET.GLFW": "2.23.0",
-          "Silk.NET.Windowing.Common": "2.23.0"
-        }
-      },
-      "Ultz.Native.GLFW": {
-        "type": "Transitive",
-        "resolved": "3.4.0",
-        "contentHash": "Iy22JopynbOJ32vA0lBhFEzGi65GQJBuJHYBYRBpydrDpNoTiHnjIXfA65Gu+8qsOr/ZEoIF8r9aHCgAXuO6DA=="
-      },
-      "sharpemu.hle": {
-        "type": "Project",
-        "dependencies": {
-          "SharpEmu.Logging": "[1.0.0, )"
-        }
-      },
-      "sharpemu.libs": {
-        "type": "Project",
-        "dependencies": {
-          "SharpEmu.HLE": "[1.0.0, )",
-          "Silk.NET.Input": "[2.23.0, )",
-          "Silk.NET.Vulkan": "[2.23.0, )",
-          "Silk.NET.Vulkan.Extensions.EXT": "[2.23.0, )",
-          "Silk.NET.Vulkan.Extensions.KHR": "[2.23.0, )",
-          "Silk.NET.Windowing": "[2.23.0, )"
-        }
-      },
-      "sharpemu.logging": {
-        "type": "Project"
-      },
-      "Silk.NET.Input": {
-        "type": "CentralTransitive",
-        "requested": "[2.23.0, )",
-        "resolved": "2.23.0",
-        "contentHash": "Xzl+tVwAp2eEd8blmGQjmJrsZPnp3PWG0KJjiAQHaY2Zr/ELVWeAROKXmZdCAvexzmte2JVGEy/dxnMycbxlpg==",
-        "dependencies": {
-          "Silk.NET.Input.Common": "2.23.0",
-          "Silk.NET.Input.Glfw": "2.23.0"
-        }
-      },
-      "Silk.NET.Vulkan": {
-        "type": "CentralTransitive",
-        "requested": "[2.23.0, )",
-        "resolved": "2.23.0",
-        "contentHash": "3/irtlSWXZ3eTi8N6nelI6L34NTB8ZJHpqVMNzZx2aX7Ek9YEQ34NoQW8/Tljrtmkg8KRhHW8hKTEzZaKV8PgA==",
-        "dependencies": {
-          "Silk.NET.Core": "2.23.0"
-        }
-      },
-      "Silk.NET.Vulkan.Extensions.EXT": {
-        "type": "CentralTransitive",
-        "requested": "[2.23.0, )",
-        "resolved": "2.23.0",
-        "contentHash": "+Oth189ksRiL6HvGCwIdnsYHawqrbO8y49u1H61z3wsfcHhQZeVDYe/wF5LD7fk3NcdgDvwFD3mLm1QWhdZySw==",
-        "dependencies": {
-          "Silk.NET.Core": "2.23.0",
-          "Silk.NET.Vulkan": "2.23.0"
-        }
-      },
-      "Silk.NET.Vulkan.Extensions.KHR": {
-        "type": "CentralTransitive",
-        "requested": "[2.23.0, )",
-        "resolved": "2.23.0",
-        "contentHash": "uRaf4j+SmH3DumjSSSUbFg33BnsGZUyXGj93O9NgGKZSJN3OTmNmQDxRew+/KiVLcgH6qzbto8aNGZ++j9GFWg==",
-        "dependencies": {
-          "Silk.NET.Core": "2.23.0",
-          "Silk.NET.Vulkan": "2.23.0"
-        }
-      },
-      "Silk.NET.Windowing": {
-        "type": "CentralTransitive",
-        "requested": "[2.23.0, )",
-        "resolved": "2.23.0",
-        "contentHash": "OPNPmt/lRyUKVYrFLQXVxyATqD3MKLc1iY1oKx1/2GppgmZxVZPwN12tekrQ4C7408kgB1L5JD1Wnirqqeb2kg==",
-        "dependencies": {
-          "Silk.NET.Windowing.Common": "2.23.0",
-          "Silk.NET.Windowing.Glfw": "2.23.0"
-        }
-      }
-    }
-  }
-}

src/SharpEmu.DebugClient/ClientEndpoint.cs

@@ -0,0 +1,54 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net;
+
+namespace SharpEmu.DebugClient;
+
+/// <summary>
+/// Parses the <c>host:port</c> the client connects to. Mirrors the server's
+/// defaults (loopback, port 5714) so a bare invocation attaches to a local
+/// emulator with no arguments.
+/// </summary>
+internal static class ClientEndpoint
+{
+    public const int DefaultPort = 5714;
+
+    public static bool TryParse(string? text, out string host, out int port, out string error)
+    {
+        host = "127.0.0.1";
+        port = DefaultPort;
+        error = string.Empty;
+        if (string.IsNullOrWhiteSpace(text))
+        {
+            return true;
+        }
+
+        var value = text.Trim();
+        var separator = value.LastIndexOf(':');
+        if (separator >= 0)
+        {
+            var portText = value[(separator + 1)..];
+            if (portText.Length > 0 && (!int.TryParse(portText, out port) || port is <= 0 or > 65535))
+            {
+                error = $"Invalid port '{portText}'.";
+                return false;
+            }
+
+            value = value[..separator];
+        }
+
+        if (!string.IsNullOrWhiteSpace(value))
+        {
+            host = string.Equals(value, "localhost", StringComparison.OrdinalIgnoreCase) ? "127.0.0.1" : value;
+        }
+
+        if (!IPAddress.TryParse(host, out _) && !Uri.CheckHostName(host).Equals(UriHostNameType.Dns))
+        {
+            error = $"Invalid host '{host}'.";
+            return false;
+        }
+
+        return true;
+    }
+}

src/SharpEmu.DebugClient/CommandTranslator.cs

@@ -0,0 +1,160 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Text.Json;
+
+namespace SharpEmu.DebugClient;
+
+/// <summary>
+/// Turns a friendly REPL line (<c>mem 0x1000 64</c>) into the JSON request the
+/// server understands. Local-only verbs (help, quit) are reported back to the
+/// caller instead of producing a request.
+/// </summary>
+internal static class CommandTranslator
+{
+    public enum ActionKind
+    {
+        SendRequest,
+        ShowHelp,
+        Quit,
+        Ignore,
+        Error,
+    }
+
+    public readonly record struct Result(ActionKind Kind, string? Payload = null, string? Error = null);
+
+    public static Result Translate(string line)
+    {
+        var trimmed = line.Trim();
+        if (trimmed.Length == 0)
+        {
+            return new Result(ActionKind.Ignore);
+        }
+
+        var parts = trimmed.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);
+        var verb = parts[0].ToLowerInvariant();
+        switch (verb)
+        {
+            case "help" or "?":
+                return new Result(ActionKind.ShowHelp);
+            case "quit" or "exit" or "q":
+                return new Result(ActionKind.Quit);
+            case "raw":
+                var json = trimmed[verb.Length..].Trim();
+                return json.Length == 0
+                    ? Error("raw requires a JSON object argument.")
+                    : Send(json);
+
+            case "ping":
+                return Request("ping");
+            case "status" or "info":
+                return Request("status");
+            case "state":
+                return Request("state");
+            case "regs" or "registers":
+                return Request("registers");
+            case "continue" or "cont" or "c":
+                return Request("continue");
+            case "step" or "s":
+                return Request("step");
+            case "pause" or "p":
+                return Request("pause");
+            case "bp" or "breakpoints" or "bl":
+                return Request("list-breakpoints");
+
+            case "setreg":
+                return parts.Length >= 3
+                    ? Request("set-register", ("register", parts[1]), ("value", parts[2]))
+                    : Error("Usage: setreg <register> <value>");
+            case "mem" or "read":
+                return parts.Length >= 3
+                    ? Request("read-memory", ("address", parts[1]), ("length", parts[2]))
+                    : Error("Usage: mem <address> <length>");
+            case "write":
+                return parts.Length >= 3
+                    ? Request("write-memory", ("address", parts[1]), ("bytes", parts[2]))
+                    : Error("Usage: write <address> <hex-bytes>");
+            case "break" or "b":
+                if (parts.Length < 2)
+                {
+                    return Error("Usage: break <address> [kind] [length]");
+                }
+
+                var breakArgs = new List<(string, string)> { ("address", parts[1]) };
+                if (parts.Length >= 3)
+                {
+                    breakArgs.Add(("kind", parts[2]));
+                }
+
+                if (parts.Length >= 4)
+                {
+                    breakArgs.Add(("length", parts[3]));
+                }
+
+                return Request("add-breakpoint", breakArgs.ToArray());
+            case "del" or "rm" or "delete":
+                return parts.Length >= 2
+                    ? Request("remove-breakpoint", ("id", parts[1]))
+                    : Error("Usage: del <id>");
+            case "enable":
+                return parts.Length >= 2
+                    ? Request("enable-breakpoint", ("id", parts[1]), ("enabled", "true"))
+                    : Error("Usage: enable <id>");
+            case "disable":
+                return parts.Length >= 2
+                    ? RequestWithBool("enable-breakpoint", ("id", parts[1]), enabledName: "enabled", enabled: false)
+                    : Error("Usage: disable <id>");
+
+            default:
+                return Error($"Unknown command '{verb}'. Type 'help' for the command list.");
+        }
+    }
+
+    private static Result Request(string command, params (string Name, string Value)[] args)
+    {
+        var payload = new Dictionary<string, object?> { ["command"] = command };
+        foreach (var (name, value) in args)
+        {
+            payload[name] = value;
+        }
+
+        return Send(JsonSerializer.Serialize(payload));
+    }
+
+    private static Result RequestWithBool(string command, (string Name, string Value) idArg, string enabledName, bool enabled)
+    {
+        var payload = new Dictionary<string, object?>
+        {
+            ["command"] = command,
+            [idArg.Name] = idArg.Value,
+            [enabledName] = enabled,
+        };
+        return Send(JsonSerializer.Serialize(payload));
+    }
+
+    private static Result Send(string json) => new(ActionKind.SendRequest, json);
+
+    private static Result Error(string message) => new(ActionKind.Error, Error: message);
+
+    public const string HelpText = """
+        SharpEmu debug client commands:
+          status | info            Show target state and last stop
+          state                    Show run state only
+          regs | registers         Dump integer registers (paused only)
+          setreg <reg> <value>     Set a register (rip/rflags/gp, paused only)
+          mem <addr> <len>         Read guest memory as hex (paused only)
+          write <addr> <hex>       Write guest memory from hex (paused only)
+          break <addr> [kind] [len]  Add a breakpoint (kind: execute/readwatch/writewatch/accesswatch)
+          bp | breakpoints         List breakpoints
+          del <id>                 Remove a breakpoint
+          enable <id> / disable <id>  Toggle a breakpoint
+          continue | c             Resume the target
+          step | s                 Resume and stop at the next frame
+          pause                    Ask a running target to stop
+          ping                     Round-trip check
+          raw <json>               Send a literal JSON request
+          help | ?                 Show this help
+          quit | exit              Disconnect and exit
+        Addresses and values accept decimal or 0x-prefixed hex.
+        """;
+}

src/SharpEmu.DebugClient/DEVELOPER_READ.md

@@ -0,0 +1,153 @@
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# SharpEmu.DebugClient
+
+A small, standalone command-line client that connects to the SharpEmu
+emulator's **live debug server** and drives it interactively. It ships as its
+own executable (`SharpEmu.DebugClient`) and takes no dependency on the emulator
+assemblies — it speaks the server's line-delimited JSON protocol directly over
+TCP, so you can also drive the server from `nc`, a script, or your own tool.
+
+> **Status:** infrastructure. The transport, protocol, session model, and
+> breakpoint store are in place. Stops are delivered at **frame boundaries**
+> (process entry and each module initializer); per-instruction stepping and data
+> watchpoints are part of the surface and become live as the CPU backend grows
+> the corresponding hooks. See [`docs/debugger-server.md`](../../docs/debugger-server.md)
+> for the architecture and protocol reference.
+
+## How it fits together
+
+```
++-------------------------+           TCP (JSON lines)         +----------------------+
+|  SharpEmu (emulator)    |  <------------------------------>  |  SharpEmu.DebugClient |
+|  --debug-server         |                                    |  (this executable)    |
+|                         |                                    |                       |
+|  DebuggerServerHost     |                                    |  REPL / --exec        |
+|   +- DebuggerServer     |  frame boundaries via ICpuDebugHook|                       |
+|   +- DebuggerSession  <-+------ CPU dispatcher ------------  |                       |
++-------------------------+                                    +----------------------+
+```
+
+The emulator is the **server**; this client is a separate process that connects
+to it and issues commands. The two never share memory — everything crosses the
+socket as JSON.
+
+## Building
+
+```bash
+dotnet build src/SharpEmu.DebugClient/SharpEmu.DebugClient.csproj
+```
+
+## Quick start
+
+1. Launch the emulator with the debug server enabled. It listens on
+   `127.0.0.1:5714` by default and, with stop-at-entry on, parks the guest at
+   its first frame until you continue:
+
+   ```bash
+   SharpEmu --debug-server "/path/to/game/eboot.bin"
+   # or choose an endpoint:
+   SharpEmu --debug-server=127.0.0.1:5714 "/path/to/game/eboot.bin"
+   ```
+
+2. In another terminal, attach the client:
+
+   ```bash
+   SharpEmu.DebugClient                 # defaults to 127.0.0.1:5714
+   SharpEmu.DebugClient 127.0.0.1:5714  # explicit endpoint
+   ```
+
+3. Drive the target:
+
+   ```
+   status
+   regs
+   break 0x00000008801234a0
+   continue
+   mem 0x00000008802000000 64
+   ```
+
+## Invocation
+
+```
+SharpEmu.DebugClient [host:port] [--exec "<command>"]... [--quiet]
+```
+
+| Option        | Meaning                                                        |
+| ------------- | ------------------------------------------------------------- |
+| `host:port`   | Server endpoint. Default `127.0.0.1:5714`. `localhost` is fine. |
+| `--exec, -e`  | Run one command non-interactively, then exit. Repeatable.     |
+| `--quiet`     | Suppress the connection banner.                               |
+| `--help, -h`  | Show usage and the command list.                              |
+
+Non-interactive example (scriptable):
+
+```bash
+SharpEmu.DebugClient --exec "break 0x8801234a0" --exec "continue"
+```
+
+## Commands
+
+Addresses and values accept decimal or `0x`-prefixed hex. Register and memory
+commands only succeed while the target is **paused**.
+
+| Command | Server verb | Description |
+| ------- | ----------- | ----------- |
+| `status` \| `info` | `status` | Target state plus the last stop. |
+| `state` | `state` | Run state only (`Running`/`Paused`/…). |
+| `regs` \| `registers` | `registers` | Dump the integer registers. |
+| `setreg <reg> <value>` | `set-register` | Set `rip`, `rflags`, or a GP register. |
+| `mem <addr> <len>` \| `read <addr> <len>` | `read-memory` | Read guest memory as hex. |
+| `write <addr> <hex>` | `write-memory` | Write guest memory from a hex string. |
+| `break <addr> [kind] [len]` \| `b …` | `add-breakpoint` | Add a breakpoint. `kind`: `execute` (default), `readwatch`, `writewatch`, `accesswatch`. |
+| `bp` \| `breakpoints` | `list-breakpoints` | List breakpoints. |
+| `del <id>` \| `rm <id>` | `remove-breakpoint` | Remove a breakpoint. |
+| `enable <id>` / `disable <id>` | `enable-breakpoint` | Toggle a breakpoint. |
+| `continue` \| `c` | `continue` | Resume a paused target. |
+| `step` \| `s` | `step` | Resume and stop at the next frame boundary. |
+| `pause` | `pause` | Ask a running target to stop at the next boundary. |
+| `ping` | `ping` | Round-trip liveness check. |
+| `raw <json>` | *(passthrough)* | Send a literal JSON request. |
+| `help` \| `?` | — | Show the command list (local). |
+| `quit` \| `exit` | — | Disconnect and exit (local). |
+
+## Output
+
+The client prints two kinds of lines as they arrive:
+
+- `reply>` — the response to a command you sent (`ok`, plus `data` or `error`).
+- `event>` — an unsolicited notification: `hello` on connect, `stopped` when the
+  target hits a breakpoint / entry / step / pause, `resumed` on continue, and
+  `terminated` when the run ends.
+
+Because replies and events share one stream, the client prints everything it
+receives rather than pairing replies to requests — a `stopped` event may arrive
+between your command and its reply.
+
+## Protocol (for building your own client)
+
+One JSON object per line, UTF-8, `\n`-terminated, in both directions.
+
+Request:
+
+```json
+{"command":"read-memory","address":"0x8802000000","length":64}
+```
+
+Reply:
+
+```json
+{"ok":true,"command":"read-memory","data":{"address":"0x0000000880200000","length":64,"bytes":"48894C24.."}}
+```
+
+Event:
+
+```json
+{"event":"stopped","reason":"Breakpoint","address":"0x00000008801234A0","frameKind":"ProcessEntry","frameLabel":"eboot.bin","registers":{ ... }}
+```
+
+The full verb list and payload fields live in
+[`docs/debugger-server.md`](../../docs/debugger-server.md).

src/SharpEmu.DebugClient/DebugClientConnection.cs

@@ -0,0 +1,120 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net.Sockets;
+using System.Text;
+using System.Text.Json;
+
+namespace SharpEmu.DebugClient;
+
+/// <summary>
+/// A thin TCP wrapper around the server's line-delimited JSON protocol: it
+/// writes request lines and runs a background loop that prints incoming
+/// responses and events as they arrive. Because the stream interleaves replies
+/// with asynchronous stop/resume events, a single reader printing everything is
+/// simpler and more robust than correlating request/response pairs.
+/// </summary>
+internal sealed class DebugClientConnection : IAsyncDisposable
+{
+    private static readonly UTF8Encoding Utf8NoBom = new(encoderShouldEmitUTF8Identifier: false);
+    private static readonly JsonSerializerOptions PrettyOptions = new() { WriteIndented = true };
+
+    private readonly TcpClient _client;
+    private readonly StreamReader _reader;
+    private readonly StreamWriter _writer;
+    private readonly SemaphoreSlim _writeLock = new(1, 1);
+
+    private DebugClientConnection(TcpClient client, NetworkStream stream)
+    {
+        _client = client;
+        _reader = new StreamReader(stream, Utf8NoBom);
+        _writer = new StreamWriter(stream, Utf8NoBom) { AutoFlush = false };
+    }
+
+    public static async Task<DebugClientConnection> ConnectAsync(string host, int port, CancellationToken cancellationToken)
+    {
+        var client = new TcpClient();
+        await client.ConnectAsync(host, port, cancellationToken).ConfigureAwait(false);
+        return new DebugClientConnection(client, client.GetStream());
+    }
+
+    /// <summary>Continuously prints incoming lines until the stream closes.</summary>
+    public async Task ReceiveLoopAsync(CancellationToken cancellationToken)
+    {
+        try
+        {
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                var line = await _reader.ReadLineAsync(cancellationToken).ConfigureAwait(false);
+                if (line is null)
+                {
+                    Console.WriteLine();
+                    Console.WriteLine("[connection closed by server]");
+                    return;
+                }
+
+                Print(line);
+            }
+        }
+        catch (OperationCanceledException)
+        {
+        }
+        catch (IOException)
+        {
+            Console.WriteLine();
+            Console.WriteLine("[connection lost]");
+        }
+    }
+
+    public async Task SendAsync(string json, CancellationToken cancellationToken)
+    {
+        await _writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await _writer.WriteLineAsync(json.AsMemory(), cancellationToken).ConfigureAwait(false);
+            await _writer.FlushAsync(cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            _writeLock.Release();
+        }
+    }
+
+    private static void Print(string line)
+    {
+        try
+        {
+            using var document = JsonDocument.Parse(line);
+            var root = document.RootElement;
+            var isEvent = root.TryGetProperty("event", out _);
+            var prefix = isEvent ? "event>" : "reply>";
+            var pretty = JsonSerializer.Serialize(root, PrettyOptions);
+            Console.WriteLine();
+            Console.WriteLine($"{prefix}\n{pretty}");
+        }
+        catch (JsonException)
+        {
+            Console.WriteLine();
+            Console.WriteLine(line);
+        }
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        try
+        {
+            await _writer.FlushAsync().ConfigureAwait(false);
+        }
+        catch (IOException)
+        {
+        }
+        catch (ObjectDisposedException)
+        {
+        }
+
+        _writeLock.Dispose();
+        _reader.Dispose();
+        await _writer.DisposeAsync().ConfigureAwait(false);
+        _client.Dispose();
+    }
+}

src/SharpEmu.DebugClient/Program.cs

@@ -0,0 +1,193 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net.Sockets;
+using SharpEmu.DebugClient;
+
+return await ClientProgram.RunAsync(args).ConfigureAwait(false);
+
+internal static class ClientProgram
+{
+    public static async Task<int> RunAsync(string[] args)
+    {
+        if (args.Any(a => a is "--help" or "-h"))
+        {
+            PrintUsage();
+            return 0;
+        }
+
+        string? endpointArg = null;
+        var execCommands = new List<string>();
+        var quiet = false;
+        for (var i = 0; i < args.Length; i++)
+        {
+            var arg = args[i];
+            if (string.Equals(arg, "--exec", StringComparison.OrdinalIgnoreCase) || string.Equals(arg, "-e", StringComparison.OrdinalIgnoreCase))
+            {
+                if (i + 1 >= args.Length)
+                {
+                    Console.Error.WriteLine("--exec requires a command argument.");
+                    return 2;
+                }
+
+                execCommands.Add(args[++i]);
+                continue;
+            }
+
+            if (string.Equals(arg, "--quiet", StringComparison.OrdinalIgnoreCase))
+            {
+                quiet = true;
+                continue;
+            }
+
+            if (arg.StartsWith('-'))
+            {
+                Console.Error.WriteLine($"Unknown option '{arg}'.");
+                PrintUsage();
+                return 2;
+            }
+
+            endpointArg ??= arg;
+        }
+
+        if (!ClientEndpoint.TryParse(endpointArg, out var host, out var port, out var endpointError))
+        {
+            Console.Error.WriteLine(endpointError);
+            return 2;
+        }
+
+        using var shutdown = new CancellationTokenSource();
+        Console.CancelKeyPress += (_, eventArgs) =>
+        {
+            eventArgs.Cancel = true;
+            shutdown.Cancel();
+        };
+
+        DebugClientConnection connection;
+        try
+        {
+            connection = await DebugClientConnection.ConnectAsync(host, port, shutdown.Token).ConfigureAwait(false);
+        }
+        catch (Exception ex) when (ex is SocketException or OperationCanceledException)
+        {
+            Console.Error.WriteLine($"Could not connect to {host}:{port}: {ex.Message}");
+            Console.Error.WriteLine("Start the emulator with --debug-server first.");
+            return 3;
+        }
+
+        await using (connection)
+        {
+            var receiveTask = connection.ReceiveLoopAsync(shutdown.Token);
+
+            if (execCommands.Count > 0)
+            {
+                await RunOneShotAsync(connection, execCommands, shutdown.Token).ConfigureAwait(false);
+            }
+            else
+            {
+                if (!quiet)
+                {
+                    Console.WriteLine($"Connected to SharpEmu debug server at {host}:{port}.");
+                    Console.WriteLine("Type 'help' for commands, 'quit' to exit.");
+                }
+
+                await RunReplAsync(connection, shutdown).ConfigureAwait(false);
+            }
+
+            shutdown.Cancel();
+            try
+            {
+                await receiveTask.ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+            }
+        }
+
+        return 0;
+    }
+
+    private static async Task RunOneShotAsync(
+        DebugClientConnection connection,
+        IReadOnlyList<string> commands,
+        CancellationToken cancellationToken)
+    {
+        foreach (var command in commands)
+        {
+            var result = CommandTranslator.Translate(command);
+            switch (result.Kind)
+            {
+                case CommandTranslator.ActionKind.SendRequest:
+                    await connection.SendAsync(result.Payload!, cancellationToken).ConfigureAwait(false);
+                    break;
+                case CommandTranslator.ActionKind.Error:
+                    Console.Error.WriteLine(result.Error);
+                    break;
+                case CommandTranslator.ActionKind.ShowHelp:
+                    Console.WriteLine(CommandTranslator.HelpText);
+                    break;
+            }
+        }
+
+        // Give the server a moment to answer before the client exits.
+        try
+        {
+            await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+        }
+    }
+
+    private static async Task RunReplAsync(DebugClientConnection connection, CancellationTokenSource shutdown)
+    {
+        while (!shutdown.IsCancellationRequested)
+        {
+            var line = await Console.In.ReadLineAsync(shutdown.Token).ConfigureAwait(false);
+            if (line is null)
+            {
+                break;
+            }
+
+            var result = CommandTranslator.Translate(line);
+            switch (result.Kind)
+            {
+                case CommandTranslator.ActionKind.Quit:
+                    return;
+                case CommandTranslator.ActionKind.ShowHelp:
+                    Console.WriteLine(CommandTranslator.HelpText);
+                    break;
+                case CommandTranslator.ActionKind.Error:
+                    Console.Error.WriteLine(result.Error);
+                    break;
+                case CommandTranslator.ActionKind.Ignore:
+                    break;
+                case CommandTranslator.ActionKind.SendRequest:
+                    try
+                    {
+                        await connection.SendAsync(result.Payload!, shutdown.Token).ConfigureAwait(false);
+                    }
+                    catch (Exception ex) when (ex is IOException or ObjectDisposedException)
+                    {
+                        Console.Error.WriteLine("Send failed; the connection is closed.");
+                        return;
+                    }
+
+                    break;
+            }
+        }
+    }
+
+    private static void PrintUsage()
+    {
+        Console.WriteLine("SharpEmu.DebugClient — live debugger client for the SharpEmu debug server.");
+        Console.WriteLine();
+        Console.WriteLine("Usage: SharpEmu.DebugClient [host:port] [--exec \"<command>\"]... [--quiet]");
+        Console.WriteLine("  host:port   Server endpoint (default 127.0.0.1:5714).");
+        Console.WriteLine("  --exec, -e  Run a command non-interactively (repeatable), then exit.");
+        Console.WriteLine("  --quiet     Suppress the connection banner.");
+        Console.WriteLine("  --help, -h  Show this help.");
+        Console.WriteLine();
+        Console.WriteLine(CommandTranslator.HelpText);
+    }
+}

src/SharpEmu.DebugClient/SharpEmu.DebugClient.csproj

@@ -0,0 +1,16 @@
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <!-- A small, standalone console tool: it speaks the debug server's
+         line-delimited JSON protocol directly over TCP and takes no dependency
+         on the emulator assemblies, so it builds and ships independently. -->
+    <OutputType>Exe</OutputType>
+    <AssemblyName>SharpEmu.DebugClient</AssemblyName>
+    <RootNamespace>SharpEmu.DebugClient</RootNamespace>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+</Project>

src/SharpEmu.Debugger/Breakpoints/Breakpoint.cs

@@ -0,0 +1,48 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Breakpoints;
+
+/// <summary>
+/// A single breakpoint or watchpoint. Instances are immutable; the owning
+/// <see cref="BreakpointStore"/> replaces an entry to change its enabled state.
+/// </summary>
+public sealed class Breakpoint
+{
+    public Breakpoint(int id, BreakpointKind kind, ulong address, ulong length = 1, bool enabled = true)
+    {
+        if (length == 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(length), "Breakpoint length must be at least one byte.");
+        }
+
+        Id = id;
+        Kind = kind;
+        Address = address;
+        Length = length;
+        Enabled = enabled;
+    }
+
+    /// <summary>The store-assigned identifier used by clients to reference it.</summary>
+    public int Id { get; }
+
+    public BreakpointKind Kind { get; }
+
+    /// <summary>The first guest address the breakpoint covers.</summary>
+    public ulong Address { get; }
+
+    /// <summary>
+    /// The number of bytes the breakpoint covers. Always one for
+    /// <see cref="BreakpointKind.Execute"/>; the watch kinds may span a range.
+    /// </summary>
+    public ulong Length { get; }
+
+    public bool Enabled { get; }
+
+    /// <summary>True when <paramref name="address"/> falls within this breakpoint.</summary>
+    public bool Covers(ulong address) => address >= Address && address < Address + Length;
+
+    /// <summary>Returns a copy with a different enabled state.</summary>
+    public Breakpoint WithEnabled(bool enabled)
+        => enabled == Enabled ? this : new Breakpoint(Id, Kind, Address, Length, enabled);
+}

src/SharpEmu.Debugger/Breakpoints/BreakpointKind.cs

@@ -0,0 +1,26 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Breakpoints;
+
+/// <summary>
+/// The kind of stop a breakpoint requests. Execution breakpoints are honoured
+/// at the frame-boundary seam that exists today; the data-watch kinds are part
+/// of the surface so client protocols and tooling can be built against them,
+/// and are armed once the execution backend can report the corresponding
+/// accesses.
+/// </summary>
+public enum BreakpointKind
+{
+    /// <summary>Stop when the instruction pointer reaches the address.</summary>
+    Execute,
+
+    /// <summary>Stop when the guest reads from the address range.</summary>
+    ReadWatch,
+
+    /// <summary>Stop when the guest writes to the address range.</summary>
+    WriteWatch,
+
+    /// <summary>Stop when the guest reads from or writes to the address range.</summary>
+    AccessWatch,
+}

src/SharpEmu.Debugger/Breakpoints/BreakpointStore.cs

@@ -0,0 +1,90 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Breakpoints;
+
+/// <summary>
+/// A thread-safe registry of breakpoints. The debug server mutates it from
+/// client-servicing threads while the emulation thread queries it at frame
+/// boundaries, so every operation takes the same lock.
+/// </summary>
+public sealed class BreakpointStore
+{
+    private readonly object _sync = new();
+    private readonly Dictionary<int, Breakpoint> _breakpoints = new();
+    private int _nextId = 1;
+
+    /// <summary>Adds a breakpoint and returns the created entry with its id.</summary>
+    public Breakpoint Add(BreakpointKind kind, ulong address, ulong length = 1)
+    {
+        lock (_sync)
+        {
+            var effectiveLength = kind == BreakpointKind.Execute ? 1UL : Math.Max(1UL, length);
+            var breakpoint = new Breakpoint(_nextId++, kind, address, effectiveLength);
+            _breakpoints[breakpoint.Id] = breakpoint;
+            return breakpoint;
+        }
+    }
+
+    /// <summary>Removes a breakpoint by id. Returns false when it did not exist.</summary>
+    public bool Remove(int id)
+    {
+        lock (_sync)
+        {
+            return _breakpoints.Remove(id);
+        }
+    }
+
+    /// <summary>Enables or disables a breakpoint by id.</summary>
+    public bool SetEnabled(int id, bool enabled)
+    {
+        lock (_sync)
+        {
+            if (!_breakpoints.TryGetValue(id, out var breakpoint))
+            {
+                return false;
+            }
+
+            _breakpoints[id] = breakpoint.WithEnabled(enabled);
+            return true;
+        }
+    }
+
+    /// <summary>Removes every breakpoint.</summary>
+    public void Clear()
+    {
+        lock (_sync)
+        {
+            _breakpoints.Clear();
+        }
+    }
+
+    /// <summary>Returns a point-in-time copy of all breakpoints.</summary>
+    public IReadOnlyList<Breakpoint> Snapshot()
+    {
+        lock (_sync)
+        {
+            return _breakpoints.Values.ToArray();
+        }
+    }
+
+    /// <summary>
+    /// Finds the first enabled execution breakpoint covering <paramref name="address"/>,
+    /// or null when none applies.
+    /// </summary>
+    public Breakpoint? FindExecuteHit(ulong address)
+    {
+        lock (_sync)
+        {
+            foreach (var breakpoint in _breakpoints.Values)
+            {
+                if (breakpoint.Enabled && breakpoint.Kind == BreakpointKind.Execute && breakpoint.Covers(address))
+                {
+                    return breakpoint;
+                }
+            }
+
+            return null;
+        }
+    }
+}

src/SharpEmu.Debugger/DebugRegisterFile.cs

@@ -0,0 +1,73 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.Core.Cpu.Debugging;
+using SharpEmu.HLE;
+
+namespace SharpEmu.Debugger;
+
+/// <summary>
+/// An immutable snapshot of the guest integer register state at a stop. XMM/YMM
+/// state is intentionally omitted here and read on demand through the target to
+/// keep the common register-dump path cheap.
+/// </summary>
+public readonly struct DebugRegisterFile
+{
+    private readonly ulong[] _generalPurpose;
+
+    public DebugRegisterFile(
+        ulong[] generalPurpose,
+        ulong rip,
+        ulong rflags,
+        ulong fsBase,
+        ulong gsBase)
+    {
+        ArgumentNullException.ThrowIfNull(generalPurpose);
+        if (generalPurpose.Length != 16)
+        {
+            throw new ArgumentException("Expected 16 general-purpose registers.", nameof(generalPurpose));
+        }
+
+        _generalPurpose = generalPurpose;
+        Rip = rip;
+        Rflags = rflags;
+        FsBase = fsBase;
+        GsBase = gsBase;
+    }
+
+    public ulong Rip { get; }
+
+    public ulong Rflags { get; }
+
+    public ulong FsBase { get; }
+
+    public ulong GsBase { get; }
+
+    /// <summary>Reads a register by identifier.</summary>
+    public ulong this[DebugRegisterId id] => id switch
+    {
+        DebugRegisterId.Rip => Rip,
+        DebugRegisterId.Rflags => Rflags,
+        DebugRegisterId.FsBase => FsBase,
+        DebugRegisterId.GsBase => GsBase,
+        _ when id.IsGeneralPurpose() => _generalPurpose[(int)id],
+        _ => throw new ArgumentOutOfRangeException(nameof(id), id, null),
+    };
+
+    /// <summary>Reads a general-purpose register.</summary>
+    public ulong this[CpuRegister register] => _generalPurpose[(int)register];
+
+    /// <summary>Captures the integer register state of a live debug frame.</summary>
+    public static DebugRegisterFile Capture(ICpuDebugFrame frame)
+    {
+        ArgumentNullException.ThrowIfNull(frame);
+
+        var gpr = new ulong[16];
+        for (var i = 0; i < gpr.Length; i++)
+        {
+            gpr[i] = frame.GetRegister((CpuRegister)i);
+        }
+
+        return new DebugRegisterFile(gpr, frame.Rip, frame.Rflags, frame.FsBase, frame.GsBase);
+    }
+}

src/SharpEmu.Debugger/DebugRegisterId.cs

@@ -0,0 +1,62 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.HLE;
+
+namespace SharpEmu.Debugger;
+
+/// <summary>
+/// The registers a debugger can name. The first sixteen values line up with
+/// <see cref="CpuRegister"/> so a general-purpose register can be converted
+/// between the two enums by casting; the remaining values cover the special
+/// registers a debug frame exposes.
+/// </summary>
+public enum DebugRegisterId
+{
+    Rax = 0,
+    Rcx = 1,
+    Rdx = 2,
+    Rbx = 3,
+    Rsp = 4,
+    Rbp = 5,
+    Rsi = 6,
+    Rdi = 7,
+    R8 = 8,
+    R9 = 9,
+    R10 = 10,
+    R11 = 11,
+    R12 = 12,
+    R13 = 13,
+    R14 = 14,
+    R15 = 15,
+
+    Rip = 16,
+    Rflags = 17,
+    FsBase = 18,
+    GsBase = 19,
+}
+
+/// <summary>Helpers for mapping between debug and CPU register identifiers.</summary>
+public static class DebugRegisterIdExtensions
+{
+    /// <summary>
+    /// True when the identifier names one of the sixteen general-purpose
+    /// registers and can be cast to <see cref="CpuRegister"/>.
+    /// </summary>
+    public static bool IsGeneralPurpose(this DebugRegisterId id)
+        => id is >= DebugRegisterId.Rax and <= DebugRegisterId.R15;
+
+    /// <summary>
+    /// Converts a general-purpose identifier to its <see cref="CpuRegister"/>.
+    /// Throws when <paramref name="id"/> is a special register.
+    /// </summary>
+    public static CpuRegister ToCpuRegister(this DebugRegisterId id)
+    {
+        if (!id.IsGeneralPurpose())
+        {
+            throw new ArgumentOutOfRangeException(nameof(id), id, "Not a general-purpose register.");
+        }
+
+        return (CpuRegister)(int)id;
+    }
+}

src/SharpEmu.Debugger/DebuggerServerHost.cs

@@ -0,0 +1,59 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net;
+using SharpEmu.Core.Cpu.Debugging;
+using SharpEmu.Debugger.Server;
+using SharpEmu.Debugger.Session;
+
+namespace SharpEmu.Debugger;
+
+/// <summary>
+/// One-call wiring of the live debugger: it owns a <see cref="DebuggerSession"/>
+/// and a <see cref="DebuggerServer"/>, exposes the <see cref="Hook"/> to attach
+/// to <c>SharpEmuRuntimeOptions.DebugHook</c>, and starts/stops the network
+/// front-end. A host constructs one, hands <see cref="Hook"/> to the runtime,
+/// calls <see cref="Start"/>, and calls <see cref="NotifyRunCompleted"/> once the
+/// runtime returns.
+/// </summary>
+public sealed class DebuggerServerHost : IAsyncDisposable
+{
+    private readonly DebuggerSession _session;
+    private readonly DebuggerServer _server;
+
+    public DebuggerServerHost(
+        DebuggerServerOptions? serverOptions = null,
+        DebuggerSessionOptions? sessionOptions = null)
+    {
+        _session = new DebuggerSession(sessionOptions);
+        _server = new DebuggerServer(_session, serverOptions);
+    }
+
+    /// <summary>The session driving the target.</summary>
+    public IDebuggerSession Session => _session;
+
+    /// <summary>
+    /// The dispatcher hook to hand to the runtime so guest frames route through
+    /// the debugger.
+    /// </summary>
+    public ICpuDebugHook Hook => _session.Hook;
+
+    /// <summary>The endpoint the server bound to, or null before <see cref="Start"/>.</summary>
+    public IPEndPoint? Endpoint => _server.Endpoint;
+
+    /// <summary>Begins accepting debugger clients.</summary>
+    public void Start() => _server.Start();
+
+    /// <summary>
+    /// Releases a parked emulation thread and marks the target terminated. Call
+    /// after the runtime's run returns so any attached client is notified and the
+    /// guest thread is never left blocked in the debugger.
+    /// </summary>
+    public void NotifyRunCompleted() => _session.NotifyTerminated();
+
+    public async ValueTask DisposeAsync()
+    {
+        _session.NotifyTerminated();
+        await _server.DisposeAsync().ConfigureAwait(false);
+    }
+}

src/SharpEmu.Debugger/Protocol/DebugCommandDispatcher.cs

@@ -0,0 +1,340 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.Debugger.Breakpoints;
+using SharpEmu.Debugger.Session;
+using SharpEmu.HLE;
+
+namespace SharpEmu.Debugger.Protocol;
+
+/// <summary>
+/// Translates parsed <see cref="DebugRequest"/> verbs into operations on an
+/// <see cref="IDebuggerSession"/> and packages the outcome as a
+/// <see cref="DebugResponse"/>. This is the single place command semantics live,
+/// so it is shared by every connection and independent of the wire format.
+/// </summary>
+public sealed class DebugCommandDispatcher
+{
+    private readonly IDebuggerSession _session;
+
+    public DebugCommandDispatcher(IDebuggerSession session)
+    {
+        _session = session ?? throw new ArgumentNullException(nameof(session));
+    }
+
+    public DebugResponse Dispatch(DebugRequest request)
+    {
+        return request.Command switch
+        {
+            JsonLineDebugProtocol.ParseErrorCommand => ParseError(request),
+            "ping" => DebugResponse.Success(request.Command),
+            "status" or "info" => Status(request),
+            "state" => DebugResponse.Success(request.Command, new Dictionary<string, object?>
+            {
+                ["state"] = _session.State.ToString(),
+            }),
+            "registers" or "regs" => Registers(request),
+            "set-register" or "set-reg" => SetRegister(request),
+            "read-memory" or "read-mem" => ReadMemory(request),
+            "write-memory" or "write-mem" => WriteMemory(request),
+            "list-breakpoints" or "breakpoints" => ListBreakpoints(request),
+            "add-breakpoint" or "break" => AddBreakpoint(request),
+            "remove-breakpoint" or "delete-breakpoint" => RemoveBreakpoint(request),
+            "enable-breakpoint" => EnableBreakpoint(request),
+            "continue" or "cont" or "c" => Simple(request, _session.Continue(), "Target is not paused."),
+            "step" or "s" => Simple(request, _session.StepFrame(), "Target is not paused."),
+            "pause" => Pause(request),
+            _ => DebugResponse.Failure(request.Command, $"Unknown command '{request.Command}'."),
+        };
+    }
+
+    private static DebugResponse ParseError(DebugRequest request)
+    {
+        var message = request.TryGetString("message", out var text) ? text : "Malformed request.";
+        return DebugResponse.Failure(request.Command, message);
+    }
+
+    private DebugResponse Status(DebugRequest request)
+    {
+        var data = new Dictionary<string, object?>
+        {
+            ["state"] = _session.State.ToString(),
+            ["breakpoints"] = _session.Breakpoints.Snapshot().Count,
+        };
+
+        if (_session.LastStop is { } stop)
+        {
+            data["lastStop"] = DescribeStop(stop);
+        }
+
+        return DebugResponse.Success(request.Command, data);
+    }
+
+    private DebugResponse Registers(DebugRequest request)
+    {
+        if (!_session.TryGetRegisters(out var registers))
+        {
+            return NotPaused(request);
+        }
+
+        return DebugResponse.Success(request.Command, new Dictionary<string, object?>
+        {
+            ["registers"] = DescribeRegisters(registers),
+        });
+    }
+
+    private DebugResponse SetRegister(DebugRequest request)
+    {
+        if (!request.TryGetString("register", out var name) || !TryParseRegister(name, out var id))
+        {
+            return DebugResponse.Failure(request.Command, "Expected a valid 'register' name.");
+        }
+
+        if (!request.TryGetUInt64("value", out var value))
+        {
+            return DebugResponse.Failure(request.Command, "Expected a 'value'.");
+        }
+
+        return _session.TrySetRegister(id, value)
+            ? DebugResponse.Success(request.Command)
+            : DebugResponse.Failure(request.Command, "Register is not writable or target is not paused.");
+    }
+
+    private DebugResponse ReadMemory(DebugRequest request)
+    {
+        if (!request.TryGetUInt64("address", out var address))
+        {
+            return DebugResponse.Failure(request.Command, "Expected an 'address'.");
+        }
+
+        if (!request.TryGetInt32("length", out var length) || length <= 0 || length > MaxMemoryChunk)
+        {
+            return DebugResponse.Failure(request.Command, $"Expected a 'length' between 1 and {MaxMemoryChunk}.");
+        }
+
+        var buffer = new byte[length];
+        if (!_session.TryReadMemory(address, buffer))
+        {
+            return DebugResponse.Failure(request.Command, "Memory is unreadable or target is not paused.");
+        }
+
+        return DebugResponse.Success(request.Command, new Dictionary<string, object?>
+        {
+            ["address"] = FormatAddress(address),
+            ["length"] = length,
+            ["bytes"] = Convert.ToHexString(buffer),
+        });
+    }
+
+    private DebugResponse WriteMemory(DebugRequest request)
+    {
+        if (!request.TryGetUInt64("address", out var address))
+        {
+            return DebugResponse.Failure(request.Command, "Expected an 'address'.");
+        }
+
+        if (!request.TryGetString("bytes", out var hex) || hex.Length == 0 || (hex.Length & 1) != 0)
+        {
+            return DebugResponse.Failure(request.Command, "Expected 'bytes' as an even-length hex string.");
+        }
+
+        byte[] data;
+        try
+        {
+            data = Convert.FromHexString(hex);
+        }
+        catch (FormatException)
+        {
+            return DebugResponse.Failure(request.Command, "'bytes' is not valid hex.");
+        }
+
+        if (data.Length > MaxMemoryChunk)
+        {
+            return DebugResponse.Failure(request.Command, $"Cannot write more than {MaxMemoryChunk} bytes at once.");
+        }
+
+        return _session.TryWriteMemory(address, data)
+            ? DebugResponse.Success(request.Command, new Dictionary<string, object?> { ["written"] = data.Length })
+            : DebugResponse.Failure(request.Command, "Memory is unwritable or target is not paused.");
+    }
+
+    private DebugResponse ListBreakpoints(DebugRequest request)
+    {
+        var breakpoints = _session.Breakpoints.Snapshot()
+            .OrderBy(breakpoint => breakpoint.Id)
+            .Select(DescribeBreakpoint)
+            .ToArray();
+
+        return DebugResponse.Success(request.Command, new Dictionary<string, object?>
+        {
+            ["breakpoints"] = breakpoints,
+        });
+    }
+
+    private DebugResponse AddBreakpoint(DebugRequest request)
+    {
+        if (!request.TryGetUInt64("address", out var address))
+        {
+            return DebugResponse.Failure(request.Command, "Expected an 'address'.");
+        }
+
+        var kind = BreakpointKind.Execute;
+        if (request.TryGetString("kind", out var kindText) && !TryParseBreakpointKind(kindText, out kind))
+        {
+            return DebugResponse.Failure(request.Command, $"Unknown breakpoint kind '{kindText}'.");
+        }
+
+        var length = 1UL;
+        if (request.TryGetUInt64("length", out var requestedLength) && requestedLength > 0)
+        {
+            length = requestedLength;
+        }
+
+        var breakpoint = _session.Breakpoints.Add(kind, address, length);
+        return DebugResponse.Success(request.Command, new Dictionary<string, object?>
+        {
+            ["breakpoint"] = DescribeBreakpoint(breakpoint),
+        });
+    }
+
+    private DebugResponse RemoveBreakpoint(DebugRequest request)
+    {
+        if (!request.TryGetInt32("id", out var id))
+        {
+            return DebugResponse.Failure(request.Command, "Expected an 'id'.");
+        }
+
+        return _session.Breakpoints.Remove(id)
+            ? DebugResponse.Success(request.Command)
+            : DebugResponse.Failure(request.Command, $"No breakpoint with id {id}.");
+    }
+
+    private DebugResponse EnableBreakpoint(DebugRequest request)
+    {
+        if (!request.TryGetInt32("id", out var id))
+        {
+            return DebugResponse.Failure(request.Command, "Expected an 'id'.");
+        }
+
+        var enabled = !request.TryGetBool("enabled", out var requested) || requested;
+        return _session.Breakpoints.SetEnabled(id, enabled)
+            ? DebugResponse.Success(request.Command)
+            : DebugResponse.Failure(request.Command, $"No breakpoint with id {id}.");
+    }
+
+    private DebugResponse Pause(DebugRequest request)
+    {
+        _session.RequestPause();
+        return DebugResponse.Success(request.Command);
+    }
+
+    private static DebugResponse Simple(DebugRequest request, bool succeeded, string failureMessage)
+        => succeeded ? DebugResponse.Success(request.Command) : DebugResponse.Failure(request.Command, failureMessage);
+
+    private static DebugResponse NotPaused(DebugRequest request)
+        => DebugResponse.Failure(request.Command, "Target is not paused.");
+
+    internal static IReadOnlyDictionary<string, object?> DescribeStop(DebugStopEvent stop)
+    {
+        var data = new Dictionary<string, object?>
+        {
+            ["reason"] = stop.Reason.ToString(),
+            ["address"] = FormatAddress(stop.Address),
+            ["frameKind"] = stop.FrameKind.ToString(),
+            ["frameLabel"] = stop.FrameLabel,
+            ["registers"] = DescribeRegisters(stop.Registers),
+        };
+
+        if (stop.Breakpoint is { } breakpoint)
+        {
+            data["breakpoint"] = DescribeBreakpoint(breakpoint);
+        }
+
+        if (stop.Result is { } result)
+        {
+            data["result"] = result.ToString();
+        }
+
+        if (stop.Detail is { } detail)
+        {
+            data["detail"] = detail;
+        }
+
+        if (stop.OpcodeBytes is { } opcodeBytes)
+        {
+            data["opcodeBytes"] = opcodeBytes;
+        }
+
+        if (stop.StallInfo is { } stall)
+        {
+            data["stall"] = new Dictionary<string, object?>
+            {
+                ["kind"] = stall.Kind.ToString(),
+                ["nid"] = stall.Nid,
+                ["instructionPointer"] = FormatAddress(stall.InstructionPointer),
+                ["dispatchIndex"] = stall.DispatchIndex,
+                ["argument0"] = FormatAddress(stall.Argument0),
+                ["argument1"] = FormatAddress(stall.Argument1),
+                ["resolved"] = stall.IsResolved,
+                ["library"] = stall.LibraryName,
+                ["function"] = stall.FunctionName,
+            };
+        }
+
+        return data;
+    }
+
+    private static IReadOnlyDictionary<string, object?> DescribeRegisters(DebugRegisterFile registers)
+    {
+        var result = new Dictionary<string, object?>(20);
+        for (var i = 0; i < 16; i++)
+        {
+            result[((CpuRegister)i).ToString().ToLowerInvariant()] = FormatAddress(registers[(CpuRegister)i]);
+        }
+
+        result["rip"] = FormatAddress(registers.Rip);
+        result["rflags"] = FormatAddress(registers.Rflags);
+        result["fs_base"] = FormatAddress(registers.FsBase);
+        result["gs_base"] = FormatAddress(registers.GsBase);
+        return result;
+    }
+
+    private static IReadOnlyDictionary<string, object?> DescribeBreakpoint(Breakpoint breakpoint)
+        => new Dictionary<string, object?>
+        {
+            ["id"] = breakpoint.Id,
+            ["kind"] = breakpoint.Kind.ToString(),
+            ["address"] = FormatAddress(breakpoint.Address),
+            ["length"] = breakpoint.Length,
+            ["enabled"] = breakpoint.Enabled,
+        };
+
+    private static string FormatAddress(ulong value) => $"0x{value:X16}";
+
+    private static bool TryParseRegister(string name, out DebugRegisterId id)
+    {
+        var normalized = name.Trim().ToLowerInvariant();
+        switch (normalized)
+        {
+            case "rip":
+                id = DebugRegisterId.Rip;
+                return true;
+            case "rflags":
+                id = DebugRegisterId.Rflags;
+                return true;
+            case "fs_base" or "fsbase":
+                id = DebugRegisterId.FsBase;
+                return true;
+            case "gs_base" or "gsbase":
+                id = DebugRegisterId.GsBase;
+                return true;
+        }
+
+        return Enum.TryParse(normalized, ignoreCase: true, out id) && Enum.IsDefined(id);
+    }
+
+    private static bool TryParseBreakpointKind(string text, out BreakpointKind kind)
+        => Enum.TryParse(text.Trim(), ignoreCase: true, out kind) && Enum.IsDefined(kind);
+
+    private const int MaxMemoryChunk = 64 * 1024;
+}

src/SharpEmu.Debugger/Protocol/DebugRequest.cs

@@ -0,0 +1,152 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Globalization;
+using System.Text.Json;
+
+namespace SharpEmu.Debugger.Protocol;
+
+/// <summary>
+/// A parsed client request: a <see cref="Command"/> verb plus a bag of named
+/// arguments backed by the original JSON. Numeric arguments accept either JSON
+/// numbers or <c>"0x"</c>-prefixed hex strings so addresses read naturally on
+/// the wire.
+/// </summary>
+public sealed class DebugRequest
+{
+    private readonly JsonElement _root;
+
+    private DebugRequest(string command, JsonElement root)
+    {
+        Command = command;
+        _root = root;
+    }
+
+    /// <summary>The lower-cased command verb.</summary>
+    public string Command { get; }
+
+    /// <summary>
+    /// Parses a single JSON object into a request. Returns false when the text is
+    /// not a JSON object or is missing a string <c>command</c> field.
+    /// </summary>
+    public static bool TryParse(string json, out DebugRequest request, out string error)
+    {
+        request = null!;
+        error = string.Empty;
+        try
+        {
+            using var document = JsonDocument.Parse(json);
+            var root = document.RootElement.Clone();
+            if (root.ValueKind != JsonValueKind.Object)
+            {
+                error = "Request must be a JSON object.";
+                return false;
+            }
+
+            if (!root.TryGetProperty("command", out var commandElement) ||
+                commandElement.ValueKind != JsonValueKind.String)
+            {
+                error = "Request is missing a string 'command'.";
+                return false;
+            }
+
+            var command = commandElement.GetString() ?? string.Empty;
+            request = new DebugRequest(command.Trim().ToLowerInvariant(), root);
+            return true;
+        }
+        catch (JsonException ex)
+        {
+            error = $"Malformed JSON: {ex.Message}";
+            return false;
+        }
+    }
+
+    public bool TryGetString(string name, out string value)
+    {
+        if (_root.TryGetProperty(name, out var element) && element.ValueKind == JsonValueKind.String)
+        {
+            value = element.GetString() ?? string.Empty;
+            return true;
+        }
+
+        value = string.Empty;
+        return false;
+    }
+
+    public bool TryGetUInt64(string name, out ulong value)
+    {
+        value = 0;
+        if (!_root.TryGetProperty(name, out var element))
+        {
+            return false;
+        }
+
+        switch (element.ValueKind)
+        {
+            case JsonValueKind.Number:
+                return element.TryGetUInt64(out value);
+            case JsonValueKind.String:
+                return TryParseNumber(element.GetString(), out value);
+            default:
+                return false;
+        }
+    }
+
+    public bool TryGetInt32(string name, out int value)
+    {
+        value = 0;
+        if (!_root.TryGetProperty(name, out var element))
+        {
+            return false;
+        }
+
+        switch (element.ValueKind)
+        {
+            case JsonValueKind.Number:
+                return element.TryGetInt32(out value);
+            case JsonValueKind.String when TryParseNumber(element.GetString(), out var parsed) && parsed <= int.MaxValue:
+                value = (int)parsed;
+                return true;
+            default:
+                return false;
+        }
+    }
+
+    public bool TryGetBool(string name, out bool value)
+    {
+        value = false;
+        if (!_root.TryGetProperty(name, out var element))
+        {
+            return false;
+        }
+
+        switch (element.ValueKind)
+        {
+            case JsonValueKind.True:
+                value = true;
+                return true;
+            case JsonValueKind.False:
+                value = false;
+                return true;
+            default:
+                return false;
+        }
+    }
+
+    private static bool TryParseNumber(string? text, out ulong value)
+    {
+        value = 0;
+        if (string.IsNullOrWhiteSpace(text))
+        {
+            return false;
+        }
+
+        text = text.Trim();
+        if (text.StartsWith("0x", StringComparison.OrdinalIgnoreCase))
+        {
+            return ulong.TryParse(text.AsSpan(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out value);
+        }
+
+        return ulong.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out value);
+    }
+}

src/SharpEmu.Debugger/Protocol/DebugResponse.cs

@@ -0,0 +1,34 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Protocol;
+
+/// <summary>
+/// The reply to a <see cref="DebugRequest"/>: either success with an optional
+/// data payload, or a failure with a human-readable message.
+/// </summary>
+public sealed class DebugResponse
+{
+    private DebugResponse(bool ok, string? command, IReadOnlyDictionary<string, object?>? data, string? error)
+    {
+        Ok = ok;
+        Command = command;
+        Data = data;
+        Error = error;
+    }
+
+    public bool Ok { get; }
+
+    /// <summary>Echoes the command the reply answers, when known.</summary>
+    public string? Command { get; }
+
+    public IReadOnlyDictionary<string, object?>? Data { get; }
+
+    public string? Error { get; }
+
+    public static DebugResponse Success(string command, IReadOnlyDictionary<string, object?>? data = null)
+        => new(ok: true, command, data, error: null);
+
+    public static DebugResponse Failure(string command, string error)
+        => new(ok: false, command, data: null, error);
+}

src/SharpEmu.Debugger/Protocol/IDebugProtocol.cs

@@ -0,0 +1,33 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Protocol;
+
+/// <summary>
+/// Frames debugger traffic on a connection. A protocol turns bytes into
+/// <see cref="DebugRequest"/> objects and serialises <see cref="DebugResponse"/>
+/// replies plus asynchronous events (stops, resumes, termination) back to the
+/// client. Swapping the implementation (line-delimited JSON today, a GDB remote
+/// serial stub later) leaves the session and server untouched.
+/// </summary>
+public interface IDebugProtocol
+{
+    /// <summary>A short protocol name reported in the handshake.</summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Reads the next request, or null at end of stream. Parse failures are
+    /// surfaced as a request with a reserved error command rather than throwing.
+    /// </summary>
+    Task<DebugRequest?> ReadRequestAsync(TextReader reader, CancellationToken cancellationToken);
+
+    /// <summary>Writes a reply to a request.</summary>
+    Task WriteResponseAsync(TextWriter writer, DebugResponse response, CancellationToken cancellationToken);
+
+    /// <summary>Writes an unsolicited event (for example a stop notification).</summary>
+    Task WriteEventAsync(
+        TextWriter writer,
+        string eventName,
+        IReadOnlyDictionary<string, object?> data,
+        CancellationToken cancellationToken);
+}

src/SharpEmu.Debugger/Protocol/JsonLineDebugProtocol.cs

@@ -0,0 +1,112 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Text.Json;
+
+namespace SharpEmu.Debugger.Protocol;
+
+/// <summary>
+/// A newline-delimited JSON protocol: one JSON object per line in each
+/// direction. Requests carry a <c>command</c>; replies carry <c>ok</c> plus
+/// <c>data</c>/<c>error</c>; events carry an <c>event</c> name. It is trivial to
+/// drive from a socket, <c>nc</c>, or a small script, which suits bring-up and
+/// tooling while a richer protocol is layered on later.
+/// </summary>
+public sealed class JsonLineDebugProtocol : IDebugProtocol
+{
+    /// <summary>The command assigned to a request that failed to parse.</summary>
+    public const string ParseErrorCommand = "$parse-error";
+
+    private static readonly JsonSerializerOptions SerializerOptions = new()
+    {
+        WriteIndented = false,
+    };
+
+    public string Name => "json-lines/1";
+
+    public async Task<DebugRequest?> ReadRequestAsync(TextReader reader, CancellationToken cancellationToken)
+    {
+        while (true)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var line = await reader.ReadLineAsync(cancellationToken).ConfigureAwait(false);
+            if (line is null)
+            {
+                return null;
+            }
+
+            if (string.IsNullOrWhiteSpace(line))
+            {
+                continue;
+            }
+
+            if (DebugRequest.TryParse(line, out var request, out var error))
+            {
+                return request;
+            }
+
+            // Surface the parse failure as a synthetic request so the connection
+            // loop can reply with an error rather than dropping the client.
+            var envelope = $"{{\"command\":\"{ParseErrorCommand}\",\"message\":{JsonSerializer.Serialize(error)}}}";
+            if (DebugRequest.TryParse(envelope, out var errorRequest, out _))
+            {
+                return errorRequest;
+            }
+        }
+    }
+
+    public async Task WriteResponseAsync(TextWriter writer, DebugResponse response, CancellationToken cancellationToken)
+    {
+        var payload = new Dictionary<string, object?>
+        {
+            ["ok"] = response.Ok,
+        };
+
+        if (response.Command is not null)
+        {
+            payload["command"] = response.Command;
+        }
+
+        if (response.Data is not null)
+        {
+            payload["data"] = response.Data;
+        }
+
+        if (response.Error is not null)
+        {
+            payload["error"] = response.Error;
+        }
+
+        await WriteLineAsync(writer, payload, cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task WriteEventAsync(
+        TextWriter writer,
+        string eventName,
+        IReadOnlyDictionary<string, object?> data,
+        CancellationToken cancellationToken)
+    {
+        var payload = new Dictionary<string, object?>(data.Count + 1)
+        {
+            ["event"] = eventName,
+        };
+
+        foreach (var (key, value) in data)
+        {
+            payload[key] = value;
+        }
+
+        await WriteLineAsync(writer, payload, cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task WriteLineAsync(
+        TextWriter writer,
+        IReadOnlyDictionary<string, object?> payload,
+        CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        var json = JsonSerializer.Serialize(payload, SerializerOptions);
+        await writer.WriteLineAsync(json.AsMemory(), cancellationToken).ConfigureAwait(false);
+        await writer.FlushAsync(cancellationToken).ConfigureAwait(false);
+    }
+}

src/SharpEmu.Debugger/Server/DebuggerClientConnection.cs

@@ -0,0 +1,158 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net.Sockets;
+using System.Text;
+using SharpEmu.Debugger.Protocol;
+using SharpEmu.Debugger.Session;
+using SharpEmu.Logging;
+
+namespace SharpEmu.Debugger.Server;
+
+/// <summary>
+/// Services a single connected client: reads requests, dispatches them against
+/// the shared session, and pushes session lifecycle events. Writes from the
+/// request loop and from event callbacks are serialised through one lock so the
+/// two never interleave a half-written line.
+/// </summary>
+internal sealed class DebuggerClientConnection : IAsyncDisposable
+{
+    private static readonly SharpEmuLogger Log = SharpEmuLog.For("SharpEmu.Debugger");
+    private static readonly UTF8Encoding Utf8NoBom = new(encoderShouldEmitUTF8Identifier: false);
+
+    private readonly TcpClient _client;
+    private readonly IDebuggerSession _session;
+    private readonly IDebugProtocol _protocol;
+    private readonly DebugCommandDispatcher _dispatcher;
+    private readonly SemaphoreSlim _writeLock = new(1, 1);
+
+    private TextWriter? _writer;
+    private CancellationToken _cancellationToken;
+
+    public DebuggerClientConnection(TcpClient client, IDebuggerSession session, IDebugProtocol protocol)
+    {
+        _client = client;
+        _session = session;
+        _protocol = protocol;
+        _dispatcher = new DebugCommandDispatcher(session);
+    }
+
+    public async Task RunAsync(CancellationToken cancellationToken)
+    {
+        _cancellationToken = cancellationToken;
+        var endpoint = _client.Client.RemoteEndPoint?.ToString() ?? "unknown";
+        Log.Info($"Debugger client connected: {endpoint}");
+
+        using var stream = _client.GetStream();
+        using var reader = new StreamReader(stream, Utf8NoBom);
+        await using var writer = new StreamWriter(stream, Utf8NoBom) { AutoFlush = false };
+        _writer = writer;
+
+        _session.Stopped += OnStopped;
+        _session.Resumed += OnResumed;
+        _session.Terminated += OnTerminated;
+        try
+        {
+            await SendEventAsync("hello", new Dictionary<string, object?>
+            {
+                ["protocol"] = _protocol.Name,
+                ["state"] = _session.State.ToString(),
+            }).ConfigureAwait(false);
+
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                var request = await _protocol.ReadRequestAsync(reader, cancellationToken).ConfigureAwait(false);
+                if (request is null)
+                {
+                    break;
+                }
+
+                var response = _dispatcher.Dispatch(request);
+                await WriteResponseAsync(response).ConfigureAwait(false);
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            // Server shutting down.
+        }
+        catch (IOException)
+        {
+            // Client dropped the connection.
+        }
+        catch (Exception ex)
+        {
+            Log.Warn($"Debugger client error ({endpoint}): {ex.Message}");
+        }
+        finally
+        {
+            _session.Stopped -= OnStopped;
+            _session.Resumed -= OnResumed;
+            _session.Terminated -= OnTerminated;
+            _writer = null;
+            Log.Info($"Debugger client disconnected: {endpoint}");
+        }
+    }
+
+    private void OnStopped(object? sender, DebugStopEvent stop)
+        => _ = SendEventAsync("stopped", DebugCommandDispatcher.DescribeStop(stop));
+
+    private void OnResumed(object? sender, EventArgs e)
+        => _ = SendEventAsync("resumed", EmptyData);
+
+    private void OnTerminated(object? sender, EventArgs e)
+        => _ = SendEventAsync("terminated", EmptyData);
+
+    private async Task WriteResponseAsync(DebugResponse response)
+    {
+        var writer = _writer;
+        if (writer is null)
+        {
+            return;
+        }
+
+        await _writeLock.WaitAsync(_cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await _protocol.WriteResponseAsync(writer, response, _cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            _writeLock.Release();
+        }
+    }
+
+    private async Task SendEventAsync(string name, IReadOnlyDictionary<string, object?> data)
+    {
+        var writer = _writer;
+        if (writer is null)
+        {
+            return;
+        }
+
+        try
+        {
+            await _writeLock.WaitAsync(_cancellationToken).ConfigureAwait(false);
+            try
+            {
+                await _protocol.WriteEventAsync(writer, name, data, _cancellationToken).ConfigureAwait(false);
+            }
+            finally
+            {
+                _writeLock.Release();
+            }
+        }
+        catch (Exception ex) when (ex is IOException or OperationCanceledException or ObjectDisposedException)
+        {
+            // The client went away between the event firing and the write.
+        }
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        _writeLock.Dispose();
+        _client.Dispose();
+        return ValueTask.CompletedTask;
+    }
+
+    private static readonly IReadOnlyDictionary<string, object?> EmptyData = new Dictionary<string, object?>();
+}

src/SharpEmu.Debugger/Server/DebuggerServer.cs

@@ -0,0 +1,136 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Collections.Concurrent;
+using System.Net;
+using System.Net.Sockets;
+using SharpEmu.Debugger.Protocol;
+using SharpEmu.Debugger.Session;
+using SharpEmu.Logging;
+
+namespace SharpEmu.Debugger.Server;
+
+/// <summary>
+/// A TCP server that exposes an <see cref="IDebuggerSession"/> to remote
+/// clients over a pluggable <see cref="IDebugProtocol"/>. Every connection sees
+/// the same session, so multiple clients (for example a UI and a scripted
+/// probe) observe a consistent view of the target.
+/// </summary>
+public sealed class DebuggerServer : IDebuggerServer
+{
+    private static readonly SharpEmuLogger Log = SharpEmuLog.For("SharpEmu.Debugger");
+
+    private readonly IDebuggerSession _session;
+    private readonly DebuggerServerOptions _options;
+    private readonly Func<IDebugProtocol> _protocolFactory;
+    private readonly ConcurrentDictionary<DebuggerClientConnection, Task> _connections = new();
+    private readonly CancellationTokenSource _shutdown = new();
+
+    private TcpListener? _listener;
+    private Task? _acceptLoop;
+
+    public DebuggerServer(
+        IDebuggerSession session,
+        DebuggerServerOptions? options = null,
+        Func<IDebugProtocol>? protocolFactory = null)
+    {
+        _session = session ?? throw new ArgumentNullException(nameof(session));
+        _options = options ?? new DebuggerServerOptions();
+        _protocolFactory = protocolFactory ?? (static () => new JsonLineDebugProtocol());
+    }
+
+    public bool IsListening => _listener is not null;
+
+    public IPEndPoint? Endpoint { get; private set; }
+
+    public void Start()
+    {
+        if (_listener is not null)
+        {
+            return;
+        }
+
+        var listener = new TcpListener(_options.BindAddress, _options.Port);
+        listener.Start(_options.MaxClients);
+        _listener = listener;
+        Endpoint = (IPEndPoint?)listener.LocalEndpoint;
+        Log.Info($"Debug server listening on {Endpoint} (protocol {_protocolFactory().Name})");
+        _acceptLoop = Task.Run(() => AcceptLoopAsync(listener, _shutdown.Token));
+    }
+
+    private async Task AcceptLoopAsync(TcpListener listener, CancellationToken cancellationToken)
+    {
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            TcpClient client;
+            try
+            {
+                client = await listener.AcceptTcpClientAsync(cancellationToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+            catch (SocketException) when (cancellationToken.IsCancellationRequested)
+            {
+                break;
+            }
+            catch (ObjectDisposedException)
+            {
+                break;
+            }
+
+            var connection = new DebuggerClientConnection(client, _session, _protocolFactory());
+            var task = Task.Run(() => ServeAsync(connection, cancellationToken), cancellationToken);
+            _connections[connection] = task;
+        }
+    }
+
+    private async Task ServeAsync(DebuggerClientConnection connection, CancellationToken cancellationToken)
+    {
+        try
+        {
+            await connection.RunAsync(cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            _connections.TryRemove(connection, out _);
+            await connection.DisposeAsync().ConfigureAwait(false);
+        }
+    }
+
+    public async Task StopAsync()
+    {
+        if (_listener is null)
+        {
+            return;
+        }
+
+        await _shutdown.CancelAsync().ConfigureAwait(false);
+        _listener.Stop();
+        _listener = null;
+
+        try
+        {
+            if (_acceptLoop is not null)
+            {
+                await _acceptLoop.ConfigureAwait(false);
+            }
+
+            await Task.WhenAll(_connections.Values).ConfigureAwait(false);
+        }
+        catch (Exception ex) when (ex is OperationCanceledException or SocketException or ObjectDisposedException)
+        {
+            // Expected while tearing connections down.
+        }
+
+        _connections.Clear();
+        Log.Info("Debug server stopped.");
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await StopAsync().ConfigureAwait(false);
+        _shutdown.Dispose();
+    }
+}

src/SharpEmu.Debugger/Server/DebuggerServerOptions.cs

@@ -0,0 +1,78 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net;
+
+namespace SharpEmu.Debugger.Server;
+
+/// <summary>Network configuration for a <see cref="DebuggerServer"/>.</summary>
+public sealed class DebuggerServerOptions
+{
+    /// <summary>The default TCP port the debug server listens on.</summary>
+    public const int DefaultPort = 5714;
+
+    /// <summary>
+    /// The address to bind. Defaults to loopback so the debug surface is not
+    /// exposed off-box; a caller must opt in to a routable address explicitly.
+    /// </summary>
+    public IPAddress BindAddress { get; init; } = IPAddress.Loopback;
+
+    /// <summary>The TCP port to listen on.</summary>
+    public int Port { get; init; } = DefaultPort;
+
+    /// <summary>
+    /// The maximum number of simultaneous client connections. Additional
+    /// connections wait in the accept backlog.
+    /// </summary>
+    public int MaxClients { get; init; } = 4;
+
+    /// <summary>
+    /// Parses a <c>host:port</c>, bare <c>port</c>, or bare host into options.
+    /// Returns false when the text cannot be interpreted.
+    /// </summary>
+    public static bool TryParseEndpoint(string? text, out DebuggerServerOptions options, out string error)
+    {
+        options = new DebuggerServerOptions();
+        error = string.Empty;
+        if (string.IsNullOrWhiteSpace(text))
+        {
+            return true;
+        }
+
+        var value = text.Trim();
+        var host = value;
+        var port = DefaultPort;
+
+        var separator = value.LastIndexOf(':');
+        if (separator >= 0)
+        {
+            var portText = value[(separator + 1)..];
+            if (portText.Length > 0)
+            {
+                if (!int.TryParse(portText, out port) || port is <= 0 or > 65535)
+                {
+                    error = $"Invalid port '{portText}'.";
+                    return false;
+                }
+            }
+
+            host = value[..separator];
+        }
+
+        var address = IPAddress.Loopback;
+        if (!string.IsNullOrWhiteSpace(host) &&
+            !string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) &&
+            !IPAddress.TryParse(host, out address!))
+        {
+            error = $"Invalid bind address '{host}'.";
+            return false;
+        }
+
+        options = new DebuggerServerOptions
+        {
+            BindAddress = address ?? IPAddress.Loopback,
+            Port = port,
+        };
+        return true;
+    }
+}

src/SharpEmu.Debugger/Server/IDebuggerServer.cs

@@ -0,0 +1,24 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Net;
+
+namespace SharpEmu.Debugger.Server;
+
+/// <summary>
+/// A network front-end that exposes a debugger session to remote clients.
+/// </summary>
+public interface IDebuggerServer : IAsyncDisposable
+{
+    /// <summary>True once the listener is accepting connections.</summary>
+    bool IsListening { get; }
+
+    /// <summary>The endpoint the server is bound to, or null before start.</summary>
+    IPEndPoint? Endpoint { get; }
+
+    /// <summary>Binds and begins accepting client connections.</summary>
+    void Start();
+
+    /// <summary>Stops accepting connections and closes active clients.</summary>
+    Task StopAsync();
+}

src/SharpEmu.Debugger/Session/DebugStopEvent.cs

@@ -0,0 +1,69 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.Core.Cpu.Debugging;
+using SharpEmu.Debugger.Breakpoints;
+using SharpEmu.HLE;
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>
+/// Describes a stop delivered to debugger clients: why the target stopped,
+/// where, and the register snapshot at that point.
+/// </summary>
+public sealed class DebugStopEvent
+{
+    public DebugStopEvent(
+        DebugStopReason reason,
+        DebugRegisterFile registers,
+        CpuDebugFrameKind frameKind,
+        string frameLabel,
+        Breakpoint? breakpoint = null,
+        OrbisGen2Result? result = null,
+        string? detail = null,
+        string? opcodeBytes = null,
+        CpuStallInfo? stallInfo = null)
+    {
+        Reason = reason;
+        Registers = registers;
+        FrameKind = frameKind;
+        FrameLabel = frameLabel ?? string.Empty;
+        Breakpoint = breakpoint;
+        Result = result;
+        Detail = detail;
+        OpcodeBytes = opcodeBytes;
+        StallInfo = stallInfo;
+    }
+
+    public DebugStopReason Reason { get; }
+
+    /// <summary>The instruction pointer where the target stopped.</summary>
+    public ulong Address => Registers.Rip;
+
+    public DebugRegisterFile Registers { get; }
+
+    public CpuDebugFrameKind FrameKind { get; }
+
+    public string FrameLabel { get; }
+
+    /// <summary>The breakpoint responsible for the stop, when applicable.</summary>
+    public Breakpoint? Breakpoint { get; }
+
+    /// <summary>
+    /// The frame result for a <see cref="DebugStopReason.Fault"/> stop; null for
+    /// non-fault stops.
+    /// </summary>
+    public OrbisGen2Result? Result { get; }
+
+    /// <summary>A human-readable summary of a fault, when applicable.</summary>
+    public string? Detail { get; }
+
+    /// <summary>
+    /// A hex preview of the bytes at <see cref="Address"/> (the faulting
+    /// instruction), when the stop is a fault and the bytes were readable.
+    /// </summary>
+    public string? OpcodeBytes { get; }
+
+    /// <summary>Structured backend evidence for a stall stop.</summary>
+    public CpuStallInfo? StallInfo { get; }
+}

src/SharpEmu.Debugger/Session/DebugStopReason.cs

@@ -0,0 +1,32 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>Why the target stopped and handed control to the debugger.</summary>
+public enum DebugStopReason
+{
+    /// <summary>Stopped at the configured entry point before running any frame.</summary>
+    EntryPoint,
+
+    /// <summary>An execution breakpoint was hit.</summary>
+    Breakpoint,
+
+    /// <summary>A data watchpoint was hit.</summary>
+    Watchpoint,
+
+    /// <summary>A single-step (frame step) request completed.</summary>
+    Step,
+
+    /// <summary>A client-requested pause took effect.</summary>
+    Pause,
+
+    /// <summary>The guest raised a fault or trap.</summary>
+    Fault,
+
+    /// <summary>
+    /// The backend detected an execution stall (for example a mutex spin loop /
+    /// livelock) with no forward progress.
+    /// </summary>
+    Stall,
+}

src/SharpEmu.Debugger/Session/DebuggerRunState.cs

@@ -0,0 +1,23 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>The execution state of a debugged target as seen by the debugger.</summary>
+public enum DebuggerRunState
+{
+    /// <summary>No guest frame has entered the debugger yet.</summary>
+    Detached,
+
+    /// <summary>The guest is executing and cannot be inspected safely.</summary>
+    Running,
+
+    /// <summary>
+    /// The guest is parked at a frame boundary. Registers and memory can be
+    /// read and written, and breakpoints can be edited.
+    /// </summary>
+    Paused,
+
+    /// <summary>The guest has finished; no further frames will run.</summary>
+    Terminated,
+}

src/SharpEmu.Debugger/Session/DebuggerSession.cs

@@ -0,0 +1,425 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.Core.Cpu.Debugging;
+using SharpEmu.Debugger.Breakpoints;
+using SharpEmu.HLE;
+using SharpEmu.Logging;
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>
+/// The default <see cref="IDebuggerSession"/>. It plugs into the CPU dispatcher
+/// as an <see cref="ICpuDebugHook"/>: when a frame boundary warrants a stop it
+/// parks the emulation thread inside <see cref="ICpuDebugHook.OnFrameEnter"/>
+/// while a debug client inspects and edits state, then releases it on
+/// continue/step.
+/// </summary>
+/// <remarks>
+/// Pausing works by blocking the emulation thread on <see cref="_resumeGate"/>
+/// from within the hook call. Because that thread is the one that owns the guest
+/// context, register and memory accessors are safe to serve from other threads
+/// only while it is parked — which is exactly the <see cref="DebuggerRunState.Paused"/>
+/// window the accessors gate on.
+/// </remarks>
+public sealed class DebuggerSession : IDebuggerSession, ICpuDebugHook
+{
+    private static readonly SharpEmuLogger Log = SharpEmuLog.For("SharpEmu.Debugger");
+
+    private readonly object _sync = new();
+    private readonly ManualResetEventSlim _resumeGate = new(initialState: false);
+    private readonly DebuggerSessionOptions _options;
+
+    private ICpuDebugFrame? _currentFrame;
+    private DebuggerRunState _state = DebuggerRunState.Detached;
+    private DebugStopEvent? _lastStop;
+    private bool _seenFirstFrame;
+    private bool _pausePending;
+    private bool _stepPending;
+
+    public DebuggerSession(DebuggerSessionOptions? options = null)
+    {
+        _options = options ?? new DebuggerSessionOptions();
+        Breakpoints = new BreakpointStore();
+    }
+
+    public BreakpointStore Breakpoints { get; }
+
+    public ICpuDebugHook Hook => this;
+
+    public event EventHandler<DebugStopEvent>? Stopped;
+
+    public event EventHandler? Resumed;
+
+    public event EventHandler? Terminated;
+
+    public DebuggerRunState State
+    {
+        get
+        {
+            lock (_sync)
+            {
+                return _state;
+            }
+        }
+    }
+
+    public DebugStopEvent? LastStop
+    {
+        get
+        {
+            lock (_sync)
+            {
+                return _lastStop;
+            }
+        }
+    }
+
+    void ICpuDebugHook.OnFrameEnter(ICpuDebugFrame frame)
+    {
+        DebugStopEvent? stop;
+        lock (_sync)
+        {
+            _currentFrame = frame;
+            var firstFrame = !_seenFirstFrame;
+            _seenFirstFrame = true;
+
+            var reason = ResolveStopReason(frame, firstFrame, out var breakpoint);
+            if (reason is null)
+            {
+                _state = DebuggerRunState.Running;
+                return;
+            }
+
+            _state = DebuggerRunState.Paused;
+            _lastStop = new DebugStopEvent(
+                reason.Value,
+                DebugRegisterFile.Capture(frame),
+                frame.Kind,
+                frame.Label,
+                breakpoint);
+            stop = _lastStop;
+            _resumeGate.Reset();
+        }
+
+        Log.Debug($"Debugger stop: {stop!.Reason} at 0x{stop.Address:X16} ({stop.FrameLabel})");
+        Stopped?.Invoke(this, stop);
+
+        // Park the emulation thread until a client resumes the target. The frame
+        // stays live and inspectable for the whole wait.
+        _resumeGate.Wait();
+
+        lock (_sync)
+        {
+            if (_state != DebuggerRunState.Terminated)
+            {
+                _state = DebuggerRunState.Running;
+            }
+        }
+
+        Resumed?.Invoke(this, EventArgs.Empty);
+    }
+
+    void ICpuDebugHook.OnFrameExit(ICpuDebugFrame frame, OrbisGen2Result result)
+    {
+        DebugStopEvent? stop = null;
+        lock (_sync)
+        {
+            if (_options.BreakOnFault &&
+                result != OrbisGen2Result.ORBIS_GEN2_OK &&
+                _state != DebuggerRunState.Terminated)
+            {
+                // Parking here keeps the post-fault frame inspectable.
+                _currentFrame = frame;
+                _state = DebuggerRunState.Paused;
+                _lastStop = BuildFaultStop(frame, result);
+                stop = _lastStop;
+                _resumeGate.Reset();
+            }
+        }
+
+        if (stop is not null)
+        {
+            Log.Debug($"Debugger fault stop: {stop.Result} at 0x{stop.Address:X16} ({stop.FrameLabel})");
+            Stopped?.Invoke(this, stop);
+            _resumeGate.Wait();
+            Resumed?.Invoke(this, EventArgs.Empty);
+        }
+
+        lock (_sync)
+        {
+            if (ReferenceEquals(_currentFrame, frame))
+            {
+                _currentFrame = null;
+            }
+
+            if (_state != DebuggerRunState.Terminated)
+            {
+                _state = DebuggerRunState.Running;
+            }
+        }
+    }
+
+    void ICpuDebugHook.OnStall(ICpuDebugFrame frame, CpuStallInfo info)
+    {
+        if (!_options.BreakOnStall)
+        {
+            return;
+        }
+
+        DebugStopEvent? stop = null;
+        lock (_sync)
+        {
+            if (_state == DebuggerRunState.Terminated)
+            {
+                return;
+            }
+
+            _currentFrame = frame;
+            _state = DebuggerRunState.Paused;
+            _lastStop = new DebugStopEvent(
+                DebugStopReason.Stall,
+                DebugRegisterFile.Capture(frame),
+                frame.Kind,
+                frame.Label,
+                breakpoint: null,
+                result: null,
+                detail: info.Detail,
+                opcodeBytes: ReadOpcodePreview(frame, info.InstructionPointer, 16),
+                stallInfo: info);
+            stop = _lastStop;
+            _resumeGate.Reset();
+        }
+
+        Log.Debug($"Debugger stall stop: {info.Kind} nid={info.Nid} at 0x{info.InstructionPointer:X16}");
+        Stopped?.Invoke(this, stop);
+        _resumeGate.Wait();
+
+        lock (_sync)
+        {
+            if (ReferenceEquals(_currentFrame, frame))
+            {
+                _currentFrame = null;
+            }
+
+            if (_state != DebuggerRunState.Terminated)
+            {
+                _state = DebuggerRunState.Running;
+            }
+        }
+
+        Resumed?.Invoke(this, EventArgs.Empty);
+    }
+
+    private static DebugStopEvent BuildFaultStop(ICpuDebugFrame frame, OrbisGen2Result result)
+    {
+        var opcodeBytes = ReadOpcodePreview(frame, frame.Rip, 16);
+        var detail = $"result={result}";
+        if (opcodeBytes is not null)
+        {
+            detail += $", bytes={opcodeBytes}";
+        }
+
+        return new DebugStopEvent(
+            DebugStopReason.Fault,
+            DebugRegisterFile.Capture(frame),
+            frame.Kind,
+            frame.Label,
+            breakpoint: null,
+            result: result,
+            detail: detail,
+            opcodeBytes: opcodeBytes);
+    }
+
+    private static string? ReadOpcodePreview(ICpuDebugFrame frame, ulong address, int maxBytes)
+    {
+        Span<byte> buffer = stackalloc byte[maxBytes];
+        var count = 0;
+        for (; count < maxBytes; count++)
+        {
+            if (!frame.Memory.TryRead(address + (ulong)count, buffer.Slice(count, 1)))
+            {
+                break;
+            }
+        }
+
+        return count == 0 ? null : Convert.ToHexString(buffer[..count]);
+    }
+
+    /// <summary>
+    /// Signals that the whole guest run has finished. Releases any parked
+    /// emulation thread and moves the session to
+    /// <see cref="DebuggerRunState.Terminated"/>.
+    /// </summary>
+    public void NotifyTerminated()
+    {
+        lock (_sync)
+        {
+            _state = DebuggerRunState.Terminated;
+            _currentFrame = null;
+        }
+
+        _resumeGate.Set();
+        Terminated?.Invoke(this, EventArgs.Empty);
+    }
+
+    private DebugStopReason? ResolveStopReason(ICpuDebugFrame frame, bool firstFrame, out Breakpoint? breakpoint)
+    {
+        breakpoint = null;
+        if (_pausePending)
+        {
+            _pausePending = false;
+            return DebugStopReason.Pause;
+        }
+
+        if (_stepPending)
+        {
+            _stepPending = false;
+            return DebugStopReason.Step;
+        }
+
+        var hit = Breakpoints.FindExecuteHit(frame.EntryPoint);
+        if (hit is not null)
+        {
+            breakpoint = hit;
+            return DebugStopReason.Breakpoint;
+        }
+
+        if (_options.StopAtEntry && firstFrame)
+        {
+            return DebugStopReason.EntryPoint;
+        }
+
+        return null;
+    }
+
+    public bool TryGetRegisters(out DebugRegisterFile registers)
+    {
+        lock (_sync)
+        {
+            if (!IsPausedWithFrame(out var frame))
+            {
+                registers = default;
+                return false;
+            }
+
+            registers = DebugRegisterFile.Capture(frame);
+            return true;
+        }
+    }
+
+    public bool TrySetRegister(DebugRegisterId id, ulong value)
+    {
+        lock (_sync)
+        {
+            if (!IsPausedWithFrame(out var frame))
+            {
+                return false;
+            }
+
+            if (id.IsGeneralPurpose())
+            {
+                frame.SetRegister(id.ToCpuRegister(), value);
+                return true;
+            }
+
+            switch (id)
+            {
+                case DebugRegisterId.Rip:
+                    frame.Rip = value;
+                    return true;
+                case DebugRegisterId.Rflags:
+                    frame.Rflags = value;
+                    return true;
+                default:
+                    // FS/GS bases are owned by the TLS setup and are read-only here.
+                    return false;
+            }
+        }
+    }
+
+    public bool TryReadMemory(ulong address, Span<byte> destination)
+    {
+        lock (_sync)
+        {
+            return IsPausedWithFrame(out var frame) && frame.Memory.TryRead(address, destination);
+        }
+    }
+
+    public bool TryWriteMemory(ulong address, ReadOnlySpan<byte> source)
+    {
+        lock (_sync)
+        {
+            return IsPausedWithFrame(out var frame) && frame.Memory.TryWrite(address, source);
+        }
+    }
+
+    public bool TryReadXmm(int registerIndex, out ulong low, out ulong high)
+    {
+        lock (_sync)
+        {
+            if (!IsPausedWithFrame(out var frame) || (uint)registerIndex >= 16)
+            {
+                low = 0;
+                high = 0;
+                return false;
+            }
+
+            frame.GetXmm(registerIndex, out low, out high);
+            return true;
+        }
+    }
+
+    public bool Continue()
+    {
+        lock (_sync)
+        {
+            if (_state != DebuggerRunState.Paused)
+            {
+                return false;
+            }
+
+            _resumeGate.Set();
+            return true;
+        }
+    }
+
+    public bool StepFrame()
+    {
+        lock (_sync)
+        {
+            if (_state != DebuggerRunState.Paused)
+            {
+                return false;
+            }
+
+            _stepPending = true;
+            _resumeGate.Set();
+            return true;
+        }
+    }
+
+    public void RequestPause()
+    {
+        lock (_sync)
+        {
+            if (_state == DebuggerRunState.Running)
+            {
+                _pausePending = true;
+            }
+        }
+    }
+
+    private bool IsPausedWithFrame(out ICpuDebugFrame frame)
+    {
+        // Callers must hold _sync.
+        if (_state == DebuggerRunState.Paused && _currentFrame is not null)
+        {
+            frame = _currentFrame;
+            return true;
+        }
+
+        frame = null!;
+        return false;
+    }
+}

src/SharpEmu.Debugger/Session/DebuggerSessionOptions.cs

@@ -0,0 +1,31 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>Configuration for a <see cref="DebuggerSession"/>.</summary>
+public sealed class DebuggerSessionOptions
+{
+    /// <summary>
+    /// When true, the session pauses at the first frame it observes so a client
+    /// can attach breakpoints before the guest runs. Defaults to true, matching
+    /// the "stop at entry" behaviour most debuggers expose.
+    /// </summary>
+    public bool StopAtEntry { get; init; } = true;
+
+    /// <summary>
+    /// When true, the session pauses when a frame ends with a non-OK result (a
+    /// CPU trap, memory fault, or unimplemented path) so a client can inspect the
+    /// post-fault register/memory state before the frame is torn down. Defaults
+    /// to true. The stop reports <see cref="DebugStopReason.Fault"/>.
+    /// </summary>
+    public bool BreakOnFault { get; init; } = true;
+
+    /// <summary>
+    /// When true, the session pauses when the backend detects an execution stall
+    /// (a mutex spin loop / livelock) before the guest is forced out of the loop,
+    /// so a client can inspect the stalled state. Defaults to true. The stop
+    /// reports <see cref="DebugStopReason.Stall"/>.
+    /// </summary>
+    public bool BreakOnStall { get; init; } = true;
+}

src/SharpEmu.Debugger/Session/IDebugTarget.cs

@@ -0,0 +1,51 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>
+/// The inspection and control surface a debugger front-end (for example a
+/// network server) drives. Register and memory accessors succeed only while the
+/// target is <see cref="DebuggerRunState.Paused"/>; they return <c>false</c>
+/// otherwise so callers never read torn state from a running guest.
+/// </summary>
+public interface IDebugTarget
+{
+    /// <summary>The current execution state.</summary>
+    DebuggerRunState State { get; }
+
+    /// <summary>The most recent stop, or null if the target has not stopped yet.</summary>
+    DebugStopEvent? LastStop { get; }
+
+    /// <summary>Reads the integer register file. Fails unless paused.</summary>
+    bool TryGetRegisters(out DebugRegisterFile registers);
+
+    /// <summary>Writes a single register. Fails unless paused.</summary>
+    bool TrySetRegister(DebugRegisterId id, ulong value);
+
+    /// <summary>Reads guest memory into <paramref name="destination"/>. Fails unless paused.</summary>
+    bool TryReadMemory(ulong address, Span<byte> destination);
+
+    /// <summary>Writes guest memory from <paramref name="source"/>. Fails unless paused.</summary>
+    bool TryWriteMemory(ulong address, ReadOnlySpan<byte> source);
+
+    /// <summary>Reads a 128-bit XMM register. Fails unless paused.</summary>
+    bool TryReadXmm(int registerIndex, out ulong low, out ulong high);
+
+    /// <summary>
+    /// Resumes a paused target. Returns false when the target was not paused.
+    /// </summary>
+    bool Continue();
+
+    /// <summary>
+    /// Resumes a paused target and stops again at the next frame boundary.
+    /// Returns false when the target was not paused.
+    /// </summary>
+    bool StepFrame();
+
+    /// <summary>
+    /// Requests that a running target stop at the next frame boundary. Has no
+    /// effect if the target is already paused or terminated.
+    /// </summary>
+    void RequestPause();
+}

src/SharpEmu.Debugger/Session/IDebuggerSession.cs

@@ -0,0 +1,43 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.Core.Cpu.Debugging;
+using SharpEmu.Debugger.Breakpoints;
+
+namespace SharpEmu.Debugger.Session;
+
+/// <summary>
+/// The debugger's coordination point. It bridges the CPU dispatcher seam
+/// (<see cref="Hook"/>) to the inspection surface (<see cref="IDebugTarget"/>),
+/// owns breakpoint state, and raises lifecycle events that a server relays to
+/// connected clients.
+/// </summary>
+public interface IDebuggerSession : IDebugTarget
+{
+    /// <summary>The breakpoints armed for this session.</summary>
+    BreakpointStore Breakpoints { get; }
+
+    /// <summary>
+    /// The dispatcher-facing hook. Assign this to
+    /// <c>SharpEmuRuntimeOptions.DebugHook</c> so guest frames are routed through
+    /// the session.
+    /// </summary>
+    ICpuDebugHook Hook { get; }
+
+    /// <summary>Raised on the emulation thread each time the target stops.</summary>
+    event EventHandler<DebugStopEvent>? Stopped;
+
+    /// <summary>Raised when a paused target resumes.</summary>
+    event EventHandler? Resumed;
+
+    /// <summary>Raised once the target has terminated.</summary>
+    event EventHandler? Terminated;
+
+    /// <summary>
+    /// Signals that the guest run has finished. Releases any parked emulation
+    /// thread and transitions the session to
+    /// <see cref="DebuggerRunState.Terminated"/>. Hosts call this after the
+    /// runtime returns.
+    /// </summary>
+    void NotifyTerminated();
+}

src/SharpEmu.Debugger/SharpEmu.Debugger.csproj

@@ -0,0 +1,16 @@
+<!--
+Copyright (C) 2026 SharpEmu Emulator Project
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <ProjectReference Include="..\SharpEmu.Core\SharpEmu.Core.csproj" />
+    <ProjectReference Include="..\SharpEmu.HLE\SharpEmu.HLE.csproj" />
+    <ProjectReference Include="..\SharpEmu.Logging\SharpEmu.Logging.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+</Project>

src/SharpEmu.GUI/App.axaml

@@ -5,6 +5,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
 
 <Application xmlns="https://github.com/avaloniaui"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             xmlns:local="clr-namespace:SharpEmu.GUI"
              x:Class="SharpEmu.GUI.App"
              RequestedThemeVariant="Dark">
 
@@ -29,8 +30,32 @@ SPDX-License-Identifier: GPL-2.0-or-later
     <SolidColorBrush x:Key="DangerBrush" Color="#E5484D" />
     <SolidColorBrush x:Key="DangerHoverBrush" Color="#F2555A" />
     <SolidColorBrush x:Key="SuccessBrush" Color="#46C46B" />
+    <SolidColorBrush x:Key="InfoBrush" Color="#58A6FF" />
     <SolidColorBrush x:Key="TileHoverBrush" Color="#1A2130" />
     <SolidColorBrush x:Key="TileSelectedBrush" Color="#212A3F" />
+
+    <ControlTheme x:Key="{x:Type local:SettingRow}" TargetType="local:SettingRow">
+      <Setter Property="Template">
+        <ControlTemplate>
+          <Grid ColumnDefinitions="*,Auto">
+            <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
+              <TextBlock x:Name="PART_Label" Text="{TemplateBinding Label}" FontSize="13" />
+              <TextBlock Text="{TemplateBinding Description}" FontSize="11"
+                         Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap"
+                         IsVisible="{Binding Description, RelativeSource={RelativeSource TemplatedParent},
+                                     Converter={x:Static StringConverters.IsNotNullOrEmpty}}" />
+            </StackPanel>
+            <StackPanel Grid.Column="1" Orientation="Horizontal" Spacing="10" VerticalAlignment="Center">
+              <ToggleSwitch OnContent="Override" OffContent="Override" MinWidth="0"
+                            VerticalAlignment="Center"
+                            IsVisible="{TemplateBinding ShowOverride}"
+                            IsChecked="{Binding IsOverridden, RelativeSource={RelativeSource TemplatedParent}, Mode=TwoWay}" />
+              <ContentPresenter x:Name="PART_Slot" Content="{TemplateBinding Content}" VerticalAlignment="Center" />
+            </StackPanel>
+          </Grid>
+        </ControlTemplate>
+      </Setter>
+    </ControlTheme>
   </Application.Resources>
 
   <Application.Styles>
@@ -55,6 +80,22 @@ SPDX-License-Identifier: GPL-2.0-or-later
       <Setter Property="Padding" Value="10,3" />
     </Style>
 
+    <!-- Session status/hotkey badges: the title-id pill geometry with a
+         tinted fill so state (RUNNING) and keys (F11) read at a glance. -->
+    <Style Selector="Border.badge">
+      <Setter Property="CornerRadius" Value="999" />
+      <Setter Property="Padding" Value="8,2" />
+      <Setter Property="BorderThickness" Value="1" />
+    </Style>
+    <Style Selector="Border.badge.running">
+      <Setter Property="Background" Value="#1E46C46B" />
+      <Setter Property="BorderBrush" Value="#5546C46B" />
+    </Style>
+    <Style Selector="Border.badge.key">
+      <Setter Property="Background" Value="#1E58A6FF" />
+      <Setter Property="BorderBrush" Value="#5558A6FF" />
+    </Style>
+
     <Style Selector="TextBlock.sectionTitle">
       <Setter Property="FontSize" Value="11" />
       <Setter Property="FontWeight" Value="SemiBold" />

src/SharpEmu.GUI/EmulatorProcess.cs

@@ -1,7 +1,6 @@
 // Copyright (C) 2026 SharpEmu Emulator Project
 // SPDX-License-Identifier: GPL-2.0-or-later
 
-using System.ComponentModel;
 using System.Diagnostics;
 using System.Runtime.InteropServices;
 using System.Text;
@@ -10,32 +9,36 @@ using Microsoft.Win32.SafeHandles;
 namespace SharpEmu.GUI;
 
 /// <summary>
-/// Launches the SharpEmu CLI as a child process with the same CET/CFG mitigation
-/// opt-outs the CLI would apply to its own relaunched child, while capturing
-/// stdout/stderr through pipes. The CLI's internal relaunch is suppressed via
-/// SHARPEMU_DISABLE_MITIGATION_RELAUNCH so output is not lost to a detached
-/// console. A kill-on-close job object ties the emulator's lifetime to the GUI.
+/// Owns an isolated emulator process. Guest virtual memory is fixed-address and
+/// cannot be reliably reused while guest-created host threads are still alive,
+/// so the GUI must never execute a game in its own process.
 /// </summary>
 internal sealed class EmulatorProcess : IDisposable
 {
-    private const uint EXTENDED_STARTUPINFO_PRESENT = 0x00080000;
-    private const uint CREATE_NO_WINDOW = 0x08000000;
-    private const int STARTF_USESTDHANDLES = 0x00000100;
-    private const uint HANDLE_FLAG_INHERIT = 0x00000001;
-    private const uint INFINITE = 0xFFFFFFFF;
-    private const int PROC_THREAD_ATTRIBUTE_MITIGATION_POLICY = 0x00020007;
-    private const uint JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000;
-    private const int JobObjectExtendedLimitInformation = 9;
-    private const ulong PROCESS_CREATION_MITIGATION_POLICY_CONTROL_FLOW_GUARD_ALWAYS_OFF = 0x00000002UL << 40;
-    private const ulong PROCESS_CREATION_MITIGATION_POLICY2_CET_USER_SHADOW_STACKS_ALWAYS_OFF = 0x00000002UL << 28;
-    private const ulong PROCESS_CREATION_MITIGATION_POLICY2_USER_CET_SET_CONTEXT_IP_VALIDATION_ALWAYS_OFF = 0x00000002UL << 32;
-    private const ulong PROCESS_CREATION_MITIGATION_POLICY2_XTENDED_CONTROL_FLOW_GUARD_ALWAYS_OFF = 0x00000002UL << 40;
+    public const int HostStopExitCode = -2;
+
+    private const uint ExtendedStartupInfoPresent = 0x00080000;
+    private const uint CreateNoWindow = 0x08000000;
+    private const int StartfUseStdHandles = 0x00000100;
+    private const uint HandleFlagInherit = 0x00000001;
+    private const uint Infinite = 0xFFFFFFFF;
+    private const int ProcThreadAttributeMitigationPolicy = 0x00020007;
+    private const uint JobObjectLimitKillOnJobClose = 0x00002000;
+    private const int JobObjectExtendedLimitInformationClass = 9;
+    private const string MitigatedChildFlag = "--sharpemu-mitigated-child";
+    private const string MitigatedChildEnvironment = "SHARPEMU_MITIGATED_CHILD";
+    private const ulong ControlFlowGuardAlwaysOff = 0x00000002UL << 40;
+    private const ulong CetUserShadowStacksAlwaysOff = 0x00000002UL << 28;
+    private const ulong UserCetSetContextIpValidationAlwaysOff = 0x00000002UL << 32;
+
+    private static readonly object EnvironmentGate = new();
 
     private readonly object _sync = new();
     private nint _processHandle;
     private nint _jobHandle;
     private Process? _fallbackProcess;
     private bool _running;
+    private bool _stopRequested;
     private bool _disposed;
 
     public event Action<string, bool>? OutputReceived;
@@ -55,29 +58,34 @@ internal sealed class EmulatorProcess : IDisposable
 
     public void Start(string exePath, IReadOnlyList<string> arguments, string? workingDirectory)
     {
+        ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
+        ArgumentNullException.ThrowIfNull(arguments);
+
         lock (_sync)
         {
-            ObjectDisposedException.ThrowIf(_disposed, this);
+            ThrowIfDisposed();
             if (_running)
             {
                 throw new InvalidOperationException("The emulator process is already running.");
             }
 
-            if (OperatingSystem.IsWindows())
-            {
-                StartWindows(exePath, arguments, workingDirectory);
-            }
-            else
-            {
-                StartFallback(exePath, arguments, workingDirectory);
-            }
-
-            _running = true;
+            _stopRequested = false;
         }
+
+        if (OperatingSystem.IsWindows())
+        {
+            StartWindows(exePath, arguments, workingDirectory);
+            return;
+        }
+
+        StartFallback(exePath, arguments, workingDirectory);
     }
 
     public void Stop()
     {
+        nint processHandle;
+        nint jobHandle;
+        Process? fallbackProcess;
         lock (_sync)
         {
             if (!_running)
@@ -85,28 +93,35 @@ internal sealed class EmulatorProcess : IDisposable
                 return;
             }
 
-            // Prefer terminating the job: it kills the whole tree, including
-            // any children the emulator spawned, even when the main process
-            // is wedged in a GPU driver call.
-            if (_jobHandle != 0)
-            {
-                _ = TerminateJobObject(_jobHandle, 1);
-            }
+            _stopRequested = true;
+            processHandle = _processHandle;
+            jobHandle = _jobHandle;
+            fallbackProcess = _fallbackProcess;
+        }
 
-            if (_processHandle != 0)
-            {
-                _ = TerminateProcess(_processHandle, 1);
-            }
+        if (jobHandle != 0)
+        {
+            _ = TerminateJobObject(jobHandle, unchecked((uint)HostStopExitCode));
+            return;
+        }
 
-            try
+        if (processHandle != 0)
+        {
+            _ = TerminateProcess(processHandle, unchecked((uint)HostStopExitCode));
+            return;
+        }
+
+        try
+        {
+            if (fallbackProcess is { HasExited: false })
             {
-                _fallbackProcess?.Kill(entireProcessTree: true);
-            }
-            catch (InvalidOperationException)
-            {
-                // Already exited.
+                fallbackProcess.Kill(entireProcessTree: true);
             }
         }
+        catch (InvalidOperationException)
+        {
+            // The process exited while Stop was handling the request.
+        }
     }
 
     public void Dispose()
@@ -124,121 +139,206 @@ internal sealed class EmulatorProcess : IDisposable
         Stop();
     }
 
-    private void StartWindows(string exePath, IReadOnlyList<string> arguments, string? workingDirectory)
+    private void StartFallback(string exePath, IReadOnlyList<string> arguments, string? workingDirectory)
     {
-        // The CLI would otherwise relaunch itself into a mitigated child whose
-        // console output cannot flow through our pipes.
-        Environment.SetEnvironmentVariable("SHARPEMU_DISABLE_MITIGATION_RELAUNCH", "1");
-
-        var securityAttributes = new SECURITY_ATTRIBUTES
+        var startInfo = new ProcessStartInfo(exePath)
         {
-            nLength = Marshal.SizeOf<SECURITY_ATTRIBUTES>(),
-            bInheritHandle = 1,
+            WorkingDirectory = string.IsNullOrWhiteSpace(workingDirectory)
+                ? Path.GetDirectoryName(exePath) ?? Environment.CurrentDirectory
+                : workingDirectory,
+            UseShellExecute = false,
+            CreateNoWindow = true,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            StandardOutputEncoding = Encoding.UTF8,
+            StandardErrorEncoding = Encoding.UTF8,
         };
-
-        if (!CreatePipe(out var stdoutRead, out var stdoutWrite, ref securityAttributes, 0) ||
-            !CreatePipe(out var stderrRead, out var stderrWrite, ref securityAttributes, 0))
+        foreach (var argument in arguments)
         {
-            throw new Win32Exception(Marshal.GetLastWin32Error(), "Failed to create output pipes.");
+            startInfo.ArgumentList.Add(argument);
         }
 
-        _ = SetHandleInformation(stdoutRead, HANDLE_FLAG_INHERIT, 0);
-        _ = SetHandleInformation(stderrRead, HANDLE_FLAG_INHERIT, 0);
+        var process = Process.Start(startInfo)
+            ?? throw new InvalidOperationException("Could not start the emulator process.");
+        process.EnableRaisingEvents = true;
+        process.OutputDataReceived += (_, eventArgs) => ForwardOutput(eventArgs.Data, isError: false);
+        process.ErrorDataReceived += (_, eventArgs) => ForwardOutput(eventArgs.Data, isError: true);
+        process.Exited += (_, _) => OnExited(process.ExitCode);
 
-        var startupInfoEx = new STARTUPINFOEX();
-        startupInfoEx.StartupInfo.cb = Marshal.SizeOf<STARTUPINFOEX>();
-        startupInfoEx.StartupInfo.dwFlags = STARTF_USESTDHANDLES;
-        startupInfoEx.StartupInfo.hStdOutput = stdoutWrite;
-        startupInfoEx.StartupInfo.hStdError = stderrWrite;
+        lock (_sync)
+        {
+            _fallbackProcess = process;
+            _running = true;
+        }
 
+        process.BeginOutputReadLine();
+        process.BeginErrorReadLine();
+    }
+
+    private unsafe void StartWindows(string exePath, IReadOnlyList<string> arguments, string? workingDirectory)
+    {
+        nint stdoutRead = 0;
+        nint stdoutWrite = 0;
+        nint stderrRead = 0;
+        nint stderrWrite = 0;
         nint attributeList = 0;
         nint mitigationPolicies = 0;
+        nint processHandle = 0;
+        nint threadHandle = 0;
+
         try
         {
+            var security = new SecurityAttributes
+            {
+                Size = Marshal.SizeOf<SecurityAttributes>(),
+                InheritHandle = 1,
+            };
+            if (!CreatePipe(out stdoutRead, out stdoutWrite, ref security, 0) ||
+                !CreatePipe(out stderrRead, out stderrWrite, ref security, 0))
+            {
+                throw new InvalidOperationException($"Could not create emulator output pipes (Win32 error {Marshal.GetLastWin32Error()}).");
+            }
+
+            if (!SetHandleInformation(stdoutRead, HandleFlagInherit, 0) ||
+                !SetHandleInformation(stderrRead, HandleFlagInherit, 0))
+            {
+                throw new InvalidOperationException($"Could not configure emulator output pipes (Win32 error {Marshal.GetLastWin32Error()}).");
+            }
+
             nuint attributeListSize = 0;
             _ = InitializeProcThreadAttributeList(0, 1, 0, ref attributeListSize);
             attributeList = Marshal.AllocHGlobal((nint)attributeListSize);
             if (!InitializeProcThreadAttributeList(attributeList, 1, 0, ref attributeListSize))
             {
-                throw new Win32Exception(Marshal.GetLastWin32Error(), "Failed to initialize the process attribute list.");
+                throw new InvalidOperationException($"Could not initialize process mitigation attributes (Win32 error {Marshal.GetLastWin32Error()}).");
             }
 
-            startupInfoEx.lpAttributeList = attributeList;
-
-            var policy1 = PROCESS_CREATION_MITIGATION_POLICY_CONTROL_FLOW_GUARD_ALWAYS_OFF;
-            var policy2 =
-                PROCESS_CREATION_MITIGATION_POLICY2_CET_USER_SHADOW_STACKS_ALWAYS_OFF |
-                PROCESS_CREATION_MITIGATION_POLICY2_USER_CET_SET_CONTEXT_IP_VALIDATION_ALWAYS_OFF;
-
             mitigationPolicies = Marshal.AllocHGlobal(sizeof(ulong) * 2);
-            Marshal.WriteInt64(mitigationPolicies, unchecked((long)policy1));
-            Marshal.WriteInt64(nint.Add(mitigationPolicies, sizeof(long)), unchecked((long)policy2));
-
+            Marshal.WriteInt64(mitigationPolicies, unchecked((long)ControlFlowGuardAlwaysOff));
+            Marshal.WriteInt64(
+                nint.Add(mitigationPolicies, sizeof(long)),
+                unchecked((long)(CetUserShadowStacksAlwaysOff | UserCetSetContextIpValidationAlwaysOff)));
             if (!UpdateProcThreadAttribute(
-                attributeList,
-                0,
-                PROC_THREAD_ATTRIBUTE_MITIGATION_POLICY,
-                mitigationPolicies,
-                (nuint)(sizeof(ulong) * 2),
-                0,
-                0))
+                    attributeList,
+                    0,
+                    (nint)ProcThreadAttributeMitigationPolicy,
+                    mitigationPolicies,
+                    (nuint)(sizeof(ulong) * 2),
+                    0,
+                    0))
             {
-                throw new Win32Exception(Marshal.GetLastWin32Error(), "Failed to apply the mitigation policy.");
+                throw new InvalidOperationException($"Could not apply process mitigations (Win32 error {Marshal.GetLastWin32Error()}).");
             }
 
-            var currentDirectory = workingDirectory ?? Environment.CurrentDirectory;
-            var created = CreateProcessW(
-                exePath,
-                new StringBuilder(BuildCommandLine(exePath, arguments)),
-                0,
-                0,
-                true,
-                EXTENDED_STARTUPINFO_PRESENT | CREATE_NO_WINDOW,
-                0,
-                currentDirectory,
-                ref startupInfoEx,
-                out var processInfo);
+            var startup = new StartupInfoEx();
+            startup.StartupInfo.Size = Marshal.SizeOf<StartupInfoEx>();
+            startup.StartupInfo.Flags = StartfUseStdHandles;
+            startup.StartupInfo.StdOutput = stdoutWrite;
+            startup.StartupInfo.StdError = stderrWrite;
+            startup.AttributeList = attributeList;
 
-            if (!created)
+            var childArguments = new List<string>(arguments.Count + 1) { MitigatedChildFlag };
+            childArguments.AddRange(arguments);
+            var commandLine = new StringBuilder(BuildCommandLine(exePath, childArguments));
+            ProcessInformation processInfo;
+            lock (EnvironmentGate)
             {
-                var error = Marshal.GetLastWin32Error();
-                throw new Win32Exception(error, $"Failed to start '{exePath}' with CET/CFG mitigation disabled (Win32 error {error}: {new Win32Exception(error).Message}).");
+                var previousValue = Environment.GetEnvironmentVariable(MitigatedChildEnvironment);
+                try
+                {
+                    Environment.SetEnvironmentVariable(MitigatedChildEnvironment, "1");
+                    if (!CreateProcessW(
+                            exePath,
+                            commandLine,
+                            0,
+                            0,
+                            true,
+                            ExtendedStartupInfoPresent | CreateNoWindow,
+                            0,
+                            string.IsNullOrWhiteSpace(workingDirectory)
+                                ? Path.GetDirectoryName(exePath) ?? Environment.CurrentDirectory
+                                : workingDirectory,
+                            ref startup,
+                            out processInfo))
+                    {
+                        throw new InvalidOperationException($"Could not start the emulator process (Win32 error {Marshal.GetLastWin32Error()}).");
+                    }
+                }
+                finally
+                {
+                    Environment.SetEnvironmentVariable(MitigatedChildEnvironment, previousValue);
+                }
             }
 
-            CloseHandle(processInfo.hThread);
-            _processHandle = processInfo.hProcess;
+            processHandle = processInfo.Process;
+            threadHandle = processInfo.Thread;
+            CloseHandle(stdoutWrite);
+            stdoutWrite = 0;
+            CloseHandle(stderrWrite);
+            stderrWrite = 0;
 
-            _jobHandle = CreateJobObjectW(0, null);
-            if (_jobHandle != 0 &&
-                (!TryEnableKillOnJobClose(_jobHandle) || !AssignProcessToJobObject(_jobHandle, processInfo.hProcess)))
+            var jobHandle = CreateJobObjectW(0, null);
+            if (jobHandle != 0 &&
+                (!TryEnableKillOnJobClose(jobHandle) || !AssignProcessToJobObject(jobHandle, processHandle)))
             {
-                CloseHandle(_jobHandle);
-                _jobHandle = 0;
+                CloseHandle(jobHandle);
+                jobHandle = 0;
             }
 
-            StartReaderThread(stdoutRead, isError: false);
-            StartReaderThread(stderrRead, isError: true);
-            StartExitWatcherThread();
+            lock (_sync)
+            {
+                _processHandle = processHandle;
+                _jobHandle = jobHandle;
+                _running = true;
+            }
+            processHandle = 0;
+
+            StartPipeReader(stdoutRead, isError: false);
+            stdoutRead = 0;
+            StartPipeReader(stderrRead, isError: true);
+            stderrRead = 0;
+            StartWindowsExitWatcher(_processHandle);
         }
         catch
         {
-            CloseHandle(stdoutRead);
-            CloseHandle(stderrRead);
+            if (processHandle != 0)
+            {
+                _ = TerminateProcess(processHandle, 1);
+            }
+
             throw;
         }
         finally
         {
-            // The child owns duplicated pipe write ends; closing ours lets the
-            // readers observe EOF when the child exits.
-            CloseHandle(stdoutWrite);
-            CloseHandle(stderrWrite);
-
+            if (threadHandle != 0)
+            {
+                CloseHandle(threadHandle);
+            }
+            if (processHandle != 0)
+            {
+                CloseHandle(processHandle);
+            }
+            if (stdoutRead != 0)
+            {
+                CloseHandle(stdoutRead);
+            }
+            if (stdoutWrite != 0)
+            {
+                CloseHandle(stdoutWrite);
+            }
+            if (stderrRead != 0)
+            {
+                CloseHandle(stderrRead);
+            }
+            if (stderrWrite != 0)
+            {
+                CloseHandle(stderrWrite);
+            }
             if (attributeList != 0)
             {
                 DeleteProcThreadAttributeList(attributeList);
                 Marshal.FreeHGlobal(attributeList);
             }
-
             if (mitigationPolicies != 0)
             {
                 Marshal.FreeHGlobal(mitigationPolicies);
@@ -246,103 +346,56 @@ internal sealed class EmulatorProcess : IDisposable
         }
     }
 
-    private void StartFallback(string exePath, IReadOnlyList<string> arguments, string? workingDirectory)
+    private void StartPipeReader(nint handle, bool isError)
     {
-        var startInfo = new ProcessStartInfo
+        var readerThread = new Thread(() =>
         {
-            FileName = exePath,
-            WorkingDirectory = workingDirectory ?? Environment.CurrentDirectory,
-            UseShellExecute = false,
-            CreateNoWindow = true,
-            RedirectStandardOutput = true,
-            RedirectStandardError = true,
-        };
-        foreach (var argument in arguments)
-        {
-            startInfo.ArgumentList.Add(argument);
-        }
-
-        var process = new Process { StartInfo = startInfo, EnableRaisingEvents = true };
-        process.OutputDataReceived += (_, e) =>
-        {
-            if (e.Data is not null)
+            using var safeHandle = new SafeFileHandle(handle, ownsHandle: true);
+            using var stream = new FileStream(safeHandle, FileAccess.Read, 4096, isAsync: false);
+            using var reader = new StreamReader(stream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true);
+            while (reader.ReadLine() is { } line)
             {
-                OutputReceived?.Invoke(e.Data, false);
+                ForwardOutput(line, isError);
             }
-        };
-        process.ErrorDataReceived += (_, e) =>
-        {
-            if (e.Data is not null)
-            {
-                OutputReceived?.Invoke(e.Data, true);
-            }
-        };
-        process.Exited += (_, _) =>
-        {
-            int exitCode;
-            try
-            {
-                exitCode = process.ExitCode;
-            }
-            catch (InvalidOperationException)
-            {
-                exitCode = -1;
-            }
-
-            OnExited(exitCode);
-        };
-
-        process.Start();
-        process.BeginOutputReadLine();
-        process.BeginErrorReadLine();
-        _fallbackProcess = process;
-    }
-
-    private void StartReaderThread(nint readHandle, bool isError)
-    {
-        var thread = new Thread(() =>
-        {
-            using var stream = new FileStream(new SafeFileHandle(readHandle, ownsHandle: true), FileAccess.Read);
-            using var reader = new StreamReader(stream, Encoding.UTF8);
-            try
-            {
-                while (reader.ReadLine() is { } line)
-                {
-                    OutputReceived?.Invoke(line, isError);
-                }
-            }
-            catch (IOException)
-            {
-                // Pipe broken on process teardown.
-            }
-        })
+        }, 256 * 1024)
         {
             IsBackground = true,
             Name = isError ? "SharpEmu stderr reader" : "SharpEmu stdout reader",
         };
-        thread.Start();
+        readerThread.Start();
     }
 
-    private void StartExitWatcherThread()
+    private void StartWindowsExitWatcher(nint processHandle)
     {
-        var processHandle = _processHandle;
-        var thread = new Thread(() =>
+        var watcher = new Thread(() =>
         {
-            _ = WaitForSingleObject(processHandle, INFINITE);
-            var exitCode = GetExitCodeProcess(processHandle, out var rawExitCode)
-                ? unchecked((int)rawExitCode)
-                : -1;
+            _ = WaitForSingleObject(processHandle, Infinite);
+            var exitCode = 1;
+            if (GetExitCodeProcess(processHandle, out var nativeExitCode))
+            {
+                exitCode = unchecked((int)nativeExitCode);
+            }
+
             OnExited(exitCode);
-        })
+        }, 128 * 1024)
         {
             IsBackground = true,
             Name = "SharpEmu exit watcher",
         };
-        thread.Start();
+        watcher.Start();
     }
 
-    private void OnExited(int exitCode)
+    private void ForwardOutput(string? line, bool isError)
     {
+        if (!string.IsNullOrEmpty(line))
+        {
+            OutputReceived?.Invoke(line, isError);
+        }
+    }
+
+    private void OnExited(int nativeExitCode)
+    {
+        int exitCode;
         lock (_sync)
         {
             if (!_running)
@@ -350,13 +403,13 @@ internal sealed class EmulatorProcess : IDisposable
                 return;
             }
 
+            exitCode = _stopRequested ? HostStopExitCode : nativeExitCode;
             _running = false;
             if (_processHandle != 0)
             {
                 CloseHandle(_processHandle);
                 _processHandle = 0;
             }
-
             if (_jobHandle != 0)
             {
                 CloseHandle(_jobHandle);
@@ -372,24 +425,19 @@ internal sealed class EmulatorProcess : IDisposable
 
     private static bool TryEnableKillOnJobClose(nint jobHandle)
     {
-        var extendedLimitInfo = new JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+        var info = new JobObjectExtendedLimitInformation
         {
-            BasicLimitInformation = new JOBOBJECT_BASIC_LIMIT_INFORMATION
+            BasicLimitInformation = new JobObjectBasicLimitInformation
             {
-                LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+                LimitFlags = JobObjectLimitKillOnJobClose,
             },
         };
-
-        var size = Marshal.SizeOf<JOBOBJECT_EXTENDED_LIMIT_INFORMATION>();
+        var size = Marshal.SizeOf<JobObjectExtendedLimitInformation>();
         var memory = Marshal.AllocHGlobal(size);
         try
         {
-            Marshal.StructureToPtr(extendedLimitInfo, memory, false);
-            return SetInformationJobObject(
-                jobHandle,
-                JobObjectExtendedLimitInformation,
-                memory,
-                unchecked((uint)size));
+            Marshal.StructureToPtr(info, memory, false);
+            return SetInformationJobObject(jobHandle, JobObjectExtendedLimitInformationClass, memory, unchecked((uint)size));
         }
         finally
         {
@@ -397,128 +445,124 @@ internal sealed class EmulatorProcess : IDisposable
         }
     }
 
-    private static string BuildCommandLine(string processPath, IReadOnlyList<string> args)
+    private static string BuildCommandLine(string processPath, IReadOnlyList<string> arguments)
     {
-        var builder = new StringBuilder();
-        builder.Append(QuoteArgument(processPath));
-        for (var i = 0; i < args.Count; i++)
+        var builder = new StringBuilder(QuoteArgument(processPath));
+        foreach (var argument in arguments)
         {
             builder.Append(' ');
-            builder.Append(QuoteArgument(args[i]));
+            builder.Append(QuoteArgument(argument));
         }
 
         return builder.ToString();
     }
 
-    private static string QuoteArgument(string argument)
+    private static string QuoteArgument(string value)
     {
-        if (argument.Length == 0)
+        if (value.Length == 0)
         {
             return "\"\"";
         }
 
-        var needsQuotes = false;
-        foreach (var c in argument)
+        if (!value.Any(static c => char.IsWhiteSpace(c) || c == '"'))
         {
-            if (char.IsWhiteSpace(c) || c == '"')
-            {
-                needsQuotes = true;
-                break;
-            }
+            return value;
         }
 
-        if (!needsQuotes)
-        {
-            return argument;
-        }
-
-        var builder = new StringBuilder(argument.Length + 2);
+        var builder = new StringBuilder(value.Length + 2);
         builder.Append('"');
-
-        var backslashCount = 0;
-        foreach (var c in argument)
+        var slashCount = 0;
+        foreach (var character in value)
         {
-            if (c == '\\')
+            if (character == '\\')
             {
-                backslashCount++;
+                slashCount++;
                 continue;
             }
 
-            if (c == '"')
+            if (character == '"')
             {
-                builder.Append('\\', (backslashCount * 2) + 1);
-                builder.Append('"');
-                backslashCount = 0;
+                builder.Append('\\', (slashCount * 2) + 1);
+                builder.Append(character);
+                slashCount = 0;
                 continue;
             }
 
-            if (backslashCount > 0)
+            if (slashCount > 0)
             {
-                builder.Append('\\', backslashCount);
-                backslashCount = 0;
+                builder.Append('\\', slashCount);
+                slashCount = 0;
             }
 
-            builder.Append(c);
+            builder.Append(character);
         }
 
-        if (backslashCount > 0)
+        if (slashCount > 0)
         {
-            builder.Append('\\', backslashCount * 2);
+            builder.Append('\\', slashCount * 2);
         }
 
         builder.Append('"');
         return builder.ToString();
     }
 
-    [StructLayout(LayoutKind.Sequential)]
-    private struct SECURITY_ATTRIBUTES
+    private void ThrowIfDisposed()
     {
-        public int nLength;
-        public nint lpSecurityDescriptor;
-        public int bInheritHandle;
+        if (_disposed)
+        {
+            throw new ObjectDisposedException(nameof(EmulatorProcess));
+        }
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct SecurityAttributes
+    {
+        public int Size;
+        public nint SecurityDescriptor;
+        public int InheritHandle;
     }
 
     [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
-    private struct STARTUPINFO
+    private struct StartupInfo
     {
-        public int cb;
-        public nint lpReserved;
-        public nint lpDesktop;
-        public nint lpTitle;
-        public int dwX;
-        public int dwY;
-        public int dwXSize;
-        public int dwYSize;
-        public int dwXCountChars;
-        public int dwYCountChars;
-        public int dwFillAttribute;
-        public int dwFlags;
-        public short wShowWindow;
-        public short cbReserved2;
-        public nint lpReserved2;
-        public nint hStdInput;
-        public nint hStdOutput;
-        public nint hStdError;
+        public int Size;
+        public nint Reserved;
+        public nint Desktop;
+        public nint Title;
+        public int X;
+        public int Y;
+        public int XSize;
+        public int YSize;
+        public int XCountChars;
+        public int YCountChars;
+        public int FillAttribute;
+        public int Flags;
+        public short ShowWindow;
+        public short Reserved2Count;
+        public nint Reserved2;
+        public nint StdInput;
+        public nint StdOutput;
+        public nint StdError;
     }
 
     [StructLayout(LayoutKind.Sequential)]
-    private struct STARTUPINFOEX
+    private struct StartupInfoEx
     {
-        public STARTUPINFO StartupInfo;
-        public nint lpAttributeList;
+        public StartupInfo StartupInfo;
+        public nint AttributeList;
     }
 
     [StructLayout(LayoutKind.Sequential)]
-    private struct PROCESS_INFORMATION
+    private struct ProcessInformation
     {
-        public nint hProcess;
-        public nint hThread;
-        public int dwProcessId;
-        public int dwThreadId;
+        public nint Process;
+        public nint Thread;
+        public int ProcessId;
+        public int ThreadId;
     }
 
     [StructLayout(LayoutKind.Sequential)]
-    private struct JOBOBJECT_BASIC_LIMIT_INFORMATION
+    private struct JobObjectBasicLimitInformation
     {
         public long PerProcessUserTimeLimit;
         public long PerJobUserTimeLimit;
@@ -532,7 +576,7 @@ internal sealed class EmulatorProcess : IDisposable
     }
 
     [StructLayout(LayoutKind.Sequential)]
-    private struct IO_COUNTERS
+    private struct IoCounters
     {
         public ulong ReadOperationCount;
         public ulong WriteOperationCount;
@@ -543,10 +587,10 @@ internal sealed class EmulatorProcess : IDisposable
     }
 
     [StructLayout(LayoutKind.Sequential)]
-    private struct JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+    private struct JobObjectExtendedLimitInformation
     {
-        public JOBOBJECT_BASIC_LIMIT_INFORMATION BasicLimitInformation;
-        public IO_COUNTERS IoInfo;
+        public JobObjectBasicLimitInformation BasicLimitInformation;
+        public IoCounters IoInfo;
         public nuint ProcessMemoryLimit;
         public nuint JobMemoryLimit;
         public nuint PeakProcessMemoryUsed;
@@ -555,66 +599,37 @@ internal sealed class EmulatorProcess : IDisposable
 
     [DllImport("kernel32.dll", SetLastError = true)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool CreatePipe(
-        out nint hReadPipe,
-        out nint hWritePipe,
-        ref SECURITY_ATTRIBUTES lpPipeAttributes,
-        uint nSize);
+    private static extern bool CreatePipe(out nint readPipe, out nint writePipe, ref SecurityAttributes attributes, uint size);
 
     [DllImport("kernel32.dll", SetLastError = true)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool SetHandleInformation(nint hObject, uint dwMask, uint dwFlags);
+    private static extern bool SetHandleInformation(nint handle, uint mask, uint flags);
 
     [DllImport("kernel32.dll", SetLastError = true)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool InitializeProcThreadAttributeList(
-        nint lpAttributeList,
-        int dwAttributeCount,
-        int dwFlags,
-        ref nuint lpSize);
+    private static extern bool InitializeProcThreadAttributeList(nint list, int count, int flags, ref nuint size);
 
     [DllImport("kernel32.dll", SetLastError = true)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool UpdateProcThreadAttribute(
-        nint lpAttributeList,
-        uint dwFlags,
-        nint attribute,
-        nint lpValue,
-        nuint cbSize,
-        nint lpPreviousValue,
-        nint lpReturnSize);
+    private static extern bool UpdateProcThreadAttribute(nint list, uint flags, nint attribute, nint value, nuint size, nint previousValue, nint returnSize);
 
     [DllImport("kernel32.dll")]
-    private static extern void DeleteProcThreadAttributeList(nint lpAttributeList);
+    private static extern void DeleteProcThreadAttributeList(nint list);
 
     [DllImport("kernel32.dll", EntryPoint = "CreateJobObjectW", SetLastError = true, CharSet = CharSet.Unicode)]
-    private static extern nint CreateJobObjectW(nint lpJobAttributes, string? lpName);
+    private static extern nint CreateJobObjectW(nint attributes, string? name);
 
     [DllImport("kernel32.dll", SetLastError = true)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool SetInformationJobObject(
-        nint hJob,
-        int jobObjectInfoClass,
-        nint lpJobObjectInfo,
-        uint cbJobObjectInfoLength);
+    private static extern bool SetInformationJobObject(nint job, int infoClass, nint info, uint size);
 
     [DllImport("kernel32.dll", SetLastError = true)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool AssignProcessToJobObject(nint hJob, nint hProcess);
+    private static extern bool AssignProcessToJobObject(nint job, nint process);
 
     [DllImport("kernel32.dll", EntryPoint = "CreateProcessW", SetLastError = true, CharSet = CharSet.Unicode)]
     [return: MarshalAs(UnmanagedType.Bool)]
-    private static extern bool CreateProcessW(
-        string applicationName,
-        StringBuilder commandLine,
-        nint processAttributes,
-        nint threadAttributes,
-        [MarshalAs(UnmanagedType.Bool)] bool inheritHandles,
-        uint creationFlags,
-        nint environment,
-        string currentDirectory,
-        ref STARTUPINFOEX startupInfo,
-        out PROCESS_INFORMATION processInformation);
+    private static extern bool CreateProcessW(string applicationName, StringBuilder commandLine, nint processAttributes, nint threadAttributes, [MarshalAs(UnmanagedType.Bool)] bool inheritHandles, uint flags, nint environment, string currentDirectory, ref StartupInfoEx startupInfo, out ProcessInformation processInformation);
 
     [DllImport("kernel32.dll", SetLastError = true)]
     private static extern uint WaitForSingleObject(nint handle, uint milliseconds);

src/SharpEmu.GUI/GameSurfaceHost.cs

@@ -0,0 +1,613 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Platform;
+using Avalonia.Threading;
+using SharpEmu.Libs.VideoOut;
+using System.Runtime.InteropServices;
+
+namespace SharpEmu.GUI;
+
+/// <summary>
+/// Native child surface owned by Avalonia. The isolated emulator process uses
+/// its platform handle to create the Vulkan presentation surface, keeping the
+/// guest address space out of the GUI process.
+/// </summary>
+public sealed class GameSurfaceHost : NativeControlHost
+{
+    private const uint SwpNoSize = 0x0001;
+    private const uint SwpNoMove = 0x0002;
+    private const uint SwpNoZOrder = 0x0004;
+    private const uint SwpNoActivate = 0x0010;
+    private const uint SwpShowWindow = 0x0040;
+    private const uint SwpHideWindow = 0x0080;
+    private const uint WsChild = 0x40000000;
+    private const uint WsVisible = 0x10000000;
+    private const uint WsClipSiblings = 0x04000000;
+    private const uint WsClipChildren = 0x02000000;
+    private const uint CsOwnDc = 0x0020;
+    private const uint WmSetCursor = 0x0020;
+    private const uint WmMouseMove = 0x0200;
+    private const int IdcArrow = 32512;
+    private const int CursorHideDelayMs = 2500;
+
+    private VulkanHostSurface? _surface;
+    private nint _windowHandle;
+    private nint _x11Display;
+    private string? _win32ClassName;
+    private WindowProcedure? _windowProcedure;
+    private nint _metalLayer;
+    private bool _presentationVisible = true;
+    private DispatcherTimer? _cursorIdleTimer;
+    private bool _cursorAutoHide;
+    private bool _cursorHidden;
+    private long _lastPointerActivity;
+
+    public GameSurfaceHost()
+    {
+        PropertyChanged += (_, change) =>
+        {
+            if (change.Property == BoundsProperty)
+            {
+                UpdateSurfaceSize();
+            }
+        };
+        LayoutUpdated += (_, _) =>
+        {
+            // Fullscreen can change a monitor's DPI scale without changing
+            // the logical Bounds. Refresh the native child from physical size.
+            UpdateSurfaceSize();
+
+            // NativeControlHost may make its HWND visible again as part of a
+            // later arrange pass. Keep a loading surface hidden until its
+            // child process reports a real first frame.
+            if (!_presentationVisible)
+            {
+                ApplyPresentationVisibility();
+            }
+        };
+    }
+
+    public event EventHandler<VulkanHostSurface>? SurfaceAvailable;
+
+    public event EventHandler<VulkanHostSurface>? SurfaceDestroyed;
+
+    public VulkanHostSurface? Surface => _surface;
+
+    public void RefreshSurfaceSize() => UpdateSurfaceSize();
+
+    /// <summary>
+    /// Hides the platform child without detaching the Vulkan surface. This
+    /// allows the launcher to return to its library while guest teardown is
+    /// still finishing on the render thread.
+    /// </summary>
+    public void SetPresentationVisible(bool visible)
+    {
+        _presentationVisible = visible;
+        ApplyPresentationVisibility();
+    }
+
+    /// <summary>
+    /// Auto-hides the mouse cursor over the game surface after a short idle
+    /// period; any pointer movement brings it back. Enabling (again) restarts
+    /// the idle countdown, so both "first frame presented" and "entered
+    /// fullscreen" can arm it. Windows-only; a no-op elsewhere.
+    /// </summary>
+    public void SetCursorAutoHide(bool enabled)
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        _cursorAutoHide = enabled;
+        _lastPointerActivity = System.Diagnostics.Stopwatch.GetTimestamp();
+        if (enabled)
+        {
+            _cursorIdleTimer ??= CreateCursorIdleTimer();
+            _cursorIdleTimer.Start();
+            return;
+        }
+
+        _cursorIdleTimer?.Stop();
+        ShowCursorNow();
+    }
+
+    private DispatcherTimer CreateCursorIdleTimer()
+    {
+        var timer = new DispatcherTimer
+        {
+            Interval = TimeSpan.FromMilliseconds(250),
+        };
+        timer.Tick += (_, _) => HideCursorWhenIdle();
+        return timer;
+    }
+
+    private void HideCursorWhenIdle()
+    {
+        if (!_cursorAutoHide || _cursorHidden || _windowHandle == 0)
+        {
+            return;
+        }
+
+        var idleMs = (System.Diagnostics.Stopwatch.GetTimestamp() - _lastPointerActivity) *
+            1000 / System.Diagnostics.Stopwatch.Frequency;
+        if (idleMs < CursorHideDelayMs)
+        {
+            return;
+        }
+
+        // Only swallow the cursor while it is actually over the game surface;
+        // hovering launcher chrome (console, toolbar) must keep the arrow.
+        if (!GetCursorPos(out var point) || WindowFromPoint(point) != _windowHandle)
+        {
+            return;
+        }
+
+        _cursorHidden = true;
+        _ = SetCursor(0);
+    }
+
+    private void ShowCursorNow()
+    {
+        if (!_cursorHidden)
+        {
+            return;
+        }
+
+        _cursorHidden = false;
+        _ = SetCursor(LoadCursorW(0, IdcArrow));
+    }
+
+    private void ApplyPresentationVisibility()
+    {
+        if (_windowHandle == 0)
+        {
+            return;
+        }
+
+        var visible = _presentationVisible;
+        if (OperatingSystem.IsWindows())
+        {
+            // SW_HIDE can be ignored for a window's initial show state. Force
+            // the state through SetWindowPos so an old child swapchain cannot
+            // remain composed while the next game is loading.
+            var flags = SwpNoSize | SwpNoMove | SwpNoZOrder | SwpNoActivate |
+                (visible ? SwpShowWindow : SwpHideWindow);
+            _ = SetWindowPos(_windowHandle, 0, 0, 0, 0, 0, flags);
+        }
+        else if (OperatingSystem.IsLinux() && _x11Display != 0)
+        {
+            _ = visible
+                ? XMapWindow(_x11Display, _windowHandle)
+                : XUnmapWindow(_x11Display, _windowHandle);
+            _ = XFlush(_x11Display);
+        }
+        else if (OperatingSystem.IsMacOS())
+        {
+            SendBool(_windowHandle, "setHidden:", !visible);
+        }
+    }
+
+    protected override IPlatformHandle CreateNativeControlCore(IPlatformHandle control)
+    {
+        PlatformHandle handle;
+        if (OperatingSystem.IsWindows())
+        {
+            handle = CreateWin32(control);
+        }
+        else if (OperatingSystem.IsLinux())
+        {
+            handle = CreateX11(control);
+        }
+        else if (OperatingSystem.IsMacOS())
+        {
+            handle = CreateMacOS();
+        }
+        else
+        {
+            throw new PlatformNotSupportedException("SharpEmu's embedded Vulkan surface is unsupported on this platform.");
+        }
+
+        UpdateSurfaceSize();
+        if (_surface is { } surface)
+        {
+            SurfaceAvailable?.Invoke(this, surface);
+        }
+
+        return handle;
+    }
+
+    protected override void DestroyNativeControlCore(IPlatformHandle control)
+    {
+        if (OperatingSystem.IsWindows())
+        {
+            SetCursorAutoHide(false);
+        }
+
+        var surface = _surface;
+        _surface = null;
+
+        if (OperatingSystem.IsWindows())
+        {
+            DestroyWin32();
+        }
+        else if (OperatingSystem.IsLinux())
+        {
+            DestroyX11();
+        }
+        else if (OperatingSystem.IsMacOS())
+        {
+            DestroyMacOS();
+        }
+
+        if (surface is not null)
+        {
+            SurfaceDestroyed?.Invoke(this, surface);
+        }
+    }
+
+    private PlatformHandle CreateWin32(IPlatformHandle control)
+    {
+        _win32ClassName = $"SharpEmuGameSurface-{Guid.NewGuid():N}";
+        _windowProcedure = WindowProcedureImpl;
+        var classInfo = new WndClassEx
+        {
+            Size = (uint)Marshal.SizeOf<WndClassEx>(),
+            Style = CsOwnDc,
+            WindowProcedure = Marshal.GetFunctionPointerForDelegate(_windowProcedure),
+            Instance = GetModuleHandleW(null),
+            ClassName = _win32ClassName,
+        };
+
+        if (RegisterClassExW(ref classInfo) == 0)
+        {
+            throw new InvalidOperationException($"Could not register the embedded game window class (Win32 error {Marshal.GetLastWin32Error()}).");
+        }
+
+        _windowHandle = CreateWindowExW(
+            0,
+            _win32ClassName,
+            "SharpEmu Game Surface",
+            WsChild | (_presentationVisible ? WsVisible : 0) | WsClipSiblings | WsClipChildren,
+            0,
+            0,
+            1,
+            1,
+            control.Handle,
+            0,
+            classInfo.Instance,
+            0);
+        if (_windowHandle == 0)
+        {
+            var error = Marshal.GetLastWin32Error();
+            _ = UnregisterClassW(_win32ClassName, classInfo.Instance);
+            throw new InvalidOperationException($"Could not create the embedded game window (Win32 error {error}).");
+        }
+
+        _surface = new VulkanHostSurface(
+            VulkanHostSurfaceKind.Win32,
+            _windowHandle,
+            classInfo.Instance);
+        return new PlatformHandle(_windowHandle, "HWND");
+    }
+
+    private PlatformHandle CreateX11(IPlatformHandle control)
+    {
+        _x11Display = XOpenDisplay(0);
+        if (_x11Display == 0)
+        {
+            throw new InvalidOperationException("Could not connect to the X11 server for the embedded game surface.");
+        }
+
+        _windowHandle = XCreateSimpleWindow(
+            _x11Display,
+            control.Handle,
+            0,
+            0,
+            1,
+            1,
+            0,
+            0,
+            0);
+        if (_windowHandle == 0)
+        {
+            XCloseDisplay(_x11Display);
+            _x11Display = 0;
+            throw new InvalidOperationException("Could not create the X11 embedded game surface.");
+        }
+
+        if (_presentationVisible)
+        {
+            _ = XMapWindow(_x11Display, _windowHandle);
+        }
+        _ = XFlush(_x11Display);
+        _surface = new VulkanHostSurface(VulkanHostSurfaceKind.Xlib, _windowHandle, _x11Display);
+        return new PlatformHandle(_windowHandle, "X11");
+    }
+
+    private PlatformHandle CreateMacOS()
+    {
+        _metalLayer = CreateObjectiveCObject("CAMetalLayer");
+        _windowHandle = CreateObjectiveCObject("NSView");
+        SendBool(_windowHandle, "setWantsLayer:", true);
+        SendPointer(_windowHandle, "setLayer:", _metalLayer);
+        SendBool(_windowHandle, "setHidden:", !_presentationVisible);
+
+        _surface = new VulkanHostSurface(VulkanHostSurfaceKind.Metal, _windowHandle, metalLayerHandle: _metalLayer);
+        return new PlatformHandle(_windowHandle, "NSView");
+    }
+
+    private void UpdateSurfaceSize()
+    {
+        if (_surface is null)
+        {
+            return;
+        }
+
+        var renderScale = (VisualRoot as TopLevel)?.RenderScaling ?? 1.0;
+        var width = Math.Max(1, (int)Math.Round(Bounds.Width * renderScale));
+        var height = Math.Max(1, (int)Math.Round(Bounds.Height * renderScale));
+        var sizeChanged = _surface.PixelWidth != width || _surface.PixelHeight != height;
+        _surface.UpdatePixelSize(width, height);
+
+        if (!sizeChanged)
+        {
+            return;
+        }
+
+        if (OperatingSystem.IsWindows() && _windowHandle != 0)
+        {
+            _ = SetWindowPos(
+                _windowHandle,
+                0,
+                0,
+                0,
+                width,
+                height,
+                SwpNoMove | SwpNoZOrder | SwpNoActivate);
+        }
+        else if (OperatingSystem.IsLinux() && _x11Display != 0 && _windowHandle != 0)
+        {
+            _ = XResizeWindow(_x11Display, _windowHandle, (uint)width, (uint)height);
+            _ = XFlush(_x11Display);
+        }
+        else if (OperatingSystem.IsMacOS() && _metalLayer != 0)
+        {
+            SendDouble(_metalLayer, "setContentsScale:", renderScale);
+        }
+    }
+
+    private void DestroyWin32()
+    {
+        if (_windowHandle != 0)
+        {
+            _ = DestroyWindow(_windowHandle);
+            _windowHandle = 0;
+        }
+
+        if (!string.IsNullOrWhiteSpace(_win32ClassName))
+        {
+            _ = UnregisterClassW(_win32ClassName, GetModuleHandleW(null));
+            _win32ClassName = null;
+        }
+
+        _windowProcedure = null;
+    }
+
+    private void DestroyX11()
+    {
+        if (_x11Display != 0 && _windowHandle != 0)
+        {
+            _ = XDestroyWindow(_x11Display, _windowHandle);
+        }
+        if (_x11Display != 0)
+        {
+            _ = XCloseDisplay(_x11Display);
+        }
+
+        _windowHandle = 0;
+        _x11Display = 0;
+    }
+
+    private void DestroyMacOS()
+    {
+        if (_windowHandle != 0)
+        {
+            SendVoid(_windowHandle, "release");
+        }
+        if (_metalLayer != 0)
+        {
+            SendVoid(_metalLayer, "release");
+        }
+
+        _windowHandle = 0;
+        _metalLayer = 0;
+    }
+
+    private nint WindowProcedureImpl(nint window, uint message, nint wParam, nint lParam)
+    {
+        if (message == WmMouseMove)
+        {
+            _lastPointerActivity = System.Diagnostics.Stopwatch.GetTimestamp();
+            ShowCursorNow();
+        }
+        else if (message == WmSetCursor && _cursorHidden)
+        {
+            // Win32 re-resolves the cursor on every mouse message; returning
+            // TRUE here keeps the parent chain from restoring the arrow.
+            _ = SetCursor(0);
+            return 1;
+        }
+
+        return DefWindowProcW(window, message, wParam, lParam);
+    }
+
+    private static nint CreateObjectiveCObject(string className)
+    {
+        var classHandle = objc_getClass(className);
+        if (classHandle == 0)
+        {
+            throw new InvalidOperationException($"Objective-C class '{className}' is unavailable.");
+        }
+
+        var instance = objc_msgSend_id(classHandle, sel_registerName("alloc"));
+        instance = objc_msgSend_id(instance, sel_registerName("init"));
+        if (instance == 0)
+        {
+            throw new InvalidOperationException($"Could not create Objective-C '{className}'.");
+        }
+
+        return instance;
+    }
+
+    private static void SendVoid(nint receiver, string selector) =>
+        objc_msgSend_void(receiver, sel_registerName(selector));
+
+    private static void SendBool(nint receiver, string selector, bool value) =>
+        objc_msgSend_bool(receiver, sel_registerName(selector), value ? (byte)1 : (byte)0);
+
+    private static void SendPointer(nint receiver, string selector, nint value) =>
+        objc_msgSend_pointer(receiver, sel_registerName(selector), value);
+
+    private static void SendDouble(nint receiver, string selector, double value) =>
+        objc_msgSend_double(receiver, sel_registerName(selector), value);
+
+    private delegate nint WindowProcedure(nint window, uint message, nint wParam, nint lParam);
+
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    private struct WndClassEx
+    {
+        public uint Size;
+        public uint Style;
+        public nint WindowProcedure;
+        public int ClassExtra;
+        public int WindowExtra;
+        public nint Instance;
+        public nint Icon;
+        public nint Cursor;
+        public nint Background;
+        public string? MenuName;
+        public string? ClassName;
+        public nint IconSmall;
+    }
+
+    [DllImport("kernel32.dll", EntryPoint = "GetModuleHandleW", CharSet = CharSet.Unicode)]
+    private static extern nint GetModuleHandleW(string? moduleName);
+
+    [DllImport("user32.dll", EntryPoint = "RegisterClassExW", SetLastError = true, CharSet = CharSet.Unicode)]
+    private static extern ushort RegisterClassExW(ref WndClassEx classInfo);
+
+    [DllImport("user32.dll", EntryPoint = "UnregisterClassW", SetLastError = true, CharSet = CharSet.Unicode)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool UnregisterClassW(string className, nint instance);
+
+    [DllImport("user32.dll", EntryPoint = "CreateWindowExW", SetLastError = true, CharSet = CharSet.Unicode)]
+    private static extern nint CreateWindowExW(
+        uint extendedStyle,
+        string className,
+        string windowName,
+        uint style,
+        int x,
+        int y,
+        int width,
+        int height,
+        nint parent,
+        nint menu,
+        nint instance,
+        nint parameter);
+
+    [DllImport("user32.dll", EntryPoint = "DestroyWindow", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool DestroyWindow(nint window);
+
+    [DllImport("user32.dll", EntryPoint = "SetWindowPos", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool SetWindowPos(
+        nint window,
+        nint insertAfter,
+        int x,
+        int y,
+        int width,
+        int height,
+        uint flags);
+
+    [DllImport("user32.dll", EntryPoint = "DefWindowProcW", CharSet = CharSet.Unicode)]
+    private static extern nint DefWindowProcW(nint window, uint message, nint wParam, nint lParam);
+
+    [DllImport("user32.dll", EntryPoint = "SetCursor")]
+    private static extern nint SetCursor(nint cursor);
+
+    [DllImport("user32.dll", EntryPoint = "LoadCursorW", CharSet = CharSet.Unicode)]
+    private static extern nint LoadCursorW(nint instance, nint cursorName);
+
+    [DllImport("user32.dll", EntryPoint = "GetCursorPos")]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool GetCursorPos(out NativePoint point);
+
+    [DllImport("user32.dll", EntryPoint = "WindowFromPoint")]
+    private static extern nint WindowFromPoint(NativePoint point);
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct NativePoint
+    {
+        public int X;
+        public int Y;
+    }
+
+    [DllImport("libX11.so.6", EntryPoint = "XOpenDisplay")]
+    private static extern nint XOpenDisplay(nint displayName);
+
+    [DllImport("libX11.so.6", EntryPoint = "XCreateSimpleWindow")]
+    private static extern nint XCreateSimpleWindow(
+        nint display,
+        nint parent,
+        int x,
+        int y,
+        uint width,
+        uint height,
+        uint borderWidth,
+        ulong border,
+        ulong background);
+
+    [DllImport("libX11.so.6", EntryPoint = "XMapWindow")]
+    private static extern int XMapWindow(nint display, nint window);
+
+    [DllImport("libX11.so.6", EntryPoint = "XUnmapWindow")]
+    private static extern int XUnmapWindow(nint display, nint window);
+
+    [DllImport("libX11.so.6", EntryPoint = "XResizeWindow")]
+    private static extern int XResizeWindow(nint display, nint window, uint width, uint height);
+
+    [DllImport("libX11.so.6", EntryPoint = "XDestroyWindow")]
+    private static extern int XDestroyWindow(nint display, nint window);
+
+    [DllImport("libX11.so.6", EntryPoint = "XCloseDisplay")]
+    private static extern int XCloseDisplay(nint display);
+
+    [DllImport("libX11.so.6", EntryPoint = "XFlush")]
+    private static extern int XFlush(nint display);
+
+    [DllImport("/usr/lib/libobjc.A.dylib")]
+    private static extern nint objc_getClass(string name);
+
+    [DllImport("/usr/lib/libobjc.A.dylib")]
+    private static extern nint sel_registerName(string name);
+
+    [DllImport("/usr/lib/libobjc.A.dylib", EntryPoint = "objc_msgSend")]
+    private static extern nint objc_msgSend_id(nint receiver, nint selector);
+
+    [DllImport("/usr/lib/libobjc.A.dylib", EntryPoint = "objc_msgSend")]
+    private static extern void objc_msgSend_void(nint receiver, nint selector);
+
+    [DllImport("/usr/lib/libobjc.A.dylib", EntryPoint = "objc_msgSend")]
+    private static extern void objc_msgSend_bool(nint receiver, nint selector, byte value);
+
+    [DllImport("/usr/lib/libobjc.A.dylib", EntryPoint = "objc_msgSend")]
+    private static extern void objc_msgSend_pointer(nint receiver, nint selector, nint value);
+
+    [DllImport("/usr/lib/libobjc.A.dylib", EntryPoint = "objc_msgSend")]
+    private static extern void objc_msgSend_double(nint receiver, nint selector, double value);
+}

src/SharpEmu.GUI/GuiConsoleMirror.cs

@@ -0,0 +1,116 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Text;
+
+namespace SharpEmu.GUI;
+
+/// <summary>
+/// Mirrors process-wide console output into the launcher console while
+/// retaining the original streams for shell users and file logging.
+/// </summary>
+internal sealed class GuiConsoleMirror : IDisposable
+{
+    private readonly TextWriter _originalOut;
+    private readonly TextWriter _originalError;
+    private int _disposed;
+
+    private GuiConsoleMirror(Action<string, bool> writeLine)
+    {
+        _originalOut = Console.Out;
+        _originalError = Console.Error;
+        Console.SetOut(new MirroringWriter(_originalOut, line => writeLine(line, false)));
+        Console.SetError(new MirroringWriter(_originalError, line => writeLine(line, true)));
+    }
+
+    public static GuiConsoleMirror Install(Action<string, bool> writeLine) => new(writeLine);
+
+    public void Dispose()
+    {
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+        {
+            return;
+        }
+
+        Console.SetOut(_originalOut);
+        Console.SetError(_originalError);
+    }
+
+    private sealed class MirroringWriter : TextWriter
+    {
+        private readonly TextWriter _inner;
+        private readonly Action<string> _writeLine;
+        private readonly StringBuilder _line = new();
+        private readonly object _gate = new();
+
+        public MirroringWriter(TextWriter inner, Action<string> writeLine)
+        {
+            _inner = inner;
+            _writeLine = writeLine;
+        }
+
+        public override Encoding Encoding => _inner.Encoding;
+
+        public override void Write(char value)
+        {
+            lock (_gate)
+            {
+                _inner.Write(value);
+                Append(value);
+            }
+        }
+
+        public override void Write(string? value)
+        {
+            if (value is null)
+            {
+                return;
+            }
+
+            lock (_gate)
+            {
+                _inner.Write(value);
+                foreach (var character in value)
+                {
+                    Append(character);
+                }
+            }
+        }
+
+        public override void WriteLine(string? value)
+        {
+            lock (_gate)
+            {
+                _inner.WriteLine(value);
+                if (!string.IsNullOrEmpty(value))
+                {
+                    _line.Append(value);
+                }
+
+                FlushLine();
+            }
+        }
+
+        private void Append(char value)
+        {
+            if (value == '\r')
+            {
+                return;
+            }
+
+            if (value == '\n')
+            {
+                FlushLine();
+                return;
+            }
+
+            _line.Append(value);
+        }
+
+        private void FlushLine()
+        {
+            _writeLine(_line.ToString());
+            _line.Clear();
+        }
+    }
+}

src/SharpEmu.GUI/GuiSettings.cs

@@ -48,6 +48,8 @@ public sealed class GuiSettings
     /// <summary>Publish launcher/game status to Discord Rich Presence.</summary>
     public bool DiscordRichPresence { get; set; } = true;
 
+    public bool CheckForUpdatesOnStartup { get; set; } = true;
+
     /// <summary>Names of SHARPEMU_* switches set to "1" in the emulator's environment at launch.</summary>
     public List<string> EnvironmentToggles { get; set; } = new();
 

src/SharpEmu.GUI/Languages/br.json

@@ -28,9 +28,9 @@
   "Options.General": "Opções Gerais",
   "Options.Env.Tab": "Ambiente",
   "Options.Section.Environment": "VARIÁVEIS DE AMBIENTE",
-  "Options.Env.Desc": "Switches passados para o emulador como variáveis de ambiente na inicialização.",
-  "Options.Env.Bthid.Desc": "Reporta o Bluetooth HID como indisponível para títulos cujo middleware de volante/FFB fica esperando indefinidamente.\nDeixe desativado normalmente. Alguns títulos travam quando a inicialização falha.",
-  "Options.Env.LoopGuard.Desc": "Não force o encerramento de títulos que repetem a mesma chamada por tempo demais.\nExperimente isso quando um jogo fecha sozinho durante o carregamento.",
+  "Options.Env.Desc": "Variáveis de ambiente passadas ao emulador durante a inicialização.",
+  "Options.Env.Bthid.Desc": "Informa o Bluetooth HID como indisponível para títulos cujo middleware de volante/FFB fica verificando indefinidamente.\nNormalmente, deixe desativado. Alguns títulos travam quando a inicialização falha.",
+  "Options.Env.LoopGuard.Desc": "Não força o encerramento de títulos que repetem a mesma chamada por tempo excessivo.\nExperimente esta opção se um jogo fechar sozinho durante o carregamento.",
   "Options.Env.VkValidation.Desc": "Ativa as camadas de validação do Vulkan para depuração de GPU.\nLento. Requer que o Vulkan SDK esteja instalado.",
   "Options.Env.DumpSpirv.Desc": "Extrai os shaders AGC e suas traduções SPIR-V para a pasta shader-dumps.\nUse ao reportar bugs de shader ou renderização.",
   "Options.Env.LogDirectMemory.Desc": "Registra alocações de memória direta e falhas no console.\nUse quando um jogo aborta ou fecha durante a inicialização (boot).",
@@ -83,7 +83,7 @@
   "Console.Title": "CONSOLE",
   "Console.SearchWatermark": "Pesquisar...",
   "Console.AutoScroll": "Rolagem automática",
-  "Console.Split": "Recortar",
+  "Console.Split": "Dividir",
   "Console.Copy": "Copiar",
   "Console.Clear": "Limpar",
   "Console.WindowTitle": "Console do SharpEmu",
@@ -134,5 +134,13 @@
   "Dialog.PsExecutables": "Executáveis de PS",
   "Dialog.SaveLogFile": "Selecione onde salvar o arquivo de log",
   "Dialog.PlainTextFiles": "Arquivos de texto simples",
-  "Dialog.LogFiles": "Arquivos de log"
+  "Dialog.LogFiles": "Arquivos de log",
+
+  "Options.About" : "Sobre",
+  "About.Github.Label": "GitHub",
+  "About.Github.Desc": "Código-fonte, problemas e desenvolvimento do projeto.",
+  "About.Discord.Label": "Discord",
+  "About.Discord.Desc": "Participe da comunidade, obtenha suporte e acompanhe o desenvolvimento.",
+  "About.GithubButton": "Contribua no GitHub!",
+  "About.DiscordButton": "Entre no nosso Discord!"
 }

src/SharpEmu.GUI/Languages/en.json

@@ -15,6 +15,7 @@
   "Library.Context.OpenFolder": "Open game folder",
   "Library.Context.CopyPath": "Copy path",
   "Library.Context.CopyTitleId": "Copy title ID",
+  "Library.Context.GameSettings": "Game settings…",
   "Library.Context.Remove": "Remove from library",
 
   "Library.Empty.Title": "Your library is empty",
@@ -31,9 +32,11 @@
   "Options.Env.Desc": "Switches passed to the emulator as environment variables at launch.",
   "Options.Env.Bthid.Desc": "Report Bluetooth HID as unavailable for titles whose wheel/FFB middleware polls forever.\nLeave off normally. Some titles freeze when init fails.",
   "Options.Env.LoopGuard.Desc": "Do not force quit titles that repeat the same call for too long.\nTry this when a game exits on its own while loading.",
+  "Options.Env.WritableApp0.Desc": "Allow titles to create and write files inside their install folder.\nNeeded by unpackaged dumps that write their save or config data under /app0.",
   "Options.Env.VkValidation.Desc": "Enable Vulkan validation layers for GPU debugging.\nSlow. Requires the Vulkan SDK to be installed.",
   "Options.Env.DumpSpirv.Desc": "Dump AGC shaders and their SPIR-V translations to the shader-dumps folder.\nUse when reporting shader or rendering bugs.",
   "Options.Env.LogDirectMemory.Desc": "Log direct memory allocations and failures to the console.\nUse when a game aborts or exits during boot.",
+  "Options.Env.LogIo.Desc": "Log file open, read, and path-resolve activity to the console.\nUse when a game cannot find its data files during boot.",
   "Options.Env.LogNp.Desc": "Log NP (PlayStation Network) library calls to the console.",
   "Options.Section.Emulation": "EMULATION",
   "Options.Section.Logging": "LOGGING",
@@ -79,6 +82,13 @@
 
   "Common.On": "On",
   "Common.Off": "Off",
+  "Common.Save": "Save",
+  "Common.Cancel": "Cancel",
+
+  "PerGame.Title": "Per-game settings — {0} ({1})",
+  "PerGame.InheritNote": "Unchecked rows inherit the global defaults.",
+  "PerGame.EnvToggles.Label": "Environment toggles",
+  "PerGame.EnvToggles.Desc": "Override the global set of SHARPEMU_* switches for this game.",
 
   "Console.Title": "CONSOLE",
   "Console.SearchWatermark": "Search...",
@@ -139,8 +149,26 @@
   "Options.About" : "About",
   "About.Github.Label": "GitHub",
   "About.Github.Desc": "Source code, issues and project development.",
+  "About.Github.LatestCommitLabel": "Latest Commit",
+  "About.Github.LatestCommitDescription": "Latest commit on the main branch",
   "About.Discord.Label": "Discord",
   "About.Discord.Desc": "Join the community, get support and follow development.",
   "About.GithubButton": "Contribute in GitHub!",
-  "About.DiscordButton": "Join our Discord!"
+  "About.DiscordButton": "Join our Discord!",
+
+  "Updater.Auto.Label": "Check for updates on startup",
+  "Updater.Auto.Desc": "Checks GitHub without delaying startup.",
+  "Updater.Label": "Updates",
+  "Updater.Check": "Check for updates",
+  "Updater.DownloadRestart": "Download and restart",
+  "Updater.Status.Ready": "Current build: {0}",
+  "Updater.Status.Checking": "Checking for updates…",
+  "Updater.Status.Current": "You are up to date ({0}).",
+  "Updater.Status.Available": "A new build is available: {0}",
+  "Updater.Status.Downloading": "Downloading update… {0}%",
+  "Updater.Status.Installing": "Installing update…",
+  "Updater.Status.Timeout": "Update check timed out after 10 seconds.",
+  "Updater.Status.Failed": "Could not check for updates.",
+  "Updater.Status.ChecksumFailed": "Downloaded update failed SHA-256 verification.",
+  "Updater.Status.Unsupported": "Automatic updating requires a Windows, Linux or macOS x64 build."
 }

src/SharpEmu.GUI/Languages/es.json

@@ -131,6 +131,8 @@
   "About.Github.Label": "GitHub",
   "About.Github.Desc": "Código fuente, issues y desarrollo del proyecto.",
   "About.Discord.Label": "Discord",
+  "About.Github.LatestCommitLabel": "Último Commit",
+  "About.Github.LatestCommitDescription": "Último commit en la rama main",
   "About.Discord.Desc": "Únete a la comunidad, recibe soporte y sigue el desarrollo.",
   "About.GithubButton": "Contribuye en GitHub!",
   "About.DiscordButton": "Únete a nuestro Discord!"

src/SharpEmu.GUI/Languages/fr.json

@@ -26,6 +26,15 @@
   "Library.Loading": "Chargement de la bibliothèque…",
 
   "Options.General": "Général",
+  "Options.Env.Tab": "Environnement",
+  "Options.Section.Environment": "VARIABLES D’ENVIRONNEMENT",
+  "Options.Env.Desc": "Paramètres passés à l’émulateur comme variables d’environnement au lancement.",
+  "Options.Env.Bthid.Desc": "Signaler le HID Bluetooth comme indisponible pour les titres dont le middleware volant/FFB interroge indéfiniment.\nLaissez désactivé normalement. Certains titres se bloquent si l’initialisation échoue.",
+  "Options.Env.LoopGuard.Desc": "Ne pas forcer la fermeture des titres qui répètent le même appel trop longtemps.\nEssayez ceci quand un jeu se ferme tout seul pendant le chargement.",
+  "Options.Env.VkValidation.Desc": "Activer les couches de validation Vulkan pour le débogage GPU.\nRalentit. Nécessite l’installation du Vulkan SDK.",
+  "Options.Env.DumpSpirv.Desc": "Exporter les shaders AGC et leurs traductions SPIR-V dans le dossier shader-dumps.\nÀ utiliser pour signaler des bugs de shader ou de rendu.",
+  "Options.Env.LogDirectMemory.Desc": "Journaliser les allocations de mémoire directe et les échecs dans la console.\nÀ utiliser quand un jeu plante ou se ferme pendant le démarrage.",
+  "Options.Env.LogNp.Desc": "Journaliser les appels de la bibliothèque NP (PlayStation Network) dans la console.",
   "Options.Section.Emulation": "ÉMULATION",
   "Options.Section.Logging": "JOURNALISATION",
   "Options.Section.Launcher": "LANCEUR",
@@ -125,5 +134,13 @@
   "Dialog.PsExecutables": "Exécutables PlayStation",
   "Dialog.SaveLogFile": "Choisir l’emplacement du fichier journal",
   "Dialog.PlainTextFiles": "Fichiers texte brut",
-  "Dialog.LogFiles": "Fichiers journaux"
+  "Dialog.LogFiles": "Fichiers journaux",
+
+  "Options.About": "À propos",
+  "About.Github.Label": "GitHub",
+  "About.Github.Desc": "Code source, issues et développement du projet.",
+  "About.Discord.Label": "Discord",
+  "About.Discord.Desc": "Rejoignez la communauté, obtenez de l’aide et suivez le développement.",
+  "About.GithubButton": "Contribuer sur GitHub !",
+  "About.DiscordButton": "Rejoindre notre Discord !"
 }

src/SharpEmu.GUI/Languages/ru.json

@@ -15,6 +15,7 @@
   "Library.Context.OpenFolder": "Открыть папку с игрой",
   "Library.Context.CopyPath": "Скопировать путь",
   "Library.Context.CopyTitleId": "Скопировать ID игры",
+  "Library.Context.GameSettings": "Настройки игры…",
   "Library.Context.Remove": "Удалить из библиотеки",
 
   "Library.Empty.Title": "Ваша библиотека пуста",
@@ -26,6 +27,17 @@
   "Library.Loading": "Загрузка библиотеки…",
 
   "Options.General": "Основные",
+  "Options.Env.Tab": "Окружение",
+  "Options.Section.Environment": "ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ",
+  "Options.Env.Desc": "Параметры, передаваемые эмулятору как переменные окружения при запуске.",
+  "Options.Env.Bthid.Desc": "Сообщать об отсутствии Bluetooth HID для игр, чьи библиотеки руля и обратной связи опрашивают устройство бесконечно.\nОбычно оставляйте выключенным. Некоторые игры зависают при сбое инициализации.",
+  "Options.Env.LoopGuard.Desc": "Не завершать принудительно игры, которые слишком долго повторяют один и тот же вызов.\nПопробуйте этот параметр, если игра сама закрывается во время загрузки.",
+  "Options.Env.WritableApp0.Desc": "Разрешить играм создавать и записывать файлы в папке установки.\nТребуется для неупакованных дампов, которые сохраняют данные или настройки в /app0.",
+  "Options.Env.VkValidation.Desc": "Включить слои валидации Vulkan для отладки GPU.\nЗамедляет работу. Требуется установленный Vulkan SDK.",
+  "Options.Env.DumpSpirv.Desc": "Сохранять шейдеры AGC и их переводы в SPIR-V в папку shader-dumps.\nИспользуйте при сообщении об ошибках шейдеров или рендеринга.",
+  "Options.Env.LogDirectMemory.Desc": "Выводить в консоль выделения прямой памяти и ошибки выделения.\nИспользуйте, если игра аварийно завершает работу или закрывается при запуске.",
+  "Options.Env.LogIo.Desc": "Выводить в консоль операции открытия и чтения файлов, а также разрешение путей.\nИспользуйте, если игра не может найти файлы данных при запуске.",
+  "Options.Env.LogNp.Desc": "Выводить в консоль вызовы библиотеки NP (PlayStation Network).",
   "Options.Section.Emulation": "ЭМУЛЯЦИЯ",
   "Options.Section.Logging": "ЛОГГИРОВАНИЕ",
   "Options.Section.Launcher": "ЛАУНЧЕР",
@@ -70,6 +82,13 @@
 
   "Common.On": "Включено",
   "Common.Off": "Выключено",
+  "Common.Save": "Сохранить",
+  "Common.Cancel": "Отмена",
+
+  "PerGame.Title": "Настройки игры — {0} ({1})",
+  "PerGame.InheritNote": "Неотмеченные строки наследуют глобальные настройки.",
+  "PerGame.EnvToggles.Label": "Переключатели окружения",
+  "PerGame.EnvToggles.Desc": "Переопределить глобальный набор переключателей SHARPEMU_* для этой игры.",
 
   "Console.Title": "КОНСОЛЬ",
   "Console.SearchWatermark": "Поиск...",
@@ -125,5 +144,30 @@
   "Dialog.PsExecutables": "Исполняемые файлы PS",
   "Dialog.SaveLogFile": "Выберите, куда сохранить файл с логами",
   "Dialog.PlainTextFiles": "Текстовые файлы",
-  "Dialog.LogFiles": "Логи"
+  "Dialog.LogFiles": "Логи",
+
+  "Options.About": "О программе",
+  "About.Github.Label": "GitHub",
+  "About.Github.Desc": "Исходный код, отчёты об ошибках и разработка проекта.",
+  "About.Github.LatestCommitLabel": "Последний коммит",
+  "About.Github.LatestCommitDescription": "Последний коммит в основной ветке",
+  "About.Discord.Label": "Discord",
+  "About.Discord.Desc": "Присоединяйтесь к сообществу, получайте поддержку и следите за разработкой.",
+  "About.GithubButton": "Участвовать в разработке на GitHub!",
+  "About.DiscordButton": "Присоединиться к нашему Discord!",
+
+  "Updater.Auto.Label": "Проверять обновления при запуске",
+  "Updater.Auto.Desc": "Проверяет GitHub без задержки запуска.",
+  "Updater.Label": "Обновления",
+  "Updater.Check": "Проверить обновления",
+  "Updater.DownloadRestart": "Скачать и перезапустить",
+  "Updater.Status.Ready": "Текущая сборка: {0}",
+  "Updater.Status.Checking": "Проверка обновлений…",
+  "Updater.Status.Current": "Установлена актуальная версия ({0}).",
+  "Updater.Status.Available": "Доступна новая сборка: {0}",
+  "Updater.Status.Downloading": "Скачивание обновления… {0}%",
+  "Updater.Status.Installing": "Установка обновления…",
+  "Updater.Status.Timeout": "Проверка обновлений превысила лимит времени в 10 секунд.",
+  "Updater.Status.Failed": "Не удалось проверить наличие обновлений.",
+  "Updater.Status.Unsupported": "Автоматическое обновление требует сборку Windows, Linux или macOS x64."
 }

src/SharpEmu.GUI/Languages/tr.json

@@ -125,5 +125,21 @@
   "Dialog.PsExecutables": "PS çalıştırılabilirleri",
   "Dialog.SaveLogFile": "Günlük dosyasının kaydedileceği yeri seçin",
   "Dialog.PlainTextFiles": "Düz Metin Dosyaları",
-  "Dialog.LogFiles": "Günlük Dosyaları"
+  "Dialog.LogFiles": "Günlük Dosyaları",
+
+  "Updater.Auto.Label": "Açılışta güncellemeleri denetle",
+  "Updater.Auto.Desc": "Açılışı geciktirmeden GitHub'ı denetler.",
+  "Updater.Label": "Güncellemeler",
+  "Updater.Check": "Güncellemeleri denetle",
+  "Updater.DownloadRestart": "İndir ve yeniden başlat",
+  "Updater.Status.Ready": "Mevcut build: {0}",
+  "Updater.Status.Checking": "Güncellemeler denetleniyor…",
+  "Updater.Status.Current": "Güncelsiniz ({0}).",
+  "Updater.Status.Available": "Yeni build mevcut: {0}",
+  "Updater.Status.Downloading": "Güncelleme indiriliyor… %{0}",
+  "Updater.Status.Installing": "Güncelleme kuruluyor…",
+  "Updater.Status.Timeout": "Güncelleme denetimi 10 saniye sonra zaman aşımına uğradı.",
+  "Updater.Status.Failed": "Güncellemeler denetlenemedi.",
+  "Updater.Status.ChecksumFailed": "İndirilen güncelleme SHA-256 doğrulamasını geçemedi.",
+  "Updater.Status.Unsupported": "Otomatik güncelleme Windows, Linux veya macOS x64 build'i gerektirir."
 }

src/SharpEmu.GUI/MainWindow.axaml

@@ -5,6 +5,8 @@ SPDX-License-Identifier: GPL-2.0-or-later
 
 <Window xmlns="https://github.com/avaloniaui"
         xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        xmlns:local="clr-namespace:SharpEmu.GUI"
+        xmlns:primitives="clr-namespace:Avalonia.Controls.Primitives;assembly=Avalonia.Controls"
         x:Class="SharpEmu.GUI.MainWindow"
         Title="SharpEmu"
         Width="1280" Height="820"
@@ -18,7 +20,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
         Icon="avares://SharpEmu.GUI/Assets/SharpEmu.ico"
         KeyDown="OnKeyDown">
 
-  <Grid RowDefinitions="Auto,*,Auto">
+  <Grid x:Name="RootLayout" RowDefinitions="Auto,*,Auto">
 
     <!-- Selected-game backdrop: key art behind the main content, dimmed by
          a scrim so tiles and text stay readable. Fades on selection. -->
@@ -56,13 +58,19 @@ SPDX-License-Identifier: GPL-2.0-or-later
     </Grid>
 
     <!-- Main content -->
-    <Grid Grid.Row="1" Margin="32,24,32,20" RowDefinitions="Auto,*,Auto,Auto">
+    <Grid x:Name="MainContent" Grid.Row="1" Margin="32,24,32,20" RowDefinitions="Auto,*,Auto,Auto">
+
+      <!-- The game owns the full client area while running. Session controls
+           use a native popup so they can stay above this native child surface. -->
+      <Border x:Name="GameView" Grid.Row="0" Grid.RowSpan="4" IsVisible="False" Background="#000000" ClipToBounds="True">
+        <Grid x:Name="GameSurfaceContainer" />
+      </Border>
 
       <!-- Library / Options page switcher, with the library toolbar sharing
            the same row on the right. Plain buttons (not TabItem) so there is
            no underline; LB/RB hint chips flank the pair and the gamepad's
            shoulder buttons actually switch pages from anywhere. -->
-      <Grid Grid.Row="0" ColumnDefinitions="Auto,*,Auto" Margin="0,0,0,20">
+      <Grid x:Name="ContentToolbar" Grid.Row="0" ColumnDefinitions="Auto,*,Auto" Margin="0,0,0,20">
         <StackPanel Grid.Column="0" Orientation="Horizontal" Spacing="14" VerticalAlignment="Center">
           <Border Classes="padHint" VerticalAlignment="Center">
             <TextBlock Text="LB" FontSize="11" FontWeight="Bold" Foreground="{StaticResource MutedBrush}" />
@@ -118,6 +126,13 @@ SPDX-License-Identifier: GPL-2.0-or-later
                   </MenuItem.Icon>
                 </MenuItem>
                 <Separator />
+                <MenuItem x:Name="CtxGameSettings" Header="Game settings…">
+                  <MenuItem.Icon>
+                    <TextBlock Text="⚙" FontSize="13" Foreground="{StaticResource MutedBrush}"
+                               HorizontalAlignment="Center" VerticalAlignment="Center" />
+                  </MenuItem.Icon>
+                </MenuItem>
+                <Separator />
                 <MenuItem x:Name="CtxRemove" Header="Remove from library"
                           Foreground="{StaticResource DangerHoverBrush}">
                   <MenuItem.Icon>
@@ -191,27 +206,19 @@ SPDX-License-Identifier: GPL-2.0-or-later
                     <StackPanel Spacing="14">
                       <TextBlock x:Name="EmulationSectionTitle" Classes="sectionTitle" Text="EMULATION" />
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="CpuEngineLabel" Text="CPU engine" FontSize="13" />
-                          <TextBlock x:Name="CpuEngineDesc" Text="Execution engine used to run game code."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ComboBox Grid.Column="1" x:Name="CpuEngineBox" Width="160" SelectedIndex="0"
+                      <local:SettingRow x:Name="CpuEngineRow" Label="CPU engine"
+                                        Description="Execution engine used to run game code.">
+                        <ComboBox x:Name="CpuEngineBox" Width="160" SelectedIndex="0"
                                   VerticalAlignment="Center" CornerRadius="8">
                           <ComboBoxItem x:Name="CpuEngineNativeItem" Content="Native" />
                         </ComboBox>
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="StrictLabel" Text="Strict dynlib resolution" FontSize="13" />
-                          <TextBlock x:Name="StrictDesc" Text="Fail the launch when an imported symbol cannot be resolved."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="StrictToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="StrictRow" Label="Strict dynlib resolution"
+                                        Description="Fail the launch when an imported symbol cannot be resolved.">
+                        <ToggleSwitch x:Name="StrictToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
                     </StackPanel>
                   </Border>
 
@@ -219,13 +226,9 @@ SPDX-License-Identifier: GPL-2.0-or-later
                     <StackPanel Spacing="14">
                       <TextBlock x:Name="LoggingSectionTitle" Classes="sectionTitle" Text="LOGGING" />
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="LogLevelLabel" Text="Log level" FontSize="13" />
-                          <TextBlock x:Name="LogLevelDesc" Text="Verbosity of the emulator console output."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ComboBox Grid.Column="1" x:Name="LogLevelBox" Width="160" SelectedIndex="2"
+                      <local:SettingRow x:Name="LogLevelRow" Label="Log level"
+                                        Description="Verbosity of the emulator console output.">
+                        <ComboBox x:Name="LogLevelBox" Width="160" SelectedIndex="2"
                                   VerticalAlignment="Center" CornerRadius="8">
                           <ComboBoxItem x:Name="LogLevelTraceItem" Content="Trace" />
                           <ComboBoxItem x:Name="LogLevelDebugItem" Content="Debug" />
@@ -234,49 +237,32 @@ SPDX-License-Identifier: GPL-2.0-or-later
                           <ComboBoxItem x:Name="LogLevelErrorItem" Content="Error" />
                           <ComboBoxItem x:Name="LogLevelCriticalItem" Content="Critical" />
                         </ComboBox>
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="TraceImportsLabel" Text="Import trace limit" FontSize="13" />
-                          <TextBlock x:Name="TraceImportsDesc" Text="Trace the first N imports per module (0 = off)."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <NumericUpDown Grid.Column="1" x:Name="TraceImportsBox" Width="160" Minimum="0"
+                      <local:SettingRow x:Name="TraceImportsRow" Label="Import trace limit"
+                                        Description="Trace the first N imports per module (0 = off).">
+                        <NumericUpDown x:Name="TraceImportsBox" Width="160" Minimum="0"
                                        Maximum="4096" Increment="16" Value="0" FormatString="0"
                                        VerticalAlignment="Center" CornerRadius="8" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="LogToFileLabel" Text="Log to file" FontSize="13" />
-                          <TextBlock x:Name="LogToFileDesc" Text="Mirror emulator output to a log file."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="LogToFileToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="LogToFileRow" Label="Log to file"
+                                        Description="Mirror emulator output to a log file.">
+                        <ToggleSwitch x:Name="LogToFileToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="LogFilePathLabel" Text="Log file path" FontSize="13" />
-                          <TextBlock x:Name="LogFilePathText" Text="No custom path"
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <Button Grid.Column="1" x:Name="SelectLogFilePathButton" Classes="ghost" Content="Select…"
+                      <local:SettingRow x:Name="LogFilePathRow" Label="Log file path"
+                                        Description="No custom path">
+                        <Button x:Name="SelectLogFilePathButton" Classes="ghost" Content="Select…"
                                 VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="OverrideLogFileLabel" Text="Override log file" FontSize="13" />
-                          <TextBlock x:Name="OverrideLogFileDesc"
-                                     Text="Use the exact file path instead of appending title ID and timestamp."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="OverrideLogFileToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="OverrideLogFileRow" Label="Override log file"
+                                        Description="Use the exact file path instead of appending title ID and timestamp.">
+                        <ToggleSwitch x:Name="OverrideLogFileToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
                     </StackPanel>
                   </Border>
 
@@ -284,37 +270,30 @@ SPDX-License-Identifier: GPL-2.0-or-later
                     <StackPanel Spacing="14">
                       <TextBlock x:Name="LauncherSectionTitle" Classes="sectionTitle" Text="LAUNCHER" />
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="LanguageLabel" Text="Emulator language" FontSize="13" />
-                          <TextBlock x:Name="LanguageDesc"
-                                     Text="Language used throughout the launcher. Applies immediately."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ComboBox Grid.Column="1" x:Name="LanguageBox" Width="160"
+                      <local:SettingRow x:Name="LanguageRow" Label="Emulator language"
+                                        Description="Language used throughout the launcher. Applies immediately.">
+                        <ComboBox x:Name="LanguageBox" Width="160"
                                   VerticalAlignment="Center" CornerRadius="8"
                                   DisplayMemberBinding="{Binding NativeName}" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="TitleMusicLabel" Text="Title music" FontSize="13" />
-                          <TextBlock x:Name="TitleMusicDesc" Text="Loop the selected game's preview music in the library."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="TitleMusicToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="TitleMusicRow" Label="Title music"
+                                        Description="Loop the selected game's preview music in the library.">
+                        <ToggleSwitch x:Name="TitleMusicToggle" OnContent="On" OffContent="Off"
                                       IsChecked="True" VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock x:Name="DiscordLabel" Text="Discord presence" FontSize="13" />
-                          <TextBlock x:Name="DiscordDesc" Text="Show the running game on your Discord profile."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="DiscordToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="DiscordRow" Label="Discord presence"
+                                        Description="Show the running game on your Discord profile.">
+                        <ToggleSwitch x:Name="DiscordToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
+
+                      <local:SettingRow x:Name="AutoUpdateRow" Label="Check for updates on startup"
+                                        Description="Checks GitHub without delaying startup.">
+                        <ToggleSwitch x:Name="AutoUpdateToggle" OnContent="On" OffContent="Off"
+                                      IsChecked="True" VerticalAlignment="Center" />
+                      </local:SettingRow>
                     </StackPanel>
                   </Border>
                   <Border Classes="card">
@@ -322,6 +301,40 @@ SPDX-License-Identifier: GPL-2.0-or-later
                       <TextBlock x:Name="AboutSectionTitle"
                                 Classes="sectionTitle"
                                 Text="ABOUT" />
+
+                      <!--Latest commit info-->
+                      <Grid ColumnDefinitions="*,Auto">
+                        <StackPanel Grid.Column="0" Orientation="Horizontal" Spacing="8" VerticalAlignment="Center">
+                          <Image Source="avares://SharpEmu.GUI/Assets/commit-icon.png"
+                                    Width="24" Height="24" VerticalAlignment="Center" />
+                          <StackPanel Spacing="2" VerticalAlignment="Center">
+                            <TextBlock x:Name="LatestCommitLabel" Text="Latest commit" FontSize="13"/>
+                            <TextBlock x:Name="LatestCommitDescription" Text="Latest commit on the main branch" FontSize="11" Foreground="{StaticResource MutedBrush}"/>
+                          </StackPanel>
+                        </StackPanel>
+
+                        <Button Grid.Column="1" x:Name="LatestCommitHashText" Classes="ghost"
+                          Content="Loading…" FontSize="12" FontFamily="Consolas,monospace"
+                          VerticalAlignment="Center" IsEnabled="False" />
+
+                      </Grid>
+
+                      <!--Update-->
+                      <Grid ColumnDefinitions="*,Auto">
+                        <StackPanel Grid.Column="0" Orientation="Horizontal" Spacing="8" VerticalAlignment="Center">
+                          <Image Source="avares://SharpEmu.GUI/Assets/update-icon.png"
+                                    Width="24"
+                                    Height="24"
+                                    VerticalAlignment="Center" />
+                          <StackPanel Spacing="2" VerticalAlignment="Center">
+                            <TextBlock x:Name="UpdateLabel" Text="Updates" FontSize="13" />
+                            <TextBlock x:Name="UpdateStatusText" Text="Current build: dev" FontSize="11"
+                                      Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
+                          </StackPanel>
+                        </StackPanel>
+                        <Button Grid.Column="1" x:Name="UpdateButton" Classes="ghost"
+                                Content="Check for updates" VerticalAlignment="Center" />
+                      </Grid>
                       
                       <!--Github-->
                       <Grid ColumnDefinitions="*,Auto">
@@ -398,71 +411,53 @@ SPDX-License-Identifier: GPL-2.0-or-later
                                  Text="Switches passed to the emulator as environment variables at launch."
                                  FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock Text="SHARPEMU_BTHID_UNAVAILABLE" FontSize="13" FontFamily="Consolas,monospace" />
-                          <TextBlock x:Name="EnvBthidDesc"
-                                     Text="Report Bluetooth HID as unavailable for titles whose wheel/FFB middleware polls forever.&#10;Leave off normally. Some titles freeze when init fails."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="EnvBthidToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="EnvBthidRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_BTHID_UNAVAILABLE"
+                                        Description="Report Bluetooth HID as unavailable for titles whose wheel/FFB middleware polls forever.&#10;Leave off normally. Some titles freeze when init fails.">
+                        <ToggleSwitch x:Name="EnvBthidToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock Text="SHARPEMU_DISABLE_IMPORT_LOOP_GUARD" FontSize="13" FontFamily="Consolas,monospace" />
-                          <TextBlock x:Name="EnvLoopGuardDesc"
-                                     Text="Do not force quit titles that repeat the same call for too long.&#10;Try this when a game exits on its own while loading."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="EnvLoopGuardToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="EnvLoopGuardRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_DISABLE_IMPORT_LOOP_GUARD"
+                                        Description="Do not force quit titles that repeat the same call for too long.&#10;Try this when a game exits on its own while loading.">
+                        <ToggleSwitch x:Name="EnvLoopGuardToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock Text="SHARPEMU_VK_VALIDATION" FontSize="13" FontFamily="Consolas,monospace" />
-                          <TextBlock x:Name="EnvVkValidationDesc"
-                                     Text="Enable Vulkan validation layers for GPU debugging.&#10;Slow. Requires the Vulkan SDK to be installed."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="EnvVkValidationToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="EnvWritableApp0Row" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_WRITABLE_APP0"
+                                        Description="Allow titles to create and write files inside their install folder.&#10;Needed by unpackaged dumps that write their save or config data under /app0.">
+                        <ToggleSwitch x:Name="EnvWritableApp0Toggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock Text="SHARPEMU_DUMP_SPIRV" FontSize="13" FontFamily="Consolas,monospace" />
-                          <TextBlock x:Name="EnvDumpSpirvDesc"
-                                     Text="Dump AGC shaders and their SPIR-V translations to the shader-dumps folder.&#10;Use when reporting shader or rendering bugs."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="EnvDumpSpirvToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="EnvVkValidationRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_VK_VALIDATION"
+                                        Description="Enable Vulkan validation layers for GPU debugging.&#10;Slow. Requires the Vulkan SDK to be installed.">
+                        <ToggleSwitch x:Name="EnvVkValidationToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock Text="SHARPEMU_LOG_DIRECT_MEMORY" FontSize="13" FontFamily="Consolas,monospace" />
-                          <TextBlock x:Name="EnvLogDirectMemoryDesc"
-                                     Text="Log direct memory allocations and failures to the console.&#10;Use when a game aborts or exits during boot."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="EnvLogDirectMemoryToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="EnvDumpSpirvRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_DUMP_SPIRV"
+                                        Description="Dump AGC shaders and their SPIR-V translations to the shader-dumps folder.&#10;Use when reporting shader or rendering bugs.">
+                        <ToggleSwitch x:Name="EnvDumpSpirvToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
 
-                      <Grid ColumnDefinitions="*,Auto">
-                        <StackPanel VerticalAlignment="Center" Spacing="2" Margin="0,0,16,0">
-                          <TextBlock Text="SHARPEMU_LOG_NP" FontSize="13" FontFamily="Consolas,monospace" />
-                          <TextBlock x:Name="EnvLogNpDesc"
-                                     Text="Log NP (PlayStation Network) library calls to the console."
-                                     FontSize="11" Foreground="{StaticResource MutedBrush}" TextWrapping="Wrap" />
-                        </StackPanel>
-                        <ToggleSwitch Grid.Column="1" x:Name="EnvLogNpToggle" OnContent="On" OffContent="Off"
+                      <local:SettingRow x:Name="EnvLogDirectMemoryRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_LOG_DIRECT_MEMORY"
+                                        Description="Log direct memory allocations and failures to the console.&#10;Use when a game aborts or exits during boot.">
+                        <ToggleSwitch x:Name="EnvLogDirectMemoryToggle" OnContent="On" OffContent="Off"
                                       VerticalAlignment="Center" />
-                      </Grid>
+                      </local:SettingRow>
+
+                      <local:SettingRow x:Name="EnvLogIoRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_LOG_IO"
+                                        Description="Log file open, read, and path-resolve activity to the console.&#10;Use when a game cannot find its data files during boot.">
+                        <ToggleSwitch x:Name="EnvLogIoToggle" OnContent="On" OffContent="Off"
+                                      VerticalAlignment="Center" />
+                      </local:SettingRow>
+
+                      <local:SettingRow x:Name="EnvLogNpRow" LabelFontFamily="Consolas,monospace" Label="SHARPEMU_LOG_NP"
+                                        Description="Log NP (PlayStation Network) library calls to the console.">
+                        <ToggleSwitch x:Name="EnvLogNpToggle" OnContent="On" OffContent="Off"
+                                      VerticalAlignment="Center" />
+                      </local:SettingRow>
                     </StackPanel>
                   </Border>
 
@@ -502,7 +497,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
       </Border>
 
       <!-- Launch bar; capped so it does not sprawl on a maximized window. -->
-      <Border Grid.Row="3" Classes="card" Margin="0,12,0,0" Padding="14" MaxWidth="1280">
+      <Border Grid.Row="3" x:Name="LaunchBar" Classes="card" Margin="0,12,0,0" Padding="14" MaxWidth="1280">
         <StackPanel Spacing="14">
           <Grid ColumnDefinitions="Auto,*,Auto">
 
@@ -567,6 +562,66 @@ SPDX-License-Identifier: GPL-2.0-or-later
       </Border>
     </Grid>
 
+    <!-- Avalonia's regular overlay layer cannot appear over a native child
+         HWND/X11/Metal surface. Keep the running-session controls in a native
+         popup so the game reaches the bottom status bar without losing Stop. -->
+    <primitives:Popup x:Name="SessionBarPopup"
+                      IsOpen="False"
+                      PlacementTarget="{Binding #GameView}"
+                      Placement="Bottom"
+                      VerticalOffset="-66"
+                      Topmost="True"
+                      ShouldUseOverlayLayer="False"
+                      TakesFocusFromNativeControl="False"
+                      IsLightDismissEnabled="False">
+      <Border Classes="card" Width="598" Height="58" CornerRadius="16" Padding="14,8">
+        <Grid ColumnDefinitions="*,Auto">
+          <StackPanel Spacing="3" VerticalAlignment="Center">
+            <StackPanel Orientation="Horizontal" Spacing="8">
+              <TextBlock x:Name="SessionGameTitle" Text="GAME RUNNING" FontSize="13" FontWeight="SemiBold"
+                         MaxWidth="240" TextTrimming="CharacterEllipsis" VerticalAlignment="Center" />
+              <Border Classes="badge running" VerticalAlignment="Center">
+                <TextBlock Text="RUNNING" FontSize="9" FontWeight="Bold" LetterSpacing="1"
+                           Foreground="{StaticResource SuccessBrush}" />
+              </Border>
+            </StackPanel>
+            <StackPanel Orientation="Horizontal" Spacing="7">
+              <Border x:Name="SessionF11Badge" Classes="badge key" VerticalAlignment="Center">
+                <TextBlock Text="F11" FontSize="9" FontWeight="Bold"
+                           Foreground="{StaticResource InfoBrush}" />
+              </Border>
+              <TextBlock x:Name="SessionHintText" Text="Fullscreen" FontSize="11"
+                         Foreground="{StaticResource MutedBrush}" VerticalAlignment="Center" />
+            </StackPanel>
+          </StackPanel>
+          <StackPanel Grid.Column="1" Orientation="Horizontal" Spacing="8" VerticalAlignment="Center">
+            <Button x:Name="SessionConsoleButton" Classes="ghost" Content="≡ Console" />
+            <Button x:Name="SessionStopButton" Classes="danger" Content="■  Stop" IsEnabled="False" />
+          </StackPanel>
+        </Grid>
+      </Border>
+    </primitives:Popup>
+
+    <!-- This is a native popup rather than an Avalonia overlay because the
+         emulated Vulkan surface is a native child window. -->
+    <primitives:Popup x:Name="SessionLoadingPopup"
+                      IsOpen="False"
+                      PlacementTarget="{Binding #GameView}"
+                      Placement="Center"
+                      Topmost="True"
+                      ShouldUseOverlayLayer="False"
+                      TakesFocusFromNativeControl="False"
+                      IsLightDismissEnabled="False">
+      <Border Classes="card" Width="380" CornerRadius="18" Padding="22,18">
+        <StackPanel Spacing="12">
+          <TextBlock x:Name="SessionLoadingTitle" Text="Loading game" FontSize="16" FontWeight="SemiBold" />
+          <TextBlock x:Name="SessionLoadingDetail" Text="Preparing the emulation session..." FontSize="12"
+                     Foreground="{StaticResource MutedBrush}" TextTrimming="CharacterEllipsis" />
+          <ProgressBar IsIndeterminate="True" Height="5" />
+        </StackPanel>
+      </Border>
+    </primitives:Popup>
+
     <!-- Status bar -->
     <Grid x:Name="StatusBar" Grid.Row="2" Height="32" Background="{StaticResource ChromeBrush}"
           ColumnDefinitions="*,Auto">

src/SharpEmu.GUI/PerGameSettings.cs

@@ -0,0 +1,115 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace SharpEmu.GUI;
+
+public sealed class PerGameSettings
+{
+    private static readonly JsonSerializerOptions SerializerOptions = new()
+    {
+        WriteIndented = true,
+    };
+
+    public string? LogLevel { get; set; }
+
+    public int? ImportTraceLimit { get; set; }
+
+    public bool? StrictDynlibResolution { get; set; }
+
+    public bool? LogToFile { get; set; }
+
+    public List<string>? EnvironmentToggles { get; set; }
+
+    [JsonIgnore]
+    public bool IsEmpty =>
+        LogLevel is null &&
+        ImportTraceLimit is null &&
+        StrictDynlibResolution is null &&
+        LogToFile is null &&
+        EnvironmentToggles is null;
+
+    public static string DirectoryPath =>
+        Path.Combine(AppContext.BaseDirectory, "user", "custom_configs");
+
+    public static string PathFor(string titleId) =>
+        Path.Combine(DirectoryPath, SanitizeTitleId(titleId) + ".json");
+
+    public static PerGameSettings? Load(string? titleId)
+    {
+        if (string.IsNullOrWhiteSpace(titleId))
+        {
+            return null;
+        }
+
+        try
+        {
+            var path = PathFor(titleId);
+            if (File.Exists(path))
+            {
+                return JsonSerializer.Deserialize<PerGameSettings>(File.ReadAllText(path), SerializerOptions);
+            }
+        }
+        catch (Exception)
+        {
+        }
+
+        return null;
+    }
+
+    public void Save(string titleId)
+    {
+        if (string.IsNullOrWhiteSpace(titleId))
+        {
+            return;
+        }
+
+        try
+        {
+            var path = PathFor(titleId);
+            if (IsEmpty)
+            {
+                if (File.Exists(path))
+                {
+                    File.Delete(path);
+                }
+
+                return;
+            }
+
+            Directory.CreateDirectory(DirectoryPath);
+            File.WriteAllText(path, JsonSerializer.Serialize(this, SerializerOptions));
+        }
+        catch (Exception)
+        {
+        }
+    }
+
+    private static string SanitizeTitleId(string titleId)
+    {
+        var trimmed = titleId.Trim();
+        foreach (var invalid in Path.GetInvalidFileNameChars())
+        {
+            trimmed = trimmed.Replace(invalid, '_');
+        }
+
+        return trimmed.Length == 0 ? "UNKNOWN" : trimmed;
+    }
+}
+
+public sealed record EffectiveLaunchSettings(
+    string LogLevel,
+    int ImportTraceLimit,
+    bool StrictDynlibResolution,
+    bool LogToFile,
+    IReadOnlyList<string> EnvironmentToggles)
+{
+    public static EffectiveLaunchSettings Resolve(GuiSettings global, PerGameSettings? perGame) => new(
+        perGame?.LogLevel ?? global.LogLevel,
+        perGame?.ImportTraceLimit ?? global.ImportTraceLimit,
+        perGame?.StrictDynlibResolution ?? global.StrictDynlibResolution,
+        perGame?.LogToFile ?? global.LogToFile,
+        perGame?.EnvironmentToggles ?? global.EnvironmentToggles);
+}

src/SharpEmu.GUI/PerGameSettingsDialog.cs

@@ -0,0 +1,205 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Layout;
+using Avalonia.Media;
+
+namespace SharpEmu.GUI;
+
+public sealed class PerGameSettingsDialog : Window
+{
+    private static readonly string[] LogLevels =
+        { "Trace", "Debug", "Info", "Warning", "Error", "Critical" };
+
+    private static readonly string[] EnvToggles =
+    {
+        "SHARPEMU_BTHID_UNAVAILABLE",
+        "SHARPEMU_DISABLE_IMPORT_LOOP_GUARD",
+        "SHARPEMU_WRITABLE_APP0",
+        "SHARPEMU_VK_VALIDATION",
+        "SHARPEMU_DUMP_SPIRV",
+        "SHARPEMU_LOG_DIRECT_MEMORY",
+        "SHARPEMU_LOG_IO",
+        "SHARPEMU_LOG_NP",
+    };
+
+    private readonly string _titleId;
+
+    private readonly SettingRow _logLevelRow;
+    private readonly ComboBox _logLevel = new() { ItemsSource = LogLevels, Width = 160 };
+
+    private readonly SettingRow _traceRow;
+    private readonly NumericUpDown _trace = new()
+    {
+        Minimum = 0, Maximum = 4096, Increment = 16, Width = 160, FormatString = "0",
+    };
+
+    private readonly SettingRow _strictRow;
+    private readonly ToggleSwitch _strict = new();
+
+    private readonly SettingRow _logToFileRow;
+    private readonly ToggleSwitch _logToFile = new();
+
+    private readonly SettingRow _envRow;
+    private readonly StackPanel _envList = new() { Orientation = Orientation.Vertical, Spacing = 8, Margin = new(0, 4, 0, 0) };
+    private readonly List<(string Name, ToggleSwitch Box)> _envBoxes = new();
+
+    public PerGameSettingsDialog(string titleId, string displayName, GuiSettings global)
+    {
+        _titleId = titleId;
+        var loc = Localization.Instance;
+
+        Title = loc.Format("PerGame.Title", displayName, titleId);
+        Width = 520;
+        MaxHeight = 720;
+        SizeToContent = SizeToContent.Height;
+        WindowStartupLocation = WindowStartupLocation.CenterOwner;
+        CanResize = false;
+
+        Background = new SolidColorBrush(Color.Parse("#0D1017"));
+
+        _strict.OnContent = _logToFile.OnContent = loc.Get("Common.On");
+        _strict.OffContent = _logToFile.OffContent = loc.Get("Common.Off");
+
+        _logLevelRow = Row(loc.Get("Options.LogLevel.Label"), loc.Get("Options.LogLevel.Desc"), _logLevel);
+        _traceRow = Row(loc.Get("Options.TraceImports.Label"), loc.Get("Options.TraceImports.Desc"), _trace);
+        _strictRow = Row(loc.Get("Options.Strict.Label"), loc.Get("Options.Strict.Desc"), _strict);
+        _logToFileRow = Row(loc.Get("Options.LogToFile.Label"), loc.Get("Options.LogToFile.Desc"), _logToFile);
+        _envRow = new SettingRow
+        {
+            Label = loc.Get("PerGame.EnvToggles.Label"),
+            Description = loc.Get("PerGame.EnvToggles.Desc"),
+            ShowOverride = true,
+        };
+
+        foreach (var name in EnvToggles)
+        {
+            var box = new ToggleSwitch { OnContent = name, OffContent = name };
+            _envBoxes.Add((name, box));
+            _envList.Children.Add(box);
+        }
+
+        var content = new StackPanel { Orientation = Orientation.Vertical, Spacing = 12, Margin = new(16) };
+        content.Children.Add(new TextBlock
+        {
+            Text = loc.Get("PerGame.InheritNote"),
+            Foreground = new SolidColorBrush(Color.Parse("#8B94A7")),
+            FontSize = 12,
+        });
+        content.Children.Add(Card(loc.Get("Options.Section.Emulation"), _strictRow));
+        content.Children.Add(Card(loc.Get("Options.Section.Logging"), _logLevelRow, _traceRow, _logToFileRow));
+        content.Children.Add(Card(loc.Get("Options.Section.Environment"), _envRow, _envList));
+
+        var save = new Button { Content = loc.Get("Common.Save"), Classes = { "accent" } };
+        var cancel = new Button { Content = loc.Get("Common.Cancel"), Classes = { "ghost" } };
+        save.Click += (_, _) => { Persist(); Close(); };
+        cancel.Click += (_, _) => Close();
+
+        var buttonBar = new Border
+        {
+            BorderBrush = new SolidColorBrush(Color.Parse("#8B94A7")) { Opacity = 0.25 },
+            BorderThickness = new Thickness(0, 1, 0, 0),
+            Padding = new(16),
+            Child = new StackPanel
+            {
+                Orientation = Orientation.Horizontal,
+                Spacing = 8,
+                HorizontalAlignment = HorizontalAlignment.Right,
+                Children = { cancel, save },
+            },
+        };
+
+        var root = new Grid { RowDefinitions = new RowDefinitions("*,Auto") };
+        var scroller = new ScrollViewer { Content = content };
+        Grid.SetRow(scroller, 0);
+        Grid.SetRow(buttonBar, 1);
+        root.Children.Add(scroller);
+        root.Children.Add(buttonBar);
+        Content = root;
+
+        LoadValues(global);
+        _envRow.PropertyChanged += (_, e) =>
+        {
+            if (e.Property == SettingRow.IsOverriddenProperty)
+            {
+                _envList.IsEnabled = _envRow.IsOverridden;
+            }
+        };
+        _envList.IsEnabled = _envRow.IsOverridden;
+    }
+
+    private static SettingRow Row(string label, string description, Control value) => new()
+    {
+        Label = label,
+        Description = description,
+        ShowOverride = true,
+        Content = value,
+    };
+
+    private static Border Card(string title, params Control[] rows)
+    {
+        var stack = new StackPanel { Orientation = Orientation.Vertical, Spacing = 14 };
+        stack.Children.Add(new TextBlock { Text = title, Classes = { "sectionTitle" } });
+        foreach (var row in rows)
+        {
+            stack.Children.Add(row);
+        }
+
+        var card = new Border { Child = stack };
+        card.Classes.Add("card");
+        return card;
+    }
+
+    private void LoadValues(GuiSettings global)
+    {
+        _logLevel.SelectedItem = Array.IndexOf(LogLevels, global.LogLevel) >= 0 ? global.LogLevel : "Info";
+        _trace.Value = global.ImportTraceLimit;
+        _strict.IsChecked = global.StrictDynlibResolution;
+        _logToFile.IsChecked = global.LogToFile;
+        foreach (var (name, box) in _envBoxes)
+        {
+            box.IsChecked = global.EnvironmentToggles.Contains(name);
+        }
+
+        var existing = PerGameSettings.Load(_titleId);
+        if (existing is null)
+        {
+            return;
+        }
+
+        if (existing.LogLevel is { } level && Array.IndexOf(LogLevels, level) >= 0)
+        {
+            _logLevelRow.IsOverridden = true;
+            _logLevel.SelectedItem = level;
+        }
+
+        if (existing.ImportTraceLimit is { } t) { _traceRow.IsOverridden = true; _trace.Value = t; }
+        if (existing.StrictDynlibResolution is { } s) { _strictRow.IsOverridden = true; _strict.IsChecked = s; }
+        if (existing.LogToFile is { } l) { _logToFileRow.IsOverridden = true; _logToFile.IsChecked = l; }
+        if (existing.EnvironmentToggles is { } env)
+        {
+            _envRow.IsOverridden = true;
+            foreach (var (name, box) in _envBoxes)
+            {
+                box.IsChecked = env.Contains(name);
+            }
+        }
+    }
+
+    private void Persist()
+    {
+        var settings = new PerGameSettings
+        {
+            LogLevel = _logLevelRow.IsOverridden ? _logLevel.SelectedItem as string : null,
+            ImportTraceLimit = _traceRow.IsOverridden ? (int)(_trace.Value ?? 0) : null,
+            StrictDynlibResolution = _strictRow.IsOverridden ? _strict.IsChecked == true : null,
+            LogToFile = _logToFileRow.IsOverridden ? _logToFile.IsChecked == true : null,
+            EnvironmentToggles = _envRow.IsOverridden
+                ? _envBoxes.Where(e => e.Box.IsChecked == true).Select(e => e.Name).ToList()
+                : null,
+        };
+        settings.Save(_titleId);
+    }
+}

src/SharpEmu.GUI/SettingRow.cs

@@ -0,0 +1,101 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Controls.Presenters;
+using Avalonia.Controls.Primitives;
+using Avalonia.Data;
+using Avalonia.Media;
+
+namespace SharpEmu.GUI;
+
+public sealed class SettingRow : ContentControl
+{
+    public static readonly StyledProperty<string?> LabelProperty =
+        AvaloniaProperty.Register<SettingRow, string?>(nameof(Label));
+
+    public static readonly StyledProperty<string?> DescriptionProperty =
+        AvaloniaProperty.Register<SettingRow, string?>(nameof(Description));
+
+    public static readonly StyledProperty<bool> ShowOverrideProperty =
+        AvaloniaProperty.Register<SettingRow, bool>(nameof(ShowOverride));
+
+    public static readonly StyledProperty<bool> IsOverriddenProperty =
+        AvaloniaProperty.Register<SettingRow, bool>(
+            nameof(IsOverridden), defaultBindingMode: BindingMode.TwoWay);
+
+    public static readonly StyledProperty<FontFamily?> LabelFontFamilyProperty =
+        AvaloniaProperty.Register<SettingRow, FontFamily?>(nameof(LabelFontFamily));
+
+    private ContentPresenter? _slot;
+    private TextBlock? _label;
+
+    public string? Label
+    {
+        get => GetValue(LabelProperty);
+        set => SetValue(LabelProperty, value);
+    }
+
+    public string? Description
+    {
+        get => GetValue(DescriptionProperty);
+        set => SetValue(DescriptionProperty, value);
+    }
+
+    public bool ShowOverride
+    {
+        get => GetValue(ShowOverrideProperty);
+        set => SetValue(ShowOverrideProperty, value);
+    }
+
+    public bool IsOverridden
+    {
+        get => GetValue(IsOverriddenProperty);
+        set => SetValue(IsOverriddenProperty, value);
+    }
+
+    public FontFamily? LabelFontFamily
+    {
+        get => GetValue(LabelFontFamilyProperty);
+        set => SetValue(LabelFontFamilyProperty, value);
+    }
+
+    protected override void OnApplyTemplate(TemplateAppliedEventArgs e)
+    {
+        base.OnApplyTemplate(e);
+        _slot = e.NameScope.Find<ContentPresenter>("PART_Slot");
+        _label = e.NameScope.Find<TextBlock>("PART_Label");
+        UpdateSlotEnabled();
+        UpdateLabelFont();
+    }
+
+    protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)
+    {
+        base.OnPropertyChanged(change);
+        if (change.Property == ShowOverrideProperty || change.Property == IsOverriddenProperty)
+        {
+            UpdateSlotEnabled();
+        }
+        else if (change.Property == LabelFontFamilyProperty)
+        {
+            UpdateLabelFont();
+        }
+    }
+
+    private void UpdateLabelFont()
+    {
+        if (_label is not null && LabelFontFamily is { } family)
+        {
+            _label.FontFamily = family;
+        }
+    }
+
+    private void UpdateSlotEnabled()
+    {
+        if (_slot is not null)
+        {
+            _slot.IsEnabled = !ShowOverride || IsOverridden;
+        }
+    }
+}