Merge remote-tracking branch 'origin/main' into pr-fix-121

# Conflicts:
#	.github/workflows/source-check.yml
#	NOTICE.md
#	README.md
#	docs/COMPLIANCE.md
#	docs/PLATFORM_IDENTITY.md
#	docs/SETUP.md
#	docs/TROUBLESHOOTING.md
#	patches/cocotron.patch
#	patches/metal--deps--indium.patch
#	tools/exec-guest.py
#	tools/run-riot-client.sh

docs/COMPLIANCE.md

@@ -2,14 +2,21 @@
 
 This project is an unofficial compatibility layer for running the macOS League of Legends
 client on Linux through Darling. It is not affiliated with, endorsed by, or sponsored by Riot
-Games, Inc.
+Games, Inc. See [interoperability and compliance scope](INTEROPERABILITY.md) for the project's
+practices on interoperability, copyright, access controls and trademarks. Neither document is
+legal advice.
 
 ## Scope
 
 - The project is about compatibility: making the client run, render and behave correctly on
   Linux.
-- It does not aim to circumvent DRM, anti-cheat, licensing, telemetry, or other platform
-  security controls, and it does not distribute a game client, game assets, or account data.
+- It does not aim to circumvent DRM, anti-cheat, licensing, telemetry, authentication, or other
+  platform security controls, and it does not distribute a game client, game assets, or account
+  data.
+- It does not forge authentication tokens or server-side integrity attestations. The synthetic
+  platform identity is local compatibility metadata, not an Apple-issued identifier or a Riot
+  credential. This repository does not pass it as Riot authentication data; the official
+  client's later handling of guest-visible values is outside this repository's scope.
 - Do not describe or present the project as a tool for evading detection, preventing bans,
   bypassing DRM, or defeating anti-cheat. Do not promise that an account will not be banned.
 
@@ -27,6 +34,19 @@ Technical facts can be described precisely without framing the work as evasion.
 touches a client check or a platform identity, say what it does and why it is needed for
 compatibility.
 
+## Known local limitations
+
+- Darling has no macOS MAC/Seatbelt/AMFI framework. The compatibility layer reports the local
+  `___mac_syscall` probe as satisfied so Chromium/CEF can start. This does **not** implement a
+  sandbox and does not make the guest secure. Treat the guest as unsandboxed and do not run
+  untrusted content. It does not interact with Riot's servers or bypass a Riot control.
+- Platform-identity values generated by `tools/configure-darling-platform.py` are synthetic and
+  local. They are not Apple-issued identifiers, credentials or authentication tokens; do not use
+  them with Apple services or to impersonate real hardware.
+- The opt-in hide helper manages local client windows while a match runs. The opt-in close helper
+  terminates eligible League client UI processes. Neither helper patches client binaries, CEF,
+  anti-cheat or DRM, and both helpers are off by default.
+
 ## Assets and third-party material
 
 - Do not add or link third-party game assets: logos, icons, fonts, screenshots, gameplay
@@ -34,6 +54,9 @@ compatibility.
 - Project icons and artwork must be original. Forks must use their own name and icon; see the
   trademark notice in `README.md` and `NOTICE.md`.
 - Do not commit local prefixes, logs, tokens, captures, or compiled client/runtime binaries.
+- Keep upstream copyright, license and attribution notices.
+- Donations are voluntary and support the free tooling. They do not sell the game, a license,
+  access or priority.
 
 ## Pull requests and issues
 
@@ -43,7 +66,11 @@ compatibility.
   scope accurate, not about hiding technical details.
 - Contributions that add third-party assets or present the project as a DRM/anti-cheat
   circumvention tool are out of scope for this repository.
+- Sign off commits under the Developer Certificate of Origin; see
+  [`CONTRIBUTING.md`](../CONTRIBUTING.md). By contributing, you confirm that you have the right
+  to submit the work and license it under the project's terms.
 
 ## Note
 
-This document describes project scope and review expectations. It is not legal advice.
+This document describes project scope and review expectations. It is not legal advice. See
+[interoperability and compliance scope](INTEROPERABILITY.md) and [`NOTICE.md`](../NOTICE.md).

docs/INTEROPERABILITY.md

@@ -0,0 +1,176 @@
+# Interoperability and compliance scope
+
+> This document explains how the project stays within interoperability and
+> responsible-use practices. It is **not legal advice**. Software, contract and
+> platform rules are fact-specific and differ by country. Consult qualified
+> counsel before distributing, modifying or using this project.
+
+## 1. Purpose
+
+`darling-lol` (<https://github.com/lucannez64/darling-lol/>) is an unofficial
+interoperability effort. It applies source patches to
+[Darling](https://github.com/darlinghq/darling), a free-software macOS
+compatibility layer, so that the official macOS Riot client can run on
+x86-64 Linux. The user obtains the client from Riot and signs in through Riot's
+own client and services.
+
+The project is not a game, a game server, an account service, a launcher for
+pirated content, or a substitute for Riot's platform. It does not provide Riot
+accounts, authentication, matchmaking, payments, telemetry or game servers.
+
+## 2. What we distribute and what we do not
+
+We keep the project on the interoperability side by distributing only:
+
+- source patches for Darling, a free-software compatibility layer;
+- original integration, build and test tooling;
+- project artwork;
+- documentation and license notices.
+
+We do **not** distribute, bundle, mirror or sublicense:
+
+- the Riot client or game binaries;
+- game assets, art, audio, video, fonts or data;
+- account databases, tokens or credentials;
+- Riot installers or installers for pirated content.
+
+The user obtains the client from Riot and installs it through Riot's own
+installer. The project does not provide accounts, authentication, matchmaking,
+payments, telemetry or game servers, and it does not sell the game, a license,
+access or priority.
+
+## 3. Platform identity
+
+Darling needs macOS-like platform metadata. `tools/configure-darling-platform.py`
+can generate synthetic serial numbers, UUIDs and related fields, or import
+values supplied by the user, so that the guest environment is internally
+consistent.
+
+These values are **local compatibility metadata**:
+
+- they are not Apple-issued identifiers, credentials or authentication tokens;
+- they are not used with Apple services and should not be used to impersonate
+  real hardware;
+- this repository does not pass them to Riot as authentication data. The values
+  are exposed to guest applications through IOKit, and the official client's
+  later handling of them is outside this repository's scope. The official client
+  authenticates through Riot's own flow.
+
+See `docs/PLATFORM_IDENTITY.md` for the schema, validation rules and warnings.
+
+## 4. Local sandbox/AMFI probe
+
+Darling has no macOS MAC, Seatbelt or AMFI framework. Chromium/CEF, which the
+Riot client embeds, probes `___mac_syscall`. An `ENOSYS` response is treated as
+fatal and prevents CEF helper processes from starting. The compatibility layer
+therefore reports the local probe as satisfied. The relevant code and comments
+are in `patches/xnu.patch` (`mac_syscall.c`).
+
+This compatibility shim:
+
+- does not implement a sandbox and does not make the guest secure;
+- does not interact with Riot's servers or alter Riot's account, payment or
+  server-side integrity flows;
+- does not grant access to Riot's content or services.
+
+Treat the guest as **unsandboxed**. Do not run untrusted content inside it. This
+is a local compatibility limitation, not a claim of security. See
+`docs/COMPLIANCE.md` for the project's terminology and scope guidance.
+
+## 5. Copyright and licenses
+
+We keep the project's copyright and licensing position clear:
+
+- the game, client, code and assets remain Riot's; we do not reproduce, store,
+  distribute or commercialise them;
+- we distribute patches to free-software Darling and original tooling, not a
+  copy of the game or the upstream runtime;
+- each patch keeps the license and notices of the upstream file it modifies;
+  original tooling is GPL-3.0-only;
+- we keep the upstream license and attribution notices in the patched files and
+  describe the project's licensing position in `NOTICE.md`;
+- we do not remove copyright or license notices from patched files;
+- we review good-faith licensing and removal requests.
+
+We do not sell the game, a license, access or priority. Donations are voluntary
+and support development of the free tooling; they do not purchase the game or
+any Riot service.
+
+## 6. Access, authentication and integrity controls
+
+The project is designed for compatibility, not for defeating access,
+authentication, payment or integrity controls:
+
+- we do not provide tools or features whose purpose is to defeat those controls;
+- we do not forge authentication tokens, session data, account data or
+  server-side integrity attestations;
+- we do not proxy or emulate Riot accounts, matchmaking, payments, telemetry or
+  game servers;
+- we do not patch Riot's client or game binaries, CEF or anti-cheat;
+- we do not automate gameplay input or provide cheats;
+- the opt-in hide helper manages local client windows while a match runs; the
+  opt-in close helper terminates eligible League client UI processes. Both are
+  off by default and do not change client binaries, CEF or anti-cheat.
+
+The synthetic platform identity in §3 is local metadata; it is not a credential.
+This repository does not pass it as Riot authentication data.
+
+## 7. User agreements and account risk
+
+Use of the project is at your own risk. You must:
+
+- own a legitimate Riot account and obtain the client from Riot;
+- comply with Riot's terms and user agreement;
+- not cheat, exploit, automate gameplay or use the project to gain an unfair
+  advantage;
+- accept that Riot does not support this environment and may suspend or ban
+  accounts, including accounts used only for testing. Do not use a main or
+  ranked account.
+
+The project does not authorise any violation of Riot's terms. If you do not
+agree, do not use the project. Account restrictions are a real risk and are
+documented in the README announcement.
+
+## 8. Trademarks and presentation
+
+League of Legends and Riot Games are trademarks or registered trademarks of Riot
+Games, Inc. The names are used only to describe the compatibility target
+(nominative use). The project:
+
+- does not use Riot logos, game art or other Riot brand assets;
+- uses an original project mark;
+- is not affiliated, endorsed or sponsored by Riot Games;
+- asks forks to use their own name and icon and not to imply endorsement.
+
+See `NOTICE.md` and `docs/COMPLIANCE.md`.
+
+## 9. Historical material
+
+Earlier revisions of the repository included a third-party game logo and an
+embedded gameplay clip. They were removed from the current tree; the current
+tree uses an original project mark and contains no gameplay media. Git history
+and third-party forks may still contain those earlier revisions. They are not
+part of the current project, are not licensed by this project, and should not be
+reused. The project will review good-faith removal requests.
+
+## 10. Notices and contact
+
+For a licensing, trademark or interoperability question, contact the maintainer
+using the address in `README.md`, or open an issue in the repository. Include:
+
+- the repository URL, file or commit at issue;
+- the right or license you assert;
+- the action you request;
+- a way to contact you.
+
+For a formal copyright notice, use the hosting platform's copyright notice
+process. This document is not a designation of an agent for any platform and
+does not replace that process.
+
+## 11. No legal advice and no warranty
+
+This document is a technical and scope statement, not legal advice. The project
+is provided "as is", without warranty of any kind. Nothing here guarantees that
+a particular use is lawful in a particular country, that Riot will not restrict
+an account, or that a court or regulator will accept the project's position. If
+you need legal certainty, consult a lawyer qualified in your country.

docs/PLATFORM_IDENTITY.md

@@ -9,6 +9,14 @@ does not issue authentic Apple identities or change CPU, GPU, or security
 metadata. The overrides are for application compatibility; they are not intended
 to bypass anti-cheat, telemetry, licensing, or platform security controls.
 
+> **Synthetic, local metadata.** These values are not Apple-issued identifiers,
+> credentials or authentication tokens. Do not use them with Apple services or
+> to impersonate real hardware. This repository does not pass them to Riot as
+> authentication data; the values are exposed to guest applications through
+> IOKit, and the official client's later handling of them is outside this
+> repository's scope. See the
+> [interoperability and compliance scope](INTEROPERABILITY.md).
+
 Preview an OpenCore `config.plist`, a flat GenSMBIOS JSON file, or an existing
 `darling-smbios.conf` without changing the selected prefix:
 

docs/SETUP.md

@@ -78,6 +78,38 @@ opts in to Hyprland-only recovery of a default-prefix Riot session with no
 visible window; it is off by default. See [troubleshooting](TROUBLESHOOTING.md#riot-exits-and-league-reports-that-it-lost-its-connection)
 for the observed failures, recovery guards and NSURLSession limitations.
 
+`RCLOL_RECOVER_STALE_CLIENT=1` opts in to partial runtime recovery before
+launch. If `darlingserver` is alive, no game is running, no managed client
+window is visible and stale Riot/League/CEF processes at least 60 seconds old
+remain, the launcher stops only that client tree and reuses the runtime. It
+recognizes `LeagueClientUx`, `Riot Client` and `RiotClientServices` windows and
+preserves `darlingserver`, launchd/mldr, sockets and `.init.pid`; if X11/Xwayland
+properties cannot be inspected it does nothing. See
+[troubleshooting](TROUBLESHOOTING.md#client-remains-running-without-a-window).
+
+`RCLOL_CLEAN_STALE_HELPERS=1` runs a preflight before the match helper starts.
+It removes `close-league-client-in-game.py` and
+`hide-league-client-in-game.py` processes of this prefix whose parent is
+`init`/`systemd`, which means the launcher that started them has exited. A
+helper of a live launcher, another prefix, the game, Riot/League/CEF and
+`darlingserver` are preserved. It fails closed when a command line,
+environment, stat entry or parent cannot be read. See
+[troubleshooting](TROUBLESHOOTING.md#multiple-client-in-game-helpers).
+
+`RCLOL_CLIENT_IN_GAME_TRICKS=1` opts in to automatic client handling during a
+match. It reads `lol-user-experience` from the installed client's
+`LCULocalPreferences.yaml`: with `potatoModeEnabled: true`, it closes the client
+UI when `closeLeagueClientDuringGame: true`, and hides the managed
+`LeagueClientUx`/`Riot Client` X11 windows when that value is false. Missing or
+invalid preference values, disabled client optimizations and unreadable files
+select no action. The low-level `RCLOL_CLOSE_CLIENT_IN_GAME=1` and
+`RCLOL_HIDE_CLIENT_IN_GAME=1` switches remain available when the automatic
+switch is not set. The feature is off by default, requires X11/Xwayland, and
+does not patch client binaries, CEF or the game. The hide helper exits after ten
+minutes without a client or match once it has seen one. See
+[the troubleshooting measurement](TROUBLESHOOTING.md#automatic-client-handling-during-a-match)
+for the measured CPU effect and limitations.
+
 `RCLOL_FILTER_HOST_ENV=1` opts in to removing host desktop-session variables before
 the guest starts: `WAYLAND_DISPLAY`, `XDG_SESSION_*`, `XDG_CURRENT_DESKTOP`,
 GNOME/KDE/GDM, systemd, SSH agent, terminal, toolkit (`QT_*`, `GTK_*`, `GDK_*`),

docs/TROUBLESHOOTING.md

@@ -149,6 +149,41 @@ ownership or window information cannot be read. A hidden background client or
 download is restarted when recovery is enabled. Other desktop environments are
 not supported by this helper; recovery is off by default.
 
+For a live Darling runtime with no visible client window but stale Riot/League/
+CEF processes at least 60 seconds old, `RCLOL_RECOVER_STALE_CLIENT=1` performs a
+partial recovery before the next launch. It keeps `darlingserver`, launchd/mldr,
+sockets and `.init.pid`, stops only the stale client process tree, and then lets
+the normal launcher start the product again. It recognizes `LeagueClientUx`,
+`Riot Client` and `RiotClientServices` windows, does nothing while a game process
+is running or when a managed client window is visible, and fails closed when
+X11/Xwayland properties are missing or unreadable. This saves the Darling
+bootstrap but not the Riot Client/CEF startup itself. If no window appears
+afterward, use a full runtime shutdown/restart.
+
+### Multiple client-in-game helpers
+
+The close/hide helper is a long-lived watcher. If an earlier launcher exits
+while it remains, the next launch can start another copy; list them with:
+
+```sh
+pgrep -af 'close-league-client-in-game.py|hide-league-client-in-game.py'
+```
+
+To remove the orphaned copies before the next helper starts:
+
+```sh
+RCLOL_CLEAN_STALE_HELPERS=1 ./scripts/run.sh
+```
+
+Only helpers of the current prefix whose parent is `init`/`systemd` are
+terminated. Helpers whose launcher is still alive, other prefixes, the game,
+Riot/League/CEF, `darlingserver` and the runtime are never touched. A dry run
+is available from the configured tools directory:
+
+```sh
+RCLOL_CLEAN_STALE_HELPERS=1 python3 build/runtime/tools/clean-stale-helpers.py --dry-run
+```
+
 ### Client window stays black after a match
 
 The League client keeps its Chromium/CEF UI (`LeagueClientUx` and its helpers)
@@ -192,6 +227,60 @@ observation, without waiting for a match:
 python3 tools/close-league-client-in-game.py --once --dry-run
 ```
 
+### Automatic client handling during a match
+
+A single opt-in switch reads the client's own preferences and chooses the mode:
+
+```sh
+RCLOL_CLIENT_IN_GAME_TRICKS=1 ./scripts/run.sh
+```
+
+It reads `lol-user-experience` from the installed client's
+`LCULocalPreferences.yaml`:
+
+| Client preference | Launcher action |
+|---|---|
+| `potatoModeEnabled: false` or unreadable | no client-in-game helper |
+| `potatoModeEnabled: true`, close preference missing or invalid | no action |
+| `potatoModeEnabled: true`, `closeLeagueClientDuringGame: true` | close the client UI |
+| `potatoModeEnabled: true`, `closeLeagueClientDuringGame: false` | hide the client windows |
+
+The hide path unmaps the `LeagueClientUx` and `Riot Client` X11 windows and maps
+them again when the game process ends. The client is not closed, the League
+backend and Riot client keep running, and the game window is never hidden. The
+close path uses the UI-close helper described above. The hide helper exits after
+ten minutes without a client or match once it has seen one; a missing or invalid
+close preference selects no helper.
+
+The low-level `RCLOL_HIDE_CLIENT_IN_GAME=1` and
+`RCLOL_CLOSE_CLIENT_IN_GAME=1` switches remain available when the automatic
+switch is not set. All modes are off by default. The helpers are
+window-management only: they do not patch client binaries, CEF, anti-cheat or
+DRM. They attribute the game to this prefix through the loader's
+`__mldr_sockpath`, and fail closed when ownership, proc state, environment or
+window information cannot be read. The hide helper requires an X11 or Xwayland
+desktop; on a native Wayland window manager without Xwayland it cannot find the
+windows.
+
+On a CPU-bound host the hide effect appears after CEF has been hidden for a few
+seconds. In a local 30-second test on an i5-3470 with a Radeon RX 550, hiding
+`LeagueClientUx` reduced the summed CPU of the matched client/CEF processes from
+120.7% to 93.4% (about 23%, or 27 percentage points, of one core); showing the
+window returned it to 119.9%. This is not a universal FPS or percentage claim:
+a game that is GPU-bound, a client with no active UI work, or a different
+desktop may show less benefit. The hidden window can also need a moment to
+repaint after it is shown.
+
+With client optimizations enabled and close-during-game enabled, the close
+helper remains the more aggressive option when in-client chat during the match
+is not needed.
+
+Diagnose the match detector without changing any window:
+
+```sh
+python3 tools/hide-league-client-in-game.py --once
+```
+
 ### Riot reports NO INTERNET FOUND while the host is online
 
 Older base runtimes ship Google DNS servers (`8.8.8.8` and `8.8.4.4`), which