feat: xlings 作为运行时底座 —— subos 环境到达程序 + self-contained 的 /proc/self/exe 陷阱 (#352, #375) (2026.8.8.1) (#376)

* docs: xlings as mcpp's runtime substrate — design and implementation plan

* fix(pack): the self-contained wrapper broke /proc/self/exe and never said so

Launching through the bundled loader makes the kernel set /proc/self/exe to
the loader. Every "find my resources next to the executable" path then
resolves against lib/ -- silently. mcpp#375 reported this as a user's own
workaround; it is in fact what mcpp's own self-contained mode produces, and
the docs explained the ELF constraint that forces the launch without ever
stating its consequence.

The ELF spec forbids $ORIGIN in PT_INTERP, so the launch itself cannot go
away. What can is the silence: the wrapper now exports MCPP_BUNDLE_DIR, and
both entry points carry it because they are documented as interchangeable.
Applications that cannot be changed are pointed at --mode vendored, where
PT_INTERP is the host loader and /proc/self/exe is correct.

* docs: retract the c_runtime axis — it answered the reporter's method, not their problem

#375 is titled "let the app link against the system libc". That is the
reporter's SOLUTION. Their problem is that the artifact cannot be distributed.
The design took the title at face value and proposed a [build] c_runtime axis
whose one new capability was host-coupled -- linking the artifact against the
host's libc.

That crosses the boundary this ecosystem exists to hold. xlings is a userspace
distribution and its hermetic policy names, first on the forbidden list, any
.so under /usr/lib* or /lib* -- libc included. mcpp should not use the host
when it does not have to.

Removing that one value leaves the axis with nothing: self-contained is
already spelled --target x86_64-linux-musl, and toolchain-coupled is today's
behaviour. It would also have created a second answerer for "may I use the
host's libc", which [build] allow_host_libs already owns.

The problem has three hermetic answers and all three already exist: emit xpkg
into the ecosystem (xlings repoints the binary at install time), a static musl
target, or pack --mode self-contained. Two of them work today; the third was
broken, and that is what the previous commit fixed. What was missing was never
a mechanism -- it was that none of the three is discoverable.

The axis is kept in the document as a rejected option rather than deleted. It
had passed 12 contract tests, 7 renderer tests and a five-assertion e2e; green
tests cannot tell you a feature should not exist, and the next person reading
#375 will have the same idea.

* feat(xlings): read the subos's own description instead of inferring it

A program needs bootstrap, discovery and configuration. xlings had the first
two and, until it grew the subos_info block, nothing for the third -- its own
module comment names the consequence by number: mcpp#352, a GLFW binary that
links fine and exits 255 because nothing told it where the GL drivers are.

mcpp is the consumer of the third one, and it reads rather than knows. That is
the property that matters: mcpp must never contain the string
LIBGL_DRIVERS_PATH, because the moment it does the graphics stack has two
owners and the next capability xlings adds becomes an mcpp code change instead
of a declaration.

Every degradation fills the `note` field and callers must print it. A subos
with no block is not exotic -- mcpp's own sandbox subos was measured in
exactly that state, 356 workspace entries and no self-description -- and
silence there is what made #352 expensive to find.

family_of duplicates a five-row mapping that xlings also has. The alternative
was asking the xlings binary, which costs a subprocess in the hot path and
fails precisely where it matters: a sandbox xlings that has not been updated.
Every row is pinned in tests, so a drift is a test failure rather than a
silent ABI disagreement.

* feat(run): a program mcpp launches gets its subos's environment

A program needs three things: it links, it finds its libraries, and it is told
where its runtime data lives. mcpp supplied the first two and nothing for the
third. xlings's graphics packages declare LIBGL_DRIVERS_PATH and friends into
the subos; `xlings subos use` applied them and `mcpp run` did not. That gap is
mcpp#352 -- a GLFW binary that links cleanly and exits 255 with no output,
because nothing ever told it where the GL drivers are.

mcpp carries whatever the subos declares and knows what none of it means. The
e2e probes a variable with no graphics meaning on purpose: naming a real one
would suggest mcpp has an opinion about it, and the moment it does the
graphics stack has two owners.

Resolved at run time rather than cached with the build. These values belong to
the subos, not to the build, so a user who switches subos between `mcpp build`
and `mcpp run` has to get the new ones; it is one file read.

The subos is derived from the toolchain binary rather than from a global, so a
toolchain inherited from another home resolves to that home's subos -- the one
whose payloads the binary was actually linked against. MCPP_SUBOS_DIR
overrides it, which is how the e2e exercises this without going near a real
subos: an earlier test wrote through a symlink and permanently broke a real
toolchain.

* docs: three ways to ship, none of which uses the host's libc

mcpp#375 asked for a supported way to make a distributable artifact and
proposed one: link against the system libc. Three routes already produce a
distributable artifact and none of them does that -- through the ecosystem
(xlings repoints the ELF at install time), a static musl target, or a bundle
carrying the toolchain's own glibc. The gap was never a mechanism. It was that
the page opened with "use mcpp pack" and never said what the alternatives
were, so the reader who wanted something else had to invent it.

The note about route A is the one that answers #375 directly: a freshly built
binary's PT_INTERP names the build machine's payload, and hand-copying that
file elsewhere fails. That is a property of hand-copying, not of the artifact
-- installed through xlings the ELF is repointed at the target's own payloads.
Saying so is what stops the next reader concluding the artifact is broken and
reaching for the host's loader to "fix" it.

* chore: 2026.8.8.1, and track xlings 2026.8.7.1

The xlings pin moves because this release consumes something new from it: the
subos_info block a subos writes to describe itself. Reading it against an
older xlings degrades quietly by design, but CI should exercise the version
that actually has it.

The bootstrap pin stays at 2026.8.6.2. It is where the self-host starts, not
what the release ships -- moving it would send every CI job looking for a
version that does not exist yet.

* fix(run): the cached fast path dropped the subos environment

`mcpp run` has two paths and only one of them had been taught about subos
declarations. The full path resolves the toolchain and applies them; the fast
path skips prepare_build entirely and built its own child environment. So a
program got its environment on the run right after a build and lost it on
every run after that -- for a GL application, "it worked once and now the
window is black", with nothing in between to attribute it to.

WHICH subos is a build property and is now recorded in the build cache. WHAT
it declares is the subos's own and is re-read on every run, so installing a
graphics stack between two runs takes effect without a rebuild. That split is
also why MCPP_SUBOS_DIR moved out of the derivation: an override means "for
this invocation", and caching one would let a single `MCPP_SUBOS_DIR=… mcpp
run` silently redirect every later run.

Found by an assertion that the test did not originally have. The first version
ran `mcpp run` once, passed, and proved nothing about the path it was written
for. The fast-path check now runs first and fails loudly if the second run did
NOT take the fast path -- without it the assertion below it is vacuous and
would keep passing after the coverage silently went away. It caught a second
defect immediately: the new cache line was written before `profile=` and
parsed after `cacheMode=`, so every entry read back as stale and the fast path
was disabled for everyone.

Two dead capability tokens, and a guard so there is no third. `# requires:
linux` and `# requires: llvm` are not capabilities run_all.sh ever sets, so
65_toolchain_runtime_dirs_for_run.sh had never executed in CI -- and it
passes. The skip line for a token that cannot exist reads exactly like the
skip line for one that legitimately does not, which is what let it sit. The
runner now refuses to start when a test declares a token outside the known
universe.

The xlings pin goes back to 2026.8.6.3. It was moved to 2026.8.7.1 for tidiness
rather than need -- subos_info degrades quietly on an older xlings by design --
and CI's fresh-sandbox jobs failed with the toolchain's own g++ exiting 127,
the signature of an interpreter that is not where the binary says it is.
Whether that is a real incompatibility is worth knowing, but not on the back of
a change that does not need it.

* fix(xlings): the env list separator is the platform's, not a literal ':'

Windows CI caught this; no amount of reading would have. resolve_env joined
and split its lists on ':', which on Windows is both the wrong separator (it
is ';') and a character that appears INSIDE every absolute path. So
de-duplication split "C:\x" into "C" and "\x", matched nothing, and the
joined value came back as "C:\...\x:C:\...\x" -- a list that grows on every
nested invocation and that no consumer can parse.

This repository has made the same mistake before, in the other direction:
find_first_of(";:") over a Windows PATH cuts at the drive-letter colon.

The three test expectations that failed were also wrong, but differently, and
the difference matters: they compared against a path JOIN while the code does
a literal substitution. The literal one is correct -- the separator inside a
declaration belongs to the subos manifest, and rewriting it to the host's
spelling would be editing a value we do not own. The assertions now say so,
and the dedup test additionally asserts the result contains NO separator at
all, which is the property that actually failed.

* fix(xlings): drop a ranges spelling that crashed the clang 20 frontend

Windows CI: `clang++: error: clang frontend command failed due to signal`,
with the diagnostic file named subos_info-*.cppm. No message beyond the
signal, so the offending construct is identified by removal rather than by a
compiler telling us.

The one exotic thing in the file was `std::ranges::find` with a member-pointer
projection into std::pair; `std::ranges::sort` went with it for the same
reason. Both are replaced by plain loops, which nothing here needed to be
fancier than.

Ruled out first: importing mcpp.platform, added in the previous commit and the
only other change to this file between the run that failed a test assertion
and the run that crashed the compiler. Four modules already import
mcpp.libs.json and mcpp.platform together (bmi_cache, stdmod, post_install,
prepare), so that combination is not it.

Stated plainly because it matters for the next person: this is a hypothesis
confirmed only by CI going green, not by a local reproduction. The crash needs
clang 20.1.7 targeting MSVC and I have no such host.

---------

Co-authored-by: speak-agent <x.d2learn.org@gmail.com>

Author: Sunrisepeak

.agents/docs/2026-08-07-xlings-as-runtime-substrate-design.md

@@ -1,9 +1,42 @@
 # 02 — Packaging for Release
 
-> A default dynamically linked binary produced by `mcpp build` normally has a
-> loader and RUNPATH tied to the build sandbox. To distribute it to other
-> machines or deploy it to a server, use `mcpp pack` to produce a release
-> tarball or directory with the appropriate runtime closure.
+> A default dynamically linked binary produced by `mcpp build` has a loader and
+> RUNPATH tied to the build sandbox. It is a development artifact, not a
+> deliverable. Three routes turn it into one — and none of them uses the host's
+> C library.
+
+## Three ways to ship
+
+Every route below produces an artifact whose C runtime comes from the
+ecosystem, never from `/lib64`. That is deliberate: mcpp builds against a
+private glibc precisely so a binary's behaviour does not depend on which
+distribution happens to be underneath it, and reaching back out to the host's
+libc to distribute would give that away at the last step.
+
+| | Route | Command | Where its C runtime comes from | Choose it when |
+|---|---|---|---|---|
+| **A** | Through the ecosystem | `mcpp emit xpkg` → `xlings install <pkg>` | the target machine's own xlings payloads | the target has xlings |
+| **B** | One static file | `mcpp build --target x86_64-linux-musl` | nowhere — it is linked in | you want a single file with no runtime at all |
+| **C** | Carry the runtime | `mcpp pack --mode self-contained` | shipped inside the bundle | any Linux, including older than the build machine |
+
+**On route A, and the thing that surprises people.** The `PT_INTERP` baked into
+a freshly built binary points at *your* machine's payload, so copying that file
+to another machine by hand does not work — the path is not there. That is not a
+property of the artifact so much as of the copy: installed through `xlings`, the
+package's ELF files are repointed at the target machine's own payloads at
+install time. The baked path is a build-machine detail, not a distribution
+format. If you are hand-copying binaries between machines, you want B or C.
+
+**On route B.** `--target …-musl` implies a static link, so there is no loader,
+no RUNPATH and nothing to find at run time. It is the smallest and most
+portable result, and the one to reach for first when the program does not need
+glibc-specific behaviour (NSS lookups, `dlopen` of host plugins).
+
+**On route C.** The bundle carries this toolchain's glibc and its loader, so it
+runs on distributions older than the build machine — the case B cannot cover
+when glibc is actually required. Read the `/proc/self/exe` note below before
+choosing it: launching through a bundled loader changes what the program sees
+about itself.
 
 ## Two axes: target (libc) × mode (bundling depth)
 
@@ -128,6 +161,37 @@ exec "$here/lib/ld-linux-x86-64.so.2" --library-path "$here/lib" "$here/bin/myap
 The layout and wrapper above use an x86_64 example. The packer derives the
 loader name from the target; for aarch64 it is `ld-linux-aarch64.so.1`.
 
+#### Trap: `/proc/self/exe` under the bundled loader
+
+Being started *by* the loader has a consequence the layout above does not
+show: the kernel sets `/proc/self/exe` to the **loader**, not to your program,
+and `/proc/self/cmdline` carries the `--library-path` argument. Every "find my
+resources next to the executable" path therefore resolves against `lib/`
+instead of the bundle root — and it does so silently. In practice that means
+a GUI toolkit rendering blank text because it cannot find its fonts, an
+`assets/` directory that appears to be missing, and helper binaries shipped
+alongside the program that cannot be located. Code that parses `argv` from
+`/proc/self/cmdline` sees the loader's arguments mixed in.
+
+This affects `self-contained` only. `vendored`, `system` and `static` all
+carry a `PT_INTERP` that the kernel can use directly, so `/proc/self/exe` is
+correct there.
+
+The wrapper exports **`MCPP_BUNDLE_DIR`** (the bundle root) for this. Resolve
+against it first and fall back only when it is unset:
+
+```c
+const char *base = getenv("MCPP_BUNDLE_DIR");   /* set by run.sh */
+if (!base) {
+    /* not launched through the wrapper — /proc/self/exe is trustworthy */
+}
+```
+
+If the application cannot be changed — a third-party GUI framework doing its
+own resolution, say — use `--mode vendored` instead. It repoints `PT_INTERP`
+at the host loader, at the cost of requiring the host's glibc to be at least
+as new as the one the artifact was built against.
+
 ## Configuration
 
 Packaging behavior is configured via the `[pack]` section in `mcpp.toml`. The

.agents/docs/2026-08-08-xlings-runtime-substrate-implementation-plan.md

@@ -1,8 +1,34 @@
 # 02 — 发布打包
 
-> 默认的动态链接 `mcpp build` 产物通常会把 loader 与 RUNPATH 指向构建沙盒。
-> 如需分发至其他机器或部署至服务器,应使用 `mcpp pack` 生成带有适当运行时闭包的
-> 发布 tarball 或目录。
+> 默认的动态链接 `mcpp build` 产物会把 loader 与 RUNPATH 指向构建沙盒。它是
+> 开发产物,不是交付物。有三条路把它变成交付物 —— **没有一条使用宿主的 C 库**。
+
+## 三种分发方式
+
+下面每一条产出的产物,其 C 运行时都来自生态,而不是 `/lib64`。这是有意的:
+mcpp 之所以针对私有 glibc 构建,正是为了让产物的行为不取决于底下是哪个发行版;
+如果最后一步又伸手去拿宿主的 libc,前面这件事就白做了。
+
+| | 方式 | 命令 | C 运行时来自哪里 | 何时选它 |
+|---|---|---|---|---|
+| **A** | 走生态 | `mcpp emit xpkg` → `xlings install <pkg>` | 目标机自己的 xlings 载荷 | 目标机装了 xlings |
+| **B** | 静态单文件 | `mcpp build --target x86_64-linux-musl` | 不来自任何地方 —— 已链进去 | 想要一个无任何运行时依赖的单文件 |
+| **C** | 自带运行时 | `mcpp pack --mode self-contained` | 随 bundle 一起分发 | 任何 Linux,含比构建机更老的 |
+
+**关于 A,以及那个让人意外的地方。** 刚构建出的二进制里烙的 `PT_INTERP` 指向
+**你这台机器**的载荷,所以手工把这个文件拷到另一台机器上跑不起来——那个路径
+在那边不存在。与其说这是产物的性质,不如说是「手工拷贝」这个动作的性质:经
+`xlings` 安装时,包里的 ELF 会在**装机期被重指到目标机自己的载荷**。烙进去的
+路径是构建机的细节,不是分发格式。如果你就是要在机器之间手工拷二进制,那你要
+的是 B 或 C。
+
+**关于 B。** `--target …-musl` 隐含静态链接,所以没有 loader、没有 RUNPATH、
+运行期不需要找任何东西。它的结果最小也最可移植,在程序不需要 glibc 专有行为
+(NSS 查询、`dlopen` 宿主插件)时应当首选。
+
+**关于 C。** bundle 里带着这套工具链的 glibc 与 loader,因此能在比构建机更老的
+发行版上跑 —— 这是 B 覆盖不了、而又确实需要 glibc 时的那一格。选它之前先读下面
+的 `/proc/self/exe` 一节:经 bundled loader 启动会改变程序对「自己在哪」的认知。
 
 ## 两条轴:target(libc) × mode(打包深度)
 
@@ -120,6 +146,32 @@ exec "$here/lib/ld-linux-x86-64.so.2" --library-path "$here/lib" "$here/bin/myap
 上面的布局与 wrapper 以 x86_64 为例。打包器会按 target 推导 loader 名称；aarch64
 对应 `ld-linux-aarch64.so.1`。
 
+#### 陷阱:经 bundled loader 启动后的 `/proc/self/exe`
+
+「由 loader 启动」有一个上面的布局看不出来的后果:内核会把 `/proc/self/exe`
+指向 **loader**,而不是你的程序;`/proc/self/cmdline` 里也混进了
+`--library-path`。于是所有「在可执行文件旁边找资源」的逻辑都会解析到 `lib/`
+而不是 bundle 根目录——而且是**静默**的。实际表现是:GUI 框架找不到字体因而
+文字渲染空白、`assets/` 目录看起来不存在、随包分发的辅助二进制定位失败。
+按 `/proc/self/cmdline` 解析 argv 的代码则会拿到混入 loader 参数的结果。
+
+这只影响 `self-contained`。`vendored`、`system`、`static` 的 `PT_INTERP`
+都能被内核直接使用,`/proc/self/exe` 是正确的。
+
+wrapper 为此导出 **`MCPP_BUNDLE_DIR`**(bundle 根目录)。优先用它,只在未设置
+时回退:
+
+```c
+const char *base = getenv("MCPP_BUNDLE_DIR");   /* 由 run.sh 设置 */
+if (!base) {
+    /* 不是经 wrapper 启动的 —— 此时 /proc/self/exe 可信 */
+}
+```
+
+如果应用本身改不了(比如第三方 GUI 框架自己做解析),改用 `--mode vendored`:
+它把 `PT_INTERP` 重指到宿主 loader,`/proc/self/exe` 正常,代价是要求宿主
+glibc 不低于构建时所用的那份。
+
 ## 配置项
 
 打包行为通过 `mcpp.toml` 中的 `[pack]` 节配置,常用字段如下:

docs/02-pack-and-release.md

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "2026.8.7.1"
+version     = "2026.8.8.1"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

docs/zh/02-pack-and-release.md

@@ -20,6 +20,8 @@ import mcpp.manifest;
 import mcpp.modgraph.scanner;
 import mcpp.toolchain.stdmod;
 import mcpp.xlings;
+import mcpp.xlings.subos_info;
+import mcpp.log;
 import mcpp.platform;
 import mcpp.fetcher.progress;
 import mcpp.project;
@@ -60,6 +62,12 @@ struct BuildCacheEntry {
     // plan.runtimeLibraryDirs is empty.
     std::string runEnvKey;
     std::string runEnvValue;
+    // The subos this build's toolchain belongs to (mcpp#352). The DIRECTORY,
+    // never the resolved variables: the environment is the subos's property
+    // and must be re-read on every run, while WHICH subos is the build's
+    // property and would otherwise be unknowable on the fast path -- which
+    // has no toolchain to derive it from.
+    std::string subosDir;
     // The resolved profile this entry was built for. Entries used to be keyed
     // by target triple alone, and the fast paths only refuse to run when an
     // EXPLICIT --profile/--dev/--release is passed — so a bare `mcpp build`
@@ -139,6 +147,16 @@ std::vector<BuildCacheEntry> read_build_cache(const std::filesystem::path& proje
             std::getline(f, e.runEnvValue);
             haveNextLine = static_cast<bool>(std::getline(f, line));
         }
+        // Optional subos line. Same back-compat contract: absent ⇒ empty ⇒
+        // the run fast path treats the entry as a miss, exactly as it already
+        // does for a cache written before runtimeEnvKey existed. Running with
+        // a DIFFERENT environment than the full path would be worse than not
+        // using the cache at all -- the program would work once and then
+        // silently stop finding its runtime data.
+        if (haveNextLine && line.starts_with("subos=")) {
+            e.subosDir = line.substr(6);
+            haveNextLine = static_cast<bool>(std::getline(f, line));
+        }
         // Optional profile line. Same back-compat contract as the two blocks
         // above: absent ⇒ e.profile stays empty ⇒ every fast path treats the
         // entry as a miss and falls through to prepare_build.
@@ -167,7 +185,8 @@ void write_build_cache(const std::filesystem::path& projectRoot,
                        const std::string& runEnvKey = "",
                        const std::string& runEnvValue = "",
                        const std::string& profile = "",
-                       const std::string& cacheMode = "") {
+                       const std::string& cacheMode = "",
+                       const std::string& subosDir = "") {
     auto path = projectRoot / kBuildCacheFile;
     auto entries = read_build_cache(projectRoot);
 
@@ -182,7 +201,7 @@ void write_build_cache(const std::filesystem::path& projectRoot,
     // Insert at front (MRU).
     BuildCacheEntry newEntry{targetTriple, outputDir.string(), ninjaProgram, fingerprintHex,
                              runtimeEnvKey, runtimeEnvValue, std::move(runTargets),
-                             runEnvKey, runEnvValue, profile, cacheMode};
+                             runEnvKey, runEnvValue, subosDir, profile, cacheMode};
     entries.insert(entries.begin(), std::move(newEntry));
 
     // Trim to LRU capacity.
@@ -210,6 +229,7 @@ void write_build_cache(const std::filesystem::path& projectRoot,
         for (auto& [name, exe] : e.runTargets) f << name << '\t' << exe << '\n';
         f << "runEnv=" << e.runEnvKey << '\n';
         f << e.runEnvValue << '\n';
+        f << "subos=" << e.subosDir << '\n';
         f << "profile=" << e.profile << '\n';
         f << "cacheMode=" << e.cacheMode << '\n';
     }
@@ -287,6 +307,55 @@ compute_run_env(const mcpp::build::BuildPlan& plan) {
     return {key, value};
 }
 
+// The environment the active subos declares for the programs it hosts
+// (mcpp#352).
+//
+// A GL application needs three things and mcpp only ever supplied two: the
+// binary links (bootstrap), it finds its libraries (RPATH), and then it has to
+// be told which driver module to load and which GL vendors exist. That third
+// one is a set of environment variables, xlings's graphics packages declare
+// them into the subos, and until now nothing carried them to a program mcpp
+// launched — `xlings subos use` applied them, `mcpp run` did not. Hence a
+// binary that links fine and exits 255 with no output.
+//
+// Resolved at RUN time, deliberately not cached with the build: these values
+// belong to the subos, not to the build, and a user who switches subos between
+// `mcpp build` and `mcpp run` must get the new one. It is a file read.
+//
+// mcpp does not know what any of these variables MEAN, and that is the design:
+// when the ecosystem gains a Vulkan loader or a new driver bridge, the
+// declaration changes and this code does not.
+// The subos a RUN should use: an explicit override if the caller set one,
+// otherwise the subos this build belongs to.
+//
+// The override lives HERE and not in the derivation, because the derivation's
+// answer is cached and this one must not be: MCPP_SUBOS_DIR says "for this
+// invocation". It exists so tests can exercise this path without touching a
+// developer's real subos — an earlier e2e wrote through a symlink and
+// permanently broke a real toolchain — and so a user can point one run at
+// another subos without switching the active one.
+std::filesystem::path subos_dir_for_run(const std::filesystem::path& buildSubos) {
+    if (const char* e = std::getenv("MCPP_SUBOS_DIR"); e && *e)
+        return std::filesystem::path(e);
+    return buildSubos;
+}
+
+std::vector<std::pair<std::string, std::string>>
+compute_subos_env(const mcpp::build::BuildPlan& plan) {
+    auto built = mcpp::xlings::paths::subos_dir_of(plan.toolchain.binaryPath);
+    auto dir = subos_dir_for_run(built ? *built : std::filesystem::path{});
+    if (dir.empty()) return {};
+    auto info = mcpp::xlings::subos::read(dir);
+    // The note is a `verbose` line rather than a warning: a subos with no
+    // self-description is the normal state of every machine whose subos
+    // predates the block, and a warning on every run would train people to
+    // ignore it. It becomes loud only where it explains a failure — the GL
+    // diagnostic path in doctor.
+    if (!info.note.empty())
+        mcpp::log::verbose("subos", info.note);
+    return mcpp::xlings::subos::resolve_env(info, dir);
+}
+
 // Compile a prepared BuildContext. Shared between `mcpp build` and `mcpp run`
 // so the latter doesn't call prepare_build twice (and re-print the toolchain
 // resolution banner).
@@ -398,12 +467,14 @@ export int run_build_plan(BuildContext& ctx, bool verbose, bool no_cache,
         auto fpHex = ctx.outputDir.filename().string();
         auto runTargets = compute_run_targets(ctx.plan);
         auto [runEnvKey, runEnvValue] = compute_run_env(ctx.plan);
+        auto subosDir = mcpp::xlings::paths::subos_dir_of(ctx.plan.toolchain.binaryPath);
         write_build_cache(ctx.projectRoot, ctx.outputDir, r->ninjaProgram,
                           std::string(targetOverride), fpHex,
                           r->runtimeEnvKey.empty() ? "-" : r->runtimeEnvKey,
                           r->runtimeEnvValue,
                           std::move(runTargets), runEnvKey, runEnvValue,
-                          ctx.profile, std::string(cache_mode_name(ctx.cacheMode)));
+                          ctx.profile, std::string(cache_mode_name(ctx.cacheMode)),
+                          subosDir ? subosDir->string() : std::string{});
     }
 
     // The one place the --strict policy is settled. Degradations reported by
@@ -754,6 +825,25 @@ std::optional<int> try_fast_run(const std::filesystem::path& projectRoot,
     std::vector<std::pair<std::string, std::string>> childEnv;
     if (!match->runEnvKey.empty() && !match->runEnvValue.empty())
         childEnv.emplace_back(match->runEnvKey, match->runEnvValue);
+    // ...and the subos's declared environment, re-READ here rather than taken
+    // from the cache. Which subos is a build property (cached above); what it
+    // declares is the subos's own, and a user who installs a graphics stack
+    // between two runs must get it without rebuilding.
+    //
+    // This is the half that a fast path is most likely to lose, and losing it
+    // would be invisible in the worst way: the first `mcpp run` after a build
+    // takes the full path and works, every later one takes this path and does
+    // not. A GL program would run once and then stop finding its driver.
+    {
+        // Same rule as the full path, through the same helper: an override
+        // for this invocation, else the subos this build was recorded against.
+        auto subosDir = subos_dir_for_run(std::filesystem::path(match->subosDir));
+        if (!subosDir.empty()) {
+            auto info = mcpp::xlings::subos::read(subosDir);
+            for (auto& kv : mcpp::xlings::subos::resolve_env(info, subosDir))
+                childEnv.push_back(std::move(kv));
+        }
+    }
 
     return mcpp::platform::process::run_exec(argv, childEnv) == 0 ? 0 : 1;
 }
@@ -827,6 +917,8 @@ export int build_run_target(const std::optional<std::string>& targetName,
     auto [runEnvKey, runEnvValue] = compute_run_env(ctx->plan);
     if (!runEnvKey.empty() && !runEnvValue.empty())
         childEnv.emplace_back(runEnvKey, runEnvValue);
+    // ...plus whatever the subos declares for the programs it hosts (#352).
+    for (auto& kv : compute_subos_env(ctx->plan)) childEnv.push_back(std::move(kv));
 
     // Direct exec (no /bin/sh): the loader env reaches ONLY the target child,
     // never mcpp or a host shell. Fixes the bundled-glibc-vs-host-libtinfo
@@ -1213,6 +1305,9 @@ export int run_tests(std::span<const std::string> passthrough,
     auto runtimeEnvKey = mcpp::platform::env::runtime_library_path_key();
     auto runtimeEnvValue = mcpp::platform::env::prepend_path_list(
         runtimeEnvKey, ctx->plan.runtimeLibraryDirs);
+    // Read once for the whole run rather than per test: it is one file, and
+    // every test in a run belongs to the same subos.
+    const auto subosEnv = compute_subos_env(ctx->plan);
 
     // macOS deliberately has no runtime-library-path key (env.cppm): injecting
     // DYLD_LIBRARY_PATH would reach every executable ninja launches and can
@@ -1283,6 +1378,10 @@ export int run_tests(std::span<const std::string> passthrough,
         std::vector<std::pair<std::string, std::string>> childEnv;
         if (!runtimeEnvKey.empty() && !runtimeEnvValue.empty())
             childEnv.emplace_back(runtimeEnvKey, runtimeEnvValue);
+        // ...and the subos's declared environment, same as `mcpp run` (#352).
+        // A GL test that cannot find a driver fails the same way a GL program
+        // does, so it must be told the same things.
+        for (auto& kv : subosEnv) childEnv.push_back(kv);
 
         // Prepend the sandbox's subos/default/bin to the CHILD PATH so test
         // binaries that shell out to bootstrapped tools (patchelf, ninja) find