feat(0.4.48): owner-anchored shim dispatch (owner -> env -> default)#316
Merged
Conversation
A shim is an artifact of exactly one home: dispatch now resolves against the home that owns the shim file first, instead of trusting ambient XLINGS_HOME. env XLINGS_HOME stays as a deprecated lower-priority fallback (borrowing) for one transition window, with a visible warning; ~/.xlings covers orphan shims. XLINGS_SHIM_ANCHOR=legacy restores the pre-0.4.48 env-first behavior as release insurance. Fixes the embedder-redirect failure class: a process tree that redirects XLINGS_HOME (e.g. mcpp's vendored registry) broke every shim-resolved tool on PATH (git, python, ...) -> package-index sync deadlocked -> 'no package index'. Reproduced end-to-end in mcpp-community/mcpp PR #114. - src/core/xvm/shim.cppm: is_home_root (structural signature), resolve_owner_home (innermost-home walk), home_knows_program (lightweight DB probe), resolve_dispatch_home (the chain + warnings) - src/core/config.cppm: Config::override_home pre-init hook; bump 0.4.48 - src/main.cpp: run the chain for shim invocations before first Config use - src/core/xself/doctor.cppm: check 2.6 'shim anchor' (warning-only, scoped to binDirs inside the home) - tests: unit suite (14 tests) + e2e scenario test, registered in linux/macos CI - design doc: .agents/docs/2026-06-04-shim-owner-anchoring-design.md updated to as-landed state
This was referenced Jun 4, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A shim is an artifact of exactly one home. Dispatch now resolves against the home that owns the shim file first, instead of trusting ambient
XLINGS_HOME:XLINGS_HOMEkeeps exactly one meaning: the management target of the xlings CLI (install/update). CLI home resolution is untouched.XLINGS_SHIM_ANCHOR=legacyrestores pre-0.4.48 env-first dispatch (release insurance, one soak cycle)..agents/docs/2026-06-04-shim-owner-anchoring-design.md(updated to as-landed state in this PR).Why
Any process tree that redirects
XLINGS_HOME(e.g. mcpp's vendored registry sandbox) silently broke every shim-resolved tool on PATH — git, python, node… The git shim failing inside mcpp's environment deadlocked package-index sync (index needs git, git bootstrap needs index) and left Windows users withmcpp build/mcpp self init --forcepermanently failing while their terminalgit --versionworked fine. Reproduced end-to-end in mcpp-community/mcpp#114; probe:Changes
src/core/xvm/shim.cppm—is_home_root(structural signature:.xlings.json+bin/xlings+subos/),resolve_owner_home(innermost-home upward walk),home_knows_program(lightweight versions-DB probe, no Config involvement),resolve_dispatch_home(the chain, legacy mode, deprecation/ambiguity warnings)src/core/config.cppm—Config::override_home()pre-init hook; ctor honors it ahead of env/self-contained; version 0.4.48src/main.cpp— run the chain for shim invocations before first Config usesrc/core/xself/doctor.cppm— check 2.6shim anchor(warning-only; scoped to binDirs physically inside the home so project-subos binDirs don't false-positive)tests/unit/test_shim_anchor.cpp— 14 tests: home-root signature, owner walk (incl. nested innermost + orphan), DB probe, chain orderingtests/e2e/shim_owner_anchoring_test.sh— owner-wins + warning / deprecated borrowing + warning / legacy mode / redirected-env (mcpp) regression; registered in linux + macos CIBehavior changes
Only one: when both the owner home and the env home have the tool, the owner now wins (previously env won) — with a visible ambiguity warning. Borrowing (tool only in env home) still works, with a deprecation warning. Everything else is unchanged or was previously a hard error.
Verification
mcpp buildclean;tests/unitpass (pre-existing local-envExtract.*failures reproduce identically on clean main, unrelated)