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.

Author: speak-agent

.github/actions/bootstrap-mcpp/action.yml

@@ -25,7 +25,7 @@ inputs:
     # `package.name`, so one of the two was simply unreachable — and which one
     # depended on the machine, which is why CI failed on `compat:lua` on
     # Windows and `mcpplibs.capi:lua` on Linux. Never pin below that.
-    default: '2026.8.7.1'
+    default: '2026.8.6.3'
   cache-target:
     description: also restore/save target/ (build artifacts + BMIs)
     required: false

.github/actions/setup-macos-llvm/action.yml

@@ -15,7 +15,7 @@ inputs:
     # Floor imposed by the index, not a routine bump — see
     # .github/actions/bootstrap-mcpp/action.yml for why 0.4.69 is required
     # (two packages named `lua` in one repo need openxlings/xlings#381).
-    default: '2026.8.7.1'
+    default: '2026.8.6.3'
 
 runs:
   using: composite

.github/workflows/bootstrap-macos.yml

@@ -17,7 +17,7 @@ jobs:
       # Dormant (workflow_dispatch only), but kept in step with the rest —
       # check_version_pins.sh holds it there. Floor: 0.4.69, below which the
       # index cannot resolve two packages that share a short name.
-      XLINGS_VERSION: '2026.8.7.1'
+      XLINGS_VERSION: '2026.8.6.3'
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-fresh-install.yml

@@ -152,7 +152,7 @@ jobs:
         env:
           XLINGS_NON_INTERACTIVE: '1'
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.7.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.6.3
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
@@ -292,7 +292,7 @@ jobs:
 
       - name: Install xlings + mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.7.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.6.3
           # Deliberately NOT writing to $GITHUB_PATH here. On container
           # images that declare no PATH in their config (opensuse/
           # tumbleweed), appending a single dir to GITHUB_PATH makes the
@@ -363,7 +363,7 @@ jobs:
           #             (older ones carry minos=15 and refuse to start).
           #   v0.4.51+: in-process sha256 — this image has no sha256sum
           #             binary, so pinned fetches failed before it.
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.7.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.6.3
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror

.github/workflows/ci-linux-e2e.yml

@@ -123,7 +123,7 @@ jobs:
 
       - name: Bootstrap xlings + released mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.7.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.6.3
           export PATH="$HOME/.xlings/subos/current/bin:$PATH"
           xlings update
           xlings install mcpp -y -g

.github/workflows/cross-build-test.yml

@@ -118,7 +118,7 @@ jobs:
           # release assets were uploaded in a broken state (records present,
           # blobs missing → 404 on GET); re-uploaded clean. The stale-INDEX
           # half is handled by the marker-clear below.
-          XLINGS_VERSION: '2026.8.7.1'
+          XLINGS_VERSION: '2026.8.6.3'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           curl -fsSL -o "/tmp/${tarball}" \
@@ -255,7 +255,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.7.1'
+          XLINGS_VERSION: '2026.8.6.3'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           curl -fsSL -o "/tmp/${tarball}" \

.github/workflows/release.yml

@@ -96,7 +96,7 @@ jobs:
           # Pin xlings to a known-good version. The upstream install
           # script always grabs `latest` (no version override), so we
           # download + self-install manually to avoid broken releases.
-          XLINGS_VERSION: '2026.8.7.1'
+          XLINGS_VERSION: '2026.8.6.3'
         run: |
           if [ ! -x "$HOME/.xlings/subos/default/bin/xlings" ]; then
             tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
@@ -288,7 +288,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.7.1'
+          XLINGS_VERSION: '2026.8.6.3'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           curl -fsSL -o "/tmp/${tarball}" \
@@ -358,11 +358,11 @@ jobs:
           # below are pinned to the same version as XLINGS_VERSION; they are
           # NOT interpolated from it, so check_version_pins.sh scans for them
           # explicitly (they were absent from the old lock-step comment).
-          XLA="xlings-2026.8.7.1-linux-aarch64.tar.gz"
+          XLA="xlings-2026.8.6.3-linux-aarch64.tar.gz"
           if curl -fsSL -o "/tmp/$XLA" \
-               "https://github.com/openxlings/xlings/releases/download/v2026.8.7.1/$XLA"; then
+               "https://github.com/openxlings/xlings/releases/download/v2026.8.6.3/$XLA"; then
             tar -xzf "/tmp/$XLA" -C /tmp
-            XLBIN=$(find /tmp/xlings-2026.8.7.1-linux-aarch64 -path '*/bin/xlings' -type f | head -1)
+            XLBIN=$(find /tmp/xlings-2026.8.6.3-linux-aarch64 -path '*/bin/xlings' -type f | head -1)
             if [ -n "$XLBIN" ]; then
               mkdir -p "$STAGING/$WRAPPER/registry/bin"
               cp "$XLBIN" "$STAGING/$WRAPPER/registry/bin/xlings"
@@ -440,7 +440,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.7.1'
+          XLINGS_VERSION: '2026.8.6.3'
         run: |
           if [ ! -x "$HOME/.xlings/subos/default/bin/xlings" ]; then
             WORK=$(mktemp -d)
@@ -622,7 +622,7 @@ jobs:
         shell: bash
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.7.1'
+          XLINGS_VERSION: '2026.8.6.3'
         run: |
           # Captured before the `cd` below, in POSIX form: this step never
           # returns to the workspace, and GITHUB_WORKSPACE is a backslash

src/build/execute.cppm

@@ -62,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`
@@ -141,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.
@@ -169,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);
 
@@ -184,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.
@@ -212,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';
     }
@@ -307,19 +325,35 @@ compute_run_env(const mcpp::build::BuildPlan& plan) {
 // 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 dir = mcpp::xlings::paths::subos_dir_for(plan.toolchain.binaryPath);
-    if (!dir) return {};
-    auto info = mcpp::xlings::subos::read(*dir);
+    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);
+    return mcpp::xlings::subos::resolve_env(info, dir);
 }
 
 // Compile a prepared BuildContext. Shared between `mcpp build` and `mcpp run`
@@ -433,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
@@ -789,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;
 }

src/xlings.cppm

@@ -44,7 +44,7 @@ namespace pinned {
     // in lock-step by hand; that list was already missing both composite
     // actions, which is how CI's sandbox sat on 0.4.30 unnoticed while
     // everything else had moved on. Don't reintroduce a hand-maintained list.
-    inline constexpr std::string_view kXlingsVersion   = "2026.8.7.1";
+    inline constexpr std::string_view kXlingsVersion   = "2026.8.6.3";
     inline constexpr std::string_view kNasmVersion     = "3.02";
 }
 
@@ -74,25 +74,25 @@ namespace paths {
     std::optional<std::filesystem::path>
     xpkgs_from_compiler(const std::filesystem::path& compilerBin);
 
-    // The subos whose declared ENVIRONMENT a program built with this toolchain
-    // should run under (mcpp#352).
+    // The subos a TOOLCHAIN belongs to (mcpp#352).
     //
     // Derived from the compiler rather than from a global: a build already
     // knows which home its toolchain came from, and asking a second source
     // would let the two disagree — the "one question, several answerers" shape
     // that the same investigation found four times over on the xlings side.
     //
-    // MCPP_SUBOS_DIR overrides it outright. That exists so tests can exercise
-    // this path without touching the developer's real environment (a lesson
-    // with a scar: 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.
+    // A PURE derivation, with no environment override in it. That is not an
+    // omission: this value gets written into the build cache, and an override
+    // means "for this invocation", not "for this build from now on". Caching
+    // one would make a single `MCPP_SUBOS_DIR=… mcpp run` silently change
+    // where every later run looked. Which subos a RUN should use is a
+    // different question, answered in execute.cppm.
     //
     // Empty when the toolchain is not sandbox-resident — a system compiler is
     // the user's explicit choice of the host world, and there is no subos
     // speaking for it.
     std::optional<std::filesystem::path>
-    subos_dir_for(const std::filesystem::path& compilerBin);
+    subos_dir_of(const std::filesystem::path& compilerBin);
 
     // Find a sibling xim tool relative to a compiler binary.
     // e.g. find_sibling_tool(gcc_bin, "binutils") returns highest version
@@ -694,9 +694,7 @@ xpkgs_from_compiler(const std::filesystem::path& compilerBin) {
 }
 
 std::optional<std::filesystem::path>
-subos_dir_for(const std::filesystem::path& compilerBin) {
-    if (const char* e = std::getenv("MCPP_SUBOS_DIR"); e && *e)
-        return std::filesystem::path(e);
+subos_dir_of(const std::filesystem::path& compilerBin) {
     auto xpkgs = xpkgs_from_compiler(compilerBin);
     if (!xpkgs) return std::nullopt;
     // <home>/data/xpkgs → <home>/subos/default. Spelled from the xpkgs dir

…sts/e2e/195_subos_env_reaches_program.sh …sts/e2e/200_subos_env_reaches_program.shtests/e2e/195_subos_env_reaches_program.sh renamed to tests/e2e/200_subos_env_reaches_program.sh tests/e2e/195_subos_env_reaches_program.sh renamed to tests/e2e/200_subos_env_reaches_program.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# requires: linux
-# 195_subos_env_reaches_program.sh — a subos's declared environment must reach
+# requires: elf
+# 200_subos_env_reaches_program.sh — a subos's declared environment must reach
 # the program mcpp launches (mcpp#352).
 #
 # A program needs three things: it links (bootstrap), it finds its libraries
@@ -55,6 +55,49 @@ echo "$out" | grep -q "PROBE=$subos/usr/lib/dri" || {
     exit 1
 }
 
+# 1b. THE SECOND RUN, which takes the cached fast path.
+#
+# This is the assertion that matters most, and the one a single-run test
+# cannot make. The fast path builds its own child environment and skips
+# prepare_build entirely; when it was first written it did not know about
+# subos declarations at all, so a program worked on the run right after a
+# build and silently stopped finding its runtime data on every run after
+# that. For a GL application that is "it worked once and now the window is
+# black", with nothing in between to attribute it to.
+out_cached=$(MCPP_SUBOS_DIR="$subos" "$MCPP" run 2>&1) || {
+    echo "cached mcpp run failed:"; echo "$out_cached"; exit 1; }
+# Self-check FIRST: prove this run actually took the fast path, otherwise the
+# assertion below is vacuous and would keep passing after the coverage it
+# exists for has silently gone away. The full path resolves the toolchain and
+# says so; the fast path skips prepare_build entirely and never prints it.
+echo "$out_cached" | grep -q 'Resolving toolchain' && {
+    echo "the second run did NOT take the cached fast path, so this test is"
+    echo "  not covering it. Fix the test before trusting the assertion below:"
+    echo "$out_cached"
+    exit 1
+}
+echo "$out_cached" | grep -q "PROBE=$subos/usr/lib/dri" || {
+    echo "the cached fast path dropped the subos environment — the program"
+    echo "  gets a different environment on its second run than its first:"
+    echo "$out_cached"
+    exit 1
+}
+
+# 1c. ...and the environment is re-READ, not cached with the build. A user
+#     who installs a graphics stack between two runs must get it without
+#     rebuilding, so changing the declaration must change the next run.
+sed -i 's#/usr/lib/dri#/usr/lib/dri2#' "$subos/.xlings.json"
+out_changed=$(MCPP_SUBOS_DIR="$subos" "$MCPP" run 2>&1) || {
+    echo "run after changing the declaration failed:"; echo "$out_changed"; exit 1; }
+echo "$out_changed" | grep -q "PROBE=$subos/usr/lib/dri2" || {
+    echo "the subos declaration changed but the program still sees the old"
+    echo "  value — the environment was cached with the build instead of"
+    echo "  being read from the subos:"
+    echo "$out_changed"
+    exit 1
+}
+sed -i 's#/usr/lib/dri2#/usr/lib/dri#' "$subos/.xlings.json"
+
 # 2. Without a subos saying anything, nothing is invented.
 out2=$("$MCPP" run 2>&1) || { echo "plain mcpp run failed:"; echo "$out2"; exit 1; }
 echo "$out2" | grep -q 'PROBE=(unset)' || {