fix(fallback): a vendored xlings behind the pin, and a sysroot from elsewhere

D4. acquire_xlings_binary returned on mere existence, so a home kept the
first xlings it ever acquired. Measured here: 2026.8.2.1 against a pin of
2026.8.6.3, with `mcpp self env` printing both numbers beside each other and
saying nothing about the gap. Not cosmetic -- the subos_info block arrived in
xlings 2026.8.5.1, so on that machine every subos declaration was discarded by
a client too old to have the API, and the mcpp#352 fix could not take effect
however current mcpp itself was. Missing features are silent by construction:
an absent block is also a legitimate state.

The first cut of this deleted the vendored binary and re-acquired. That
replaced 2026.8.2.1 with the system's 0.4.51 -- older still, and missing the
very feature the replacement existed to restore. Being behind the pin
justifies looking for a replacement; it does not justify taking whatever
turns up. candidate_source_version() now prices the replacement before the
old one is removed, and the epoch-crossing comparison (0.4.x vs YYYY.M.D.N)
is pinned by a test, since both schemes live on the same disk.

D5. remap_xlings_baked_sysroot asked whether gcc's baked sysroot exists. Wrong
axis: gcc records `--sysroot=<...>/.xlings/subos/default` as a string when it
is built and keeps reporting it in every project it later serves, and a
machine with several checkouts has many directories by that name. The baked
path therefore routinely exists and belongs to someone else -- a build inside
mcpp resolved a sysroot under an unrelated repo. The predicate is now
ownership, not existence.

doctor reports both. The sysroot finding is anchored on the mcpp home and the
project rather than on the compiler's own tree: written the obvious way it
consulted xpkgs_from_compiler(binaryPath), which returns nothing when the
compiler is reached through an xvm shim -- the default project-local case, and
this machine's. It would have shipped as a check that never checked.

  tests/unit/test_xlings_version_pin.cpp     +1 (epoch crossing)
  tests/unit/test_sysroot_ownership.cpp      +7 (new; no filesystem, on purpose)

Author: speak-agent

src/config.cppm

@@ -600,7 +600,8 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
 
     // 6. Acquire xlings binary if needed
     if (cfg.xlingsBinaryMode == "bundled") {
-        auto xbin = mcpp::fallback::acquire_xlings_binary(cfg.xlingsBinary, quiet);
+        auto xbin = mcpp::fallback::acquire_xlings_binary(
+            cfg.xlingsBinary, quiet, kXlingsPinnedVersion);
         if (!xbin) return std::unexpected(ConfigError{xbin.error()});
     } else if (cfg.xlingsBinaryMode == "system") {
         auto sysPath = mcpp::platform::fs::which(

src/doctor.cppm

@@ -14,6 +14,8 @@ import mcpp.bmi_cache.maintenance;
 import mcpp.build.prepare;
 import mcpp.build.plan;
 import mcpp.config;
+import mcpp.fallback.probe_sysroot;
+import mcpp.fallback.xlings_binary;
 import mcpp.fallback.install_integrity;
 import mcpp.fetcher.progress;
 import mcpp.home;
@@ -69,6 +71,7 @@ export std::vector<std::string> parse_readelf_runpath(std::string_view dump) {
 // `mcpp self env`.
 export int env_report() {
     auto cfg = mcpp::config::load_or_init(/*quiet=*/false, mcpp::fetcher::make_bootstrap_progress_callback());
+
     if (!cfg) { mcpp::ui::error(cfg.error().message); return 4; }
 
     mcpp::config::print_env(*cfg);
@@ -98,6 +101,7 @@ export int doctor_report() {
         err(std::format("toolchain detection failed: {}", tc.error().message));
     } else {
         ok(std::format("{} at {}", tc->label(), tc->binaryPath.string()));
+
     }
 
     // Windows: report the system MSVC (msvc@system). Absence is a warning,
@@ -204,6 +208,28 @@ export int doctor_report() {
 
     mcpp::ui::status("Checking", "registry");
     auto cfg = mcpp::config::load_or_init(/*quiet=*/false, mcpp::fetcher::make_bootstrap_progress_callback());
+
+    // Whose sysroot is this? gcc bakes `--sysroot=<...>/subos/default`
+    // at build time, and that path is a string, not a reference -- it
+    // keeps naming wherever the compiler was built no matter which
+    // project it now serves. A developer machine has many directories by
+    // that name, so the baked one frequently EXISTS while belonging to an
+    // unrelated checkout, and headers then come from a tree this build
+    // never declared. Existence is not ownership.
+    if (tc && cfg) {
+        std::error_code cwdEc;
+        auto project = std::filesystem::current_path(cwdEc);
+        if (mcpp::fallback::sysroot_is_foreign(
+                tc->sysroot, (*cfg).registryDir,
+                cwdEc ? std::filesystem::path{} : project))
+            warn(std::format(
+                "sysroot {} belongs to neither this mcpp home ({}) nor "
+                "this project — headers would come from a tree nothing "
+                "here declared. mcpp remaps a baked sysroot when it can "
+                "find the equivalent under the registry; seeing it here "
+                "means it could not",
+                tc->sysroot.string(), (*cfg).registryDir.string()));
+    }
     if (!cfg) {
         err(cfg.error().message);
     } else {
@@ -366,6 +392,33 @@ export int doctor_report() {
         else if (!sawAny)
             ok("no installed toolchains to check");
 
+        // The vendored xlings, against the version this mcpp expects.
+        //
+        // Nothing else surfaces this. `mcpp self env` prints both numbers and
+        // says nothing about the gap, and a home that acquired its xlings once
+        // never revisited it -- so a machine could sit years behind while every
+        // command looked healthy. What goes missing is silent by nature:
+        // features mcpp reads FROM xlings (the subos_info block, for one)
+        // simply never appear, and the code that consumes them degrades
+        // quietly because a missing block is also a legitimate state.
+        {
+            auto have = mcpp::fallback::vendored_xlings_version((*cfg).xlingsBinary);
+            const auto want = std::string(mcpp::config::kXlingsPinnedVersion);
+            if (have.empty()) {
+                warn(std::format("cannot read the vendored xlings version at {}",
+                                 (*cfg).xlingsBinary.string()));
+            } else if (mcpp::fallback::version_is_older(have, want)) {
+                warn(std::format(
+                    "vendored xlings is {} but this mcpp expects {} — features "
+                    "mcpp reads from xlings may be silently absent (the subos "
+                    "self-description arrived in 2026.8.5.1). It is replaced "
+                    "automatically on the next `mcpp self init`",
+                    have, want));
+            } else {
+                ok(std::format("vendored xlings {} (pinned {})", have, want));
+            }
+        }
+
         // Dangling symlinks under registry/subos/default/lib — these point
         // into xim payload lib dirs; a removed package leaves them broken.
         auto subosLib = (*cfg).xlingsHome() / "subos" / "default" / "lib";

src/fallback/probe_sysroot.cppm

@@ -17,17 +17,40 @@ import mcpp.log;
 
 export namespace mcpp::fallback {
 
-// When GCC reports a sysroot ending in "subos/default" that doesn't exist
-// on the current machine (baked build-time path), remap it to the
-// equivalent sysroot relative to the compiler's own xpkgs directory.
+// When GCC reports a baked "subos/default" sysroot that does not belong to
+// THIS toolchain's home, remap it to the equivalent sysroot under the
+// compiler's own xpkgs tree.
+//
+// The predicate used to be "does not exist", which is the wrong axis. A
+// developer machine has more than one project-local `.xlings/subos/default`,
+// and gcc's baked path can name one of them: it exists, so the remap was
+// skipped and every build in an unrelated project inherited another
+// project's sysroot. Measured -- a build in mcpp resolved
+// `--sysroot=<other-repo>/.xlings/subos/default`.
+//
+// Existence says nothing about ownership. What matters is whether the path is
+// under the same registry as the compiler, and a path that is not gets
+// remapped whether or not something happens to be there.
 std::optional<std::filesystem::path>
 remap_xlings_baked_sysroot(std::string_view reportedPath,
                            const std::filesystem::path& compilerBin) {
     if (reportedPath.empty()) return std::nullopt;
     if (!reportedPath.ends_with("subos/default")) return std::nullopt;
-    if (std::filesystem::exists(std::string(reportedPath))) return std::nullopt;
 
-    if (auto xpkgs = mcpp::xlings::paths::xpkgs_from_compiler(compilerBin)) {
+    auto xpkgsOpt = mcpp::xlings::paths::xpkgs_from_compiler(compilerBin);
+    if (xpkgsOpt) {
+        // Owned by this toolchain's registry? Then it is the right answer.
+        auto registry = xpkgsOpt->parent_path().parent_path();
+        std::error_code ec;
+        auto rel = std::filesystem::path(std::string(reportedPath))
+                       .lexically_relative(registry);
+        const bool inside = !rel.empty()
+                         && rel.native().rfind("..", 0) != 0;
+        if (inside && std::filesystem::exists(std::string(reportedPath), ec))
+            return std::nullopt;
+    }
+
+    if (auto xpkgs = std::move(xpkgsOpt)) {
         // xpkgs is <registry>/data/xpkgs -> registry = xpkgs/../..
         auto registrySysroot = xpkgs->parent_path().parent_path()
                                / "subos" / "default";
@@ -37,6 +60,30 @@ remap_xlings_baked_sysroot(std::string_view reportedPath,
     return std::nullopt;
 }
 
+// Is this sysroot foreign -- neither this mcpp home's registry nor a tree
+// belonging to the project being built?
+//
+// The hazard is specific and was measured: gcc bakes `--sysroot=<...>/.xlings/
+// subos/default` as a STRING at build time, and a developer machine has many
+// directories by that name. The baked one therefore frequently EXISTS while
+// belonging to an unrelated checkout, and headers silently come from a tree
+// this build never declared. remap_xlings_baked_sysroot repairs the case it
+// can see; this predicate is what reports the case it cannot.
+//
+// Both anchors are required. Registry alone would flag every legitimate
+// project-local tree; project alone would flag every payload sysroot.
+bool sysroot_is_foreign(const std::filesystem::path& sysroot,
+                        const std::filesystem::path& registryRoot,
+                        const std::filesystem::path& projectRoot) {
+    if (sysroot.empty()) return false;
+    auto under = [&](const std::filesystem::path& anchor) {
+        if (anchor.empty()) return false;
+        auto rel = sysroot.lexically_relative(anchor);
+        return !rel.empty() && rel.native().rfind("..", 0) != 0;
+    };
+    return !under(registryRoot) && !under(projectRoot);
+}
+
 // Parse a Clang .cfg file alongside the compiler binary for --sysroot=.
 std::optional<std::filesystem::path>
 parse_clang_cfg_sysroot(const std::filesystem::path& compilerBin) {

src/fallback/xlings_binary.cppm

@@ -7,6 +7,7 @@
 
 module;
 #include <cstdlib>
+#include <cctype>
 
 export module mcpp.fallback.xlings_binary;
 
@@ -17,9 +18,70 @@ export namespace mcpp::fallback {
 
 // Try to acquire (copy) the xlings binary to destBin.
 // Returns destBin on success or an error string.
+// The version already vendored at destBin, or empty when it cannot be read.
+std::string vendored_xlings_version(const std::filesystem::path& bin);
+
+// The version the acquisition chain WOULD install, without installing it.
+// Empty when nothing is available. Replacing a vendored binary is only an
+// improvement when this is newer than what is already there.
+std::string candidate_source_version();
+
+// True when `have` is strictly older than `want`, comparing dot-separated
+// numeric components. Anything unparseable answers false -- a version this
+// code does not understand is not evidence of being behind.
+bool version_is_older(std::string_view have, std::string_view want);
+
+// Try to acquire (copy) the xlings binary to destBin.
+//
+// `pinnedVersion` is the version this mcpp expects. A vendored binary OLDER
+// than the pin is replaced; one that is newer or equal is left alone.
+//
+// This used to return early on mere existence, with no version comparison at
+// all, and nothing else ever revisited the file. A home created once kept
+// whatever xlings it first acquired forever -- measured at 2026.8.2.1 against
+// a pin of 2026.8.6.3, with `mcpp self env` printing both numbers side by side
+// and saying nothing about the gap. The cost is not cosmetic: features mcpp
+// reads from xlings simply do not appear. The subos_info block arrived in
+// 2026.8.5.1, so on that machine the graphics packages' declarations were
+// discarded by a client too old to have the API, and mcpp#352's fix could
+// never take effect.
+//
+// Strictly-older, not not-equal: a user who put a newer xlings there on
+// purpose must not be downgraded by an mcpp that happens to pin an older one.
 std::expected<std::filesystem::path, std::string>
-acquire_xlings_binary(const std::filesystem::path& destBin, bool quiet = false) {
-    if (std::filesystem::exists(destBin)) return destBin;
+acquire_xlings_binary(const std::filesystem::path& destBin, bool quiet = false,
+                      std::string_view pinnedVersion = {}) {
+    if (std::filesystem::exists(destBin)) {
+        auto have = vendored_xlings_version(destBin);
+        if (pinnedVersion.empty() || have.empty()
+            || !version_is_older(have, pinnedVersion))
+            return destBin;
+
+        // Behind the pin -- but replacing is only an improvement if what we
+        // would put there is actually newer. The acquisition chain below ends
+        // at whatever `which xlings` finds, and on a machine whose system
+        // xlings is ANCIENT that is a downgrade dressed up as an update.
+        //
+        // Learned by doing it: this code first deleted the vendored binary and
+        // re-acquired, which replaced 2026.8.2.1 with the system's 0.4.51 --
+        // older still, and equally missing the feature the check exists to
+        // restore. Look before leaping.
+        auto candidate = candidate_source_version();
+        if (candidate.empty() || !version_is_older(have, candidate)) {
+            if (!quiet)
+                std::println("{:>12} vendored xlings {} is older than the "
+                             "pinned {}, but no newer source is available "
+                             "(keeping it; run `xlings self update`)",
+                             "Note", have, pinnedVersion);
+            return destBin;
+        }
+        if (!quiet)
+            std::println("{:>12} vendored xlings {} -> {} (pinned {})",
+                         "Updating", have, candidate, pinnedVersion);
+        std::error_code rec;
+        std::filesystem::remove(destBin, rec);
+        // fall through and re-acquire
+    }
 
     std::error_code ec;
     std::filesystem::create_directories(destBin.parent_path(), ec);
@@ -82,4 +144,75 @@ acquire_xlings_binary(const std::filesystem::path& destBin, bool quiet = false)
         (destBin.parent_path().parent_path() / "config.toml").string()));
 }
 
+
+std::string vendored_xlings_version(const std::filesystem::path& bin) {
+    std::error_code ec;
+    if (!std::filesystem::exists(bin, ec)) return {};
+    auto r = mcpp::platform::process::capture(std::format(
+        "{} --version 2>/dev/null", mcpp::platform::shell::quote(bin.string())));
+    if (r.exit_code != 0) return {};
+    // Output carries ANSI colour; take the first dotted-numeric run.
+    std::string out;
+    for (std::size_t i = 0; i < r.output.size(); ++i) {
+        if (r.output[i] == '\x1b') {              // skip CSI
+            while (i < r.output.size() && r.output[i] != 'm') ++i;
+            continue;
+        }
+        out += r.output[i];
+    }
+    std::size_t i = 0;
+    while (i < out.size()) {
+        if (std::isdigit(static_cast<unsigned char>(out[i]))) {
+            auto j = i;
+            while (j < out.size()
+                   && (std::isdigit(static_cast<unsigned char>(out[j]))
+                       || out[j] == '.')) ++j;
+            auto cand = out.substr(i, j - i);
+            if (cand.find('.') != std::string::npos) return cand;
+            i = j;
+        } else ++i;
+    }
+    return {};
+}
+
+bool version_is_older(std::string_view have, std::string_view want) {
+    auto parts = [](std::string_view v) {
+        std::vector<long long> out;
+        std::size_t i = 0;
+        while (i <= v.size()) {
+            auto dot = v.find('.', i);
+            auto seg = v.substr(i, dot == std::string_view::npos
+                                       ? std::string_view::npos : dot - i);
+            long long n = 0;
+            auto [p, e] = std::from_chars(seg.data(), seg.data() + seg.size(), n);
+            if (e != std::errc{}) return std::vector<long long>{};
+            out.push_back(n);
+            if (dot == std::string_view::npos) break;
+            i = dot + 1;
+        }
+        return out;
+    };
+    auto a = parts(have), b = parts(want);
+    if (a.empty() || b.empty()) return false;   // unparseable is not "behind"
+    for (std::size_t i = 0; i < std::max(a.size(), b.size()); ++i) {
+        long long x = i < a.size() ? a[i] : 0;
+        long long y = i < b.size() ? b[i] : 0;
+        if (x != y) return x < y;
+    }
+    return false;
+}
+
+
+std::string candidate_source_version() {
+    if (const char* e = std::getenv("MCPP_VENDORED_XLINGS"); e && *e) {
+        std::error_code ec;
+        if (std::filesystem::exists(std::filesystem::path(e), ec))
+            return vendored_xlings_version(std::filesystem::path(e));
+    }
+    if (auto sys = mcpp::platform::fs::which(
+            std::string("xlings") + std::string(mcpp::platform::exe_suffix)))
+        return vendored_xlings_version(*sys);
+    return {};
+}
+
 } // namespace mcpp::fallback