@@ -77,6 +77,45 @@
   ⚠️ **没有任何生产路径会带着全 `None` 的 `TargetSide` 走到 flags**:`resolve`
   给普通本机构建的是 `cAbi = { Payload, … }`。夹具现在照实写。
 
+- **⭐ 载荷的 C++ 运行时,服务的是载荷的 C 库。**
+
+  ```
+  undefined reference to `__cxa_allocate_exception'
+  undefined reference to `std::runtime_error::runtime_error(char const*)'
+  ```
+
+  契约表用 `system_from_graph()` 决定要不要取载荷的 C++ 归档 —— 又是那个跨两层的
+  OR。一个「内核接口来自包、而 C 库与 C++ 运行时都来自载荷」的程序本该由那些归档
+  服务,OR 却说不是,`-nostdlib++` 于是砍掉了它要用的那一份。
+
+  ⚠️ **这一处在两个方向上都错过。** 最初是 `targetCxxRuntime`,对 C 程序失败
+  (它没有 C++ 运行时,答「否」被读成「载荷的是对的」);#486 换成 OR,又矫枉过正。
+  **C 库才是决定它的那一层** —— 理由 `check_layering` 早已反向陈述:载荷的 C++
+  运行时是对着载荷的 C 库配置的,所以当且仅当那份 C 库在用时它才可用。
+
+- **⭐ `build.mcpp` 的 `PATH` 前置 mcpp 自己的工具目录。**
+
+  ```
+  PATH=<mcpp 自己的工具目录>:<mcpp 启动时的 PATH>
+  ```
+
+  mcpp 把工具装进自己的 sub-OS(写下这条时那台机器上有 221 个),而此前
+  build.mcpp 继承的 PATH 里**一个都没有**。它想用某个工具,只能像 shell 脚本
+  一样去问 PATH —— 而 `command -v` 回答的是「这台机器有什么」,不是「这次构建
+  用什么」。
+
+  实测代价:`command -v qemu-system-riscv64` 命中一个 shim,执行时答
+  `[error] qemu-system-riscv64 is not installed in this subos` —— 找到了、
+  报告为存在、却跑不了,而真正的那份就在 mcpp 自己的目录里,不在 PATH 上。
+
+  ⚠️ **前置而非替换。** build.mcpp 合理地会调 `git`、`python3`、shell,这些
+  mcpp 都不提供;只有 mcpp 的目录的 PATH 会把它们全部弄坏。前置让隔离的那份
+  成为默认答案,宿主留在后面仍可达。
+
+  ⭐ 解析**只发生一次**:`toolsBinDir` 在 `get_cfg` 之后算好,交给
+  `fill_target_build_env` —— 而不是在它的两个调用点各算一遍。本次发布修的三条
+  缺陷全部来自「一个事实在多处各自推导」,这个字段不再添一处。
+
 ### 测试
 
 - 五条单元测试,**按 `Origin` 的四个值各一条**,外加一条把缺陷本身写成断言
 
@@ -482,6 +482,30 @@ These values are folded into the re-run key **unconditionally** — changing the
 target, profile, or feature set re-runs the program without any
 `rerun-if-env-changed` declaration.
 
+### `PATH` — this build system's tools first (mcpp 2026.8.25.1+)
+
+The child's `PATH` is the one mcpp was started with, **prefixed** with the
+directory mcpp installs its own tools into. A build program that looks up a
+tool therefore finds the copy this build system placed there, and still reaches
+anything else the machine has.
+
+```
+PATH=<mcpp's own tool directory>:<the PATH mcpp itself was started with>
+```
+
+Why it is a prefix and not a replacement: a build program legitimately calls
+`git`, `python3` or a shell, none of which mcpp ships. Front position makes the
+isolated copy the default answer; the host stays reachable behind it.
+
+⚠️ **`command -v` answers about the machine, not about this build.** Before
+this, a program asking `PATH` for a tool mcpp had installed could get an
+unrelated one — measured on `qemu-system-riscv64`, where the answer was a shim
+that reports "is not installed in this subos" when executed, while the working
+copy sat in mcpp's own directory and was not on `PATH` at all.
+
+The directory is empty on an installation that has no sub-OS yet, and `PATH` is
+then left exactly as inherited.
+
 ## Dependencies' build.mcpp (mcpp 0.0.95+)
 
 A dependency that ships a `build.mcpp` gets it compiled and run too (the
 
@@ -105,6 +105,30 @@ struct BuildProgramEnv {
     // the same re-run key: a rebuilt tool re-runs the program that uses it,
     // with no `rerun-if-changed` needed from the author.
     std::vector<std::pair<std::string, std::string>> toolPaths;
+    // ⭐⭐ THE DIRECTORY THIS BUILD SYSTEM'S OWN TOOLS ARE IN, PUT AT THE FRONT
+    // OF THE CHILD'S `PATH`.
+    //
+    // A build program that wants a tool has, until this field, had to find it
+    // the way any shell script would — and `command -v` answers about the
+    // machine, not about this build. Measured 2026-08-25: mcpp installs
+    // `qemu-system-riscv64` into its own subos, and a probe that asked PATH
+    // got an xlings shim that answers, when run,
+    //
+    //     [error] qemu-system-riscv64 is not installed in this subos (_)
+    //
+    // — found, reported as present, and unable to execute. The 221 programs
+    // mcpp had installed on purpose were not on that PATH at all.
+    //
+    // ⚠️ PREPENDED, NOT SUBSTITUTED. A build program legitimately reaches for
+    // things this build system does not ship — `git`, `python3`, a shell — and
+    // a PATH containing only mcpp's directory would break every one of them for
+    // the sake of a guarantee nobody asked for. Front position is what makes
+    // the isolated copy the default answer; the host stays reachable behind it.
+    //
+    // This is the same division of labour as `toolchainDir` and `compilerId`
+    // above: a package should be able to ASK rather than guess, and the thing
+    // that knows the answer is the one that installed the tools.
+    std::string toolsBin;
     // #355 step 5: dependency-provided modules to compile FOR THE HOST and make
     // importable from this build.mcpp — reusable build rules distributed as
     // ordinary mcpp packages (`import mcpp.rules.protobuf;`) instead of a
@@ -412,6 +436,24 @@ contract_env(const fs::path& root, const fs::path& outDir, const BuildProgramEnv
     // append the platform's exe suffix itself, and a tool's adjacent DATA
     // (protoc's well-known .proto files, say) lives in the package tree, which
     // dep_dir() already exposes.
+    // ── The child's PATH, with this build system's own tools in front ───────
+    //
+    // See `BuildProgramEnv::toolsBin` for why this exists and why it is a
+    // prefix rather than a replacement.
+    //
+    // ⚠️ THE INHERITED VALUE IS READ HERE AND NOT ASSUMED. `extraEnv` replaces
+    // a variable outright in the child, so writing only mcpp's directory would
+    // silently be the substitution this deliberately is not.
+    if (!env.toolsBin.empty()) {
+        const char* inherited = std::getenv("PATH");
+        std::string path = env.toolsBin;
+        if (inherited && *inherited) {
+            path += mcpp::platform::env::path_list_separator();
+            path += inherited;
+        }
+        e.emplace_back("PATH", path);
+    }
+
     for (auto const& [var, path] : env.toolPaths) {
         auto [it, inserted] = depVarValue.try_emplace(var, path);
         if (inserted) {
 
@@ -854,8 +854,19 @@ mcpp::platform::process::RunResult run_with_network_retry(
 }
 
 void fill_target_build_env(mcpp::build::BuildProgramEnv& e,
-                           const mcpp::toolchain::Toolchain* tc)
+                           const mcpp::toolchain::Toolchain* tc,
+                           const std::string& toolsBin)
 {
+    // ⭐ ONE CALL, AND THAT IS THE POINT OF THIS FUNCTION.
+    //
+    // Every answer a build program would otherwise hardcode is filled here, so
+    // that the two call sites below cannot drift apart. `toolsBin` arrives as
+    // an argument rather than being resolved here because this is a free
+    // function with no configuration in scope — and resolving it twice at the
+    // call sites is exactly the shape that produced three regressions in
+    // #486: one fact, derived in more than one place, agreeing until it did
+    // not.
+    e.toolsBin = toolsBin;
     e.toolchainDir  = (tc && !tc->binaryPath.empty())
         ? tc->binaryPath.parent_path().parent_path().string() : std::string{};
     e.targetSysroot = tc ? tc->targetSysrootRoot.string() : std::string{};
@@ -1280,6 +1291,28 @@ prepare_build(bool print_fingerprint,
         return &*cfg_opt;
     };
 
+    // ⭐ WHERE THIS BUILD SYSTEM'S OWN TOOLS ARE, RESOLVED ONCE.
+    //
+    // Read once here rather than at each `fill_target_build_env` call, because
+    // there are two of them (root package and dependency) and a value derived
+    // separately at each is a value that can disagree. That is not a
+    // hypothetical shape in this file: three defects fixed in this release
+    // came from one fact being computed in more than one place — see
+    // `TargetSide::c_library_is_the_payloads` and the note in
+    // `cache_key.cppm`.
+    //
+    // Through the config resolver, not `~/.mcpp`: `MCPP_HOME` moves this
+    // directory, and every other consumer of it (doctor, resources) reads it
+    // the same way. Empty when the directory does not exist — a fresh
+    // installation has no sub-OS yet, and `contract_env` then leaves `PATH`
+    // untouched rather than prefixing a path to nothing.
+    std::string toolsBinDir;
+    if (auto c = get_cfg(/*requireBootstrap=*/false)) {
+        auto bin = (*c)->xlingsHome() / "subos" / "default" / "bin";
+        std::error_code tec;
+        if (std::filesystem::is_directory(bin, tec)) toolsBinDir = bin.string();
+    }
+
     // Resolve one exact runtime contract before resolving/fixing a toolchain.
     // The fixup is itself a consumer of RuntimeBinding: doing it first would
     // recreate #392 by letting directory order choose a libc and only later
@@ -5541,7 +5574,7 @@ prepare_build(bool print_fingerprint,
         // The payload ROOT (not the driver), the target's C library, and the
         // three answers that keep a board package from hardcoding a toolchain
         // or a libc. All four in one call — see fill_target_build_env.
-        fill_target_build_env(bpEnv, tc ? &*tc : nullptr);
+        fill_target_build_env(bpEnv, tc ? &*tc : nullptr, toolsBinDir);
             bpEnv.profile      = effectiveProfile;
             bpEnv.features     = feature_closure(pkg.manifest, req, depDefaultFeatures);
             bpEnv.artifactsDir = workRoot / "target" / ".build-mcpp" / "deps"
@@ -6018,7 +6051,7 @@ prepare_build(bool print_fingerprint,
         // The payload ROOT (not the driver), the target's C library, and the
         // three answers that keep a board package from hardcoding a toolchain
         // or a libc. All four in one call — see fill_target_build_env.
-        fill_target_build_env(bpEnv, tc ? &*tc : nullptr);
+        fill_target_build_env(bpEnv, tc ? &*tc : nullptr, toolsBinDir);
         bpEnv.profile      = effectiveProfile;
         // Set explicitly rather than relying on build_dir()'s root-relative
         // default: under BuildOverrides::work_dir the package root is shared
 
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# requires: gcc unix-shell
+# A build program looks up a tool and finds the one mcpp installed.
+#
+# ⚠️ IT USED TO FIND WHATEVER THE MACHINE HAD, AND `command -v` CANNOT TELL THE
+# DIFFERENCE.
+#
+# mcpp installs its tools into its own sub-OS — 221 programs on the machine
+# this was written on, cross-compilers and emulators among them — and until
+# 2026.8.25.1 none of them were on the PATH a build program inherited.
+# Measured with a build program that printed its own PATH:
+#
+#     /home/…/.xlings/data/xpkgs/xim-x-claude/2.1.222
+#     /home/…/mcpp/.xlings/subos/_/bin
+#     /home/…/.xlings/subos/current/bin
+#     subos/bin in PATH: NO
+#
+# The concrete cost, from the same day: `command -v qemu-system-riscv64`
+# returned an xlings shim that answers, when run,
+#
+#     [error] qemu-system-riscv64 is not installed in this subos (_)
+#
+# — found, reported present, unable to execute, while the real one sat in
+# mcpp's own directory unreachable.
+#
+# ⭐ PREPENDED, NOT SUBSTITUTED, AND THIS FILE ASSERTS BOTH HALVES. A build
+# program legitimately reaches for things mcpp does not ship, so the host's
+# entries must survive behind mcpp's. A test that only checked the first entry
+# would pass on a PATH that had thrown the rest away.
+set -e
+
+MCPP="${MCPP:-mcpp}"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+mkdir -p "$work/app/src"
+cd "$work/app"
+
+cat > mcpp.toml <<'TOML'
+[package]
+name    = "pathprobe"
+version = "0.1.0"
+TOML
+printf 'int main() { return 0; }\n' > src/main.cpp
+
+# ⚠️ A NON-ZERO EXIT, BECAUSE THAT IS WHAT MAKES THE OUTPUT VISIBLE. mcpp
+# prints a build program's stdout only when it fails — a probe that succeeds
+# says nothing, which is a property of the protocol and not of this test.
+cat > build.mcpp <<'CPP'
+import std;
+
+int main() {
+    const char* p = std::getenv("PATH");
+    std::string_view path(p ? p : "");
+    std::string_view first;
+    for (auto part : std::views::split(path, ':')) {
+        first = std::string_view(part);
+        break;
+    }
+    std::println("PROBE_FIRST={}", first);
+    std::println("PROBE_ENTRIES={}", std::ranges::count(path, ':') + 1);
+    return 1;
+}
+CPP
+
+out="$("$MCPP" build 2>&1 || true)"
+
+first="$(printf '%s\n' "$out" | grep -oP 'PROBE_FIRST=\K.*' | head -1)"
+entries="$(printf '%s\n' "$out" | grep -oP 'PROBE_ENTRIES=\K[0-9]+' | head -1)"
+
+if [ -z "$first" ]; then
+    echo "SKIP: the build program did not report — it may not have run here"
+    printf '%s\n' "$out" | grep -iE 'error' | head -3
+    exit 0
+fi
+
+case "$first" in
+  */subos/default/bin)
+    echo "  ok  the first PATH entry is this build system's own tools: $first" ;;
+  *)
+    echo "FAIL: the first PATH entry is not mcpp's tools directory"
+    echo "        got: $first"
+    exit 1 ;;
+esac
+
+# ⭐ AND THE HOST IS STILL BEHIND IT. One entry means the inherited PATH was
+# replaced rather than extended, which would break every build program that
+# calls `git`, `python3` or a shell.
+if [ "${entries:-1}" -gt 1 ]; then
+    echo "  ok  the inherited PATH survives behind it ($entries entries)"
+else
+    echo "FAIL: PATH was replaced, not prefixed — only $entries entry"
+    exit 1
+fi
+
+echo "OK: a build program finds this build system's tools first, and the host's after"