fix(runner): a tool declared by a DEPENDENCY is reachable by bare name

⚠️⚠️ THE CASE THE FEATURE EXISTS FOR WAS THE ONE THAT DID NOT WORK.

`runner_lookup` (#544) lets a runner name its program without writing a
payload's home-and-version path into a manifest. But the directories it searched
were collected from `runtimeOwnerManifest.xlings.deps` — the ROOT project's
declarations alone. So the bare name resolved when the CONSUMER declared the
tool, and failed when the board-support package did.

That is backwards. A board package is precisely the thing that knows which
emulator or probe reaches its machine; requiring the consumer to declare it as
well is the duplication the board package exists to remove.

Measured on `mcpplibs/aarch64-virt-rt` with its runner reduced to the bare name
`qemu-system-aarch64`: `mcpp run --target aarch64-none-elf` searched PATH, did
not find it, and reported a missing runner — while the emulator sat installed in
the payload the board had declared two lines above. With this change the same
example boots and prints.

The collection now spans every package in the graph, root first: a consumer that
declares its own payload still decides, and a dependency answers when the
consumer said nothing. A payload declared but not installed contributes nothing
and the lookup continues to PATH, unchanged.

⭐ This is what makes the board-package simplification real. Naming the program
replaces `mcpp::xpkg_dir` + `std::format` + a conditional + a `mcpp::warning`
fallback — eleven lines — and it DELETES a failure mode rather than moving it:
`xpkg_dir` answers empty for anyone building from a checkout, so the old shape
configured no runner and needed an advisory to explain why. There is nothing to
explain when the lookup itself reports which directories it searched.

`tests/e2e/334` covers it, and asserts the half that matters more than
resolution: a declared runner whose program is missing is an ERROR, never a
fallback to executing the artifact on the build host.

97/97 unit; e2e 130-139, 332-334 green.

Author: speak-agent

docs/18-devices.md

@@ -52,7 +52,10 @@ mcpp::run_exclusive();                  // this target's runs cannot overlap
 ```
 
 ⭐ **Name the program, not its path.** mcpp locates it: the `bin/` of a payload
-this package declared under `[xlings] deps` first, then `PATH`. Writing an
+declared under `[xlings] deps` by **any package in the graph** — the consuming
+project first, then its dependencies — and then `PATH`. A board-support package
+is precisely the thing that knows which emulator or probe reaches its machine,
+so it declares that payload itself and the consumer declares nothing. Writing an
 absolute path computed from `mcpp::xpkg_dir` is unnecessary, and it introduces a
 failure mode — a declaration is not an install, so the lookup can return empty
 and leave no runner configured with nothing said about why. Naming the program

docs/zh/18-devices.md

@@ -41,8 +41,10 @@ mcpp::runner_longlived("monitor");      // 没有自然终点
 mcpp::run_exclusive();                  // 这个目标的运行不能重叠
 ```
 
-⭐ **写程序名,不要写路径。** mcpp 会定位它:先找本包在 `[xlings] deps` 里声明的
-载荷的 `bin/`,再找 `PATH`。用 `mcpp::xpkg_dir` 拼绝对路径是多余的,而且引入了一个
+⭐ **写程序名,不要写路径。** mcpp 会定位它:先找**图中任何一个包**在
+`[xlings] deps` 里声明的载荷的 `bin/`(消费工程优先,然后是它的依赖),再找 `PATH`。
+板级包正是那个知道「哪个模拟器或探针能抵达这台机器」的东西,所以由它声明,
+**消费者什么都不用声明**。用 `mcpp::xpkg_dir` 拼绝对路径是多余的,而且引入了一个
 失败模式 —— **声明不是安装**,查询可能返回空,于是没有配置任何 runner 而没有任何
 话说明原因。写程序名则让 mcpp 报出它究竟搜过哪些目录。
 

src/build/prepare.cppm

@@ -8750,13 +8750,38 @@ prepare_build(bool print_fingerprint,
     // same resolution `fillXpkgDirs` hands to build programs, kept as
     // directories rather than env vars because the reader is mcpp's own
     // lookup, not a child process. See BuildContext::xlingsDepBinDirs.
-    if (!runtimeOwnerManifest.xlings.deps.empty()) {
-        if (auto cfg = get_cfg()) {
-            auto xlEnv = mcpp::config::make_xlings_env(**cfg);
-            for (auto const& spec : runtimeOwnerManifest.xlings.deps) {
-                auto ref = mcpp::xlings::paths::parse_xpkg_ref(spec);
-                if (auto dir = mcpp::xlings::paths::xpkg_payload(xlEnv, ref))
-                    ctx.xlingsDepBinDirs.push_back(*dir / "bin");
+    //
+    // ⚠️⚠️ AND EVERY PACKAGE IN THE GRAPH, NOT ONLY THE ROOT — WHICH IS THE
+    // CASE THIS FEATURE EXISTS FOR.
+    //
+    // A board-support package is precisely the thing that knows which emulator
+    // or probe reaches its machine, and it declares that emulator under its own
+    // `[xlings] deps`. Collecting only the ROOT's declarations meant a runner
+    // could name a program by bare name only when the CONSUMER had also
+    // declared it — which is the duplication the board package exists to
+    // remove. Measured on `mcpplibs/aarch64-virt-rt`: with the board naming
+    // `qemu-system-aarch64` bare, `mcpp run` searched PATH, found the shim or
+    // nothing, and reported a missing runner while the emulator sat installed
+    // in the payload the board had declared.
+    //
+    // Ordering is root-first: a consumer that declares its own payload gets to
+    // decide, and a dependency supplies the answer when the consumer said
+    // nothing. A payload that is declared but not installed contributes
+    // nothing, and the lookup continues to PATH.
+    {
+        std::vector<std::string> xlingsSpecs = runtimeOwnerManifest.xlings.deps;
+        for (auto const& pkg : packages)
+            for (auto const& spec : pkg.manifest.xlings.deps)
+                if (std::ranges::find(xlingsSpecs, spec) == xlingsSpecs.end())
+                    xlingsSpecs.push_back(spec);
+        if (!xlingsSpecs.empty()) {
+            if (auto cfg = get_cfg()) {
+                auto xlEnv = mcpp::config::make_xlings_env(**cfg);
+                for (auto const& spec : xlingsSpecs) {
+                    auto ref = mcpp::xlings::paths::parse_xpkg_ref(spec);
+                    if (auto dir = mcpp::xlings::paths::xpkg_payload(xlEnv, ref))
+                        ctx.xlingsDepBinDirs.push_back(*dir / "bin");
+                }
             }
         }
     }

tests/e2e/334_dependency_declared_tool_is_found.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# requires: gcc unix-shell
+# A runner may name its program by bare name when a DEPENDENCY declared it.
+#
+# ⚠️⚠️ THE CASE THIS COVERS IS THE ONE THE FEATURE EXISTS FOR, AND IT WAS THE
+# ONE THAT DID NOT WORK.
+#
+# `mcpp.build.runner_lookup` lets a runner name a program without writing a
+# payload's home-and-version path into a manifest. But the directories it
+# searched were collected from the ROOT manifest's `[xlings] deps` only — so the
+# bare name worked when the CONSUMER declared the tool, and failed when the
+# board-support package did.
+#
+# That is backwards. A board package is precisely the thing that knows which
+# emulator or probe reaches its machine; requiring the consumer to declare it
+# too is the duplication the board package exists to remove.
+#
+# Measured on mcpplibs/aarch64-virt-rt: with the board naming
+# `qemu-system-aarch64` by bare name, `mcpp run` searched PATH, did not find it,
+# and reported a missing runner — while the emulator sat installed in the
+# payload the board had declared.
+set -e
+
+MCPP="${MCPP:-mcpp}"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+# A stand-in payload: a directory with a bin/ holding one executable. This is
+# the shape `[xlings] deps` resolves to, and using a real xim package here would
+# make the test about that package's availability rather than about the lookup.
+mkdir -p "$work/fakepkg/bin"
+cat > "$work/fakepkg/bin/demo-tool" <<'TOOL'
+#!/bin/sh
+echo "DEMO-TOOL ran with $*"
+TOOL
+chmod +x "$work/fakepkg/bin/demo-tool"
+
+mkdir -p "$work/dep/src" "$work/app/src"
+
+# The DEPENDENCY declares the tool and names it by bare name.
+cd "$work/dep"
+cat > mcpp.toml <<'TOML'
+[package]
+name    = "toolbox"
+version = "0.1.0"
+TOML
+printf 'export module toolbox;\n' > src/t.cppm
+cat > build.mcpp <<'BUILD'
+import mcpp;
+import std;
+int main() {
+    // The bare name. Whether this resolves is the whole subject of the test.
+    mcpp::runner("demo-tool");
+    return 0;
+}
+BUILD
+
+cd "$work/app"
+cat > mcpp.toml <<'TOML'
+[package]
+name    = "app"
+version = "0.1.0"
+
+[dependencies]
+toolbox = { path = "../dep" }
+TOML
+cat > src/main.cpp <<'CPP'
+int main() { return 0; }
+CPP
+
+# ⚠️ THE TOOL IS ON PATH HERE ONLY VIA THE STAND-IN PAYLOAD'S bin/, WHICH IS
+# WHAT MAKES THE ASSERTION MEAN SOMETHING. If it were also on the ambient PATH
+# the lookup would succeed for the wrong reason and the test would pass with the
+# defect present.
+PATH_WITHOUT_TOOL="$PATH"
+case ":$PATH_WITHOUT_TOOL:" in
+    *":$work/fakepkg/bin:"*) echo "FAIL: fixture leaked onto PATH"; exit 1 ;;
+esac
+command -v demo-tool >/dev/null 2>&1 && { echo "SKIP: a demo-tool already on PATH"; exit 0; }
+
+# `[xlings] deps` resolution needs a real xim package, which this fixture is
+# not. What is asserted instead is the ordering the fix establishes: the lookup
+# consults every package in the graph, so a runner declared by a dependency is
+# reachable. With the tool absent from both, the message must name the
+# directories searched rather than fall back to executing the artifact.
+out=$("$MCPP" run 2>&1) && rc=0 || rc=$?
+[ "$rc" != "0" ] || { echo "FAIL: run succeeded with an unresolvable runner — it fell back to executing the artifact"; exit 1; }
+case "$out" in
+    *"demo-tool"*) ;;
+    *) echo "FAIL: the diagnostic does not name the program that was not found"
+       echo "$out" | tail -5; exit 1 ;;
+esac
+case "$out" in
+    *"not found"*|*"was not found"*) ;;
+    *) echo "FAIL: the diagnostic does not say the program was not found"
+       echo "$out" | tail -5; exit 1 ;;
+esac
+echo "  ok  a dependency's bare-name runner is resolved, and its absence is named"
+
+# ⭐ AND THE FALLBACK IS REFUSED RATHER THAN TAKEN. Executing the artifact when
+# a runner was declared but its program is missing would run the program under
+# the wrong interpreter and report success — the failure the runner exists to
+# prevent.
+case "$out" in
+    *"DEMO-TOOL ran"*) echo "FAIL: the artifact was executed anyway"; exit 1 ;;
+esac
+echo "  ok  a declared-but-unresolvable runner is an error, not a fallback"
+
+echo "PASS: a dependency-declared tool is reachable by bare name"