toolchain: a stated linker reaches the link on every shape, and gcc says it cannot

`--ld-path` was appended inside the Linux clang branch, the only one that
consumes `link_toolchain_flags`. On macOS the stated linker therefore entered the
fingerprint -- touching the wrapper declined the fast path -- and took no part in
the link, with nothing said; the toolchain lab measured it on macos-15, where
build.ninja held no `--ld-path`. e2e 875 asserts that flag but skips on a host
without the llvm payload, which macOS CI is.

The flag belongs to the driver, not to a platform, so it is added once after every
shape has built its line. For a gcc toolchain the declaration is now refused where
it is read: gcc selects a linker by the name `ld` inside a `-B` directory, so a
program named anything else could not be chosen, and a silent `-B` would be the
same defect in the other direction.

Author: speak-agent

.agents/docs/2026-10-01-tool-and-toolchain-sources-design.md

@@ -150,5 +150,11 @@ action 描述的是一次还不存在的构建;一个载荷请求也无法回答
   的预算是 128 KiB,而只有 Windows 上 `capture_exec` 所经的 shell 是 8191 字节。覆盖它的是
   mcpp-plugins 的 `all-rules-compile`(导入十五个宿主模块)与两个单测——每种 tokenize 语法
   一个,因为 clang 与 GCC 把反斜杠当转义,cl 与 clang-cl 不当。
+- `tools = { ld = ... }` 只对 clang 驱动成立(`--ld-path`);gcc 按 `-B` 目录里的名字 `ld`
+  选链接器,所以一个别名程序无法那样被选中,声明处直接拒绝而不是在链接时忽略。这条起初写成了
+  Linux clang 分支里的一行,于是 macOS 的 Apple 链接形状拿不到它——被陈述的链接器进了指纹
+  (改动 wrapper 会让快速路径失效),却不参与链接,而且什么都不说。现在它在所有形状之后追加
+  一次。覆盖它的是 toolchain-lab:e2e 875 在没有装 llvm 载荷的宿主上 SKIP,而 macOS CI 正是
+  这样的宿主。
 - 工具链描述数据化(核心读描述文件、不再硬编码 `to_xim_package`)不在本次范围;
   `[toolchain] { path }` 的字段已经与那份描述同形,所以它是后续的第三种载体,而不是改写。

src/build/flags.cppm

@@ -975,14 +975,6 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         link_toolchain_flags +=
             mcpp::toolchain::ClangDriverModel::kLinkDriverFlags;
         }
-        // A LINKER STATED BY ROLE (mcpp#755, `tools = { ld = ... }`): clang's
-        // `--ld-path` names the program, after `-fuse-ld` has chosen the
-        // flavour, so the flags that follow still speak to the same linker.
-        if (auto* ld = plan.toolchain.tool_override("ld")) {
-            const auto opt = " --ld-path=" + escape_path(*ld);
-            link_toolchain_flags += opt;
-            link_toolchain_flags_c += opt;
-        }
         f.sysroot = link_toolchain_flags;
     } else if (lm.mode != mcpp::toolchain::CLibMode::None) {
         // GCC (or Clang without cfg): --sysroot from probe, or the payload
@@ -2401,6 +2393,27 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         }
     }
 
+    // A LINKER STATED BY ROLE (mcpp#755, `tools = { ld = ... }`), AFTER EVERY
+    // SHAPE HAS BUILT ITS LINE.
+    //
+    // It was appended inside the Linux clang branch, the only one that consumes
+    // `link_toolchain_flags`: on macOS the stated linker entered the fingerprint
+    // -- the fast path declined when the wrapper changed -- and took no part in
+    // the link, with nothing said (measured in the toolchain lab on macos-15,
+    // where `build.ninja` held no `--ld-path`). The flag belongs to the driver,
+    // not to a platform, so it is added once here, for every shape.
+    //
+    // Clang only: `--ld-path` is clang's. GCC chooses its linker by name inside a
+    // `-B` directory, so a program named anything else could not be selected that
+    // way, and a silent `-B` would be the same defect in the other direction. A
+    // gcc toolchain that states `ld` is refused where the declaration is read.
+    if (plan.toolchain.compiler == mcpp::toolchain::CompilerId::Clang)
+        if (auto* ld = plan.toolchain.tool_override("ld")) {
+            const auto opt = " --ld-path=" + escape_path(*ld);
+            if (f.ld.find("--ld-path=") == std::string::npos)  f.ld  += opt;
+            if (f.ldC.find("--ld-path=") == std::string::npos) f.ldC += opt;
+        }
+
     return f;
 }
 

src/build/prepare/local_toolchain.cpp

@@ -240,6 +240,20 @@ step2_use_local_toolchain(PrepareState& state, const mcpp::toolchain::ToolchainS
     for (auto const& [role, p] : lt.tools)
         if (!fs::exists(p, ec))
             return refuse(std::format("tools.{} names '{}', which does not exist", role, p));
+    // A STATED LINKER REACHES THE LINK THROUGH CLANG'S `--ld-path`, which gcc
+    // does not have: gcc selects a linker by the name `ld` inside a `-B`
+    // directory, so a program named anything else cannot be chosen that way.
+    // Refused here rather than ignored in the link: the alternative is a stated
+    // tool that enters the fingerprint and takes no part in the build, which is
+    // what this mechanism exists to prevent.
+    if (family == "gcc")
+        for (auto const& [role, p] : lt.tools)
+            if (role == "ld")
+                return refuse(std::format(
+                    "tools.ld names '{}', and this is a gcc toolchain: a linker is stated "
+                    "through clang's `--ld-path`, which gcc has no counterpart for. Either "
+                    "name an llvm toolchain, or place a program called `ld` in the tree "
+                    "gcc searches", p));
     if (!lt.sysroot.empty() && !fs::is_directory(lt.sysroot, ec))
         return refuse(std::format("sysroot '{}' is not a directory", lt.sysroot));
     state.explicit_compiler = driver;