diff --git a/.agents/docs/2026-08-21-freestanding-outstanding-four.md b/.agents/docs/2026-08-21-freestanding-outstanding-four.md
index f0c5fc76..da682638 100644
--- a/.agents/docs/2026-08-21-freestanding-outstanding-four.md
+++ b/.agents/docs/2026-08-21-freestanding-outstanding-four.md
@@ -676,6 +676,35 @@ openarch 的第三个后端因此写得出来,而**第三台机器正是把门
 
 ---
 
+## 4.5 ⚠️ 顺带暴露的一个引擎缺口:构建程序无法在成功时说话
+
+`openarch` 的三机器模板发布后,用**发布出去的**包走完整条
+`mcpp new --template openarch`:生成的工程三个目标都构建得出,而 `mcpp run` 在两台
+有模拟器的机器上都失败。
+
+成因是清单里的 `[xlings] deps` **是声明而不是安装触发器** —— 它让
+`mcpp::xpkg_dir` 能问「那个包落在哪」,自己不装任何东西。干净 registry 上它返回空,
+`build.mcpp` 静默地不配置 runner,而 mcpp 给出的建议是「写一个 `runner` 键」:一般
+情况下对,在这里不对(这个工程有 runner,只是条件性的)。
+
+⭐ 普通裸机工程遇不到:板级包把模拟器写在**索引描述符的平台 `deps`** 里,那些是随包
+安装的。只有没有板级包的工程才会掉进来。
+
+⚠️ **而构建程序没有办法说出这件事。** 一条 `std::cerr` 提示被写出来、实测、然后删掉:
+mcpp 用 `capture_exec` 抓构建程序,**只在非零退出时**打印抓到的东西,于是那条提示在
+最需要它的那些构建上一个字都不打印。留着比不留更糟,因为它看起来像个修复。让构建失败
+也不对 —— `mcpp build` 不需要模拟器。
+
+⇒ **`mcpp:` 指令表里没有「成功但有话说」的通道。** 现有的是 action / cfg / cflag /
+cxxflag / generated / graph / include / link / protocol / rerun / runner / source。
+一个 `mcpp:warning <text>` 指令会让这一类情形可被诊断 —— 包不在时、可选特性被跳过时、
+构建程序做了一个消费者应当知道的回退时。
+
+判据:一个最小的构建程序发出 `mcpp:warning`,`mcpp build` **成功**并把那行文字显示
+给用户;而 e2e 断言那行确实出现在输出里,而不只是断言构建成功。
+
+---
+
 ## 5. 排序与建议
 
 | | 项 | 状态 | 建议 |