fix: 两处按宿主分岔的缺陷,都只在 Linux 之外成立

这两条是把规则包在 macOS 与 Windows 上真正跑一遍时暴露的。两处的共同形状是:
一段代码的正确性依赖于宿主,而这个仓库的 CI 只在其中一个宿主上执行它。

## 一、构建程序的链接不带工具链自己的运行时目录(macOS)

`host_link_tokens` 有两个出口:一个把 clang 的配置逐条写出来,一个信任载荷自带的
`<driver>.cfg`。第二个提前 return,跳过了给 `Toolchain::linkRuntimeDirs` 发
`-L` 与 `-rpath` 的那一段。

信任 cfg 决定的是**链哪些运行时**,它从来没有决定**去哪里找**。macOS 上 `-lc++`
于是经 SDK 解析到系统那份,而头文件来自载荷。两者在头文件引用了系统库还没导出的
符号那一刻分道扬镳 —— macos-14 上编译一个只有 `import std` 的构建程序:

    ld64.lld: error: undefined symbol: std::__1::__is_posix_terminal(__sFILE*)
    >>> referenced by std::__1::__print::__is_terminal(__sFILE*)

`std::print` 不是 header-only 的,它的两个重载都要到 libc++ **dylib** 里取支持
符号,而那两个符号是在 macOS 14 不带的那一版里加进去的。macOS 15 有,所以这个项目
用到的每一台 macOS runner 都是绿的。

载荷自带 `lib/libc++.1.0.dylib` —— 与它自己的头文件配套的那一份 —— 而
`linkRuntimeDirs` 早就命名了那个目录。给它发 `-L` 与 `-rpath` 是 Linux 那条路
一直在做的事;macOS 上被跳过,只是因为这个分支先 return 了。

⭐ **构建程序正是绝对 rpath 该在的地方**:它从不被分发,mcpp 编译它、在这台机器上
运行它、按这套工具链的身份缓存它。同一个问题对**产物**的答案由分发契约决定,不归
这个函数回答。

判据 `HostFlags.EveryExitNamesTheToolchainRuntimeDirs`:把两个出口都测一遍。为此
`CfgBypass` 补了第三个取值 `Never` —— 缺陷所在的那个分支在 Linux 上不可达
(`LinuxOnly` 在那里折叠成 `Always`),而一条只能在它写给的两个宿主上跑的判据,会
继承同一个盲点。实测:把修复拿掉,这条当场变红。

## 二、版本约束里的 `>` 被 cmd.exe 读成重定向(Windows)

mcpp 把供给请求作为 JSON 参数放在 shell 命令行上交给 xlings。`shell::quote` 回答
的是**子进程**那一层的解析 —— MSVCRT,它给内嵌引号的转义是 `\"` —— 而 cmd.exe
不认这个转义:对它来说每个 `"` 只是在切换引用状态。于是一段 JSON 走到 `>` 的时候,
它背后的引号数是**偶数**,`>` 成了重定向,重定向目标是 JSON 的其余部分:

    Provisioning [xlings.workspace] entries declared by dependencies (xim:shaderc@>=2026.3)
    The filename, directory name, or volume label syntax is incorrect.
    error: provisioning ... failed: xlings exited 1

windows-2022 实测。`>=` 正是每个规则包声明下界用的形态,而**在此之前没有任何一条能
在 Windows 上生效的声明带过 `>`**,所以整个形态在那个宿主上从没被走到过。

修法是标准的双重转义:先按子进程的规则引用,再给每个 cmd 元字符(包括引号本身)前
缀 `^`。没有任何 `"` 是裸的,cmd 就从不进入引用状态,于是每个元字符都是被转义而不是
被引用的 —— 这是两套规则同时成立的唯一状态。cmd 去掉那些 `^`,子进程看到的正是
`quote_windows` 的输出。

⚠️ `%` 不转义也无法转义:变量展开发生在 `^` 处理之前,而 `%%` 只在批处理文件里可用。
这一点写在函数注释里;这里的 JSON 参数不含 `%`。

判据是两个模拟器 —— 一个复现 cmd 的解析,一个复现 MSVCRT 的 argv 解析 —— 断言的是
**子进程收到的参数等于本来要传的那个 JSON**,而不是转义的拼写。另有一条反向判据
断言旧的引用方式确实让 cmd 看见了一个活的元字符,否则正向那条什么都不证明。

端到端的判据在 mcpp-plugins:它的 Windows job 目前用精确版本绕开这条缺陷,等这个
修复发布后把声明改回 `>=2026.3`,那条 job 就是这个修复的端到端判据。

Author: speak-agent

modules/platform/src/shell.cppm

@@ -27,6 +27,37 @@ std::string quote(std::string_view s);
 std::string quote_windows(std::string_view s);
 std::string quote_posix(std::string_view s);
 
+// An argument that must survive TWO parsers: cmd.exe's, and then the child
+// program's own argv parsing.
+//
+// `quote_windows` answers only the second. Its `\"` escape belongs to the
+// MSVCRT argv rules, and cmd.exe does not know it: to cmd every `"` simply
+// toggles a quote state, so a payload carrying an EVEN number of them before a
+// metacharacter leaves that character unquoted. Measured on windows-2022 with
+// a JSON argument -- `{"targets":["xim:shaderc@>=2026.3"],"yes":true}` puts
+// four quotes before the `>`, and cmd read it as a REDIRECTION, answering
+//
+//   The filename, directory name, or volume label syntax is incorrect.
+//
+// which arrived as a package-provisioning failure naming a package.
+//
+// The answer is the standard double escape: quote for the child, then prefix
+// every cmd metacharacter -- the quotes included -- with `^`. With no `"` left
+// unescaped cmd never enters a quoted region, so every metacharacter is
+// escaped rather than quoted, which is the only state in which both rules
+// hold. cmd removes the carets and the child sees exactly `quote_windows`.
+//
+// `%` IS NOT ESCAPED AND CANNOT BE. Variable expansion happens before caret
+// processing, and the batch-file escape (`%%`) is not available on a command
+// line. Callers passing text that may contain `%` need a different mechanism;
+// the JSON arguments this exists for do not.
+std::string quote_windows_through_cmd(std::string_view s);
+
+// Host-selecting: `quote_windows_through_cmd` on Windows, `quote_posix`
+// elsewhere. Use this wherever an argument reaches a shell and may contain
+// metacharacters -- notably JSON, and any version constraint spelled `>=`.
+std::string quote_through_shell(std::string_view s);
+
 // Silent redirect — stdout + stderr → /dev/null (or NUL on Windows).
 // stdin is NOT touched here; that's the responsibility of
 // mcpp::platform::process::seal_stdin, which is auto-applied by capture /
@@ -67,6 +98,24 @@ std::string quote_posix(std::string_view s) {
     return out;
 }
 
+std::string quote_windows_through_cmd(std::string_view s) {
+    const std::string inner = quote_windows(s);
+    std::string out;
+    out.reserve(inner.size() * 2);
+    for (char c : inner) {
+        switch (c) {
+            case '"': case '<': case '>': case '&': case '|':
+            case '^': case '(': case ')':
+                out.push_back('^');
+                break;
+            default:
+                break;
+        }
+        out.push_back(c);
+    }
+    return out;
+}
+
 std::string quote(std::string_view s) {
 #if defined(_WIN32)
     return quote_windows(s);
@@ -75,4 +124,12 @@ std::string quote(std::string_view s) {
 #endif
 }
 
+std::string quote_through_shell(std::string_view s) {
+#if defined(_WIN32)
+    return quote_windows_through_cmd(s);
+#else
+    return quote_posix(s);
+#endif
+}
+
 } // namespace mcpp::platform::shell

src/build/build_program.cppm

@@ -775,7 +775,11 @@ std::expected<void, std::string> run_build_program(
     compilerIdentity += "\nbuild-program-link=";
     compilerIdentity += muslStaticHelper  ? "musl-static-v1"
                       : mingwStaticHelper ? "mingw-static-v1"
-                                          : "default-v2";   // v2: DT_RPATH on Linux
+                                          : "default-v3";   // v2: DT_RPATH on Linux
+                                                            // v3: + the same on
+                                                            //     macOS/Windows,
+                                                            //     where the cfg
+                                                            //     path skipped it
     std::string programHash  = mcpp::toolchain::hash_file(src);
     std::string compilerHash = mcpp::toolchain::hash_string(compilerIdentity);
 

src/toolchain/hostflags.cppm

@@ -49,7 +49,14 @@ struct HostFlagOptions {
     //               needs_explicit_libcxx path owns; duplicating that for a
     //               host compile produced undefined __cxa_* /
     //               __gxx_personality_v0 (build_program.cppm, pre-existing).
-    enum class CfgBypass { Always, LinuxOnly };
+    //   Never     — always trust the cfg. No caller selects it; it completes
+    //               the enum, and it is what makes the cfg-trusting branch of
+    //               `host_link_tokens` reachable from a test on a Linux
+    //               runner. `LinuxOnly` folds into `Always` there, so without
+    //               this value that branch could only be exercised on the two
+    //               hosts it was written for -- which is how it came to be
+    //               missing the runtime-directory tokens in the first place.
+    enum class CfgBypass { Always, LinuxOnly, Never };
     CfgBypass cfgBypass = CfgBypass::Always;
 
     // binutils `-B` so the driver finds as/ld. A GCC/libstdc++ payload
@@ -206,7 +213,8 @@ std::vector<std::string> host_compile_tokens(const Toolchain& tc,
 
     const bool bypassCfg =
         dm.hasCfg && (opt.cfgBypass == HostFlagOptions::CfgBypass::Always
-                      || mcpp::platform::is_linux);
+                      || (opt.cfgBypass == HostFlagOptions::CfgBypass::LinuxOnly
+                          && mcpp::platform::is_linux));
 
     // Trusting the cfg means contributing no include paths, stdlib selection
     // or runtime choices — it already carries them. It does NOT mean
@@ -297,6 +305,20 @@ std::vector<std::string> bmi_reference_tokens(std::string_view usePrefix,
              std::string(p.substr(sp + 1)) + bmi.string() };
 }
 
+// The toolchain's own runtime directories, on both exits of the function
+// below. `-L` is link-time and wanted everywhere; rpath is an ELF and Mach-O
+// concept. A PE target reaches here too, where the rpath flag is inert and
+// self-containment comes from the static link instead (#299).
+void append_runtime_lib_dirs(const Toolchain& tc, const HostFlagOptions& opt,
+                             const PathEscape& esc, std::vector<std::string>& out) {
+    if (!opt.runtimeLibDirs) return;
+    for (auto& d : tc.linkRuntimeDirs) {
+        out.push_back("-L" + esc(d));
+        if constexpr (mcpp::platform::supports_rpath)
+            out.push_back("-Wl,-rpath," + esc(d));
+    }
+}
+
 std::vector<std::string> host_link_tokens(const Toolchain& tc,
                                           const HostFlagOptions& opt,
                                           const PathEscape& esc) {
@@ -308,7 +330,8 @@ std::vector<std::string> host_link_tokens(const Toolchain& tc,
 
     const bool bypassCfg =
         dm.hasCfg && (opt.cfgBypass == HostFlagOptions::CfgBypass::Always
-                      || mcpp::platform::is_linux);
+                      || (opt.cfgBypass == HostFlagOptions::CfgBypass::LinuxOnly
+                          && mcpp::platform::is_linux));
 
     if (bypassCfg) {
         for (auto& t : dm.link_tokens(esc)) out.push_back(t);
@@ -336,6 +359,37 @@ std::vector<std::string> host_link_tokens(const Toolchain& tc,
         // lld ships with the very toolchain doing the compile, so it cannot
         // be diverted to a libc++ it was not built against.
         if constexpr (mcpp::platform::is_macos) out.push_back("-fuse-ld=lld");
+        // AND THE RUNTIME DIRECTORIES, WHICH THIS PATH USED TO SKIP.
+        //
+        // Trusting clang's cfg decides WHICH runtimes are linked. It does not
+        // decide WHERE they are found, and on macOS `-lc++` resolves through
+        // the SDK to /usr/lib/libc++.tbd -- the system copy, whose version
+        // floats with the host OS -- while the headers come from the payload.
+        // The two disagree the moment the headers reference a symbol the
+        // system library does not export yet:
+        //
+        //   ld64.lld: error: undefined symbol:
+        //       std::__1::__is_posix_terminal(__sFILE*)
+        //   >>> referenced by std::__1::__print::__is_terminal(__sFILE*)
+        //
+        // measured on macos-14 compiling a build program that does nothing but
+        // `import std`. `std::print` is not header-only: its FILE* and ostream
+        // overloads call into the libc++ dylib, and those two support symbols
+        // arrived in a version macOS 14 does not ship. macOS 15's copy has
+        // them, which is why every macOS runner this project uses was green.
+        //
+        // The payload ships its own `lib/libc++.1.0.dylib` -- the toolchain's
+        // own copy, matching its own headers -- and `linkRuntimeDirs` already
+        // names that directory. Emitting `-L` and `-rpath` for it is what the
+        // Linux path has always done here; it was skipped on macOS only
+        // because this branch returned first.
+        //
+        // A BUILD PROGRAM IS THE RIGHT PLACE FOR AN ABSOLUTE RPATH. It is
+        // never distributed: mcpp compiles it, runs it on this machine, and
+        // caches it against this toolchain's identity. The equivalent question
+        // for an ARTIFACT is decided by the distribution contract, and is not
+        // this function's to answer.
+        append_runtime_lib_dirs(tc, opt, esc, out);
         return out;
     }
 
@@ -346,16 +400,7 @@ std::vector<std::string> host_link_tokens(const Toolchain& tc,
             out.push_back("-B" + esc(ar.parent_path()));
     }
 
-    if (opt.runtimeLibDirs) {
-        // -L is link-time and wanted everywhere; rpath is an ELF-only concept.
-        // A PE target reaches here too, where the flag is inert and
-        // self-containment comes from the static link instead (#299).
-        for (auto& d : tc.linkRuntimeDirs) {
-            out.push_back("-L" + esc(d));
-            if constexpr (mcpp::platform::supports_rpath)
-                out.push_back("-Wl,-rpath," + esc(d));
-        }
-    }
+    append_runtime_lib_dirs(tc, opt, esc, out);
 
     return out;
 }

src/xlings/xlings.cppm

@@ -259,6 +259,10 @@ namespace paths {
 // Shell-escape (single-quote) a string for the command line.
 std::string shq(std::string_view s);
 
+// `shq` for an argument that may carry a shell metacharacter (JSON, `>=`).
+// See `shell::quote_windows_through_cmd`.
+std::string shq_meta(std::string_view s);
+
 // ─── Shell command builders ─────────────────────────────────────────
 
 // Build the standard xlings command prefix with proper env vars.
@@ -772,6 +776,13 @@ std::string shq(std::string_view s) {
     return mcpp::platform::shell::quote(s);
 }
 
+// The same, for an argument that may carry a shell metacharacter -- which the
+// JSON payloads below do, and which a version constraint spelled `>=` does.
+// See `quote_windows_through_cmd` for what `shq` alone leaves unprotected.
+std::string shq_meta(std::string_view s) {
+    return mcpp::platform::shell::quote_through_shell(s);
+}
+
 // ─── Path helpers ───────────────────────────────────────────────────
 
 namespace paths {
@@ -1157,7 +1168,7 @@ std::string build_interface_command(const Env& env,
                                     std::string_view capability,
                                     std::string_view argsJson) {
     return std::format("{} interface {} --args {} {}",
-        build_command_prefix(env), capability, shq(argsJson),
+        build_command_prefix(env), capability, shq_meta(argsJson),
         mcpp::platform::null_redirect);
 }
 
@@ -1417,15 +1428,15 @@ int install_with_progress(const Env& env, std::string_view target,
         if constexpr (mcpp::platform::is_windows) {
             return std::format("{} interface install_packages --args {} {} <NUL",
                 build_command_prefix(env),
-                shq(argsJson),
+                shq_meta(argsJson),
                 mcpp::platform::null_redirect);
         } else {
             return std::format(
                 "cd {} && env -u XLINGS_PROJECT_DIR XLINGS_HOME={} {} interface install_packages --args {} {} </dev/null",
                 shq(env.home.string()),
                 shq(env.home.string()),
                 shq(env.binary.string()),
-                shq(argsJson),
+                shq_meta(argsJson),
                 mcpp::platform::null_redirect);
         }
     }();

tests/unit/test_hostflags.cpp

@@ -206,6 +206,83 @@ TEST(HostFlags, CfgBypassLinuxOnlyDiffersFromAlwaysOffLinux) {
     }
 }
 
+// ── Every exit of host_link_tokens names the toolchain's runtime dirs ───────
+//
+// THE DEFECT THIS STATES. `host_link_tokens` has two exits: one that spells
+// clang's configuration out and one that trusts the bundled `<driver>.cfg`.
+// The second returned early, before the block that emits `-L` and `-rpath`
+// for `Toolchain::linkRuntimeDirs`. Trusting the cfg decides WHICH runtimes
+// are linked; it never decided WHERE they are found, and on macOS `-lc++`
+// then resolved through the SDK to the system library while the headers came
+// from the payload. Measured on macos-14, compiling a build program that does
+// nothing but `import std`:
+//
+//   ld64.lld: error: undefined symbol: std::__1::__is_posix_terminal(__sFILE*)
+//
+// -- a symbol `std::print`'s inline machinery references and that release's
+// libc++ does not export. The payload ships its own copy, one directory the
+// early return had dropped.
+//
+// AND WHY THIS TEST CAN RUN ON LINUX. The branch is chosen by the host: with
+// `LinuxOnly`, a Linux build always takes the spelled-out exit, so the exit
+// that had the defect is unreachable from a Linux runner. `CfgBypass::Never`
+// exists to make it reachable -- the defect lived in a branch that only two
+// of the three CI hosts could execute, and a test that could only run there
+// would inherit the same blind spot.
+namespace {
+
+// A directory that looks enough like a clang payload for `resolve_clang_driver`
+// to report `hasCfg`: a driver file and a sibling `<driver>.cfg`.
+struct FakeClangPayload {
+    std::filesystem::path root;
+    explicit FakeClangPayload(std::string_view name) {
+        root = std::filesystem::temp_directory_path()
+             / ("mcpp-hostflags-" + std::string(name));
+        std::filesystem::remove_all(root);
+        std::filesystem::create_directories(root / "bin");
+        std::filesystem::create_directories(root / "lib");
+        std::ofstream{root / "bin" / "clang++"} << "";
+        std::ofstream{root / "bin" / "clang++.cfg"} << "";
+    }
+    ~FakeClangPayload() { std::error_code ec; std::filesystem::remove_all(root, ec); }
+};
+
+bool names_dir(const std::vector<std::string>& tokens, std::string_view dir) {
+    return std::ranges::any_of(tokens, [&](auto const& t) {
+        return t == std::string("-L") + std::string(dir);
+    });
+}
+
+} // namespace
+
+TEST(HostFlags, EveryExitNamesTheToolchainRuntimeDirs) {
+    FakeClangPayload payload{"runtime-dirs"};
+    auto tc = tc_for(CompilerId::Clang);
+    tc.binaryPath = payload.root / "bin" / "clang++";
+    tc.linkRuntimeDirs = { payload.root / "lib" };
+
+    HostFlagOptions opt;
+    opt.runtimeLibDirs = true;
+
+    // The cfg-trusting exit -- the one that returned early.
+    opt.cfgBypass = HostFlagOptions::CfgBypass::Never;
+    auto trusting = mcpp::toolchain::host_link_tokens(tc, opt, mcpp::toolchain::no_escape);
+    EXPECT_TRUE(names_dir(trusting, (payload.root / "lib").string()))
+        << "the cfg-trusting exit dropped the toolchain's own runtime directory, "
+           "so `-lc++` resolves to whatever the system has";
+
+    // The spelled-out exit, which always did.
+    opt.cfgBypass = HostFlagOptions::CfgBypass::Always;
+    auto spelled = mcpp::toolchain::host_link_tokens(tc, opt, mcpp::toolchain::no_escape);
+    EXPECT_TRUE(names_dir(spelled, (payload.root / "lib").string()));
+
+    // And the option is still an option: nothing is emitted when it is off.
+    opt.runtimeLibDirs = false;
+    opt.cfgBypass = HostFlagOptions::CfgBypass::Never;
+    auto off = mcpp::toolchain::host_link_tokens(tc, opt, mcpp::toolchain::no_escape);
+    EXPECT_FALSE(names_dir(off, (payload.root / "lib").string()));
+}
+
 TEST(HostFlags, DeploymentTargetOnlyOnMacos) {
     auto tc = tc_for(CompilerId::GCC);
     HostFlagOptions opt;