sandbox xlings is vendored once and never refreshed — an in-place mcpp upgrade keeps resolving deps with the old one #289

The sandbox's xlings is copied once at self init and never revisited, so upgrading mcpp in place leaves the old one running dependency resolution. mcpp already knows which version it wants — it prints it — but never compares.

The gap, in three facts

1. mcpp knows the version it expects. src/xlings.cppm:39:

namespace pinned {
    // Keep in lock-step with the XLINGS_VERSION pins in release.yml /
    // cross-build-test.yml / ci-linux-e2e.yml (the xlings actually bundled
    // into releases). Printed by `mcpp self env`.
    inline constexpr std::string_view kXlingsVersion   = "0.4.69";
}

mcpp self env shows it:

MCPP_HOME           = /home/speak/.mcpp
xlings binary       = /home/speak/.mcpp/registry/bin/xlings
xlings pinned       = 0.4.69          <-- known

2. That constant is consumed in exactly one place — the diagnostic print. grep -rn kXlingsPinnedVersion src/ returns two hits: the definition and std::println in config.cppm:698. Nothing compares it to what is actually on disk, and doctor.cppm does not check the xlings version at all.

3. The acquisition point returns early. src/fallback/xlings_binary.cppm:22:

acquire_xlings_binary(const std::filesystem::path& destBin, bool quiet = false) {
    if (std::filesystem::exists(destBin)) return destBin;   // <-- never revisited

It has one caller (config.cppm:634). So the copy made the first time ~/.mcpp/registry was created is the copy that stays, whatever mcpp version is running on top of it.

Why it matters now

MCPP_HOME defaults to the shared user sandbox, not the install directory — a freshly installed 0.0.109 still resolves ~/.mcpp/registry/bin/xlings, i.e. whatever was there before:

$ <fresh 0.0.109 install>/bin/mcpp self env
MCPP_HOME     = /home/speak/.mcpp
xlings binary = /home/speak/.mcpp/registry/bin/xlings

mcpp-index's SPEC-001 short-name migration put two packages literally named lua in one index repo — compat:lua and mcpplibs.capi:lua, both pulled in transitively via mcpplibs.xpkg. Before xlings 0.4.69 (openxlings/xlings#381) a repo keyed its table by the bare package.name, so one of the two is unreachable — and which one depends on iteration order. In CI this showed up as Windows failing on compat:lua while Linux failed on mcpplibs.capi:lua, with no message anywhere saying the xlings doing the resolving was too old:

error: xlings install_packages failed (exit 1) for 'lua@5.4.7' ...

CI was measured at 0.4.30 in the sandbox while the system xlings had already moved on — 39 minor versions of drift, invisible.

Who is affected: only sandboxes created before 0.4.69 and then upgraded in place. Release tarballs ship their own bundled xlings (<install>/registry/bin/xlings, 0.4.69 in 0.0.109), so a clean install is fine. Verified: fresh XLINGS_HOME → xlings install mcpp@0.0.109 → bundled xlings reports 0.4.69.

Proposed direction

Every mcpp release already ships a version-bound xlings at a stable relative path:

<install>/mcpp                    wrapper
<install>/bin/mcpp                real binary
<install>/registry/bin/xlings     bundled, version-bound

So at runtime mcpp can compare the sandbox copy against kXlingsPinnedVersion and, on mismatch, refresh it from its own bundled copy. This is not mcpp guessing at the user's environment — it is mcpp restoring an invariant it already declares and already knows the correct value for.

Sequencing suggestion, so the safe half can land without waiting on the design of the second:

1. Detect + diagnose. Compare the sandbox xlings version to kXlingsPinnedVersion. On mismatch, emit an actionable error/warning naming both versions and pointing at the remedy (mcpp self init --force works today, it is just undiscoverable). Add the same check to mcpp doctor. Pure information, no writes.
2. Refresh from the bundled copy. On mismatch, copy <install>/registry/bin/xlings over the sandbox copy. Open questions worth settling deliberately rather than in passing:
   • Is the binary alone sufficient, or does a 0.4.30 → 0.4.69 jump need the sandbox's registry/ runtime data reinitialised too? A binary/runtime mismatch inside the sandbox could be worse than a stale-but-consistent one.
   • Should it be silent, announced, or gated on a flag? Overwriting something in a user's ~/.mcpp without a word is the part I would not want to get wrong by default.
   • Downgrade direction: if the sandbox has a newer xlings than the running mcpp pins, overwriting is a regression.

Adjacent, same shape

kXlingsVersion's own comment says to keep it "in lock-step with the XLINGS_VERSION pins in release.yml / cross-build-test.yml / ci-linux-e2e.yml" — by hand, enforced nowhere. That list is already incomplete: .github/actions/bootstrap-mcpp and .github/actions/setup-macos-llvm also pin an xlings version (both were still on 0.4.30 until #287 today, which is what let CI's sandbox rot). A check that the constant and the workflow pins agree would stop the next silent divergence.

Context: found while shipping 0.0.109 (#286 / #287 / #288). Recorded as F1 in .agents/docs/2026-07-26-bare-name-wire-address-implementation-plan.md, which also lists five smaller release-ops findings from the same batch.