[Docs] (Anland): runbook and skill for bringing up MobileGL with anland and KDE Plasma

2026-11-07 01:53:24 +09:00 · 2026-10-02 10:31:35 -04:00
parent 7520e53b5e
commit 82d96a63c9
31 changed files with 1051 additions and 0 deletions
@@ -0,0 +1,3 @@
+# Everything here is executed by bash/sh on Linux, Android or WSL: keep LF even on a Windows checkout
+# (core.autocrlf=true would otherwise hand sh a script full of $'\r').
+* text=auto eol=lf
@@ -0,0 +1,151 @@
+---
+name: anland-mobilegl-plasma
+description: Bring up, rebuild, deploy, switch backends on, test and debug the "MobileGL + anland + KDE Plasma" stack - a rooted Android tablet whose anland APK embeds the MobileGL server, plus a Droidspaces Arch Linux ARM container running KWin/plasmashell/Chrome through the MobileGL client library and GBM backend - driven from this Windows machine (Git Bash, WSL archlinux, adb). Use it after a phone reboot, when changing server (NDK) or client (container glibc) MobileGL code or anland's KWin backend/patch, when switching Espryt/Magma, when validating zero-copy dma-buf presentation, and when chasing crashes, black windows, noise or software-rendering fallbacks in the Plasma session.
+---
+
+# MobileGL on anland KDE Plasma
+
+Human-readable runbook (Chinese, same content): `docs/Disaggregated/notes/anland/runbook-plasma.md`.
+Background: `docs/Disaggregated/notes/anland/handoff-legacy-mobilegl-unified.md` (state, commits, known
+issues) and `plan-ahb-dmabuf.md` (zero-copy design).  All scripts are in `scripts/` next to this file;
+parameters are documented at the top of each script and in `scripts/env.sh`.
+
+**The phone may be shared with another session.** Before anything that restarts the app, the daemon,
+the container session or replaces a library, run the read-only `scripts/device/status.sh` and make sure
+nobody else is mid-test.  Use your own `ct.sh` channel names (others use c, c2, c3, xd, xr, gbm).
+
+## Architecture (10 lines)
+
+1. Phone: Lenovo TB321FU (Y700, Adreno 750, Android 15, kernel 6.1), rooted with **KernelSU** (`/data/adb/ksu`, `ksud`; `su -c` works). USB serial `HA27Q3LQ`, or wireless adb `ip:port`.
+2. anland APK `com.anland.consumer.mobilegl` (debuggable build of anland branch `legacy-mobilegl-unified`): UI process + private service process `:mobilegl` (`MobileGLWorker`), which loads the **server** `libMobileGL.so` (NDK, from MobileGL `feat/disaggregated`) and listens on abstract socket `@anland-mobilegl`. One process serves every client (KWin, plasmashell, ksplash, Chrome...), one backend per process.
+3. Backend = `setprop debug.mobilegl.backend DirectGLES|DirectVulkan` (Espryt = DirectGLES, Magma = DirectVulkan; prop lost on reboot) and must equal the container's `/etc/mobilegl/backend` (what every client reports; mismatch = "Hello.backendType disagrees with pinned backend").
+4. Experiment display daemon `/data/adb/modules/anland-daemon/display_daemon /data/local/tmp/anland-mobilegl/display.sock` (display/input broker; NOT started at boot - the module only starts the original one on `/data/local/tmp/display_daemon.sock`, leave that alone).
+5. Container `arch-kde-mgl` (Droidspaces 6.4.5, Arch Linux ARM aarch64 glibc, host net, `rootfs.img` mounted at `/mnt/Droidspaces/arch-kde-mgl` on the Android side). Bind mounts: `/data/local/tmp/anland-mobilegl` -> `/run/anland-mobilegl`, `/data/local/tmp/display_daemon.sock` -> `/run/display.sock`.
+6. `desktop-session.service` (User=swung0x48) has drop-in `ExecStart=/opt/mobilegl/bin/mobilegl-startup.sh plasma`, which writes a user drop-in for `plasma-kwin_wayland.service` (kwin_wayland_wrapper -> `/opt/mobilegl/kwin/bin/kwin_wayland` + `/opt/mobilegl/kwin/lib/libkwin.so.6.7.4`, `ANLAND_MOBILEGL=1`, `MOBILEGL_IPC_SURFACE=server`) and runs `startplasma-wayland`.
+7. KWin 6.7.4 with anland's `anland` backend renders straight into the anland Android Surface through the server. Every other GL process is `MOBILEGL_IPC_SURFACE=offscreen` and presents through KWin.
+8. Client = `/opt/mobilegl/lib/libMobileGL.so` (glibc aarch64): glvnd EGL vendor (`/opt/mobilegl/share/glvnd/egl_vendor.d/50_mobilegl.json`), GLX vendor (`/usr/lib/libGLX_mobilegl.so.0`, `__GLX_VENDOR_LIBRARY_NAME=mobilegl`), env `MOBILEGL_TRANSPORT=spawn MOBILEGL_IPC_DATA=shm MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl`.
+9. Zero-copy windows: client `wl_egl_window` frames are server-allocated AHardwareBuffer "shared images" exported as dma-buf fds over `zwp_linux_dmabuf_v1`; KWin imports them with EGL and the server recognises its own buffer by inode. KWin gets a DRM device via `GBM_BACKEND=mobilegl` -> `/usr/lib/gbm/mobilegl_gbm.so` (node is only an identity, never ioctl'd). Without linux-dmabuf the client falls back to wl_shm readback.
+10. X11 apps (Xwayland) use the MobileGL GLX vendor with per-frame readback + `xcb_put_image`. Chrome runs ANGLE-GLES over MobileGL EGL with the GPU in-process (`mobilegl-startup.sh chrome`).
+
+## First-time prerequisites (Windows host)
+
+- Git Bash, `adb` (SDK platform-tools), CMake >= 3.22 and Ninja on PATH (seen: CMake 3.27.6, Ninja 1.13.2), Python 3 + Pillow (only `rec.sh`).
+- Android NDK **27.2.12479018** at `%LOCALAPPDATA%/Android/Sdk/ndk/27.2.12479018` (override `ANDROID_NDK`).
+- WSL distro **archlinux** with clang, lld, llvm, cmake, ninja. **lld's major version must equal clang/llvm-libs'** (lld 23 on llvm 22 broke `ld.lld`; working set: all 22.1.6). Then export the sysroot once: `bash scripts/xsysroot/refresh-sysroot.sh` (-> `~/sysroots/arch-kde-mgl` + `~/sysroots/aarch64-arch.cmake`; re-run after container package upgrades, then `xbuild.sh --reconfigure`).
+- MobileGL worktree (never build in the shared main checkout): `GIT_LFS_SKIP_SMUDGE=1 git worktree add ...`, `git submodule update --init --recursive`, and copy `3rdparty/glslang/External/spirv-tools` from the main checkout (the submodule leaves it empty).
+- anland worktree on `legacy-mobilegl-unified` (KWin patch/backend, startup script, `mobilegl-tools/`).
+- Phone side that already exists and is NOT recreated by this skill: the APK (build: anland `consumers/anland_v5/android_consumer/MOBILEGL.md`, gradle `:app:assemblePlainDebug` with `MOBILEGL_DIST`, `-PmobileglApplicationId=com.anland.consumer.mobilegl`; reinstalling with another key changes the UID and needs the KernelSU grant again - `mobilegl-tools/ksu_grant.c`), the anland KernelSU modules (`anland-daemon`, `anland-awl`), the container with KWin's configured build tree `/root/mobilegl-build/kwin-6.7.4/build` and pristine `/root/gbm-dev/kwin-a/src`.
+- Install the helpers once (container must be running): `bash scripts/push-tools.sh` (device/*.sh -> `/data/local/tmp/anl`, `mgrun` -> container `/usr/local/bin`, `kwprep.sh` -> container `/root`).
+
+Run host scripts from Git Bash as `bash scripts/<x>.sh`.  Raw adb with device paths needs `MSYS_NO_PATHCONV=1` and the whole root command in one quoted string: `adb shell 'su -c "..."'`.  A device script can also be run without pushing: `MSYS_NO_PATHCONV=1 adb shell 'su -c sh' < scripts/device/status.sh`.
+
+## Bring-up after a phone reboot
+
+Nothing of the session survives a reboot.  Either `adb shell 'su -c "sh /data/local/tmp/anl/bringup.sh [DirectGLES|DirectVulkan]"'`, or by hand, in this order:
+
+```sh
+adb connect <ip>:<port>                       # only for wireless debugging (e.g. USB cannot power it)
+export MSYS_NO_PATHCONV=1
+adb shell 'su -c "svc power stayon true"'
+adb shell 'su -c "setprop debug.mobilegl.backend DirectVulkan"'     # or DirectGLES; match /etc/mobilegl/backend
+adb shell 'su -c "am start -n com.anland.consumer.mobilegl/com.anland.consumer.MainActivity --es socket_path /data/local/tmp/anland-mobilegl/display.sock"'
+adb shell 'su -c "/data/local/Droidspaces/bin/droidspaces -C /data/local/Droidspaces/Containers/arch-kde-mgl/container.config start"'
+adb shell 'su -c "sh /data/local/tmp/anl/restart-daemon.sh"'       # experiment display daemon, chmod 777 dir / 666 socket
+adb shell 'su -c "sh /data/local/tmp/anl/run-plasma.sh"'           # restarts app + desktop-session, ~90 s
+```
+
+`droidspaces` has no `status` command; `droidspaces show` lists running containers.  Do not use the old
+`/data/local/tmp/restart-daemon.sh` (it kills a hard-coded PID).  Check with `device/status.sh`.
+
+## Build and deploy loops
+
+**Server (Android, NDK) -> APK lib**
+```sh
+bash scripts/build-android.sh          # -> <worktree>/build-android/libMobileGL.so (RelWithDebInfo, unstripped)
+bash scripts/cyc.sh s1                 # clear sticky SW-renderer key, push, swap into APK, restart session, screenshot $ANL_DIR/s1.png, print fatals
+```
+`device/swap.sh` overwrites `/data/app/.../lib/arm64/libMobileGL.so` keeping owner/mode/SELinux context (original saved as `/data/local/tmp/anland-mobilegl/libMobileGL.so.orig`); no re-signing. To swap without the session restart: push to `/data/local/tmp/anland-mobilegl/libMobileGL.new.so`, `su -c "sh /data/local/tmp/anl/swap.sh"`, then `run-plasma.sh` anyway (KWin does not reconnect to a new server process).
+
+**Client + GBM backend (container glibc) via WSL cross-build**
+```sh
+bash scripts/xbuild.sh [--reconfigure]  # WSL ~/mgl-xbuild-a64; ~150 s full, seconds incremental
+bash scripts/xdeploy.sh                 # rename-into-place install of libMobileGL.so + mobilegl_gbm.so, aliases, vendor JSON
+```
+Running clients keep the old inode; restart the client, or `run-plasma.sh` for KWin/plasmashell.  Build server and client from the **same commit** (both stamp `git rev-parse HEAD`), else the logs WARN "compatible wire with different build".  Fallback in-container build (slow): `scripts/sync-src.sh` + anland `mobilegl-tools/anland-build-client.sh`.
+
+**KWin (anland backend / kwin.patch) - built inside the container**
+```sh
+bash scripts/kwin-stage.sh build        # stage CR-stripped patch+backend+startup script, kwprep.sh, background sync-build-kwin.sh
+printf 'tail -5 /root/kwin-build.log\n' | bash scripts/ct.sh kw     # wait for "== ALL DONE =="
+adb shell 'su -c "sh /data/local/tmp/anl/run-plasma.sh"'
+```
+`sync-build-kwin.sh` (anland `producers/kde/Arch_v5/`) copies only the backend sources, then `ninja -j4`, installs `kwin_wayland`, `libkwin.so.6.7.4`, the patched screencast plugin and `/opt/mobilegl/bin/mobilegl-startup.sh` by atomic rename.  `kwprep.sh` is what applies changed `kwin.patch` hunks to core KWin files.  Repo-root `libdisplay_producer/` is not synced by either.  `kwin-stage.sh` is assembled from those two scripts and was not run as one unit yet.
+
+**Unit tests (no device)** - in WSL (the MSVC build of this branch is broken):
+```sh
+MSYS2_ARG_CONV_EXCL='*' wsl -d archlinux -- bash /mnt/c/<worktree>/.claude/skills/anland-mobilegl-plasma/scripts/wsl-test.sh MultiSessionTest TwinOwnershipTest
+MSYS2_ARG_CONV_EXCL='*' wsl -d archlinux -- bash -lc 'cd ~/mgl-anl-bld && ctest -R "MultiSession|TwinOwnership" -E DirectVulkan --output-on-failure'
+```
+`wsl-all.sh` builds and runs every unit test.  Never run DirectVulkan integration tests; never two ctest runs at once.
+
+## Switching backends
+
+`adb shell 'su -c "sh /data/local/tmp/anl/switch.sh DirectGLES"'` (sets the prop, writes `/etc/mobilegl/backend`, restarts the app), then `run-plasma.sh` - the running session's clients are pinned to the old backend.  `cyc.sh` keeps whatever is set.
+
+## Test clients and how to verify
+
+Inside the container as root (`printf '...' | bash scripts/ct.sh <chan>`), `mgrun offscreen <cmd>` runs a client as swung0x48 in the live session (log `/tmp/mgl-run.client.log`, override base with `MGLOG=/tmp/x.log`):
+```sh
+mgrun offscreen eglinfo -B ; mgrun offscreen glxinfo -B
+timeout 25 mgrun offscreen glmark2-es2-wayland -s 1280x720 --run-forever > /tmp/gm.out 2>&1 &
+sleep 8; grep -a "presented through" /tmp/mgl-run.client.log
+```
+Chrome: `bash scripts/chrome-launch.sh <tag> [flags]` (log `/tmp/mgl-chrome-<tag>.client.log`, screenshot `ch-<tag>.png`).
+Probes: `scripts/probes/texfmt.c` (texture formats keep alpha?), `dmahash.c` (hash a process's dma-bufs); build in the container, e.g. `gcc -O1 /root/texfmt.c -o /usr/local/bin/mgl-texfmt -lEGL`, run with `mgrun offscreen`.
+
+A result counts only if ALL hold:
+- client log says `presented through linux-dmabuf shared images` (not `wl_shm`; `could not be presented through a linux-dmabuf shared image` = fell back);
+- `bash scripts/shot.sh g 2 1` gives two different hashes while the client animates (a "fast" score can mean frames are not shown);
+- `adb logcat -b crash -d` and `adb logcat -d | grep -E "Fatal signal|Abort message|E MobileGL"` are clean (a frozen window is usually a dead server);
+- for plasmashell verdicts, the sticky software renderer is off (below) and `/tmp/mgl-plasmashell.client.log` is freshly written.
+Reference (glmark2-es2-wayland 1280x720, zero-copy vs wl_shm): Espryt 187 vs 49, Magma 158 vs 34.  Rerun any surprising pass.
+
+## Logs
+
+| What | Where |
+|---|---|
+| KWin client side | container `/tmp/mobilegl-compositor.client.log` |
+| plasmashell / ksplash | `/tmp/mgl-plasmashell.client.log`, `/tmp/mgl-ksplash.client.log` (user drop-ins `~/.config/systemd/user/plasma-{plasmashell,ksplash}.service.d/mobilegl-log.conf`) |
+| mgrun / Chrome | `/tmp/mgl-run.client.log`, `/tmp/mgl-chrome-<tag>.client.log` (+ `/tmp/chrome-<tag>-out.log`) |
+| Server | `adb logcat -s MobileGL`; file `/data/data/com.anland.consumer.mobilegl/files/mobilegl-server.server.log` |
+| Native crashes | `adb logcat -b crash -d`; container `coredumpctl list` |
+| Session / KWin stderr | container `journalctl -u desktop-session --no-pager`, `journalctl --no-pager --since -2min \| grep kwin_wayland` |
+| Display daemon | `/data/local/tmp/anland-mobilegl/display-daemon.log` |
+
+`MOBILEGL_LOG_FILE_PATH=/tmp/x.log` produces `/tmp/x.client.log` (and `.server.log` for forwarded lines); files are truncated on open, so one base per process.  Client builds log at INFO.  Symbolize server frames with `$ANDROID_NDK/toolchains/llvm/prebuilt/windows-x86_64/bin/llvm-addr2line.exe -Cfe build-android/libMobileGL.so <offset>`.
+
+## Pitfalls
+
+- **pkill -f self-match**: a `ct.sh`/`droidspaces run bash -lc "<script>"` process carries the script in its argv; `pkill -f chrome` kills the runner. Use `pkill -x`.
+- **Root-owned /tmp files**: a log created by a root-run client cannot be reopened by swung0x48 later (no log appears). `rm -f` it as root first.
+- **Sticky Plasma software renderer**: after any server crash Plasma writes `[QtQuickRendererSettings] SceneGraphBackend=software` into `~swung0x48/.config/kdeglobals`; plasmashell then renders on the CPU and screenshots still look fine (tray icon "正在使用的软件渲染器"). Delete before any verdict: `sudo -u swung0x48 kwriteconfig6 --file kdeglobals --group QtQuickRendererSettings --key SceneGraphBackend --delete` (cyc.sh does it), restart the session.
+- **Lock screen**: autolock is off (`kscreenlockerrc [Daemon] Autolock=false`); a real lock can only be left by typing the password (logind lock/unlock is not supported for this session type - `device/unlock.sh` is unverified). Test the greeter with `/usr/lib/kscreenlocker_greet --testing` and kill it.
+- **CRLF**: `core.autocrlf=true` here; anland's backend sources and `sync-build-kwin.sh` are CRLF in the Windows checkout. Strip CR before anything runs on Linux/Android (`tr -d '\r'`; `ct.sh`, `push-tools.sh`, `kwin-stage.sh` do). This skill has a `.gitattributes` forcing LF.
+- **Display daemon not auto-started** after reboot: KWin logs "failed to connect to display daemon at /run/anland-mobilegl/display.sock" and the session exits in ~3 s.
+- **Device power/connection**: low battery or the screen turning off (30 s default) can kill the SurfaceView - `svc power stayon true`; wireless adb `ip:port` changes per pairing - never pin `-s HA27Q3LQ`, use `ANDROID_SERIAL` if several devices are attached.
+- **Container vs phone paths**: container `/tmp` is a different place from the phone's `/data/local/tmp`; move files via `/mnt/Droidspaces/arch-kde-mgl/root` (container `/root`) or `/data/local/tmp/anland-mobilegl` (= container `/run/anland-mobilegl`).
+- **Never overwrite a mapped .so in place** (container or APK while running): copy to a new inode and `mv -f`; the APK swap force-stops the app first.
+- **Input**: plain `adb shell input` is blocked - use `su -c input`; anland grabs the touchscreen, so if `input tap` does nothing use `input mouse tap x y`. Never `debuggerd -b` a container process (signal 35 kills glibc processes).
+- **linux-dmabuf**: the client must use `create` + roundtrip, never `create_immed` (KWin answers a failed immediate import with a protocol error that kills the client).
+- **Cross-session bugs**: noise / another window's pixels after some client starts or exits = process-global state in the multi-session server (handles are per client, FBO/VAO per context). Repro with `kscreenlocker_greet --testing`.
+- `/etc/environment` leaks Mesa/KGSL variables through pam_env; `mobilegl-startup.sh` unsets them - keep that when editing it.
+- `handoff` mentions a `kwin_wayland` logging shim and `/tmp/mgl-kwin-<pid>.log`: stale - `/opt/mobilegl/kwin/bin/kwin_wayland` is now the real binary and logs to `/tmp/mobilegl-compositor.client.log`.
+
+## House rules
+
+- Work in a git worktree, never in the shared main checkout or its build dirs; worktrees need `GIT_LFS_SKIP_SMUDGE=1`.
+- Commit with `git commit --no-verify`, one short sentence, **no** `Co-Authored-By` trailer.
+- Never run the DirectVulkan integration tests (`ctest -E DirectVulkan`).
+- No external project names ("Mesa", "Zink", ...) in source code or comments; describe the technique.
+- Vendor-agnostic only on the zero-copy path: AHB, EGL_ANDROID_*, VK_ANDROID AHB import, sync_file, dma-buf, libgbm ABI - no kgsl/gralloc layouts/QCOM modifiers.
+- Identity caches key on monotonic lifetime ids, never GL names or pointers.
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# build-android.sh - build the Android SERVER libMobileGL.so (NDK, arm64-v8a) that the anland APK embeds.
+# Output: $MGL_WORKTREE/build-android/libMobileGL.so (RelWithDebInfo, unstripped, ~320 MB; keep it for
+# llvm-addr2line, it is what cyc.sh pushes).  Stamp = worktree HEAD, so the container client
+# (xbuild.sh, same stamp) and the server agree on the build ("compatible wire with different build"
+# WARN otherwise).  Env: MGL_WORKTREE, ANDROID_NDK, BUILD_DIR (default build-android), JOBS (12).
+# Log level is compiled to INFO.
+set -euo pipefail
+. "$(dirname "$0")/env.sh"
+W=$MGL_WORKTREE
+B=$W/${BUILD_DIR:-build-android}
+STAMP=$(git -C "$W" rev-parse HEAD)
+if [ ! -f "$B/build.ninja" ]; then
+cmake -S "$W" -B "$B" -G Ninja -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" \
+  -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-26 -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+  -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON \
+  -DMOBILEGL_BUILD_TEST=OFF -DMOBILEGL_BUILD_BENCHMARK=OFF \
+  -DCMAKE_CXX_FLAGS=-DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO \
+  -DMOBILEGL_BUILD_STAMP="$STAMP"
+else
+cmake "$B" -DMOBILEGL_BUILD_STAMP="$STAMP" >/dev/null
+fi
+cmake --build "$B" --target MobileGL -j"${JOBS:-12}"
+ls -la "$B/libMobileGL.so"
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# chrome-launch.sh <tag> [extra chrome flags...] - (re)start Chrome inside the running Plasma session
+# through mobilegl-startup.sh's `chrome` mode (ANGLE GLES over MobileGL EGL, in-process GPU), client
+# log /tmp/mgl-chrome-<tag>.client.log, then print its "presented through" line and save a screenshot
+# to $ANL_DIR/ch-<tag>.png.  Kills the running chrome first (pkill -x, never -f).
+# Env: WAIT (s before checking, default 20), CHANNEL (ct.sh channel, default chrome).
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+TAG=${1:?usage: chrome-launch.sh <tag> [chrome flags...]}; shift
+bash "$here/ct.sh" "${CHANNEL:-chrome}" <<IN
+pkill -x chrome; sleep 2
+U=\$(id -u $MGL_DESKTOP_USER)
+sudo -u $MGL_DESKTOP_USER env XDG_RUNTIME_DIR=/run/user/\$U WAYLAND_DISPLAY=wayland-0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/\$U/bus __EGL_VENDOR_LIBRARY_FILENAMES=/opt/mobilegl/share/glvnd/egl_vendor.d/50_mobilegl.json MOBILEGL_TRANSPORT=spawn MOBILEGL_IPC_DATA=shm MOBILEGL_ENDPOINT=unix:@anland-mobilegl MOBILEGL_BACKEND_TYPE=\$(cat /etc/mobilegl/backend) MOBILEGL_LOG_FILE_PATH=/tmp/mgl-chrome-$TAG.log bash -c 'nohup /opt/mobilegl/bin/mobilegl-startup.sh chrome --restore-last-session $* > /tmp/chrome-$TAG-out.log 2>&1 &'
+sleep ${WAIT:-20}
+grep -ah 'presented through' /tmp/mgl-chrome-$TAG.client.log | head -3
+IN
+adb_ shell "su -c 'screencap -p $DEV_SHARE/ch-$TAG.png'"
+adb_ pull "$DEV_SHARE/ch-$TAG.png" "$ANL_DIR/ch-$TAG.png" >/dev/null && echo "screenshot: $ANL_DIR/ch-$TAG.png"
@@ -0,0 +1,29 @@
+#!/bin/bash
+# kwprep.sh - (container, as root) bring the live KWin tree /root/mobilegl-build/kwin-6.7.4 in line with
+# anland's kwin.patch + anland backend sources, touching ONLY files whose content changed (keeps the
+# ninja build incremental).  It re-applies the whole patch to a pristine copy of KWin's src/
+# (/root/gbm-dev/kwin-a/src) in /root/kp and copies every patched file that differs into the live tree,
+# then copies changed backend files.  Build + install afterwards with anland's sync-build-kwin.sh.
+#
+# Input: /root/kwsync.tgz, a tar made in the anland worktree's producers/kde directory:
+#   tar czf kwsync.tgz Arch_v5/kwin.patch Arch_v5/mobilegl-startup.sh anland_backend_Arch_v5/src/backends/anland/
+# and pushed to the container's /root (e.g. via /mnt/Droidspaces/arch-kde-mgl/root/ on the Android side).
+# The pristine tree /root/gbm-dev/kwin-a/src was set up by hand earlier (unverified that it is exactly
+# upstream 6.7.4); patch hunks that fail are reported by `patch`.
+set -e
+rm -rf /root/kwsync && mkdir -p /root/kwsync && tar xzf /root/kwsync.tgz -C /root/kwsync
+P=/root/kwsync/Arch_v5/kwin.patch
+rm -rf /root/kp && mkdir -p /root/kp && cp -a /root/gbm-dev/kwin-a/src /root/kp/
+cd /root/kp && patch -p1 -s < $P
+LIVE=/root/mobilegl-build/kwin-6.7.4
+FILES=$(grep -E '^\+\+\+ b/' $P | sed 's|^+++ b/||' | awk '{print $1}' | sort -u)
+for f in $FILES; do
+  if [ -f "/root/kp/$f" ] && ! cmp -s "/root/kp/$f" "$LIVE/$f"; then cp "/root/kp/$f" "$LIVE/$f"; echo "updated $f"; fi
+done
+for f in /root/kwsync/anland_backend_Arch_v5/src/backends/anland/*; do
+  # libdisplay_producer is a symlink in git; a Windows checkout turns it into a small text file. The live
+  # tree has the real directory (repo-root libdisplay_producer/), which neither script syncs.
+  [ -f "$f" ] && [ "$(basename $f)" != libdisplay_producer ] || continue
+  b=$(basename $f); if ! cmp -s "$f" "$LIVE/src/backends/anland/$b"; then cp "$f" "$LIVE/src/backends/anland/$b"; echo "updated anland/$b"; fi
+done
+echo PREP_DONE
@@ -0,0 +1,21 @@
+#!/bin/bash
+# mgrun <surface: offscreen|server> <command...> - (container, as root) run one MobileGL client as the
+# desktop user inside the running Plasma session.  Installed as /usr/local/bin/mgrun (push-tools.sh).
+#   mgrun offscreen glmark2-es2-wayland -s 1280x720     # Wayland client, presents through KWin
+#   mgrun offscreen eglinfo -B ; mgrun offscreen glxinfo -B   # glxinfo goes through Xwayland + GLX vendor
+# "server" is only for a client that owns the Android Surface itself (KWin does); everything else is
+# offscreen.  Backend = /etc/mobilegl/backend (must match the server).  Client log:
+# ${MGLOG:-/tmp/mgl-run.log} -> the library writes /tmp/mgl-run.client.log (truncated per run; give
+# concurrent clients different MGLOG values).  Env: MGLOG, DESKTOP_USER (swung0x48).
+S=$1; shift
+DU=${DESKTOP_USER:-swung0x48}
+U=$(id -u "$DU")
+cd /tmp
+exec sudo -u "$DU" env XDG_RUNTIME_DIR=/run/user/$U WAYLAND_DISPLAY=wayland-0 DISPLAY=:0 \
+  XAUTHORITY=$(ls /run/user/$U/xauth_* 2>/dev/null | head -1) \
+  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$U/bus QT_QPA_PLATFORM=wayland \
+  __EGL_VENDOR_LIBRARY_FILENAMES=/opt/mobilegl/share/glvnd/egl_vendor.d/50_mobilegl.json \
+  __GLX_VENDOR_LIBRARY_NAME=mobilegl \
+  MOBILEGL_TRANSPORT=spawn MOBILEGL_IPC_DATA=shm MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl \
+  MOBILEGL_IPC_SURFACE=$S MOBILEGL_BACKEND_TYPE=$(cat /etc/mobilegl/backend 2>/dev/null || echo DirectGLES) \
+  MOBILEGL_LOG_FILE_PATH=${MGLOG:-/tmp/mgl-run.log} "$@"
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# ct.sh <channel> [script-file] - run a bash script as ROOT inside the container (login shell),
+# reading the script from the file or from stdin.  Generic form of the old c.sh/c2.sh/c3.sh.
+#
+#   printf '%s\n' 'ls -la /tmp/*.log' | bash ct.sh mychan
+#   bash ct.sh mychan ./something.cmd
+#
+# How: the script is written to $ANL_DIR/<channel>.cmd, pushed to $DEV_TOOLS/<channel>.cmd together with
+# a one-line <channel>.sh that does `droidspaces --name=<container> run bash -lc "$(cat <channel>.cmd)"`,
+# and that runs under `su`.  Quoting through adb + su + droidspaces is thereby avoided entirely.
+#
+# Pick a channel name of your own: other sessions on the same phone use c, c2, c3, xd, xr, gbm...;
+# writing to their channel files races with them.  CR characters are stripped (Windows checkouts).
+# Inside, run user-side commands with `sudo -u <desktop user> env XDG_RUNTIME_DIR=/run/user/<uid> ...`.
+# Never `pkill -f <word>` in a channel script: the `bash -lc "<script>"` process carries the whole
+# script on its command line and kills itself.  Use `pkill -x <name>`.
+set -euo pipefail
+. "$(dirname "$0")/env.sh"
+ch=${1:?usage: ct.sh <channel> [script-file]}
+src=${2:--}
+if [ "$src" = - ]; then tr -d '\r' > "$ANL_DIR/$ch.cmd"; else tr -d '\r' < "$src" > "$ANL_DIR/$ch.cmd"; fi
+printf '%s\n' "$DS_BIN --name=$MGL_CONTAINER run bash -lc \"\$(cat $DEV_TOOLS/$ch.cmd)\"" > "$ANL_DIR/$ch.sh"
+adb_ shell "mkdir -p $DEV_TOOLS"
+adb_ push "$ANL_DIR/$ch.cmd" "$DEV_TOOLS/$ch.cmd" >/dev/null
+adb_ push "$ANL_DIR/$ch.sh" "$DEV_TOOLS/$ch.sh" >/dev/null
+adb_ shell "su -c 'sh $DEV_TOOLS/$ch.sh'"
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# cyc.sh <shot-name> - one server iteration: clear Plasma's sticky software-renderer key, push the
+# NDK-built server lib, swap it into the installed APK (device/swap.sh), restart app + Plasma session
+# (device/run-plasma.sh, ~90 s), screenshot to $ANL_DIR/<shot-name>.png, print fatal logcat lines.
+# Env: SERVER_LIB (default $MGL_WORKTREE/build-android/libMobileGL.so), WAIT (s after the session
+# restart, default 15), N (logcat lines, default 20), CHANNEL (ct.sh channel, default cyc).
+# Needs device/swap.sh + device/run-plasma.sh in $DEV_TOOLS (push-tools.sh).  RESTARTS THE SESSION.
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+shot=${1:?usage: cyc.sh <shot-name>}
+LIB=${SERVER_LIB:-$MGL_WORKTREE/build-android/libMobileGL.so}
+printf '%s\n' "sudo -u $MGL_DESKTOP_USER kwriteconfig6 --file kdeglobals --group QtQuickRendererSettings --key SceneGraphBackend --delete; rm -f /tmp/mgl-plasmashell.client.log" \
+    | bash "$here/ct.sh" "${CHANNEL:-cyc}"
+adb_ push "$LIB" "$DEV_SHARE/libMobileGL.new.so" >/dev/null
+adb_ logcat -c
+adb_ shell "su -c 'sh $DEV_TOOLS/swap.sh >/dev/null && sh $DEV_TOOLS/run-plasma.sh >/dev/null 2>&1; sleep ${WAIT:-15}; screencap -p $DEV_SHARE/$shot.png'"
+adb_ pull "$DEV_SHARE/$shot.png" "$ANL_DIR/$shot.png" >/dev/null && echo "screenshot: $ANL_DIR/$shot.png"
+adb_ logcat -d | grep -E "Fatal signal|FATAL|Abort message|Magma wire buffer|E MobileGL" | cut -c1-260 | head -"${N:-20}" || true
@@ -0,0 +1,29 @@
+# bringup.sh [DirectGLES|DirectVulkan] - (Android root shell) bring the stack up after a phone reboot:
+# stay-awake, container, backend property, experiment display daemon, anland app, then the Plasma
+# session (run-plasma.sh, ~90 s; skip with NO_PLASMA=1).  The backend defaults to the container's
+# /etc/mobilegl/backend (persists across reboots; the property does not).
+# Assembled from the documented manual steps; not exercised as one unit yet.  Re-running restarts the
+# daemon, the app and the session.  Run: su -c "sh /data/local/tmp/anl/bringup.sh"
+# Env: PKG, CONTAINER, DS, SOCK, TOOLS (dir holding run-plasma.sh / restart-daemon.sh; default: this dir).
+D=${DS:-/data/local/Droidspaces/bin/droidspaces}
+P=${PKG:-com.anland.consumer.mobilegl}
+C=${CONTAINER:-arch-kde-mgl}
+SOCK=${SOCK:-/data/local/tmp/anland-mobilegl/display.sock}
+T=${TOOLS:-$(dirname $0)}
+svc power stayon true
+if $D show 2>/dev/null | grep -q " $C "; then
+    echo "container $C already running"
+else
+    $D -C /data/local/Droidspaces/Containers/$C/container.config start
+    sleep 5
+fi
+B=${1:-$(cat /mnt/Droidspaces/$C/etc/mobilegl/backend 2>/dev/null)}
+B=${B:-DirectGLES}
+setprop debug.mobilegl.backend $B
+echo "$B" > /mnt/Droidspaces/$C/etc/mobilegl/backend
+echo "backend: $(getprop debug.mobilegl.backend)"
+sh $T/restart-daemon.sh
+am start -n $P/com.anland.consumer.MainActivity --es socket_path $SOCK >/dev/null
+sleep 3
+if pidof $P:mobilegl >/dev/null; then echo "server process $P:mobilegl up"; else echo "WARNING: $P:mobilegl not running"; fi
+[ "${NO_PLASMA:-0}" = 1 ] || sh $T/run-plasma.sh
@@ -0,0 +1,20 @@
+# restart-daemon.sh - (Android root shell) (re)start the EXPERIMENT's anland display daemon on $SOCK.
+# It is not started at boot (the anland-daemon module's service.sh only starts the original daemon on
+# /data/local/tmp/display_daemon.sock, which must be left alone).  Without it KWin logs
+# "failed to connect to display daemon at /run/anland-mobilegl/display.sock" and the session dies in ~3 s.
+# The container sees $SOCK as /run/anland-mobilegl/display.sock (bind mount in container.config);
+# uid 1000 in the container must connect, hence 777 dir / 666 socket.
+# Env: SOCK, DAEMON (/data/adb/modules/anland-daemon/display_daemon).
+SOCK=${SOCK:-/data/local/tmp/anland-mobilegl/display.sock}
+DAEMON=${DAEMON:-/data/adb/modules/anland-daemon/display_daemon}
+DIR=$(dirname $SOCK)
+for p in $(ps -A -o PID,ARGS | grep "display_daemon $SOCK" | grep -v grep | awk '{print $1}'); do kill $p; done
+sleep 1
+rm -f $SOCK
+mkdir -p $DIR
+nohup $DAEMON $SOCK > $DIR/display-daemon.log 2>&1 &
+sleep 1
+chmod 777 $DIR
+chmod 666 $SOCK
+echo "daemon restarted:"
+ps -A -o PID,ARGS | grep "display_daemon $SOCK" | grep -v grep
@@ -0,0 +1,26 @@
+# run-plasma.sh - (Android root shell) restart the anland app and the container's Plasma session
+# (desktop-session.service -> mobilegl-startup.sh plasma).  Takes ~90 s (two 40 s waits: logind must
+# finish tearing the old user session down before the new one starts).  Prints the unit status, the
+# plasma user units and recent coredumps.  Run: su -c "sh /data/local/tmp/anl/run-plasma.sh"
+# Env: PKG, CONTAINER, DESKTOP_USER (swung0x48), SOCK, DS (droidspaces binary).
+D=${DS:-/data/local/Droidspaces/bin/droidspaces}
+P=${PKG:-com.anland.consumer.mobilegl}
+C=${CONTAINER:-arch-kde-mgl}
+U=${DESKTOP_USER:-swung0x48}
+SOCK=${SOCK:-/data/local/tmp/anland-mobilegl/display.sock}
+am force-stop $P
+am start -n $P/com.anland.consumer.MainActivity --es socket_path $SOCK >/dev/null
+sleep 3
+$D --name=$C run bash -lc "
+systemctl stop desktop-session.service 2>/dev/null
+loginctl terminate-user $U 2>/dev/null; sleep 40
+systemctl reset-failed desktop-session.service
+rm -f /tmp/mobilegl-compositor.log
+date +%s > /tmp/plasma-start
+systemctl start desktop-session.service
+sleep 40
+systemctl --no-pager status desktop-session.service | head -8
+UID_=\$(id -u $U)
+sudo -u $U XDG_RUNTIME_DIR=/run/user/\$UID_ systemctl --user --no-pager list-units --all 'plasma*' 2>&1 | head -30
+coredumpctl --no-pager list --since '-2min' 2>&1 | tail -5
+"
@@ -0,0 +1,12 @@
+# status.sh - (Android root shell) READ-ONLY health check of the whole stack.
+# Run: su -c "sh /data/local/tmp/anl/status.sh"      Env: PKG, CONTAINER, DS, SOCK.
+D=${DS:-/data/local/Droidspaces/bin/droidspaces}
+P=${PKG:-com.anland.consumer.mobilegl}
+C=${CONTAINER:-arch-kde-mgl}
+SOCK=${SOCK:-/data/local/tmp/anland-mobilegl/display.sock}
+echo "battery: $(dumpsys battery | grep ' level:' | tr -d ' ')  $(dumpsys power | grep -o 'mStayOn=[a-z]*')"
+echo "prop debug.mobilegl.backend=$(getprop debug.mobilegl.backend)  container /etc/mobilegl/backend=$(cat /mnt/Droidspaces/$C/etc/mobilegl/backend 2>/dev/null)"
+echo "app pid: $(pidof $P)  server (:mobilegl) pid: $(pidof $P:mobilegl)"
+ps -A -o PID,ARGS | grep "display_daemon $SOCK" | grep -v grep || echo "experiment display daemon NOT running"
+$D show
+$D --name=$C run bash -lc 'echo "desktop-session: $(systemctl is-active desktop-session.service)"; pgrep -a -x kwin_wayland; pgrep -a -x plasmashell; grep -A1 QtQuickRendererSettings /home/*/.config/kdeglobals 2>/dev/null || echo "kdeglobals: no sticky software renderer"'
@@ -0,0 +1,17 @@
+# swap.sh - (Android root shell) replace the server libMobileGL.so inside the INSTALLED anland APK with
+# $SHARE/libMobileGL.new.so, keeping owner, mode and SELinux context; force-stops the app.  The first
+# run backs the APK's original lib up to $SHARE/libMobileGL.so.orig.  No re-signing/reinstall (that
+# would change the app UID and lose its root grant).  Run: su -c "sh /data/local/tmp/anl/swap.sh"
+# Env: PKG (com.anland.consumer.mobilegl), SHARE (/data/local/tmp/anland-mobilegl).
+set -e
+P=${PKG:-com.anland.consumer.mobilegl}
+SHARE=${SHARE:-/data/local/tmp/anland-mobilegl}
+D=$(dirname $(pm path $P | sed 's/package://'))/lib/arm64
+ls -laZ $D
+[ -f $SHARE/libMobileGL.so.orig ] || cp $D/libMobileGL.so $SHARE/libMobileGL.so.orig
+am force-stop $P
+CTX=$(ls -Z $D/libMobileGL.so | awk '{print $1}')
+OWN=$(stat -c %u:%g $D/libMobileGL.so)
+cp $SHARE/libMobileGL.new.so $D/libMobileGL.so
+chown $OWN $D/libMobileGL.so; chmod 755 $D/libMobileGL.so; chcon $CTX $D/libMobileGL.so
+ls -laZ $D/libMobileGL.so
@@ -0,0 +1,15 @@
+# switch.sh <DirectGLES|DirectVulkan> - (Android root shell) select the server backend: Espryt =
+# DirectGLES, Magma = DirectVulkan.  Sets the system property the server reads (lost on reboot), writes
+# the container's /etc/mobilegl/backend (what every client and the KWin drop-in report; it must match or
+# the server refuses the client: "Hello.backendType disagrees with pinned backend"), restarts the app.
+# The running Plasma session still speaks the old backend: run run-plasma.sh afterwards.
+# Env: PKG, CONTAINER (arch-kde-mgl), SOCK (display daemon socket).
+B=${1:?usage: switch.sh DirectGLES|DirectVulkan}
+P=${PKG:-com.anland.consumer.mobilegl}
+C=${CONTAINER:-arch-kde-mgl}
+SOCK=${SOCK:-/data/local/tmp/anland-mobilegl/display.sock}
+setprop debug.mobilegl.backend $B
+echo $B > /mnt/Droidspaces/$C/etc/mobilegl/backend
+am force-stop $P
+am start -n $P/com.anland.consumer.MainActivity --es socket_path $SOCK >/dev/null
+sleep 4
@@ -0,0 +1,8 @@
+# unlock.sh - (Android root shell) ask logind to unlock the desktop user's session.  UNVERIFIED that this
+# helps here: the handoff notes this logind session type does not support lock-session (a real lock
+# screen then needs the password).  Prevention: [Daemon] Autolock=false in ~/.config/kscreenlockerrc.
+# Env: DS, CONTAINER, DESKTOP_USER.
+D=${DS:-/data/local/Droidspaces/bin/droidspaces}
+C=${CONTAINER:-arch-kde-mgl}
+U=${DESKTOP_USER:-swung0x48}
+$D --name=$C run bash -lc "S=\$(loginctl list-sessions --no-legend | awk '\$3==\"$U\"{print \$1}' | head -1); loginctl unlock-session \$S; echo unlocked \$S"
@@ -0,0 +1,41 @@
+# env.sh - shared parameters for the host-side (Git Bash) scripts of the anland-mobilegl-plasma skill.
+# Sourced, never run. Every value can be overridden from the environment before calling a script.
+#
+#   MGL_WORKTREE    MobileGL worktree (Windows form C:/...). Default: the worktree this skill lives in.
+#   ANL_DIR         Local scratch dir: channel files, screenshots, xdist/. Default: %LOCALAPPDATA%/Temp/anl
+#   ANDROID_NDK     NDK used for the Android server lib. Default: <SDK>/ndk/27.2.12479018
+#   MGL_PKG         Anland APK that embeds the server. Default: com.anland.consumer.mobilegl
+#   MGL_CONTAINER   Droidspaces container. Default: arch-kde-mgl
+#   MGL_DESKTOP_USER  Desktop user inside the container. Default: swung0x48
+#   DS_BIN          droidspaces binary on the phone. Default: /data/local/Droidspaces/bin/droidspaces
+#   DEV_TOOLS       Phone dir for device/*.sh and channel files. Default: /data/local/tmp/anl
+#   DEV_SHARE       Phone dir bind-mounted into the container as /run/anland-mobilegl (screenshots,
+#                   server lib staging, display daemon socket). Default: /data/local/tmp/anland-mobilegl
+#   ANDROID_SERIAL  Honoured by adb itself; leave unset when only one device is attached
+#                   (USB serial or a wireless "ip:port").
+
+_skill_scripts=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+if [ -z "${MGL_WORKTREE:-}" ]; then
+    MGL_WORKTREE=$(cd "$_skill_scripts/../../../.." && pwd -W 2>/dev/null || pwd)
+fi
+: "${ANL_DIR:=$(cygpath -m "${LOCALAPPDATA:-C:/Users/$USERNAME/AppData/Local}" 2>/dev/null || echo /tmp)/Temp/anl}"
+: "${ANDROID_NDK:=$(cygpath -m "${LOCALAPPDATA:-C:/Users/$USERNAME/AppData/Local}" 2>/dev/null)/Android/Sdk/ndk/27.2.12479018}"
+: "${MGL_PKG:=com.anland.consumer.mobilegl}"
+: "${MGL_CONTAINER:=arch-kde-mgl}"
+: "${MGL_DESKTOP_USER:=swung0x48}"
+: "${DS_BIN:=/data/local/Droidspaces/bin/droidspaces}"
+: "${DEV_TOOLS:=/data/local/tmp/anl}"
+: "${DEV_SHARE:=/data/local/tmp/anland-mobilegl}"
+# The container rootfs as Android root sees it (the container's /tmp is NOT visible here).
+CT_ROOT=/mnt/Droidspaces/$MGL_CONTAINER
+export MGL_WORKTREE ANL_DIR ANDROID_NDK MGL_PKG MGL_CONTAINER MGL_DESKTOP_USER DS_BIN DEV_TOOLS DEV_SHARE CT_ROOT
+
+# Git Bash would rewrite /data/... arguments into C:/Program Files/Git/data/...; keep them literal.
+# Consequence: pass LOCAL paths to Windows tools (adb, cmake, git) in C:/ form, never /c/.
+export MSYS_NO_PATHCONV=1
+adb_() { MSYS2_ARG_CONV_EXCL='*' adb "$@"; }
+
+# C:/x/y -> /mnt/c/x/y (for WSL).
+win2wsl() { local p=$1 d; d=$(printf '%s' "${p:0:1}" | tr 'A-Z' 'a-z'); printf '/mnt/%s%s' "$d" "${p:2}"; }
+
+mkdir -p "$ANL_DIR"
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# kwin-stage.sh [build] - stage anland's KWin changes (kwin.patch, anland backend sources,
+# mobilegl-startup.sh, sync-build-kwin.sh) for the in-container KWin rebuild; with "build", also run
+# kwprep.sh (apply changed patch hunks / backend files to the live tree) and start sync-build-kwin.sh
+# (ninja -j4 + atomic install into /opt/mobilegl/kwin, screencast plugin, startup script) in the
+# background, log /root/kwin-build.log.  KWin is NOT restarted: run device/run-plasma.sh afterwards.
+# Poll:  printf 'tail -5 /root/kwin-build.log\n' | bash ct.sh kw
+#
+# Two staging places, because the two container scripts read different ones:
+#   /root/kwsync.tgz                            <- kwprep.sh (installed by push-tools.sh)
+#   $DEV_SHARE/kwin-sync = /run/anland-mobilegl/kwin-sync  <- sync-build-kwin.sh (as kwin-sync/sync-build.sh)
+# All files are CR-stripped: the Windows checkout of anland has CRLF backend sources and a CRLF
+# sync-build-kwin.sh (bash then fails on $'\r').
+# Assembled from kwprep.sh + sync-build-kwin.sh; not exercised as one unit yet.
+# Env: ANLAND_WORKTREE (anland checkout on branch legacy-mobilegl-unified, Windows form),
+#      CHANNEL (ct.sh channel, default kw).
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+: "${ANLAND_WORKTREE:=$(cygpath -m "$USERPROFILE" 2>/dev/null)/AndroidStudioProjects/anland/.claude/worktrees/mgl-unified}"
+K=$ANLAND_WORKTREE/producers/kde
+st=$ANL_DIR/kwstage
+rm -rf "$st"; mkdir -p "$st/kwsync/Arch_v5" "$st/kwsync/anland_backend_Arch_v5/src/backends/anland" "$st/kwin-sync/anland" "$st/kwin-sync/misc"
+lf() { tr -d '\r' < "$1" > "$2"; }
+for f in "$K"/anland_backend_Arch_v5/src/backends/anland/*; do
+    b=$(basename "$f"); [ "$b" = libdisplay_producer ] && continue
+    lf "$f" "$st/kwsync/anland_backend_Arch_v5/src/backends/anland/$b"
+    lf "$f" "$st/kwin-sync/anland/$b"
+done
+for f in kwin.patch mobilegl-startup.sh; do
+    lf "$K/Arch_v5/$f" "$st/kwsync/Arch_v5/$f"
+    lf "$K/Arch_v5/$f" "$st/kwin-sync/misc/$f"
+done
+lf "$K/Arch_v5/sync-build-kwin.sh" "$st/kwin-sync/sync-build.sh"
+(cd "$st/kwsync" && tar --force-local -czf ../kwsync.tgz Arch_v5 anland_backend_Arch_v5)
+tar --force-local -C "$st" -czf "$st/kwin-sync.tgz" kwin-sync
+adb_ push "$st/kwsync.tgz" "$DEV_TOOLS/kwsync.tgz" >/dev/null
+adb_ push "$st/kwin-sync.tgz" "$DEV_TOOLS/kwin-sync.tgz" >/dev/null
+adb_ shell "su -c 'cp $DEV_TOOLS/kwsync.tgz $CT_ROOT/root/kwsync.tgz && tar xzf $DEV_TOOLS/kwin-sync.tgz -C $DEV_SHARE && chmod -R a+rX $DEV_SHARE/kwin-sync && rm -f $DEV_TOOLS/kwsync.tgz $DEV_TOOLS/kwin-sync.tgz && echo staged'"
+if [ "${1:-}" = build ]; then
+    bash "$here/ct.sh" "${CHANNEL:-kw}" <<'IN'
+bash /root/kwprep.sh || exit 1
+nohup bash /run/anland-mobilegl/kwin-sync/sync-build.sh > /root/kwin-build.log 2>&1 < /dev/null &
+echo "kwin build started (pid $!), log /root/kwin-build.log; it ends with '== ALL DONE =='"
+IN
+fi
@@ -0,0 +1,34 @@
+// dmahash <pid> : for each dma-buf fd of <pid> at least 1 MB, print inode, size and a sampled checksum.
+#include <dirent.h>
+#include <fcntl.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+int main(int argc, char** argv) {
+    char dir[64];
+    snprintf(dir, sizeof dir, "/proc/%s/fd", argv[1]);
+    DIR* d = opendir(dir);
+    if (!d) { perror("opendir"); return 1; }
+    struct dirent* e;
+    while ((e = readdir(d))) {
+        char p[128], l[128] = {0};
+        snprintf(p, sizeof p, "%s/%s", dir, e->d_name);
+        if (readlink(p, l, sizeof l - 1) <= 0 || strncmp(l, "/dmabuf", 7) != 0) continue;
+        int fd = open(p, O_RDONLY);
+        if (fd < 0) continue;
+        struct stat st; fstat(fd, &st);
+        if (st.st_size < (1 << 20)) { close(fd); continue; }
+        const uint8_t* m = mmap(NULL, st.st_size, PROT_READ, MAP_SHARED, fd, 0);
+        if (m == MAP_FAILED) { printf("fd %s ino %lu mmap failed\n", e->d_name, (unsigned long)st.st_ino); close(fd); continue; }
+        uint64_t h = 1469598103934665603ull; unsigned nz = 0;
+        for (off_t i = 0; i < st.st_size; i += 64) { h = (h ^ m[i]) * 1099511628211ull; nz += m[i] != 0; }
+        printf("fd %s ino %lu size %ld hash %016llx nz %u\n", e->d_name, (unsigned long)st.st_ino, (long)st.st_size,
+               (unsigned long long)h, nz);
+        munmap((void*)m, st.st_size); close(fd);
+    }
+    return 0;
+}
@@ -0,0 +1,95 @@
+/* texfmt: does a texture keep its alpha? One opaque red texel and one transparent texel per
+ * format, sampled across a 64x64 ES3 pbuffer cleared white with SRC_ALPHA blending. Expect the
+ * left half red and the right half WHITE; a black right half means the alpha was lost. */
+#include <EGL/egl.h>
+#include <GLES3/gl3.h>
+#include <GLES2/gl2ext.h>
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+#define P(T, n) T n = (T)eglGetProcAddress(#n)
+static const char* vs = "#version 300 es\nlayout(location=0) in vec2 p; out vec2 uv; void main(){uv=p*0.5+0.5; gl_Position=vec4(p,0,1);}";
+static const char* fs = "#version 300 es\nprecision mediump float; uniform sampler2D t; uniform int mode; in vec2 uv; out vec4 o;"
+                        "void main(){vec4 c=texture(t,uv); o = mode==1 ? vec4(1.0,0.0,0.0,c.a) : (mode==2 ? vec4(c.r,0.0,0.0,c.r) : c);}";
+int main(void) {
+    EGLDisplay d = eglGetDisplay(EGL_DEFAULT_DISPLAY); eglInitialize(d, 0, 0); eglBindAPI(EGL_OPENGL_ES_API);
+    EGLint ca[] = {EGL_SURFACE_TYPE, EGL_PBUFFER_BIT, EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT, EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8, EGL_NONE};
+    EGLConfig c; EGLint n; eglChooseConfig(d, ca, &c, 1, &n);
+    EGLint xa[] = {EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE};
+    EGLContext x = eglCreateContext(d, c, EGL_NO_CONTEXT, xa);
+    EGLint pa[] = {EGL_WIDTH, 64, EGL_HEIGHT, 64, EGL_NONE};
+    EGLSurface s = eglCreatePbufferSurface(d, c, pa); eglMakeCurrent(d, s, s, x);
+    P(PFNGLCREATESHADERPROC, glCreateShader); P(PFNGLSHADERSOURCEPROC, glShaderSource); P(PFNGLCOMPILESHADERPROC, glCompileShader);
+    P(PFNGLCREATEPROGRAMPROC, glCreateProgram); P(PFNGLATTACHSHADERPROC, glAttachShader); P(PFNGLLINKPROGRAMPROC, glLinkProgram);
+    P(PFNGLUSEPROGRAMPROC, glUseProgram); P(PFNGLGETUNIFORMLOCATIONPROC, glGetUniformLocation); P(PFNGLUNIFORM1IPROC, glUniform1i);
+    P(PFNGLGENBUFFERSPROC, glGenBuffers); P(PFNGLBINDBUFFERPROC, glBindBuffer); P(PFNGLBUFFERDATAPROC, glBufferData);
+    P(PFNGLVERTEXATTRIBPOINTERPROC, glVertexAttribPointer); P(PFNGLENABLEVERTEXATTRIBARRAYPROC, glEnableVertexAttribArray);
+    P(PFNGLDRAWARRAYSPROC, glDrawArrays); P(PFNGLCLEARCOLORPROC, glClearColor); P(PFNGLCLEARPROC, glClear);
+    P(PFNGLREADPIXELSPROC, glReadPixels); P(PFNGLVIEWPORTPROC, glViewport); P(PFNGLGENTEXTURESPROC, glGenTextures);
+    P(PFNGLBINDTEXTUREPROC, glBindTexture); P(PFNGLTEXIMAGE2DPROC, glTexImage2D); P(PFNGLTEXPARAMETERIPROC, glTexParameteri);
+    P(PFNGLENABLEPROC, glEnable); P(PFNGLBLENDFUNCPROC, glBlendFunc); P(PFNGLGETERRORPROC, glGetError);
+    P(PFNGLTEXSTORAGE2DPROC, glTexStorage2D); P(PFNGLTEXSUBIMAGE2DPROC, glTexSubImage2D); P(PFNGLGETSTRINGPROC, glGetString);
+    printf("GL_VERSION %s\n", glGetString(GL_VERSION));
+    printf("BGRA ext: %s\n", strstr((const char*)glGetString(GL_EXTENSIONS), "GL_EXT_texture_format_BGRA8888") ? "yes" : "no");
+    GLuint v = glCreateShader(GL_VERTEX_SHADER), f = glCreateShader(GL_FRAGMENT_SHADER);
+    glShaderSource(v, 1, &vs, 0); glCompileShader(v); glShaderSource(f, 1, &fs, 0); glCompileShader(f);
+    GLuint pr = glCreateProgram(); glAttachShader(pr, v); glAttachShader(pr, f); glLinkProgram(pr); glUseProgram(pr);
+    float q[] = {-1,-1, 1,-1, -1,1, 1,1};
+    GLuint vbo; glGenBuffers(1, &vbo); glBindBuffer(GL_ARRAY_BUFFER, vbo);
+    glBufferData(GL_ARRAY_BUFFER, sizeof q, q, GL_STATIC_DRAW); glVertexAttribPointer(0, 2, GL_FLOAT, 0, 0, 0); glEnableVertexAttribArray(0);
+    GLint lm = glGetUniformLocation(pr, "mode");
+    glEnable(GL_BLEND); glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+    struct { const char* name; GLint ifmt; GLenum fmt; int bpp; int mode; int storage; GLenum sized; unsigned char px[8]; } cases[] = {
+        {"RGBA/TexImage", GL_RGBA, GL_RGBA, 4, 0, 0, 0, {255,0,0,255, 0,0,0,0}},
+        {"BGRA_EXT/TexImage", GL_BGRA_EXT, GL_BGRA_EXT, 4, 0, 0, 0, {0,0,255,255, 0,0,0,0}},
+        {"BGRA8_EXT/TexStorage+Sub", 0, GL_BGRA_EXT, 4, 0, 1, GL_BGRA8_EXT, {0,0,255,255, 0,0,0,0}},
+        {"RGBA8/TexStorage+Sub", 0, GL_RGBA, 4, 0, 1, GL_RGBA8, {255,0,0,255, 0,0,0,0}},
+        {"ALPHA", GL_ALPHA, GL_ALPHA, 1, 1, 0, 0, {255, 0}},
+        {"LUMINANCE_ALPHA", GL_LUMINANCE_ALPHA, GL_LUMINANCE_ALPHA, 2, 1, 0, 0, {255,255, 0,0}},
+        {"R8/TexStorage+Sub", 0, GL_RED, 1, 2, 1, GL_R8, {255, 0}},
+    };
+    for (unsigned i = 0; i < sizeof cases / sizeof cases[0]; ++i) {
+        GLuint t; glGenTextures(1, &t); glBindTexture(GL_TEXTURE_2D, t);
+        glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
+        glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+        while (glGetError()) {}
+        if (cases[i].storage) {
+            glTexStorage2D(GL_TEXTURE_2D, 1, cases[i].sized, 2, 1);
+            glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, 2, 1, cases[i].fmt, GL_UNSIGNED_BYTE, cases[i].px);
+        } else {
+            glTexImage2D(GL_TEXTURE_2D, 0, cases[i].ifmt, 2, 1, 0, cases[i].fmt, GL_UNSIGNED_BYTE, cases[i].px);
+        }
+        GLenum err = glGetError();
+        glUniform1i(lm, cases[i].mode);
+        glViewport(0, 0, 64, 64); glClearColor(1, 1, 1, 1); glClear(GL_COLOR_BUFFER_BIT);
+        glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
+        unsigned char l[4], r[4];
+        glReadPixels(16, 32, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, l); glReadPixels(48, 32, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, r);
+        const int ok = l[0] > 200 && l[1] < 60 && l[2] < 60 && r[0] > 200 && r[1] > 200 && r[2] > 200;
+        printf("%-26s err=0x%04x left=%3d,%3d,%3d right=%3d,%3d,%3d %s\n", cases[i].name, err, l[0], l[1], l[2], r[0], r[1], r[2], ok ? "ok" : "BAD");
+    }
+    /* ANGLE's emulation of ALPHA8 / LUMINANCE_ALPHA8 on a desktop-GL driver: R8 / RG8 + swizzle. */
+    P(PFNGLTEXPARAMETERIPROC, glTexParameteri2);
+    struct { const char* name; GLenum sized, fmt; int bpp; GLint sw[4]; unsigned char px[4]; unsigned char wantL[3], wantR[3]; } sz[] = {
+        {"R8 swizzled as ALPHA8", GL_R8, GL_RED, 1, {GL_ZERO, GL_ZERO, GL_ZERO, GL_RED}, {255, 0}, {0,0,0}, {255,255,255}},
+        {"RG8 swizzled as LUM_ALPHA", GL_RG8, GL_RG, 2, {GL_RED, GL_RED, GL_RED, GL_GREEN}, {255,255, 0,0}, {255,255,255}, {255,255,255}},
+        {"RG8 as LUM_ALPHA (lum 0)", GL_RG8, GL_RG, 2, {GL_RED, GL_RED, GL_RED, GL_GREEN}, {0,255, 0,0}, {0,0,0}, {255,255,255}},
+    };
+    glUniform1i(lm, 0);
+    for (unsigned i = 0; i < sizeof sz / sizeof sz[0]; ++i) {
+        GLuint t; glGenTextures(1, &t); glBindTexture(GL_TEXTURE_2D, t);
+        glTexParameteri2(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST); glTexParameteri2(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
+        glTexStorage2D(GL_TEXTURE_2D, 1, sz[i].sized, 2, 1);
+        glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, 2, 1, sz[i].fmt, GL_UNSIGNED_BYTE, sz[i].px);
+        glTexParameteri2(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, sz[i].sw[0]); glTexParameteri2(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_G, sz[i].sw[1]);
+        glTexParameteri2(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, sz[i].sw[2]); glTexParameteri2(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_A, sz[i].sw[3]);
+        GLenum err = glGetError();
+        glClearColor(1, 1, 1, 1); glClear(GL_COLOR_BUFFER_BIT); glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
+        unsigned char l[4], r[4];
+        glReadPixels(16, 32, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, l); glReadPixels(48, 32, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, r);
+        int ok = 1;
+        for (int k = 0; k < 3; ++k) ok = ok && abs(l[k] - sz[i].wantL[k]) < 40 && abs(r[k] - sz[i].wantR[k]) < 40;
+        printf("%-26s err=0x%04x left=%3d,%3d,%3d right=%3d,%3d,%3d %s\n", sz[i].name, err, l[0], l[1], l[2], r[0], r[1], r[2], ok ? "ok" : "BAD");
+    }
+    return 0;
+}
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# push-tools.sh - install this skill's device- and container-side helpers on the phone.
+#   device/*.sh      -> $DEV_TOOLS            (run as root: adb shell 'su -c "sh $DEV_TOOLS/<x>.sh"')
+#   container/mgrun  -> <container>/usr/local/bin/mgrun
+#   container/kwprep.sh -> <container>/root/kwprep.sh
+# Needs the container running (its rootfs is mounted at $CT_ROOT only then).
+# Overwrites same-named files other sessions may be using in $DEV_TOOLS; check first on a shared phone.
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+adb_ shell "mkdir -p $DEV_TOOLS"
+for f in "$here"/device/*.sh; do
+    tr -d '\r' < "$f" > "$ANL_DIR/push.tmp"
+    adb_ push "$ANL_DIR/push.tmp" "$DEV_TOOLS/$(basename "$f")" >/dev/null
+    echo "pushed $DEV_TOOLS/$(basename "$f")"
+done
+for f in mgrun kwprep.sh; do
+    tr -d '\r' < "$here/container/$f" > "$ANL_DIR/push.tmp"
+    adb_ push "$ANL_DIR/push.tmp" "$DEV_TOOLS/$f" >/dev/null
+done
+rm -f "$ANL_DIR/push.tmp"
+adb_ shell "su -c 'cp $DEV_TOOLS/mgrun $CT_ROOT/usr/local/bin/mgrun && chmod 755 $CT_ROOT/usr/local/bin/mgrun && cp $DEV_TOOLS/kwprep.sh $CT_ROOT/root/kwprep.sh && echo installed mgrun kwprep.sh'"
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# rec.sh <name> - record 3 s of the screen while opening Kickoff, extract frames inside the container
+# with ffmpeg, pull them to $ANL_DIR/af_<name>/ and build a 3x4 contact sheet $ANL_DIR/grid_<name>.png
+# (needs Python + Pillow on Windows).  Use it to catch flicker/black frames a single screenshot misses.
+# Env: TAP="x y" Kickoff button position (default "69 1349" = bottom-left on the 2560x1600 tablet;
+# device specific).  Note: anland grabs the touchscreen (EVIOCGRAB); if `input tap` does nothing, use
+# `input mouse tap x y`.  Env CHANNEL (default rec).
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+N=${1:?usage: rec.sh <name>}; TAP=${TAP:-69 1349}
+adb_ shell "su -c 'input keyevent 111; sleep 1.5; (screenrecord --time-limit 3 --bit-rate 20000000 $DEV_SHARE/$N.mp4 &); sleep 0.7; input tap $TAP; sleep 3; cp $DEV_SHARE/$N.mp4 $CT_ROOT/root/$N.mp4'"
+bash "$here/ct.sh" "${CHANNEL:-rec}" <<IN
+rm -rf /root/af_$N; mkdir -p /root/af_$N; ffmpeg -loglevel quiet -i /root/$N.mp4 -vf scale=1000:-1 -fps_mode passthrough /root/af_$N/f%03d.png; ls /root/af_$N | wc -l
+IN
+adb_ shell "su -c 'rm -rf $DEV_SHARE/af_$N; cp -r $CT_ROOT/root/af_$N $DEV_SHARE/ && chmod -R 777 $DEV_SHARE/af_$N'"
+rm -rf "$ANL_DIR/af_$N"; adb_ pull "$DEV_SHARE/af_$N" "$ANL_DIR/" >/dev/null
+python - "$ANL_DIR/af_$N" "$ANL_DIR/grid_$N.png" <<'P'
+import sys, os
+from PIL import Image
+d, out = sys.argv[1], sys.argv[2]
+fs = sorted(os.listdir(d)); n = len(fs)
+pick = [fs[min(n-1, int(i * n / 12))] for i in range(12)]
+ims = [Image.open(os.path.join(d, f)) for f in pick]
+w, h = ims[0].size; tw, th = w // 2, h // 2
+g = Image.new('RGB', (tw * 3, th * 4))
+for i, im in enumerate(ims): g.paste(im.resize((tw, th)), ((i % 3) * tw, (i // 3) * th))
+g.save(out); print(n, pick)
+P
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# shot.sh <name> [count] [interval-s] - take <count> (default 2) phone screenshots <interval> s apart
+# (default 1), pull them to $ANL_DIR/<name>-<i>.png and print their md5.  Identical hashes while an
+# animated client (glmark2, a video) runs mean the frames are NOT reaching the screen.
+set -euo pipefail
+. "$(dirname "$0")/env.sh"
+name=${1:?usage: shot.sh <name> [count] [interval]}; n=${2:-2}; dt=${3:-1}
+cmd=""; i=1
+while [ "$i" -le "$n" ]; do cmd="$cmd screencap -p $DEV_SHARE/$name-$i.png; sleep $dt;"; i=$((i+1)); done
+adb_ shell "su -c '$cmd'"
+i=1
+while [ "$i" -le "$n" ]; do
+    adb_ pull "$DEV_SHARE/$name-$i.png" "$ANL_DIR/$name-$i.png" >/dev/null
+    md5sum "$ANL_DIR/$name-$i.png"; i=$((i+1))
+done
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# sync-src.sh - FALLBACK path only (the WSL cross build, xbuild.sh, replaced it).  Pushes the files the
+# worktree changed since the container's source stamp into the container's MobileGL source tree
+# (/root/mobilegl-unified-src), keeping mtimes so the in-container ninja build stays incremental;
+# then build/install inside the container with anland's anland-build-client.sh
+# (producers/kde/Arch_v5/mobilegl-tools/, gcc, -j4, slow on the phone).
+# A full re-sync of the tree is anland's anland-sync-source.sh (MOBILEGL_REPO=<worktree>).
+set -euo pipefail
+. "$(dirname "$0")/env.sh"
+SRC=$CT_ROOT/root/mobilegl-unified-src
+STAMP=$(adb_ shell "su -c 'cat $SRC/.anland-build-stamp'" | tr -d '\r\n')
+cd "$MGL_WORKTREE"
+FILES=$( (git diff --name-only --diff-filter=d "$STAMP"; git ls-files --others --exclude-standard) \
+    | grep -v -E '^(3rdparty/|build-android|\.anland-build-stamp|\.claude/)' | sort -u)
+echo "$(echo "$FILES" | wc -l) files since $STAMP"
+tar --force-local -czf "$ANL_DIR/src-delta.tgz" $FILES
+adb_ push "$ANL_DIR/src-delta.tgz" /data/local/tmp/src-delta.tgz >/dev/null
+HEAD=$(git rev-parse HEAD)
+adb_ shell "su -c 'tar xzf /data/local/tmp/src-delta.tgz -C $SRC && echo $HEAD > $SRC/.anland-build-stamp && echo synced'"
@@ -0,0 +1,9 @@
+#!/bin/bash
+# wsl-all.sh - run INSIDE WSL archlinux after wsl-test.sh configured $B: build every *Test target except
+# DirectVulkan*/Benchmark* and run the unit label.  NEVER run the DirectVulkan integration tests
+# (they need a live device + manual intervention); never run two ctest suites at once.
+B=${B:-$HOME/mgl-anl-bld}
+cd $B
+T=$(ninja -t targets all 2>/dev/null | grep -oE "^[A-Za-z]+Test:" | tr -d : | sort -u | grep -v -E "^(DirectVulkan|Benchmark)" | tr "\n" " ")
+ninja -j14 MobileGLServer $T 2>&1 | grep -E "error:|FAILED" | head -10
+ctest -L unit -j10 --timeout 300 -E "DirectVulkan" 2>&1 | tail -25
@@ -0,0 +1,13 @@
+#!/bin/bash
+# wsl-test.sh <targets...> - run INSIDE WSL archlinux: configure (once) and build MobileGL unit-test
+# targets for the host (clang, disaggregated + in-process server ON).  From Git Bash:
+#   MSYS2_ARG_CONV_EXCL='*' wsl -d archlinux -- bash /mnt/c/<worktree>/.claude/skills/anland-mobilegl-plasma/scripts/wsl-test.sh MultiSessionTest
+# then ctest in $B (see wsl-all.sh).  Env: W (worktree, WSL path; default: derived from this file),
+# B (build dir, default ~/mgl-anl-bld).  The Windows MSVC build of feat/disaggregated is broken; use this.
+set -e
+W=${W:-$(cd "$(dirname "$0")/../../../.." && pwd)}
+B=${B:-$HOME/mgl-anl-bld}
+if [ ! -f $B/build.ninja ]; then
+cmake -S $W -B $B -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DMOBILEGL_BUILD_TEST=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON -DMOBILEGL_BUILD_STAMP=wsl
+fi
+cmake --build $B --target "$@" -j16
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# xbuild.sh [--reconfigure] [extra ninja targets...] - cross-build the container CLIENT: libMobileGL.so
+# (glibc aarch64, glvnd EGL/GLX vendor) + mobilegl_gbm.so (GBM backend), in WSL archlinux with
+# clang + lld against a sysroot exported from the container (xsysroot/refresh-sysroot.sh).
+# Full build ~150 s, incremental seconds.  Deploy with xdeploy.sh.
+# Env: MGL_WORKTREE (source, Windows form), MGL_XBUILD_DIR (WSL build dir, default ~/mgl-xbuild-a64),
+#      MGL_JOBS (16), WSL_DISTRO (archlinux).
+# Prereq in WSL: clang, lld, llvm (lld major MUST equal clang/llvm-libs major - lld 23 on llvm 22
+# broke ld.lld), cmake, ninja; ~/sysroots/aarch64-arch.cmake + ~/sysroots/arch-kde-mgl.
+set -euo pipefail
+. "$(dirname "$0")/env.sh"
+STAMP=$(git -C "$MGL_WORKTREE" rev-parse HEAD)
+RECONF=0
+if [ "${1:-}" = "--reconfigure" ]; then RECONF=1; shift; fi
+EXTRA="$*"
+SRC_WSL=$(win2wsl "$MGL_WORKTREE")
+wsl -d "${WSL_DISTRO:-archlinux}" -- env SRC="$SRC_WSL" STAMP="$STAMP" RECONF="$RECONF" EXTRA="$EXTRA" \
+    OUT="${MGL_XBUILD_DIR:-}" JOBS="${MGL_JOBS:-16}" bash -s <<'IN' 2>&1 | tr -d '\0' | grep -av '^wsl:'
+set -euo pipefail
+OUT=${OUT:-$HOME/mgl-xbuild-a64}
+TC=$HOME/sysroots/aarch64-arch.cmake
+[ -f "$TC" ] || { echo "missing toolchain $TC (run xsysroot/refresh-sysroot.sh)"; exit 1; }
+ld.lld --version >/dev/null || { echo "ld.lld is not runnable in WSL (lld/llvm version mismatch?)"; exit 1; }
+t0=$(date +%s)
+if [ "$RECONF" = 1 ] || [ ! -f "$OUT/build.ninja" ]; then
+    rm -rf "$OUT/CMakeCache.txt" "$OUT/CMakeFiles"
+    cmake -S "$SRC" -B "$OUT" -G Ninja --toolchain "$TC" -DMOBILEGL_BUILD_STAMP="$STAMP" \
+        -DCMAKE_BUILD_TYPE=Release -DMOBILEGL_BUILD_TEST=OFF -DMOBILEGL_BUILD_BENCHMARK=OFF \
+        -DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_ENABLE_LTO=OFF
+elif ! grep -qx "MOBILEGL_BUILD_STAMP:STRING=$STAMP" "$OUT/CMakeCache.txt"; then
+    cmake -S "$SRC" -B "$OUT" -DMOBILEGL_BUILD_STAMP="$STAMP" >/dev/null
+fi
+t1=$(date +%s)
+cmake --build "$OUT" --target MobileGL mobilegl_gbm $EXTRA -j"$JOBS"
+t2=$(date +%s)
+echo "stamp:     $STAMP"
+echo "configure: $((t1-t0))s   build: $((t2-t1))s"
+for f in "$OUT/libMobileGL.so" "$OUT/MobileGL/MG_Gbm/mobilegl_gbm.so"; do
+    ls -la "$f"; echo "  windows: $(wslpath -w "$f")"
+done
+IN
+exit "${PIPESTATUS[0]}"
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# xdeploy.sh - install the WSL cross-built libMobileGL.so + mobilegl_gbm.so into the container, exactly
+# like anland's anland-build-client.sh: copy to a NEW inode and rename into place (overwriting a mapped
+# .so in place crashes every running client, KWin included), refresh the libEGL/libGL aliases, the
+# glvnd GLX vendor link and the EGL vendor JSON.  Does not restart anything: already-running clients
+# keep the old inode; restart the client (or the session) to pick up the new library.
+# Env: MGL_XBUILD_DIR (WSL build dir), CHANNEL (ct.sh channel, default xd), WSL_DISTRO.
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+mkdir -p "$ANL_DIR/xdist"
+# 1. Copy the build outputs out of WSL.
+wsl -d "${WSL_DISTRO:-archlinux}" -- env OUT="${MGL_XBUILD_DIR:-}" D="$(win2wsl "$ANL_DIR")/xdist" bash -s <<'IN' 2>&1 | tr -d '\0' | grep -av '^wsl:'
+set -e; OUT=${OUT:-$HOME/mgl-xbuild-a64}
+cp -f "$OUT/libMobileGL.so" "$D/libMobileGL.so"; cp -f "$OUT/MobileGL/MG_Gbm/mobilegl_gbm.so" "$D/mobilegl_gbm.so"
+sha256sum "$D/libMobileGL.so" "$D/mobilegl_gbm.so"
+IN
+# 2. Push to the phone and stage them in the container's /root/xdeploy (the container's /tmp and the
+#    phone's /data/local/tmp are different places; the rootfs is reachable at $CT_ROOT).
+adb_ shell "mkdir -p $DEV_TOOLS/xdist"
+adb_ push "$ANL_DIR/xdist/libMobileGL.so" "$DEV_TOOLS/xdist/libMobileGL.so"
+adb_ push "$ANL_DIR/xdist/mobilegl_gbm.so" "$DEV_TOOLS/xdist/mobilegl_gbm.so"
+adb_ shell "su -c 'mkdir -p $CT_ROOT/root/xdeploy && cp $DEV_TOOLS/xdist/libMobileGL.so $DEV_TOOLS/xdist/mobilegl_gbm.so $CT_ROOT/root/xdeploy/ && rm -f $DEV_TOOLS/xdist/*.so'"
+# 3. Install inside the container.
+bash "$here/ct.sh" "${CHANNEL:-xd}" <<'IN'
+set -euo pipefail
+in=/root/xdeploy
+mkdir -p /opt/mobilegl/lib /opt/mobilegl/share/glvnd/egl_vendor.d
+cp "$in/libMobileGL.so" /opt/mobilegl/lib/libMobileGL.so.new
+mv -f /opt/mobilegl/lib/libMobileGL.so.new /opt/mobilegl/lib/libMobileGL.so
+for lib in libEGL.so libEGL.so.1 libGL.so libGL.so.1; do ln -sf libMobileGL.so "/opt/mobilegl/lib/$lib"; done
+ln -sf /opt/mobilegl/lib/libMobileGL.so /usr/lib/libGLX_mobilegl.so.0
+printf '%s\n' '{"file_format_version":"1.0.0","ICD":{"library_path":"/opt/mobilegl/lib/libMobileGL.so"}}' >/opt/mobilegl/share/glvnd/egl_vendor.d/50_mobilegl.json
+mkdir -p /usr/lib/gbm
+cp "$in/mobilegl_gbm.so" /usr/lib/gbm/mobilegl_gbm.so.new
+mv -f /usr/lib/gbm/mobilegl_gbm.so.new /usr/lib/gbm/mobilegl_gbm.so
+rm -f "$in/libMobileGL.so" "$in/mobilegl_gbm.so"
+sha256sum /opt/mobilegl/lib/libMobileGL.so /usr/lib/gbm/mobilegl_gbm.so
+echo DEPLOYED
+IN
@@ -0,0 +1,47 @@
+# Cross toolchain: WSL clang -> aarch64 Arch Linux ARM (glibc) container "arch-kde-mgl".
+# Sysroot exported from the container by refresh-sysroot.sh (default $HOME/sysroots/arch-kde-mgl).
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR aarch64)
+
+set(_triple aarch64-unknown-linux-gnu)
+if (DEFINED ENV{MGL_SYSROOT})
+    set(_sysroot "$ENV{MGL_SYSROOT}")
+else()
+    set(_sysroot "$ENV{HOME}/sysroots/arch-kde-mgl")
+endif()
+# The container's GCC install dir (crtbegin/crtend, libgcc, libstdc++ via /usr/include/c++/<ver>).
+file(GLOB _gcc_dirs LIST_DIRECTORIES true "${_sysroot}/usr/lib/gcc/${_triple}/*")
+list(SORT _gcc_dirs COMPARE NATURAL ORDER DESCENDING)
+list(GET _gcc_dirs 0 _gcc_install_dir)
+
+set(CMAKE_SYSROOT "${_sysroot}")
+set(CMAKE_C_COMPILER clang)
+set(CMAKE_CXX_COMPILER clang++)
+set(CMAKE_ASM_COMPILER clang)
+set(CMAKE_C_COMPILER_TARGET ${_triple})
+set(CMAKE_CXX_COMPILER_TARGET ${_triple})
+set(CMAKE_ASM_COMPILER_TARGET ${_triple})
+set(CMAKE_AR llvm-ar)
+set(CMAKE_RANLIB llvm-ranlib)
+set(CMAKE_NM llvm-nm)
+set(CMAKE_OBJCOPY llvm-objcopy)
+set(CMAKE_STRIP llvm-strip)
+
+set(_xflags "--gcc-install-dir=${_gcc_install_dir}")
+set(CMAKE_C_FLAGS_INIT "${_xflags}")
+set(CMAKE_CXX_FLAGS_INIT "${_xflags}")
+set(CMAKE_ASM_FLAGS_INIT "${_xflags}")
+set(CMAKE_EXE_LINKER_FLAGS_INIT "-fuse-ld=lld")
+set(CMAKE_SHARED_LINKER_FLAGS_INIT "-fuse-ld=lld")
+set(CMAKE_MODULE_LINKER_FLAGS_INIT "-fuse-ld=lld")
+set(CMAKE_LINKER_TYPE LLD)
+
+set(CMAKE_FIND_ROOT_PATH "${_sysroot}")
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
+
+set(ENV{PKG_CONFIG_SYSROOT_DIR} "${_sysroot}")
+set(ENV{PKG_CONFIG_LIBDIR} "${_sysroot}/usr/lib/pkgconfig:${_sysroot}/usr/share/pkgconfig")
+set(ENV{PKG_CONFIG_PATH} "")
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# xsysroot/refresh-sysroot.sh - (re)export the cross sysroot from the container into WSL
+# ~/sysroots/arch-kde-mgl and install the toolchain file as ~/sysroots/aarch64-arch.cmake.
+# Read-only on the container side (it only tars headers/libs into /root and moves the tarball out).
+# Run once on a new machine, and again after the container upgrades glibc/gcc/vulkan/libdrm/gbm;
+# then `bash xbuild.sh --reconfigure`.  Env: CHANNEL (default xr), WSL_DISTRO.
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/../env.sh"
+cp -f "$here/aarch64-arch.cmake" "$ANL_DIR/aarch64-arch.cmake"
+bash "$here/../ct.sh" "${CHANNEL:-xr}" <<'IN'
+set -e; cd /
+L=$(ls -d usr/lib/*crt*.o usr/lib/lib{c,m,mvec,pthread,dl,rt,util,resolv,anl,stdc++,stdc++fs,stdc++exp,supc++,gcc_s,atomic,vulkan,drm,drm_*,gbm,z}.* usr/lib/lib{c,m}_nonshared* usr/lib/ld-linux* usr/lib/pkgconfig usr/share/pkgconfig usr/share/cmake/VulkanHeaders usr/lib/cmake/Vulkan* 2>/dev/null)
+tar czf /root/xsysroot.tar.gz --exclude='usr/lib/gcc/*/*/cc1' --exclude='usr/lib/gcc/*/*/cc1plus' --exclude='usr/lib/gcc/*/*/lto1' --exclude='usr/lib/gcc/*/*/lto-wrapper' --exclude='usr/lib/gcc/*/*/collect2' --exclude='usr/lib/gcc/*/*/plugin' --exclude='usr/lib/gcc/*/*/install-tools' --exclude='usr/lib/gcc/*/*/liblto_plugin.so' lib usr/include usr/lib/gcc $L
+echo SYSROOT_TAR_DONE
+IN
+adb_ shell "su -c 'mv $CT_ROOT/root/xsysroot.tar.gz $DEV_TOOLS/xsysroot.tar.gz && chmod 644 $DEV_TOOLS/xsysroot.tar.gz'"
+adb_ pull "$DEV_TOOLS/xsysroot.tar.gz" "$ANL_DIR/xsysroot.tar.gz"
+adb_ shell "su -c 'rm -f $DEV_TOOLS/xsysroot.tar.gz'"
+wsl -d "${WSL_DISTRO:-archlinux}" -- env A="$(win2wsl "$ANL_DIR")" bash -s <<'IN' 2>&1 | tr -d '\0' | grep -av '^wsl:'
+set -e; S=$HOME/sysroots/arch-kde-mgl; rm -rf "$S.new"; mkdir -p "$S.new"
+tar xzf "$A/xsysroot.tar.gz" -C "$S.new"
+rm -rf "$S"; mv "$S.new" "$S"; cp -f "$A/aarch64-arch.cmake" "$HOME/sysroots/aarch64-arch.cmake"
+du -sh "$S"; ls "$S/usr/lib/gcc/aarch64-unknown-linux-gnu/"
+IN
+rm -f "$ANL_DIR/xsysroot.tar.gz"
@@ -8,6 +8,7 @@
 | [`report-mobilegl.md`](report-mobilegl.md) | MobileGL 侧：Linux client 构建与导出、EGL / GLX 能力、split 的 present 路径、AHB / fd / fence 现状、会话与多窗口限制、GL 覆盖面、文档漂移 |
 | [`kgsl-as-server.md`](kgsl-as-server.md) | 把内核 kgsl 看成 server：A / B 实为"缓冲归谁"之分，6.x + Mesa 是 A、5.x 是 B；拆分层级与 virtio-gpu native context / virgl 的对应 |
 | [`plan-ahb-dmabuf.md`](plan-ahb-dmabuf.md) | 计划：server 分配 AHB 当 dma-buf，linux-dmabuf + GBM 后端 + 薄节点，窗口零拷贝；厂商中立规则与分阶段 |
+| [`runbook-plasma.md`](runbook-plasma.md) | 操作手册：在 Windows 主机 + 平板上从零拉起 / 重启后拉起 MobileGL + anland + KDE Plasma，server / client / KWin 的构建部署循环、切后端、验证、日志与常见坑（配套 skill `.claude/skills/anland-mobilegl-plasma/`） |
 | [`brief-anland.md`](brief-anland.md)、[`brief-mobilegl.md`](brief-mobilegl.md) | 派给 Codex 的原始提示词。**两份都把后端名写反了**：Espryt = DirectGLES（GLES），Magma = DirectVulkan（Vulkan）；报告已纠正 |

 ## 结论
@@ -0,0 +1,153 @@
+# Runbook：在这台 Windows 机器 + 平板上起 / 迭代 MobileGL + anland + KDE Plasma（2026-10-02）
+
+> 操作手册，不是设计笔记。配套 Claude Code skill：`.claude/skills/anland-mobilegl-plasma/`（`SKILL.md` 是本文的精简版，`scripts/` 是本文引用的全部脚本，每个脚本开头注明了参数）。现状、提交与已知问题见 [`handoff-legacy-mobilegl-unified.md`](handoff-legacy-mobilegl-unified.md)，零拷贝的设计见 [`plan-ahb-dmabuf.md`](plan-ahb-dmabuf.md)。下文路径与命令按 2026-10-02 设备上的实际状态核对过；标"未验证"的是没跑通过或只从旧记录推出来的。
+
+**设备可能正被别的会话使用。** 凡是会重启 app / daemon / 容器会话、或替换库的操作，先跑只读的 `scripts/device/status.sh` 看一眼，确认没人在测；`ct.sh` 的通道名用自己的（别人在用 c、c2、c3、xd、xr、gbm）。
+
+## 架构
+
+- **平板**：Lenovo TB321FU（Y700，Adreno 750，Android 15，内核 6.1），**KernelSU** root（`/data/adb/ksu`、`ksud`；不是 Magisk），`su -c` 可用。USB 序列号 `HA27Q3LQ`，也常走无线调试 `ip:port`。
+- **anland APK** `com.anland.consumer.mobilegl`（anland 分支 `legacy-mobilegl-unified` 的 debuggable 构建）：UI 进程 + 私有 Service 进程 `:mobilegl`（`MobileGLWorker`）。后者加载 **server** `libMobileGL.so`（NDK 构建，MobileGL 分支 `feat/disaggregated`），监听抽象 socket `@anland-mobilegl`。一个进程服务所有 client（KWin、plasmashell、ksplash、Chrome……），一个进程只服务一种后端。
+- **后端**：`setprop debug.mobilegl.backend DirectGLES|DirectVulkan`（Espryt = DirectGLES，Magma = DirectVulkan；重启丢失），必须与容器里的 `/etc/mobilegl/backend` 一致——所有 client 按这个文件报后端，不一致 server 拒绝（"Hello.backendType disagrees with pinned backend"）。
+- **实验用 display daemon**：`/data/adb/modules/anland-daemon/display_daemon /data/local/tmp/anland-mobilegl/display.sock`（显示 / 输入中介）。**开机不会自动起**——模块的 `service.sh` 只起原版那个（`/data/local/tmp/display_daemon.sock`），原版不要动。
+- **容器** `arch-kde-mgl`：Droidspaces 6.4.5，Arch Linux ARM（aarch64 glibc），host 网络；Android 侧 `rootfs.img` 挂在 `/mnt/Droidspaces/arch-kde-mgl`。bind mount：`/data/local/tmp/anland-mobilegl` → `/run/anland-mobilegl`，`/data/local/tmp/display_daemon.sock` → `/run/display.sock`。
+- **会话**：`desktop-session.service`（User=swung0x48）的 drop-in 把 ExecStart 换成 `/opt/mobilegl/bin/mobilegl-startup.sh plasma`；它每次写 `plasma-kwin_wayland.service` 的用户 drop-in（经 `kwin_wayland_wrapper` 起 `/opt/mobilegl/kwin/bin/kwin_wayland` + `/opt/mobilegl/kwin/lib/libkwin.so.6.7.4`，`ANLAND_MOBILEGL=1`、`MOBILEGL_IPC_SURFACE=server`），然后 `startplasma-wayland`。
+- **KWin 6.7.4** 带 anland 的 `anland` 后端，经 server 直接画进 anland 的 Android Surface。其余 GL 进程都是 `MOBILEGL_IPC_SURFACE=offscreen`，经 KWin 合成上屏。
+- **client 库** `/opt/mobilegl/lib/libMobileGL.so`（glibc aarch64）：glvnd 的 EGL vendor（`/opt/mobilegl/share/glvnd/egl_vendor.d/50_mobilegl.json`）+ GLX vendor（`/usr/lib/libGLX_mobilegl.so.0`，`__GLX_VENDOR_LIBRARY_NAME=mobilegl`）；环境 `MOBILEGL_TRANSPORT=spawn MOBILEGL_IPC_DATA=shm MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl`。
+- **零拷贝窗口**：client 的 `wl_egl_window` 帧是 server 分配的 AHardwareBuffer（shared image），以 dma-buf fd 经 `zwp_linux_dmabuf_v1` 交给 KWin；KWin 用 EGL 导入，server 按 inode 认出是自己发出的那块。KWin 的 DRM 设备来自 `GBM_BACKEND=mobilegl` → `/usr/lib/gbm/mobilegl_gbm.so`（节点只当身份，从不 ioctl）。没有 linux-dmabuf 时退回 wl_shm 回读。
+- **X11**（Xwayland）走 MobileGL 的 GLX vendor，每帧回读 + `xcb_put_image`。Chrome 用 `mobilegl-startup.sh chrome`：ANGLE GLES 跑在 MobileGL EGL 上，GPU 在浏览器进程内。
+
+## 首次准备（Windows 主机）
+
+- Git Bash、`adb`（SDK platform-tools）、PATH 上有 CMake ≥ 3.22 与 Ninja（本机 CMake 3.27.6、Ninja 1.13.2）；`rec.sh` 另需 Python 3 + Pillow。
+- Android NDK **27.2.12479018**，默认 `%LOCALAPPDATA%/Android/Sdk/ndk/27.2.12479018`（`ANDROID_NDK` 可覆盖）。
+- WSL 发行版 **archlinux**：clang、lld、llvm、cmake、ninja。**lld 的大版本必须等于 clang / llvm-libs**（曾经 lld 23 配 llvm 22，`ld.lld` 直接跑不起来；现在全是 22.1.6）。然后导出一次 sysroot：`bash scripts/xsysroot/refresh-sysroot.sh`（得到 WSL 里的 `~/sysroots/arch-kde-mgl` 与 `~/sysroots/aarch64-arch.cmake`，glibc 2.43、gcc 16；容器升级 glibc / gcc / vulkan / libdrm / gbm 后要重跑，再 `xbuild.sh --reconfigure`）。
+- MobileGL 用独立 worktree（主 checkout 和它的构建目录是共用的，别动）：`GIT_LFS_SKIP_SMUDGE=1 git worktree add ...`，`git submodule update --init --recursive`，再从主 checkout 拷 `3rdparty/glslang/External/spirv-tools`（submodule 初始化后是空的，configure 会报找不到 SPIR-V tools）。
+- anland worktree，分支 `legacy-mobilegl-unified`（KWin patch / 后端源码、启动脚本、`mobilegl-tools/`）。
+- 设备侧已经存在、本 runbook **不负责从零搭**的：APK（按 anland `consumers/anland_v5/android_consumer/MOBILEGL.md`，gradle `:app:assemblePlainDebug`，`MOBILEGL_DIST` 指向 server 库，`-PmobileglApplicationId=com.anland.consumer.mobilegl`；换签名重装会换 UID，要重做 KernelSU 授权，见 `mobilegl-tools/ksu_grant.c`）、anland 的 KernelSU 模块（`anland-daemon`、`anland-awl`）、容器本身，以及容器里配置好的 KWin 构建目录 `/root/mobilegl-build/kwin-6.7.4/build` 和原版 KWin 源码 `/root/gbm-dev/kwin-a/src`。从零重建这些未验证。
+- 装一次辅助脚本（容器要在跑）：`bash scripts/push-tools.sh`——`device/*.sh` 到 `/data/local/tmp/anl`，`mgrun` 到容器 `/usr/local/bin`，`kwprep.sh` 到容器 `/root`。
+
+主机脚本都在 Git Bash 里 `bash scripts/<x>.sh` 运行。直接敲 adb 时，带设备路径要加 `MSYS_NO_PATHCONV=1`（否则 `/data/...` 被改写成 Git 安装目录），root 命令整个包进一层引号：`adb shell 'su -c "..."'`。设备脚本也可以不推送直接跑：`MSYS_NO_PATHCONV=1 adb shell 'su -c sh' < scripts/device/status.sh`。
+
+## 平板重启后的拉起
+
+重启后整套会话一样都不在。可以一条 `adb shell 'su -c "sh /data/local/tmp/anl/bringup.sh [DirectGLES|DirectVulkan]"'`（按下面的步骤拼出来的，还没整体跑过），或者按顺序手敲：
+
+```sh
+adb connect <ip>:<port>        # 只有无线调试才需要（比如 USB 供不上电时）
+export MSYS_NO_PATHCONV=1
+adb shell 'su -c "svc power stayon true"'
+adb shell 'su -c "setprop debug.mobilegl.backend DirectVulkan"'      # 或 DirectGLES，与 /etc/mobilegl/backend 一致
+adb shell 'su -c "am start -n com.anland.consumer.mobilegl/com.anland.consumer.MainActivity --es socket_path /data/local/tmp/anland-mobilegl/display.sock"'
+adb shell 'su -c "/data/local/Droidspaces/bin/droidspaces -C /data/local/Droidspaces/Containers/arch-kde-mgl/container.config start"'
+adb shell 'su -c "sh /data/local/tmp/anl/restart-daemon.sh"'        # 实验 daemon；目录 777、socket 666（容器里 uid 1000 要连）
+adb shell 'su -c "sh /data/local/tmp/anl/run-plasma.sh"'            # 重启 app 与 desktop-session，约 90 秒
+```
+
+`droidspaces` 没有 `status` 子命令，`droidspaces show` 列出在跑的容器。不要用旧的 `/data/local/tmp/restart-daemon.sh`（里面 kill 的是写死的 PID）。起完用 `device/status.sh` 检查：两个进程、daemon、会话 active、kwin_wayland 与 plasmashell 在跑、kdeglobals 里没有软件渲染键。
+
+## 构建与部署循环
+
+### server（Android，NDK）→ 替换 APK 里的库
+
+```sh
+bash scripts/build-android.sh     # → <worktree>/build-android/libMobileGL.so（RelWithDebInfo，不 strip，约 320 MB，留着给 addr2line）
+bash scripts/cyc.sh s1            # 删粘滞软件渲染键 → 推库 → 换进 APK → 重启会话 → 截图 $ANL_DIR/s1.png → 打印 fatal
+```
+
+`device/swap.sh` 直接 root 覆盖 `/data/app/.../lib/arm64/libMobileGL.so`，保留 owner / 权限 / SELinux context，第一次运行把原件存为 `/data/local/tmp/anland-mobilegl/libMobileGL.so.orig`；不重签 APK（重签要重装，UID 会变，授权要重做）。只换库不跑 cyc：推到 `/data/local/tmp/anland-mobilegl/libMobileGL.new.so`，`su -c "sh /data/local/tmp/anl/swap.sh"`，之后照样要 `run-plasma.sh`——server 进程换了，KWin 不会重连。
+
+### client + GBM 后端（容器 glibc），WSL 交叉编译
+
+```sh
+bash scripts/xbuild.sh [--reconfigure]   # WSL ~/mgl-xbuild-a64；全量约 150 秒，增量几秒
+bash scripts/xdeploy.sh                  # 新 inode 改名就位安装 libMobileGL.so + mobilegl_gbm.so，刷新别名、GLX 链接、vendor JSON
+```
+
+已经在跑的 client 继续映射旧 inode：重启那个 client，KWin / plasmashell 就 `run-plasma.sh`。server 与 client **同一个 commit** 构建（两边 stamp 都取 `git rev-parse HEAD`），否则日志里 WARN "compatible wire with different build"。容器内构建是备用路径（慢）：`scripts/sync-src.sh` 同步改动的文件，再在容器里跑 anland 的 `mobilegl-tools/anland-build-client.sh`。
+
+### KWin（anland 后端 / kwin.patch），在容器里编
+
+```sh
+bash scripts/kwin-stage.sh build                                  # 去 CR 后暂存 patch + 后端 + 启动脚本，跑 kwprep.sh，后台起 sync-build-kwin.sh
+printf 'tail -5 /root/kwin-build.log\n' | bash scripts/ct.sh kw   # 等到 "== ALL DONE =="
+adb shell 'su -c "sh /data/local/tmp/anl/run-plasma.sh"'
+```
+
+两处暂存是因为两个容器脚本读的地方不同：`kwprep.sh` 读容器 `/root/kwsync.tgz`，把 `kwin.patch` 重新打到原版 KWin 源码的副本上，只把内容变了的文件拷进活树（保持 ninja 增量）；anland 的 `sync-build-kwin.sh`（`producers/kde/Arch_v5/`）读 `/run/anland-mobilegl/kwin-sync/`，只同步后端源码，`ninja -j4`，再以原子改名安装 `kwin_wayland`、`libkwin.so.6.7.4`、打过补丁的 screencast 插件和 `/opt/mobilegl/bin/mobilegl-startup.sh`，不重启合成器。仓库根的 `libdisplay_producer/` 两个脚本都不同步。`kwin-stage.sh` 是把这两步拼起来的，还没整体跑过。
+
+### 单元测试（不用设备）
+
+这个分支的 MSVC 构建是坏的，在 WSL 里编：
+
+```sh
+MSYS2_ARG_CONV_EXCL='*' wsl -d archlinux -- bash /mnt/c/<worktree>/.claude/skills/anland-mobilegl-plasma/scripts/wsl-test.sh MultiSessionTest TwinOwnershipTest
+MSYS2_ARG_CONV_EXCL='*' wsl -d archlinux -- bash -lc 'cd ~/mgl-anl-bld && ctest -R "MultiSession|TwinOwnership" -E DirectVulkan --output-on-failure'
+```
+
+`wsl-all.sh` 编并跑全部单元测试。DirectVulkan 集成测试永远不要跑；两个 ctest 不要同时跑。
+
+## 切换后端
+
+`adb shell 'su -c "sh /data/local/tmp/anl/switch.sh DirectGLES"'`（设属性、写 `/etc/mobilegl/backend`、重启 app），然后 `run-plasma.sh`——正在跑的会话里各 client 还钉在旧后端上。`cyc.sh` 不改后端。
+
+## 跑测试 client 与验证
+
+在容器里以 root 执行（`printf '...' | bash scripts/ct.sh <通道>`），`mgrun offscreen <命令>` 以 swung0x48 身份在当前会话里起一个 client（日志 `/tmp/mgl-run.client.log`，`MGLOG=/tmp/x.log` 可换）：
+
+```sh
+mgrun offscreen eglinfo -B ; mgrun offscreen glxinfo -B
+timeout 25 mgrun offscreen glmark2-es2-wayland -s 1280x720 --run-forever > /tmp/gm.out 2>&1 &
+sleep 8; grep -a "presented through" /tmp/mgl-run.client.log
+```
+
+Chrome：`bash scripts/chrome-launch.sh <tag> [参数]`（日志 `/tmp/mgl-chrome-<tag>.client.log`，截图 `ch-<tag>.png`）。探针：`scripts/probes/texfmt.c`（各纹理格式是否保住 alpha）、`dmahash.c`（对某进程的 dma-buf 取样哈希）；放进容器 `/root` 编，例如 `gcc -O1 /root/texfmt.c -o /usr/local/bin/mgl-texfmt -lEGL`，用 `mgrun offscreen` 跑（之前的确切编译参数未验证）。
+
+结论成立要同时满足：
+
+- client 日志是 `presented through linux-dmabuf shared images`，不是 `wl_shm`；出现 `could not be presented through a linux-dmabuf shared image` 说明退回了；
+- client 在动的时候 `bash scripts/shot.sh g 2 1` 两张截图哈希不同——dma-buf 下分数"很快"可能是帧根本没上屏；
+- `adb logcat -b crash -d` 与 `adb logcat -d | grep -E "Fatal signal|Abort message|E MobileGL"` 干净——窗口冻住多半是 server 死了；
+- 对 plasmashell 下结论前，粘滞软件渲染已关（见下），且 `/tmp/mgl-plasmashell.client.log` 是新写的。
+
+参考（glmark2-es2-wayland 1280x720，零拷贝 vs wl_shm）：Espryt 187 vs 49，Magma 158 vs 34。出乎意料的通过要复跑。
+
+## 日志
+
+| 内容 | 位置 |
+|---|---|
+| KWin 的 client 侧 | 容器 `/tmp/mobilegl-compositor.client.log` |
+| plasmashell / ksplash | `/tmp/mgl-plasmashell.client.log`、`/tmp/mgl-ksplash.client.log`（用户 drop-in `~/.config/systemd/user/plasma-{plasmashell,ksplash}.service.d/mobilegl-log.conf`） |
+| mgrun / Chrome | `/tmp/mgl-run.client.log`、`/tmp/mgl-chrome-<tag>.client.log`（+ `/tmp/chrome-<tag>-out.log`） |
+| server | `adb logcat -s MobileGL`；文件 `/data/data/com.anland.consumer.mobilegl/files/mobilegl-server.server.log` |
+| native 崩溃 | `adb logcat -b crash -d`；容器里 `coredumpctl list` |
+| 会话 / KWin stderr | 容器 `journalctl -u desktop-session --no-pager`、`journalctl --no-pager --since -2min \| grep kwin_wayland` |
+| display daemon | `/data/local/tmp/anland-mobilegl/display-daemon.log` |
+
+`MOBILEGL_LOG_FILE_PATH=/tmp/x.log` 实际写 `/tmp/x.client.log`（server 转发的行进 `.server.log`），打开时截断，所以每个进程一个 base。client 构建的日志级别是 INFO。server 栈帧用 `$ANDROID_NDK/toolchains/llvm/prebuilt/windows-x86_64/bin/llvm-addr2line.exe -Cfe build-android/libMobileGL.so <偏移>` 符号化。
+
+## 常见坑
+
+- **pkill -f 误杀自己**：`ct.sh` / `droidspaces run bash -lc "<脚本>"` 的进程参数里带着整段脚本，`pkill -f chrome` 会先把执行者杀掉。用 `pkill -x`。
+- **/tmp 里 root 的文件**：root 跑 client 留下的日志，之后 swung0x48 打不开（日志不出现）。先以 root `rm -f`。
+- **Plasma 软件渲染是粘滞的**：server 一崩，Plasma 就把 `[QtQuickRendererSettings] SceneGraphBackend=software` 写进 `~swung0x48/.config/kdeglobals`，之后 plasmashell 全用 CPU 渲染，截图照样正常（托盘里有"正在使用的软件渲染器"图标）。下结论前删掉：`sudo -u swung0x48 kwriteconfig6 --file kdeglobals --group QtQuickRendererSettings --key SceneGraphBackend --delete`（cyc.sh 会做），再重启会话。
+- **锁屏**：自动锁屏已关（`kscreenlockerrc` 的 `[Daemon] Autolock=false`）；真锁上只能输密码——这种 logind 会话不支持 lock-session，`device/unlock.sh` 的 unlock-session 能否解开未验证。测 greeter 用 `/usr/lib/kscreenlocker_greet --testing` 再杀掉。
+- **CRLF**：本机 `core.autocrlf=true`，anland 的后端源码和 `sync-build-kwin.sh` 在 Windows checkout 里是 CRLF。凡是要在 Linux / Android 上执行的先 `tr -d '\r'`（`ct.sh`、`push-tools.sh`、`kwin-stage.sh` 已处理）；skill 目录有 `.gitattributes` 强制 LF。
+- **display daemon 开机不自启**：KWin 报 "failed to connect to display daemon at /run/anland-mobilegl/display.sock"，会话约 3 秒退出。
+- **电量 / 连接**：电量低或熄屏（默认 30 秒）可能让 SurfaceView 被回收——`svc power stayon true`；无线调试的端口每次配对都变——脚本里不要写死 `-s HA27Q3LQ`，多设备时设 `ANDROID_SERIAL`。
+- **容器与 Android 路径**：容器的 `/tmp` 和平板的 `/data/local/tmp` 不是一个地方；文件经 `/mnt/Droidspaces/arch-kde-mgl/root`（= 容器 `/root`）或 `/data/local/tmp/anland-mobilegl`（= 容器 `/run/anland-mobilegl`）中转。
+- **正在映射的 .so 不要原地覆盖**（容器里或运行中的 APK）：拷成新 inode 再 `mv -f`；APK 换库前先 force-stop。
+- **输入注入**：普通 `adb shell input` 被拦，要 `su -c input`；anland 抓了触摸屏，`input tap` 无效时用 `input mouse tap x y`。不要对容器进程用 `debuggerd -b`（信号 35 会直接杀掉 glibc 进程）。
+- **linux-dmabuf**：client 必须 `create` + roundtrip，不能 `create_immed`（KWin 对失败的立即导入回协议错误，直接断开 client）。
+- **跨会话 bug**：某个 client 起来或退出后出现噪点 / 别的窗口的残影，先怀疑多会话 server 里的进程级状态（handle 是每 client 各自的，FBO / VAO 是每 context 的）。复现用 `kscreenlocker_greet --testing`。
+- `/etc/environment` 经 pam_env 带进 Mesa / KGSL 变量，`mobilegl-startup.sh` 里把它们 unset 了，改脚本时保留。
+- handoff 里提到的 `kwin_wayland` 日志 shim 与 `/tmp/mgl-kwin-<pid>.log` 已过时：`/opt/mobilegl/kwin/bin/kwin_wayland` 现在就是真二进制，KWin 的 client 日志在 `/tmp/mobilegl-compositor.client.log`。
+
+## 规矩
+
+- 在 git worktree 里干活，不碰共用的主 checkout 和它的构建目录；worktree 要 `GIT_LFS_SKIP_SMUDGE=1`。
+- 提交用 `git commit --no-verify`，一句话的短消息，**不加** `Co-Authored-By`。
+- DirectVulkan 集成测试不跑（`ctest -E DirectVulkan`）。
+- 源码和注释里不写外部项目名（"Mesa"、"Zink" 等），只描述手法。
+- 零拷贝路径只用厂商中立的设施：AHB、EGL_ANDROID_*、VK_ANDROID 的 AHB 导入、sync_file、dma-buf、libgbm ABI；不碰 kgsl / gralloc 私有布局 / 高通修饰符。
+- 身份缓存用单调递增的生命期 id 作键，不用 GL 名字或指针。