修复 CI 冷缓存工具链

Author: helantianshen

.agent/HANDOFF.md

@@ -23,9 +23,9 @@ concurrency:
 
 env:
   # Pinned rather than "newest": a bootstrap that floats turns an upstream
-  # release into a red build on an unrelated PR. Floor is xlings 0.4.69
-  # (the index keys by (namespace, name) from there on) — never pin below it.
-  XLINGS_VERSION: v2026.8.11.2
+  # release into a red build on an unrelated PR. 2026.8.27.5 is the cold-cache
+  # floor: older clients can declare glibc 2.44 while installing 2.44.2.
+  XLINGS_VERSION: v2026.8.27.5
   XLINGS_NON_INTERACTIVE: '1'
 
 jobs:

.github/workflows/ci-linux.yml

@@ -19,7 +19,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  XLINGS_VERSION: v2026.8.11.2
+  # Keep aligned with the Linux cold-cache floor.
+  XLINGS_VERSION: v2026.8.27.5
   XLINGS_NON_INTERACTIVE: '1'
 
 jobs:

.github/workflows/ci-macos.yml

@@ -21,8 +21,9 @@ concurrency:
 
 env:
   # Both installers read this: the shell one takes it as an argument or an env
-  # var, the PowerShell one defaults its -Version parameter to it.
-  XLINGS_VERSION: v2026.8.11.2
+  # var, the PowerShell one defaults its -Version parameter to it. Keep this
+  # aligned with the Linux cold-cache floor.
+  XLINGS_VERSION: v2026.8.27.5
   XLINGS_NON_INTERACTIVE: '1'
 
 jobs:

.github/workflows/ci-windows.yml

@@ -1,5 +1,5 @@
 {
   "workspace": {
-    "mcpp": "2026.8.11.2"
+    "mcpp": "2026.8.28.1"
   }
 }

.xlings.json

@@ -0,0 +1,25 @@
+# CMP CI 冷缓存工具链修复计划
+
+**日期：** 2026-08-30
+**设计：** `docs/superpowers/specs/2026-08-30-cmp-ci-cold-cache-toolchain-design.md`
+**状态：** 执行中
+
+## 执行规则
+
+只处理 PR #10 已证实的冷缓存工具链失配。每一步先验证再继续；不修改 CMP 源码、依赖、
+编译器版本或未失败的 workflow 引导流程。
+
+## 任务
+
+- [x] 核对 PR #10 三平台结果与 Linux 失败步骤。
+- [x] 核对 mcpp 官方修复提交、版本边界与 xlings 版本下限。
+- [x] 自审设计：发现 mcpp 沙箱会复制 workflow 的 xlings，纠正为同步提升两个 pin。
+- [x] 将 `.xlings.json` 的 mcpp 固定为 `2026.8.28.1`。
+- [x] 将三个 workflow 的引导 xlings 固定为 `2026.8.27.5`，不改执行流程。
+- [x] 安装项目工具并确认实际 mcpp 版本。
+- [x] 运行 Dev/Release 严格无缓存构建和完整测试：两套均为 140/140。
+- [x] 运行 `examples/basic`，全部既有输出与退出状态正确。
+- [x] 自审最终差异并更新 HANDOFF；纠正 workflow 中已过时的版本下限注释。
+- [ ] 本地提交并推送当前分支。
+- [ ] 等待 PR #10 的 Linux、macOS、Windows 检查全部通过。
+- [ ] 根据实际远程结果同步项目当前状态文档。

docs/superpowers/plans/2026-08-30-cmp-ci-cold-cache-toolchain.md

@@ -0,0 +1,66 @@
+# CMP CI 冷缓存工具链修复设计
+
+**日期：** 2026-08-30
+**状态：** 本地实现并验证，远程 CI 待确认
+**基线：** PR #10，提交 `1804044`
+
+## 问题
+
+PR #10 的 macOS arm64 与 Windows x86_64 检查通过；Linux x86_64 在 `Build library`
+阶段、尚未编译 CMP 代码前失败：
+
+```text
+selected RuntimeBinding glibc@2.44 requires payload
+'.../xim-x-glibc/2.44', but it is not installed
+```
+
+冷缓存中实际安装的是 `2.44.2`。项目固定的 mcpp `2026.8.11.2` 携带旧版 xlings，
+运行时绑定使用编译期常量 `2.44`，而当前索引把该请求解析为 `2.44.2`，两种版本身份
+因此失配。本机已有缓存，所以此前本地验证无法复现。
+
+## 选择
+
+同时提升互相配套的两个精确版本：
+
+- `.xlings.json`：mcpp `2026.8.11.2` → `2026.8.28.1`；
+- 三个平台 workflow：引导 xlings `2026.8.11.2` → `2026.8.27.5`。
+
+mcpp 官方提交 `473ee0520b00` 表明 `2026.8.28.1` 是首个随包固定 xlings
+`2026.8.27.5` 的 mcpp 版本；该 xlings 从索引读取运行时绑定，并保证声明版本优先于
+索引的 `latest`。这直接修复冷缓存中“声明 2.44、安装 2.44.2”的根因。
+
+不选其他方案：
+
+- 不固定旧 glibc 载荷，也不增加 CI 缓存；两者只会隐藏索引与绑定失配。
+- 不使用 mcpp `2026.8.27.1`；它已能兼容唯一的版本精化，但尚未携带最终固定的
+  xlings 版本。
+- 不升级到当前最新的 mcpp `2026.8.29.1`；它包含与本问题无关的构建规则改动。
+- 不只提升 mcpp。失败日志显示 mcpp 首次初始化会把 workflow 提供的系统 xlings 复制进
+  私有沙箱；保留旧引导版本会继续制造错误绑定，只能依赖新版 mcpp 的兼容回退。
+
+## 修改边界
+
+- 修改 `.xlings.json` 与三个 workflow 中的四个精确版本值及必要的下限注释；workflow
+  步骤不变。
+- 保持 LLVM `22.1.8`、Asio `1.38.1`、gtest `1.15.2`、CMP API 与源码不变。
+- 记录本次诊断、验证和远程 CI 结果；只有取得结果后才更新“三平台待确认”的文档状态。
+- 不合并 PR #10。
+
+## 验收
+
+1. `xlings install -y` 成功，`mcpp --version` 报告 `2026.8.28.1`。
+2. Dev 与 Release 严格、关闭缓存的构建和 140 项测试全部通过。
+3. `examples/basic` 构建运行成功并输出既有示例结果。
+4. 推送后 PR #10 的 Linux、macOS、Windows 三项检查全部通过。
+
+## 风险
+
+mcpp 尚未到 1.0，工具版本提升可能改变模块扫描或清单校验。完整本地双配置门禁与远程
+三平台门禁共同约束该风险；若任一门失败，只修复有证据的兼容问题，不扩大 CMP API。
+
+## 自审结论
+
+最初方案只提升项目 mcpp。复查 Linux 日志与 mcpp `acquire_xlings_binary()` 后确认，冷启动
+时沙箱 xlings 来自 workflow 的系统版本；因此只提升 mcpp 虽可依赖版本精化回退，但没有
+消除错误绑定的来源。最终方案同时固定官方配套的 mcpp `2026.8.28.1` 与 xlings
+`2026.8.27.5`，其余边界不变。