diff --git a/.agents/docs/2026-10-17-upgrade-continuity-design.md b/.agents/docs/2026-10-17-upgrade-continuity-design.md
new file mode 100644
index 00000000..75961a04
--- /dev/null
+++ b/.agents/docs/2026-10-17-upgrade-continuity-design.md
@@ -0,0 +1,268 @@
+---
+subject: design
+status: active
+---
+
+# 升级的连续性：打包修订不在使用路径上替换载荷、替换失败不拆掉可用状态、home 中的悬空记录自愈、真实的升级 lane
+
+- 日期：2026-10-17。状态：修订 3，已实施（libxpkg #50、xlings #678 与 2026.10.17.1、xim-pkgindex #993、mcpp #815）。
+- 起因：用户报告。`xlings self update && xlings update mcpp -y` 之后，`mcpp new hhss && mcpp run` 每次失败：
+  `toolchain 'llvm@23.1.3': install of 'xim:llvm@23.1.3' failed … sysroot update refused before metadata changed:
+  c++@16.1.0: installed asset registration missing`；`mcpp self doctor` 不报错。
+- 基线：`main` `f4816141`（mcpp 2026.10.16.3，内置 xlings 2026.10.16.2）；openxlings/xlings `03a2002c`
+  （2026.10.16.2）；openxlings/xim-pkgindex `5a70d12`。
+- 证据：本地复现（Linux x86_64）；probe PR #814 两轮运行
+  [38989869868](https://github.com/mcpp-community/mcpp/actions/runs/38989869868)（11 个 job）、
+  [38990143701](https://github.com/mcpp-community/mcpp/actions/runs/38990143701)（3 个 job），见 §2。
+- 范围：每个仓库一个 PR：libxpkg（L1，`floor` 的解析）、xim-pkgindex（I1）、xlings（X1–X4，一次发布）、mcpp。
+  发布顺序 libxpkg → xlings → mcpp；xim-pkgindex 的规范与检查与之并行，最后合入。不分阶段，不留临时方案。
+
+## 0. 结论
+
+升级之所以不是无感的，是 2026.10.16.1 把「打包修订是否最新」并进了「载荷是否完整」，而 mcpp 在使用路径
+（build/run/test/doctor）上把「不完整」当作「未安装」同步重装。于是 index 中任何一次修订号上调，都会在用户
+下一次 `mcpp run` 时变成一次替换：在一致的 home 中是一次多余的下载（gcc 101.7 MB、llvm、glibc 36.7 MB），
+在带一条悬空记录的 home 中是每次都失败，而 xlings 保留下来的可用载荷被 mcpp 丢弃。CI 全部从空 home 起步，
+装出来的修订号永远等于索引的修订号，这条路径从未被执行。
+
+修复是四个不变量，各落到唯一的位置：
+
+1. **使用不变更**（P1）：使用命令不替换一个可用的载荷。修订号不同是「有更新的打包」，不是「不完整」；
+   只有低于索引声明的可用下限（`floor`）时才必须替换。
+2. **替换失败不降级**（P3）：替换是事务；失败时旧载荷仍可用就继续用，并如实报告。
+3. **一个事务只被自己的问题阻止**（P4）：工作区中引用不存在注册的记录是垃圾，xlings 在每个元数据事务开始时
+   以 doctor 的同一个函数规范化并报告。
+4. **诊断只读且如实**（P5），**升级由真实的上一发布版验证**（P6）。
+
+## 1. 现象与链条
+
+用户机器上的完整链条（代码位置以基线为准）：
+
+1. mcpp 2026.10.16.3 第一次运行，把内置 xlings 从 2026.10.10.2 换成钉住的 2026.10.16.2。
+2. `Fetcher::resolve_xpkg_path`（`src/pm/package_fetcher.cppm`）的 `complete_here()` 问提供者
+   `payload_status`。xlings 2026.10.16.1 起，`payload_state_()`（xlings `src/core/xim/commands.cpp`）在
+   `payload_revision_verdict(...).stale` 时返回 `complete=false`（xlings #676，即 10-16 设计的 X4）。
+   llvm 23.1.3 在索引中为 revision 1（xim-pkgindex #938，2026-10-08），载荷记录为 0。
+3. `complete_here()` 失败，mcpp 在 `mcpp run` 内调用安装。xlings 计划为 `reinstall: recipe revision 1,
+   installed revision 0`，下载、解包、把旧载荷移到一边。
+4. 元数据事务的投影预检 `prepare_projection_change`（xlings `src/core/xvm/materialize.cpp`）对被重新配置的
+   target `c++` 收集期望的投影：`c++` 的 active 是 `16.1.0`（gcc 的），版本库里没有这条注册 →
+   `collect_claims(..., ClaimSource::Present)` 返回 `installed asset registration missing`。事务拒绝，
+   旧载荷放回（`kept the previous payload`）。
+5. mcpp 再次 `complete_here()`：仍是 `complete=false`（修订号仍旧）→ 报错。失败后的索引刷新打印
+   `Refreshing package index — xim:llvm@23.1.3 not found locally (one-time)`：载荷与描述文件都在本地，
+   这句话的理由是错的，而且每过一次 debounce 窗口就出现一次。
+6. `mcpp self doctor` 的 runtime capabilities 检查调用 `prepare_build`，又发起一次同样的重装；失败被报告为
+   `ok (run inside a package to check its runtime capabilities)`，而用户就在包里。它的 toolchain 一节检查的是
+   PATH 上的 `~/.xlings/subos/default/bin/g++`，不是 mcpp 为这个项目解析的 llvm。
+
+升级前为什么没事：v2026.10.11.1 的 `resolve_xpkg_path` 只看 `.mcpp_ok` 标记，不看修订号；xlings 2026.10.10.2 的
+`payload_status` 也不看。10-16 设计以「mcpp 不写载荷」取消标记、改由提供者回答完整性（§7.1、X4），
+`docs/specs/package-identity.md` §10.3 第 3 条把「修订号与索引条目一致」写进了完整性。该设计的兼容一节写的是
+「已安装的 mcpp 行为不变」，实现与之相反。
+
+用户 home 的状态（诊断脚本实测）：版本库在 `.xlings.json`（无 `data/versions.json`）；`xim-gnu-gcc` 只剩
+`15.1.0`，`c++` 只剩 `15.1.0 / 22.1.8 / 23.1.3`，工作区却以 `16.1.0` 为 active；工作区有而版本库没有的记录
+529 条；指向 `/tmp/claude-1000/fakehome/...` 的条目 1827 个（来源见 §3 F6）。
+
+## 2. 实测（probe #814）
+
+上一发布版 2026.10.11.1（自带 xlings 2026.10.10.2）建立 home，装 llvm@23.1.3（Linux 另装 gcc@16.1.0），
+`mcpp new && mcpp run`；换成 2026.10.16.3，在同一 home 中 `mcpp new && mcpp run` 若干次。
+
+| 变体 | 平台 | 升级后第一次 run | 结论 |
+|---|---|---|---|
+| plain（今天的索引） | x86_64、aarch64、macOS、Windows | rc 0，1 s，无下载 | 修订号一致时升级无感 |
+| snapshot（xim-pkgindex `ebf1fbb`，2026-10-07，真实的旧修订载荷） | x86_64 | 旧索引仍在时：rc 0，1–2 s，无替换，**用 revision 0 的 llvm 构建并运行成功**；`index update` 后：llvm 项目下载 glibc 36.7 MB 并替换 llvm（19–24 s），gcc 项目下载 gcc 16.1.0-r1 101.7 MB 与 binutils 2.42.1 | 修订号上调在使用路径上变成替换与下载 |
+| stamp（载荷记录的修订号与索引不同） | x86_64、aarch64、macOS、Windows | rc 0，12–30 s，重新下载 llvm（Linux 另有 glibc、gcc） | 机制跨平台 |
+| orphan（stamp + gcc 的 `c++@16.1.0` 为 active 且版本库无此注册，即用户 home 的形状） | x86_64、aarch64 | **rc 101，每次**（22–45 s 后失败），与用户报错逐字一致；`mcpp self doctor`（项目内）发起安装且返回 0 | 一条悬空记录使替换永久失败；doctor 改变状态且不报告 |
+
+附带的实测事实：
+
+- llvm revision 0 与 1 的 cfg 唯一差别是 glibc 库目录（`glibc/2.44.3/lib` → `lib64`）；glibc revision 4 的载荷
+  同时有 `lib` 与 `lib64 -> lib`，所以 revision 0 的 llvm 在 revision 4 的 glibc 上仍然自洽。头文件搜索列表相同。
+- orphan 变体中，gcc 项目的运行替换了 gcc（修订 0 → 1），gcc 的 `config()` 重新注册了 `c++@16.1.0`，悬空记录
+  随之消失，此后 llvm 的替换成功。即：**重新配置记录的拥有者能修复它，但 xlings 不会主动这样做**。
+- `xlings self doctor` 对 orphan home 报 4 条 binding state 发现（`xvm-active-version-missing` 等），
+  其中给出的 `run xlings install c++` 把 target 当成了包名。
+- 修订号的波及面（xim-pkgindex `5a70d12`，Linux）：llvm 20.1.7/22.1.8/23.1.3 revision 1（10-08，归档不变，
+  cfg 随 glibc 布局）；gcc 16.1.0 revision 1（10-12，`16.1.0-r1` 新归档，去掉硬链接，为 Android/FAT）；
+  glibc 2.44.3 revision 4（去掉硬链接，为 Android）；binutils revision 2。每个在这些日期之前装过的 Linux home
+  都会在升级后的第一次 run 中替换它们。
+- macOS 上 `mcpp self doctor` 的 toolchain 一节报告 `/usr/bin/g++`（Apple clang 17），并因一条 Xcode SDK 的
+  警告返回 1。
+
+## 3. 根因
+
+### F1 使用路径替换载荷
+
+完整性（载荷在、有内容、没有失败标记）与时效（安装的修订号是否等于索引当前的修订号）是两个独立的事实，
+2026.10.16.1 把后者并进了前者。使用路径只该关心前者：一个完整的载荷，连同它安装时解析出的闭包
+（载荷中的 `.xlings-resolution.json`），是自洽的，可以使用。修订号上调的原因多种多样：为 Android 去掉硬链接、
+随依赖的布局重新生成 cfg、修复一个所有人都会遇到的缺陷。只有最后一种要求已装的载荷必须替换，而这一点只有
+写描述文件的人知道。今天的数据模型无法表达它，于是 xlings 和 mcpp 只能对所有修订号一律替换。
+
+### F2 替换失败丢弃可用载荷
+
+xlings 的替换是事务（`PayloadReplacement`，失败放回旧载荷），但 mcpp 在失败后仍以 `complete` 判断，旧载荷
+因修订号旧而被判为不完整，于是报错。提示固定为「retry」，而这次失败是确定性的。失败后的索引刷新沿用
+`DescriptorMiss` 的理由（`not found locally (one-time)`），对一个本地存在的描述文件既不真也不是一次性的。
+
+### F3 一个事务被别的包的悬空记录阻止
+
+投影预检对「被重新配置的 target 的期望投影」使用 `ClaimSource::Present`，遇到没有注册的 active 版本就拒绝。
+这条记录属于 gcc，与 llvm 的事务无关；它本来就是坏的（`c++` 的 shim 无处可派发），llvm 的替换只是第一个读到它。
+xlings 的 doctor 已经认得它（`xvm-active-version-missing`），`--fix` 也有处理悬空引用的代码（`repair_state_`），
+但安装路径没有用同一个函数。结果是一个与本次操作无关的旧问题把这次操作永久卡住。
+
+### F4 诊断命令改变状态且掩盖失败
+
+`mcpp self doctor` 的 runtime capabilities 检查调用完整的 `prepare_build`，因此会安装与替换；它把准备失败
+一律说成「不在包里」。toolchain 一节用 `mcpp::toolchain::detect()` 检查 PATH 上的编译器，不是 mcpp 为当前
+上下文解析的工具链，所以在工具链坏掉时报 `ok`。
+
+### F5 CI 看不见升级
+
+mcpp 的 fresh-install 与 e2e 每次新建 `MCPP_HOME`，从当前索引安装。`916_a_home_from_before_keeps_working`
+手写一个只有假 mcpplibs 包的 home，不含工具链、不用上一版的 xlings、不跑 `mcpp new && mcpp run`；10-16 设计
+§15 写的「2026.10.11.1 建立的 home」在落地时变成了伪造的 home。xlings 的 `install_revision_test.sh` 是干净 home
+中单个 hook-only 包，没有多个包共享一个 target，也没有不一致的记录。
+
+### F6 用户 home 的污染
+
+1827 个条目与 doctor 中数百条悬空链接指向 `/tmp/claude-1000/fakehome/.mcpp/registry/...`，即曾有以假 HOME
+运行的测试进程写入了真实的 `~/.mcpp/registry`。来源进程未定位。产品侧的要求由 F3 的自愈覆盖（坏记录不再阻止
+操作）；这台机器的 home 另行修复，不属于本设计的代码改动。
+
+## 4. 原则
+
+- **P1 使用不变更。** build、run、test、pack、doctor 等使用命令不替换一个可用的载荷。可用 = 完整，且安装的修订号
+  不低于索引条目声明的 `floor`。
+- **P2 身份与可用性分离。** 载荷的身份仍是 `(namespace, name, version, revision)`；构建记录的是**实际使用的**
+  身份。索引的当前修订号决定新安装得到什么，不决定已安装的是否可用。
+- **P3 替换是事务，失败不降级。** 替换只发生在显式的供给命令中，或可用性要求它时；失败后旧载荷仍可用就继续用。
+- **P4 版本库是 home 的权威。** 工作区中引用不存在注册的记录是垃圾；任何元数据事务开始时以 doctor 的同一个函数
+  规范化，并说出做了什么。一个事务只能被它自己的问题阻止。
+- **P5 诊断只读且如实。** doctor 不安装、不替换；它报告 mcpp 实际会用的东西，失败就说失败。
+- **P6 升级由真实的上一发布版验证。** 不伪造旧 home。
+
+## 5. 决策
+
+| # | 决策 | 理由 |
+|---|---|---|
+| D1 | 提供者契约分开报告完整性与时效：`payload_status` 与 `install_targets` 的每个载荷给出 `complete`（只表示完整性）、`revision`（索引当前）、`installed_revision`、`floor`、`usable`（`complete` 且 `installed_revision ≥ floor`；未记录修订号的载荷按可用）、`current`（`installed_revision == revision`）。xlings 以特性 `payload_currency` 宣告；mcpp 的 `unmet()` 要求它 | F1：一个字段承载两件事，调用方就无法区分「旧」与「坏」。判定由提供者给出，mcpp 不复刻版本文法与修订号规则（10-16 设计的端口边界） |
+| D2 | 索引的版本条目可声明 `floor`（最低可用修订号，`0 ≤ floor ≤ revision`，缺省 0）。修订号上调时由描述文件作者决定已装的旧修订是否仍可用；现有条目不声明，即全部可用 | 只有作者知道一次修订是「为 Android 去掉硬链接」还是「所有人都会踩的缺陷」。§2 实测本次的 llvm、gcc、glibc 修订对已装载荷都不要求替换 |
+| D3 | mcpp 的载荷解析分两种意图：**使用**（build/run/test/pack/doctor、运行库 glibc 的 `ensure_declared_runtime`、宿主工具引导）与**供给**（`mcpp toolchain install`）。使用：`usable` 即用；不可用（缺失、不完整、低于 floor）才安装或替换，并以状态行说明原因（`Updating llvm@23.1.3  packaging revision 0 → 1 (below the index's floor 1)`）。供给：`usable && !current` 时替换为当前修订（`Updating … packaging revision 0 → 1`），`current` 时说已安装 | P1、P3。用户显式要求的才是升级；`mcpp toolchain install <spec>` 本来就是「让这个工具链就绪」的命令，不新增动词 |
+| D4 | 库依赖（mcpplibs 等，#524 A）保持「描述文件与载荷同修订」：修订号不同按未安装处理，在构建中替换。它们获得 D5 的失败语义与 X2 的自愈 | 库依赖的描述文件在构建时被读（链接面、flags，#524 的实例），载荷必须与之一致；工具链与运行库的构建输入是载荷本身及其安装时的闭包，不读描述文件。两者语义不同，各自正确 |
+| D5 | 替换失败：提供者的替换是事务，原载荷保留。只有供给意图会替换一个仍 usable 的载荷，它失败时报错，并说明仍在使用的修订号；使用意图只替换不 usable 的载荷，失败时没有可退回的载荷，报错。（修订 1 写的「使用意图继续用旧载荷」在使用意图下不会出现：使用意图对 usable 的载荷不发起替换。）提示由错误码决定：确定性的拒绝（`E_INTERNAL`、`E_PERMISSION`、`E_DISK_FULL`、`E_CANCELLED`）不说 retry、不经命令行重试、不刷新索引；只有 `E_NOT_FOUND`（以及没有错误码的旧路径）触发失败后的索引刷新，理由文本为「could not be installed; the index may predate it」 | F2。诊断分级：使用意图下为命令失败并给出原因，供给意图下为命令失败并说明仍在使用的修订号 |
+| D6 | 时效的呈现不在构建中：`mcpp index update` 结束时列出非当前的已装载荷，`mcpp toolchain list` 标出 `packaging revision 1 available`（JSON 为 `installedRevision`/`availableRevision`），doctor 同样报告；构建中的自动刷新只在 verbose 日志中记录 | 无感：构建输出不随索引变化而变化；用户在显式改变索引的那一刻、在查看工具链时看到它 |
+| D7 | mcpp doctor 只读且如实：runtime capabilities 以不供给的意图准备（解析失败即报告错误与原因）；toolchain 一节报告 mcpp 为当前上下文解析的工具链（项目 → 配置默认），附载荷状态（`usable/current`、两个修订号）与 xlings home 的一致性摘要（悬空记录数，来自 X3）；PATH 上的编译器不再作为「toolchain」报告 | F4、P5 |
+| D8 | 构建身份记录实际使用的修订号：运行时契约（`package-identity` §10.2 的 `revision=<n>`）本来就读载荷的安装记录；工具链的驱动身份在修订号大于 0 时追加 `payload-revision: <n>`（同样读安装记录），因而进入指纹与缓存键 | P2：同一项目在两个修订的载荷上构建，产物与缓存不得混用。代价：修订号大于 0 的工具链在升级后重建一次缓存，CHANGELOG 写明 |
+| D9 | CI 增加真实升级 lane，§7 | P6、F5 |
+
+开放问题（维护者选择，不是推迟的范围）：
+
+- **O1** 悬空 active 的处理（X2）：推荐「解除该 target 的 active，并报告 `c++: active version 16.1.0 had no
+  registration; deactivated (xlings use c++ <version>)`」；另一选项是改选该 target 另一个已注册的版本。推荐前者，
+  因为改选会悄悄改变用户 shell 中 `c++` 指向的编译器。
+- **O2** `floor` 放在索引（推荐，D2）还是 mcpp 内置表。放在 mcpp 只能表达「mcpp 需要」，不能表达「这个包的这次
+  修订修了所有人的缺陷」；前者在需要时也可以由 mcpp 对索引提出。
+
+## 6. 生态的需求
+
+libxpkg（recipe 的解析者，`PlatformResource::revision` 在此）：
+
+- **L1** 版本条目解析 `floor`（非负整数，高于 `revision` 时按 `revision` 读）；`ResolvedResource` 随 `ref` 报告解析到的条目的
+  `floor`；版本 0.0.65。
+
+xim-pkgindex：
+
+- **I1** V2 规范为版本条目增加 `floor`；`.github/scripts/check-revision.lua` 校验 `0 ≤ floor ≤ revision`、位置
+  （版本项上，不在 alias 与按架构的表内），`floor` 不属于资源。现有条目不需要改动。（修订 1 曾要求「不改
+  `revision` 不得提高 `floor`」；实施时删去：作者事后才确认某个已发布修订修复了所有已装载荷的缺陷时，把 `floor`
+  提到这个修订是正当的。）
+
+xlings（一次发布，mcpp 的 PR 把内置 xlings 钉到它）：
+
+- **X1** `payload_status`、`install_targets` 按 D1 报告；特性 `payload_currency`；协议版本上调。xlings 的安装计划
+  不变：被请求的目标与计划中的依赖都按 `current` 替换。一次安装是供给动作，新载荷是对着索引当前的闭包写成的，
+  它的依赖必须同为当前修订（llvm revision 1 的 cfg 指向 glibc revision 4 的 `lib64`，配上 revision 3 的 glibc
+  就不自洽）。使用路径不受影响：按 P1，使用意图对一个 usable 的载荷根本不发起安装。（修订 1 曾写「依赖按
+  usable 判断」，实施前的审读发现上述不自洽，改为此条。）
+- **X2** 元数据事务（`process_xvm_operations_`、`publish_removal_state_`）在本包的注册读取作用域之前，以 doctor 的同一个
+  函数（`xvm::plan_scope_reference_repair`）规范化候选工作区：引用不存在注册的 `installed[]` 条目删除，悬空 active 按 O1
+  解除；本包自己的注册恢复了的记录不算修复。规范化随事务提交，提交后以 `scope_repaired` 事件报告（mcpp 原样显示）；
+  其他 subos 的投影用规范化后的副本计算，不写回。投影预检本身不变：规范化之后，悬空记录不再进入预检。
+- **X3** doctor：当前 subos 的 `--fix` 调用 X2 的同一个函数（含 `installed[]`）；`xvm-active-version-missing` 与
+  `xvm-subos-active-missing` 的 remedy 不再把 target 当包名，改为 `xlings self doctor --fix` 或 `xlings use <target>
+  <version>`（注册已缺失，拥有者无从得知）；`system_status` 输出 `binding_state` 摘要（特性 `binding_state`），供 mcpp
+  doctor 读取。
+- **X4** 测试：两个包注册同一 target、删除一方的注册后，另一方的安装与替换成功并报告规范化；`payload_status`
+  的六个字段与 `floor` 的组合；依赖中的旧修订不被替换。新测试在 2026.10.16.2 上必须失败。
+
+## 7. 测试
+
+mcpp：
+
+- **单元（provider 端口的假实现）**：`(complete, usable, current, 意图)` → 动作的完整矩阵（用、替换、安装、报错、
+  降级继续）；替换失败且旧载荷 usable 时使用意图继续、供给意图报错；错误码 → 提示与是否刷新的对应。
+- **e2e（本地夹具，离线）**：以本地索引夹具与载荷记录，断言旧修订的工具链被使用、构建无下载、`mcpp toolchain
+  list` 标出可用的新修订、`mcpp toolchain install` 替换它；doctor 在项目中不发起任何安装（以提供者调用日志断言）。
+- **CI lane `ci-upgrade.yml`**（Linux x86_64、aarch64、macOS、Windows）：上一发布版（从 GitHub release 取，版本由
+  `mcpp-release.json` 与本仓库版本推出，每次发布自动前移）建立 home、装工具链、`mcpp new && mcpp run`；换成本 PR
+  构建的 mcpp，断言 `mcpp new && mcpp run` 成功、零下载、无替换。Linux x86_64 另跑 snapshot（旧修订载荷）与
+  orphan（悬空记录）两个变体：前者断言零下载且 `index update` 报告非当前载荷，后者断言成功并出现规范化报告。
+- 新增测试在 2026.10.16.3 上必须失败（snapshot 与 orphan 变体已由 probe 证明会失败）。
+- `916` 保留为 index 迁移的 e2e，其注释不再声称覆盖「旧 home 继续可用」；升级由上面的 lane 覆盖。
+
+## 8. 规范与文档
+
+- `docs/specs/package-identity.md`：§10.2 改写 mcpp 侧对修订号的三处使用（工具链与运行库按 usable，库依赖按
+  一致，契约记录实际使用的修订号）；§10.3 第 3 条把「修订号与索引条目一致」移出完整性，加入 usable 与 current
+  的定义；变更记录与版本。
+- `docs/specs/toolchain-management.md`：`mcpp toolchain install` 对已装旧修订的语义；`toolchain list` 的时效列。
+- `docs/` 与 `docs/zh/` 中工具链管理与 doctor 的章节：升级、修订号与 `floor` 的用户可见行为。
+
+## 9. 提交顺序（一个 PR 内）
+
+1. 内置 xlings 钉到 X1–X4 的发布；`unmet()` 要求 `payload_currency`；provider 端口的 `PayloadStatus` 增加 D1 字段。
+2. 解析意图（D3）与失败语义（D5）：`resolve_xpkg_path` 的意图参数，使用与供给的调用点逐一标明；
+   `ensure_declared_runtime` 与宿主工具引导走使用意图；单元测试。
+3. D8：工具链指纹与运行时契约取 `installed_revision`。
+4. D6：`index update` 的非当前载荷报告、`toolchain list` 的时效列。
+5. D7：doctor 只读与如实；读取 X3 的一致性摘要。
+6. 失败后刷新的理由与条件（D5）。
+7. e2e 与 `ci-upgrade.yml`；规范、双语文档、CHANGELOG。
+
+## 10. 这台机器
+
+用户的 home 需要单独修复，不依赖本设计落地：它的版本库与工作区有 529 条不一致，且有 1827 个条目指向不存在的
+假 HOME。probe 实测「重新配置悬空记录的拥有者」能修复 `c++@16.1.0` 这一条；整体上更稳妥的是在备份后重建
+`~/.mcpp/registry`。具体操作由维护者决定。
+
+## 11. 实施计划与依赖
+
+```
+L1 libxpkg floor ──► X1 payload_status/install_targets 六字段 ──┐
+I1 规范与 check-revision（并行）                                ├─► xlings 发布 2026.10.17.1 ──► M1 钉住与 unmet()
+X2 事务规范化（plan_scope_reference_repair）──┬─► X4 测试 ──────┘                          │
+X3 doctor 共用函数、remedy、system_status 的 binding_state ─┘                              ▼
+                                         M2 意图与失败语义（D3/D5）──► M3 D8 ──► M4 D6 ──► M5 D7 ──► M6 测试与 ci-upgrade
+                                                                                                   │
+                                                                         规范、双语文档、CHANGELOG ◄┘
+```
+
+| 任务 | 仓库 | 内容 | 依赖 | 验证 |
+|---|---|---|---|---|
+| L1 | libxpkg | `floor` 的解析与随 `ref` 解析；夹具与单元测试；0.0.65 | — | `mcpp test` |
+| I1 | xim-pkgindex | V2 规范的 `floor`；`check-revision.lua` 的范围与「不改 revision 不得抬 floor」；双语文档 | — | 本地对 `main` 跑检查脚本 |
+| X1 | xlings | `payload_state_` 的 `complete` 只表示完整性；六字段；`payload_currency`；协议 1.11 | L1 | 单元与 e2e |
+| X2 | xlings | 纯函数 `plan_scope_reference_repair`；`process_xvm_operations_`、`publish_removal_state_` 先规范化候选工作区并报告（`scope_repaired` 数据事件与日志）；其他 subos 的投影用规范化后的副本 | — | 单元、e2e（两包共享 target） |
+| X3 | xlings | doctor 的当前 subos 修复调用同一纯函数（含 `installed[]`）；`xvm-active-version-missing` 的 remedy；`system_status` 输出 `binding_state` 摘要，特性 `binding_state` | X2 | 单元 |
+| X4 | xlings | e2e：orphan 形状下替换成功并报告规范化；`payload_status` 字段与 `floor` 组合 | X1–X3 | 在 2026.10.16.2 上失败 |
+| M1 | mcpp | 内置 xlings 2026.10.17.1；`unmet()` 要求 `payload_currency`；`PayloadStatus` 增字段 | xlings 发布 | 单元 |
+| M2 | mcpp | `PayloadIntent{Locate, Use, Provision}`；调用点逐一标明；失败语义按错误码；失败后刷新只对 `E_NOT_FOUND` | M1 | 单元（假提供者） |
+| M3 | mcpp | 工具链 `driverIdent` 记录载荷的 `installed_revision`（>0 时） | M2 | 单元 |
+| M4 | mcpp | `index update` 结束时报告非当前载荷；`toolchain list` 的时效标注 | M1 | e2e |
+| M5 | mcpp | doctor 只读：runtime capabilities 以 Locate 准备；toolchain 一节报告解析到的工具链与载荷状态、home 一致性摘要 | M2 | e2e（调用日志无安装） |
+| M6 | mcpp | e2e（离线夹具）；`ci-upgrade.yml`（4 平台 + snapshot/orphan）；916 注释 | M1–M5 | CI；在 2026.10.16.3 上失败 |
diff --git a/.agents/docs/README.md b/.agents/docs/README.md
index de9396ca..d039868d 100644
--- a/.agents/docs/README.md
+++ b/.agents/docs/README.md
@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-332 records.
+333 records.
 
 ## By subject
 
@@ -31,6 +31,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### design
 
+- [升级的连续性：打包修订不在使用路径上替换载荷、替换失败不拆掉可用状态、home 中的悬空记录自愈、真实的升级 lane](2026-10-17-upgrade-continuity-design.md) — active
 - [一处来源，一种含义：工作空间的传递语义、生成输出、模块角色与首次运行（#786、#785、#778、#790）](2026-10-10-one-source-one-meaning-design.md) — landed
 - [2026.10.5.3 发布方案：32 位 x86 的架构词汇、资源编译器的识别与增量（#776 后续）](2026-10-06-windows-x86-arch-vocabulary-and-rc-follow-ups-design.md) — active
 - [下一个版本的发布方案：标准库模块、原生 MSVC LTO 与导出发现、共享库的链接配置、Windows 参数引号（#768 后续、#770、#771）](2026-10-05-std-module-pair-msvc-lto-and-export-discovery-design.md) — active
@@ -129,6 +130,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-10
 
+- [升级的连续性：打包修订不在使用路径上替换载荷、替换失败不拆掉可用状态、home 中的悬空记录自愈、真实的升级 lane](2026-10-17-upgrade-continuity-design.md) — active
 - [mcpp 对 xlings 的依赖：Provider 端口、归属与位置、上游复用、系统级安装、payload 不可变、文件系统能力与长路径（#809）](2026-10-16-xlings-provider-port-and-shared-store-design.md) — active
 - [构建依赖的一条管线：配置与产物两轴、包的实例、库接口、兼容系统与工作空间收尾（#797）](2026-10-11-build-dependencies-one-pipeline-design.md) — active
 - [一处来源，一种含义：工作空间的传递语义、生成输出、模块角色与首次运行（#786、#785、#778、#790）](2026-10-10-one-source-one-meaning-design.md) — landed
diff --git a/.github/actions/bootstrap-mcpp/action.yml b/.github/actions/bootstrap-mcpp/action.yml
index 6d5efab5..b6366ab5 100644
--- a/.github/actions/bootstrap-mcpp/action.yml
+++ b/.github/actions/bootstrap-mcpp/action.yml
@@ -33,7 +33,7 @@ inputs:
     # `package.name`, so one of the two was simply unreachable — and which one
     # depended on the machine, which is why CI failed on `compat:lua` on
     # Windows and `mcpplibs.capi:lua` on Linux. Never pin below that.
-    default: '2026.10.16.2'
+    default: '2026.10.17.1'
 
 outputs:
   sandbox-key:
diff --git a/.github/actions/setup-macos-llvm/action.yml b/.github/actions/setup-macos-llvm/action.yml
index 807df7ce..e31d3836 100644
--- a/.github/actions/setup-macos-llvm/action.yml
+++ b/.github/actions/setup-macos-llvm/action.yml
@@ -15,7 +15,7 @@ inputs:
     # Floor imposed by the index, not a routine bump — see
     # .github/actions/bootstrap-mcpp/action.yml for why 0.4.69 is required
     # (two packages named `lua` in one repo need openxlings/xlings#381).
-    default: '2026.10.16.2'
+    default: '2026.10.17.1'
   image:
     description: >
       The runner label the job runs on (macos-15, xcode-27). It is part of the
diff --git a/.github/tools/upgrade_lane.sh b/.github/tools/upgrade_lane.sh
new file mode 100644
index 00000000..74f13315
--- /dev/null
+++ b/.github/tools/upgrade_lane.sh
@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# upgrade_lane.sh <variant> <new-mcpp> <new-xlings> -- a home the previous
+# release made keeps working under this commit's mcpp (design 2026-10-17 D9).
+#
+# Every other lane starts from an empty home, so the installed packaging
+# revision always equals the index's and an upgrade is never executed. A user
+# upgraded to 2026.10.16.3 and every `mcpp run` failed from then on; nothing
+# in CI could see it. This lane builds the home with the PREVIOUS RELEASE --
+# the newest published release that is not this commit's version, read from
+# GitHub, so it moves forward with every release -- and then runs this
+# commit's mcpp in it, laid out as a release (bin/mcpp, registry/bin/xlings).
+#
+# variant:
+#   plain     the previous release installs from today's index.
+#   snapshot  the previous release installs from the xim index of 2026-10-07
+#             (xim-pkgindex ebf1fbb): payloads genuinely of older packaging
+#             revisions (llvm revision 0, gcc 16.1.0 before -r1).
+#   orphan    every payload recorded at another revision, and `c++` active at
+#             gcc's version whose registration is gone (a reported home).
+#
+# Asserted, every variant: the first `mcpp new && mcpp run` of the new mcpp
+# succeeds and downloads nothing; a second run likewise; `mcpp self doctor`
+# in the project installs nothing and names the toolchain the build uses.
+# snapshot: `mcpp index update` names the newer packagings, the run after it
+# still downloads nothing, and `mcpp toolchain list` offers the new one.
+# orphan: `mcpp toolchain install` replaces the payload, and the dangling
+# record is reported as repaired instead of refusing the replacement.
+set -uo pipefail
+VARIANT="${1:?variant}"
+NEW_MCPP="${2:?new mcpp binary}"
+NEW_XLINGS="${3:?new xlings binary}"
+SNAPSHOT=ebf1fbb3417ec513b923279044433887b3af8850
+TC=llvm@23.1.3
+
+unset MCPP_VENDORED_XLINGS MCPP MCPP_FRESH MCPP_BOOT XLINGS_HOME XLINGS_PROJECT_DIR XLINGS_ACTIVE_SUBOS
+W="${RUNNER_TEMP:-/tmp}/upgrade-lane"
+rm -rf "$W"; mkdir -p "$W"
+export MCPP_HOME="$W/home"
+REG="$MCPP_HOME/registry"
+PY=$(command -v python3 || command -v python)
+FAILED=0
+fail() { echo "::error::upgrade lane ($VARIANT): $*"; FAILED=1; }
+
+case "$(uname -s)-$(uname -m)" in
+  Linux-x86_64)  PLAT=linux-x86_64;   EXT=tar.gz; EXE= ;;
+  Linux-aarch64) PLAT=linux-aarch64;  EXT=tar.gz; EXE= ;;
+  Darwin-arm64)  PLAT=macosx-arm64;   EXT=tar.gz; EXE= ;;
+  MINGW*|MSYS*)  PLAT=windows-x86_64; EXT=zip;    EXE=.exe ;;
+  *) echo "::error::unknown platform $(uname -a)"; exit 1 ;;
+esac
+IS_LINUX=0; [[ $PLAT == linux-* ]] && IS_LINUX=1
+
+# ── the previous release ───────────────────────────────────────────────
+CURRENT=$(sed -n 's/^version *= *"\([^"]*\)".*/\1/p' mcpp.toml | head -1)
+OLD_VER=$(curl -fsSL ${GH_TOKEN:+-H "Authorization: Bearer $GH_TOKEN"} \
+            "https://api.github.com/repos/mcpp-community/mcpp/releases?per_page=20" \
+          | "$PY" -c '
+import json, sys
+current = sys.argv[1]
+for r in json.load(sys.stdin):
+    v = r["tag_name"].lstrip("v")
+    if not r["draft"] and not r["prerelease"] and v != current:
+        print(v); break
+' "$CURRENT")
+case "$OLD_VER" in ''|*[!0-9.]*) echo "::error::no previous release resolved (got '$OLD_VER')"; exit 1 ;; esac
+echo "previous release: $OLD_VER; this commit: $CURRENT ($PLAT, variant $VARIANT)"
+
+name="mcpp-$OLD_VER-$PLAT.$EXT"
+bash .github/tools/fetch_release.sh \
+  "https://github.com/mcpp-community/mcpp/releases/download/v$OLD_VER/$name" "$W/$name" || exit 1
+mkdir -p "$W/x"
+if [[ $EXT == zip ]]; then
+  "$PY" -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).extractall(sys.argv[2])" "$W/$name" "$W/x"
+else
+  tar xzf "$W/$name" -C "$W/x"
+fi
+mv "$W/x/mcpp-$OLD_VER-$PLAT" "$W/old"
+OLD="$W/old/bin/mcpp$EXE"
+mkdir -p "$W/new/bin" "$W/new/registry/bin"
+cp "$NEW_MCPP" "$W/new/bin/mcpp$EXE"
+cp "$NEW_XLINGS" "$W/new/registry/bin/xlings$EXE"
+chmod +x "$OLD" "$W/old/registry/bin/xlings$EXE" "$W/new/bin/mcpp$EXE" "$W/new/registry/bin/xlings$EXE" 2>/dev/null
+NEW="$W/new/bin/mcpp$EXE"
+"$OLD" --version; "$NEW" --version
+
+# run <label> <dir> <bin> args...: the log is kept; returns the exit code.
+run() {
+  local label=$1 dir=$2 bin=$3; shift 3
+  echo "::group::$label: (cd $dir && mcpp $*)"
+  (cd "$dir" && "$bin" "$@") > "$W/$label.log" 2>&1
+  local rc=$?
+  sed -e 's/\x1b\[[0-9;]*[A-Za-z]//g' "$W/$label.log" | tr '\r' '\n' | grep -v '^\s*Planning ' | tail -60
+  echo "--> rc=$rc"
+  echo "::endgroup::"
+  return $rc
+}
+downloads() { grep -o "Downloading [^ ]*" "$W/$1.log" | sort -u | tr '\n' ' '; }
+new_project() {  # <dir> <bin>
+  (cd "$W" && "$2" new "$1" > /dev/null 2>&1) || mkdir -p "$W/$1"
+  printf '\n[toolchain]\ndefault = "%s"\n' "$TC" >> "$W/$1/mcpp.toml"
+}
+
+# ── the previous release builds the home ───────────────────────────────
+run old-env "$W" "$OLD" self env || fail "the previous release does not start"
+if [ "$VARIANT" = snapshot ]; then
+  git clone -q --filter=blob:none https://github.com/openxlings/xim-pkgindex "$W/xpi" \
+    && git -C "$W/xpi" checkout -q "$SNAPSHOT" || { echo "::error::cannot fetch the snapshot index"; exit 1; }
+  idx="$REG/data/xim-pkgindex"
+  [ -d "$idx" ] || idx=$(find "$MCPP_HOME" -type d -name xim-pkgindex | head -1)
+  find "$idx" -mindepth 1 -maxdepth 1 ! -name .xlings-index-version -exec rm -rf {} +
+  (cd "$W/xpi" && git archive HEAD) | tar x -C "$idx"
+  echo "llvm.lua revisions now: $(grep -o 'revision = [0-9]*' "$idx/pkgs/l/llvm.lua" | sort -u | tr '\n' ' ')"
+fi
+run old-tc "$W" "$OLD" toolchain install "$TC" || fail "the previous release cannot install $TC"
+[ "$VARIANT" = orphan ] && { run old-tc-gcc "$W" "$OLD" toolchain install gcc@16.1.0 || fail "the previous release cannot install gcc"; }
+new_project p-old "$OLD"
+run old-run "$W/p-old" "$OLD" run || fail "the previous release cannot run a new project"
+
+if [ "$VARIANT" = orphan ]; then
+  "$PY" - "$REG" <<'PY' || fail "could not shape the orphan home"
+import glob, json, os, sys
+reg = sys.argv[1]
+for f in glob.glob(os.path.join(reg, "data", "xpkgs", "xim-x-*", "*", ".xpkg-install.json")):
+    d = json.load(open(f)); r = d.get("revision", 0)
+    d["revision"] = 1 if r == 0 else r - 1
+    json.dump(d, open(f, "w"), indent=2)
+wsf = os.path.join(reg, "subos", "default", ".xlings.json")
+wsdoc = json.load(open(wsf)); ws = wsdoc["workspace"]
+dbf = os.path.join(reg, "data", "versions.json")
+src = json.load(open(dbf))["versions"] if os.path.exists(dbf) else json.load(open(os.path.join(reg, ".xlings.json")))["versions"]
+owners = {k: (v.get("bindingGroup") or {}).get("provider") for k, v in src.get("c++", {}).get("versions", {}).items()}
+keys = [k for k, p in owners.items() if p and "gcc" in p]
+if not keys: sys.exit("no gcc-owned c++ registration: %r" % owners)
+key = keys[0]
+entry = ws.get("c++")
+if isinstance(entry, dict): entry["active"] = key
+else: ws["c++"] = key
+json.dump(wsdoc, open(wsf, "w"))
+for path in (dbf, os.path.join(reg, ".xlings.json")):
+    if not os.path.exists(path): continue
+    doc = json.load(open(path)); c = doc.get("versions", {}).get("c++", {})
+    c.get("versions", {}).pop(key, None)
+    for edges in c.get("bindings", {}).values(): edges.pop(key, None)
+    json.dump(doc, open(path, "w"))
+print("c++ active at %s, its registration removed" % key)
+PY
+fi
+
+# ── this commit's mcpp in that home ────────────────────────────────────
+if [ "$VARIANT" = snapshot ]; then
+  run new-run-on-old-index "$W/p-old" "$NEW" run || fail "the old project does not run on the old index"
+  [ -z "$(downloads new-run-on-old-index)" ] || fail "the run on the old index downloaded: $(downloads new-run-on-old-index)"
+  run new-index-update "$W" "$NEW" index update || fail "index update failed"
+  grep -q "newer packagings" "$W/new-index-update.log" \
+    || fail "index update does not name the newer packagings of installed payloads"
+fi
+new_project p-new "$NEW"
+run new-run1 "$W/p-new" "$NEW" run || fail "the first run of the new mcpp failed"
+[ -z "$(downloads new-run1)" ] || fail "the first run downloaded: $(downloads new-run1)"
+# A payload replaced names its package (`Updating llvm@23.1.3  packaging
+# revision 0 → 1`); the vendored xlings update is not one.
+grep -Eq "^\s*(Updating|Reinstalling) [^ ]+@" "$W/new-run1.log" && fail "the first run replaced a payload"
+run new-run2 "$W/p-new" "$NEW" run || fail "the second run failed"
+[ -z "$(downloads new-run2)" ] || fail "the second run downloaded: $(downloads new-run2)"
+run new-run-old-project "$W/p-old" "$NEW" run || fail "the project the previous release made does not run"
+[ -z "$(downloads new-run-old-project)" ] || fail "the old project's run downloaded: $(downloads new-run-old-project)"
+
+run new-doctor "$W/p-new" "$NEW" self doctor
+[ -z "$(downloads new-doctor)" ] || fail "doctor downloaded: $(downloads new-doctor)"
+grep -q "what a build here uses" "$W/new-doctor.log" || fail "doctor does not name the toolchain the build uses"
+
+if [ "$VARIANT" = snapshot ]; then
+  run new-toolchain-list "$W" "$NEW" toolchain list || fail "toolchain list failed"
+  grep -q "packaging revision .* available" "$W/new-toolchain-list.log" \
+    || fail "toolchain list does not offer the newer packaging"
+fi
+if [ "$VARIANT" = orphan ]; then
+  run new-provision "$W" "$NEW" toolchain install "$TC" || fail "toolchain install could not replace the payload"
+  grep -q "installed asset registration missing" "$W/new-provision.log" \
+    && fail "the replacement was refused by the dangling record"
+  grep -qi "deactivated\|dangling" "$W/new-provision.log" \
+    || fail "the repaired record is not reported"
+  run new-run-after-provision "$W/p-new" "$NEW" run || fail "the run after the replacement failed"
+fi
+
+{
+  echo "### upgrade lane: $PLAT / $VARIANT ($OLD_VER → $CURRENT)"
+  echo
+  for l in "$W"/*.log; do
+    b=$(basename "$l" .log)
+    echo "- \`$b\`: downloads [$(downloads "$b")]"
+  done
+} >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+mkdir -p "${GITHUB_WORKSPACE:-.}/upgrade-lane-logs"
+cp "$W"/*.log "${GITHUB_WORKSPACE:-.}/upgrade-lane-logs/" 2>/dev/null || true
+[ "$FAILED" = 0 ] && echo "PASS: upgrade lane ($VARIANT)"
+exit "$FAILED"
diff --git a/.github/workflows/bootstrap-macos.yml b/.github/workflows/bootstrap-macos.yml
index 0953ae26..abd2f95d 100644
--- a/.github/workflows/bootstrap-macos.yml
+++ b/.github/workflows/bootstrap-macos.yml
@@ -17,7 +17,7 @@ jobs:
       # Dormant (workflow_dispatch only), but kept in step with the rest —
       # check_version_pins.sh holds it there. Floor: 0.4.69, below which the
       # index cannot resolve two packages that share a short name.
-      XLINGS_VERSION: '2026.10.16.2'
+      XLINGS_VERSION: '2026.10.17.1'
     steps:
       - uses: actions/checkout@v4
 
diff --git a/.github/workflows/ci-bootstrap.yml b/.github/workflows/ci-bootstrap.yml
index 811a52f4..05cdc654 100644
--- a/.github/workflows/ci-bootstrap.yml
+++ b/.github/workflows/ci-bootstrap.yml
@@ -41,7 +41,7 @@ jobs:
         os: [ubuntu-24.04, macos-15, windows-2025]
     env:
       XLINGS_NON_INTERACTIVE: '1'
-      XLINGS_VERSION: '2026.10.16.2'
+      XLINGS_VERSION: '2026.10.17.1'
     steps:
       - uses: actions/checkout@v4
 
@@ -50,7 +50,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.17.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
           echo "$HOME/.xlings/bin" >> "$GITHUB_PATH"
 
@@ -124,7 +124,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.17.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install the newest release and build the tree with it (mcpp build --strict)
diff --git a/.github/workflows/ci-fresh-install.yml b/.github/workflows/ci-fresh-install.yml
index e27940be..c6decda3 100644
--- a/.github/workflows/ci-fresh-install.yml
+++ b/.github/workflows/ci-fresh-install.yml
@@ -152,7 +152,7 @@ jobs:
         env:
           XLINGS_NON_INTERACTIVE: '1'
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.17.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
@@ -315,7 +315,7 @@ jobs:
 
       - name: Install xlings + mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.17.1
           # Deliberately NOT writing to $GITHUB_PATH here. On container
           # images that declare no PATH in their config (opensuse/
           # tumbleweed), appending a single dir to GITHUB_PATH makes the
@@ -464,7 +464,7 @@ jobs:
           #             (older ones carry minos=15 and refuse to start).
           #   v0.4.51+: in-process sha256 — this image has no sha256sum
           #             binary, so pinned fetches failed before it.
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.17.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
diff --git a/.github/workflows/ci-linux-e2e.yml b/.github/workflows/ci-linux-e2e.yml
index e4cf916a..6add974f 100644
--- a/.github/workflows/ci-linux-e2e.yml
+++ b/.github/workflows/ci-linux-e2e.yml
@@ -414,7 +414,7 @@ jobs:
 
       - name: Bootstrap xlings + released mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.17.1
           export PATH="$HOME/.xlings/subos/current/bin:$PATH"
           xlings update
           xlings install mcpp -y -g
diff --git a/.github/workflows/ci-upgrade.yml b/.github/workflows/ci-upgrade.yml
new file mode 100644
index 00000000..277f4bcd
--- /dev/null
+++ b/.github/workflows/ci-upgrade.yml
@@ -0,0 +1,64 @@
+name: ci-upgrade
+
+# A home the previous release made keeps working under this commit's mcpp
+# (design .agents/docs/2026-10-17-upgrade-continuity-design.md, D9).
+#
+# Every other lane starts from an empty MCPP_HOME, so the packaging revision a
+# payload records always equals the index's, and an upgrade is never executed.
+# 2026.10.16.3 replaced every payload of an older revision inside the user's
+# next `mcpp run`, and on a home with one dangling record failed every run;
+# nothing in CI could see it. Here the PREVIOUS RELEASE (the newest published
+# one that is not this commit's version, read from GitHub at run time, so the
+# lane moves forward with every release) builds the home, and this commit's
+# binary, laid out as a release with the xlings it pins, runs in it.
+# .github/tools/upgrade_lane.sh holds the steps and the assertions.
+#
+# Called by ci.yml after each host's build, with the binary build.yml produced
+# (use-built-mcpp, rule R1 of the 2026-10-02 CI record).
+
+on:
+  workflow_call:
+
+jobs:
+  upgrade:
+    name: upgrade from the previous release (${{ matrix.host }}, ${{ matrix.variant }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { host: linux-x86_64,   runs-on: ubuntu-24.04,     variant: plain }
+          - { host: linux-x86_64,   runs-on: ubuntu-24.04,     variant: snapshot }
+          - { host: linux-x86_64,   runs-on: ubuntu-24.04,     variant: orphan }
+          - { host: linux-aarch64,  runs-on: ubuntu-24.04-arm, variant: plain }
+          - { host: macos-arm64,    runs-on: macos-15,         variant: plain }
+          - { host: windows-x86_64, runs-on: windows-latest,   variant: plain }
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - if: ${{ matrix.host != 'macos-arm64' }}
+        uses: ./.github/actions/bootstrap-mcpp
+      - if: ${{ matrix.host == 'macos-arm64' }}
+        uses: ./.github/actions/setup-macos-llvm
+        with:
+          image: macos-15
+
+      - uses: ./.github/actions/use-built-mcpp
+        with:
+          host: ${{ matrix.host }}
+
+      - name: The previous release's home runs this commit's mcpp without downloading or failing (${{ matrix.variant }})
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          test -x "$MCPP_VENDORED_XLINGS"
+          bash .github/tools/upgrade_lane.sh "${{ matrix.variant }}" "$MCPP_FRESH" "$MCPP_VENDORED_XLINGS"
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: upgrade-lane-${{ matrix.host }}-${{ matrix.variant }}
+          path: upgrade-lane-logs/
+          if-no-files-found: ignore
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3722d4a9..7bd559a3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -240,6 +240,12 @@ jobs:
     needs: [build-linux, build-linux-arm, build-macos, build-windows]
     uses: ./.github/workflows/ci-target-matrix.yml
 
+  # A home the previous release made, run by this commit's mcpp (D9 of the
+  # 2026-10-17 upgrade-continuity design).
+  upgrade:
+    needs: [build-linux, build-linux-arm, build-macos, build-windows]
+    uses: ./.github/workflows/ci-upgrade.yml
+
   # Pull requests and dispatch only, as when it was a workflow of its own.
   openkal:
     needs: [build-linux, build-linux-arm, build-macos, build-windows]
diff --git a/.github/workflows/cross-build-test.yml b/.github/workflows/cross-build-test.yml
index fac33d54..11752564 100644
--- a/.github/workflows/cross-build-test.yml
+++ b/.github/workflows/cross-build-test.yml
@@ -131,7 +131,7 @@ jobs:
           # release assets were uploaded in a broken state (records present,
           # blobs missing → 404 on GET); re-uploaded clean. The stale-INDEX
           # half is handled by the marker-clear below.
-          XLINGS_VERSION: '2026.10.16.2'
+          XLINGS_VERSION: '2026.10.17.1'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
@@ -323,7 +323,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.10.16.2'
+          XLINGS_VERSION: '2026.10.17.1'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a723324d..9e0e7328 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -104,7 +104,7 @@ jobs:
           # Pin xlings to a known-good version. The upstream install
           # script always grabs `latest` (no version override), so we
           # download + self-install manually to avoid broken releases.
-          XLINGS_VERSION: '2026.10.16.2'
+          XLINGS_VERSION: '2026.10.17.1'
         run: |
           # BY VERSION, NOT BY PRESENCE. A restored ~/.xlings holds the
           # xlings of an earlier release, and this binary is the one the
@@ -329,7 +329,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.10.16.2'
+          XLINGS_VERSION: '2026.10.17.1'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
@@ -400,7 +400,7 @@ jobs:
           # below are pinned to the same version as XLINGS_VERSION; they are
           # NOT interpolated from it, so check_version_pins.sh scans for them
           # explicitly (they were absent from the old lock-step comment).
-          XLA="xlings-2026.10.16.2-linux-aarch64.tar.gz"
+          XLA="xlings-2026.10.17.1-linux-aarch64.tar.gz"
           # NOT fetch_release.sh: this asset is OPTIONAL and the `if` is the
           # point — an arch with no prebuilt xlings must fall through quietly,
           # while the helper retries a 404 five times before giving up. The one
@@ -409,9 +409,9 @@ jobs:
           # cover it.
           if curl -fsSL --retry 3 --retry-delay 2 --retry-all-errors \
                --connect-timeout 20 --max-time 600 -o "/tmp/$XLA" \
-               "https://github.com/openxlings/xlings/releases/download/v2026.10.16.2/$XLA"; then
+               "https://github.com/openxlings/xlings/releases/download/v2026.10.17.1/$XLA"; then
             tar -xzf "/tmp/$XLA" -C /tmp
-            XLBIN=$(find /tmp/xlings-2026.10.16.2-linux-aarch64 -path '*/bin/xlings' -type f | head -1)
+            XLBIN=$(find /tmp/xlings-2026.10.17.1-linux-aarch64 -path '*/bin/xlings' -type f | head -1)
             if [ -n "$XLBIN" ]; then
               mkdir -p "$STAGING/$WRAPPER/registry/bin"
               cp "$XLBIN" "$STAGING/$WRAPPER/registry/bin/xlings"
@@ -489,7 +489,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.10.16.2'
+          XLINGS_VERSION: '2026.10.17.1'
         run: |
           # By version, not by presence (see the Linux job).
           have=$("$HOME/.xlings/subos/default/bin/xlings" --version 2>/dev/null | awk '{print $2}')
@@ -676,7 +676,7 @@ jobs:
         shell: bash
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.10.16.2'
+          XLINGS_VERSION: '2026.10.17.1'
         run: |
           # Captured before the `cd` below, in POSIX form: this step never
           # returns to the workspace, and GITHUB_WORKSPACE is a backslash
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4039ae9e..c6025830 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,56 @@
 > Each `## [<version>]` section is that release's notes. Entries are written in English
 > from 2026.9.28.3 on; earlier entries remain as written.
 
+## [2026.10.17.1] - 2026-10-17
+
+### Fixed
+
+- An upgrade no longer replaces installed payloads inside a build. A payload
+  the index has since repackaged under the same version (a raised packaging
+  `revision`) is used while the provider calls it usable; 2026.10.16.x
+  replaced llvm, gcc (101.7 MB) and glibc (36.7 MB) on a user's next
+  `mcpp run`. Only a payload below the version's `floor`, incomplete or
+  missing is installed by a build, and the build says why (`Updating
+  llvm@23.1.3  packaging revision 0 → 1 (revision 0 is below the index's
+  floor 1)`). `mcpp toolchain install <toolchain>` takes the new packaging.
+- A home with a record that points at nothing no longer fails every build.
+  `c++` active at a gcc version whose registration was gone made every
+  replacement of llvm refuse with `sysroot update refused before metadata
+  changed: c++@16.1.0: installed asset registration missing`. The bundled
+  xlings drops such records in every install and mcpp reports it (`Repaired
+  c++@16.1.0 in mcpp's package home had no registration; deactivated`).
+- A failed install is described by its cause. A refusal the provider decided
+  is said once and is neither retried through the command line nor followed by
+  an index refresh; only a package the provider could not find refreshes the
+  index, and the line says so (`could not be installed; the index may predate
+  it`) instead of `not found locally (one-time)`. A replacement that fails
+  keeps the installed payload, and `mcpp toolchain install` names the
+  revision still in use.
+- `mcpp self doctor` changes nothing. It reports the toolchain a build in the
+  current directory resolves (the configured default outside a package) with
+  its payload's packaging revision, says when that build would install first
+  instead of installing, and reports records in mcpp's package home that point
+  at nothing. It used to start the build's installs and report the compiler
+  on PATH as the toolchain.
+
+### Added
+
+- `mcpp index update` lists installed payloads the refreshed index packages
+  anew; `mcpp toolchain list` marks them (`packaging revision 1 available`),
+  in `--format json` as `installedRevision` / `availableRevision`.
+- CI: an upgrade lane (`ci-upgrade.yml`) builds a home with the previous
+  release, read from GitHub at run time, and runs this commit's mcpp in it on
+  Linux x86_64 and aarch64, macOS and Windows, with an old-index and a
+  dangling-record variant on Linux.
+
+### Changed
+
+- Bundle xlings 2026.10.17.1 (openxlings/xlings#678): `payload_status`
+  reports integrity, `usable` and `current` apart (protocol 1.11).
+- A toolchain payload's packaging revision, when above 0, is part of the
+  toolchain's identity in the build fingerprint and the caches. A toolchain
+  with a revision rebuilds its caches once after the upgrade.
+
 ## [2026.10.16.3] - 2026-10-17
 
 ### Fixed
diff --git a/docs/09-commands-by-scenario.md b/docs/09-commands-by-scenario.md
index 9b23e7dd..afef5b65 100644
--- a/docs/09-commands-by-scenario.md
+++ b/docs/09-commands-by-scenario.md
@@ -494,12 +494,20 @@ $ mcpp xpkg parse mcpp.plugins.lua --json
 `mcpp self doctor` checks the toolchain, the `std` module, the registry, cache
 health, the last runtime-closure verdict, and installed GCC payloads for
 fixincludes-frozen headers left over from the build machine that produced
-them, and reports what it found rather than only what failed:
+them, and reports what it found rather than only what failed. It changes
+nothing: the toolchain it reports is the one a build in the current directory
+resolves (the configured default outside a package), with its payload's
+packaging revision; when that build would install or replace a package first,
+doctor says so instead of doing it. It also reports whether mcpp's package home
+holds records that point at nothing (2026.10.17.1+):
 
 ```
 $ mcpp self doctor
     Checking toolchain
-          ok gcc 13.3.0 (x86_64-linux-gnu) at /usr/bin/g++
+          ok llvm 23.1.3 (x86_64-unknown-linux-gnu) at ~/.mcpp/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++ (what a build here uses)
+          ok payload llvm@23.1.3, packaging revision 1 (current)
+    Checking package home
+          ok consistent
     Checking cache health
           ok build cache size = 2.5 GiB
 warning: pre-v1 cache at '/home/speak/.mcpp/bmi' occupies 167.5 MiB and is no longer used — `mcpp cache clean --legacy` reclaims it
diff --git a/docs/20-toolchains.md b/docs/20-toolchains.md
index a7e763f3..77ed724d 100644
--- a/docs/20-toolchains.md
+++ b/docs/20-toolchains.md
@@ -94,6 +94,29 @@ mcpp toolchain install gcc 15               # installs the highest 15.x.y versio
 mcpp toolchain install gcc@16               # the @ form works too
 ```
 
+### A newer packaging of an installed toolchain (2026.10.17.1+)
+
+The index raises a version's packaging `revision` when what it installs changes
+under the same upstream version (a cfg regenerated for a new glibc layout, hard
+links removed for Android). Builds keep using an installed payload while it is
+*usable*; a build does not download a newer packaging of a toolchain it already
+has. `mcpp index update` lists the installed payloads the refreshed index
+packages anew, `mcpp toolchain list` marks them, and installing the toolchain by
+name takes the new packaging:
+
+```text
+$ mcpp toolchain list
+Toolchains:
+  *  llvm 23.1.3             (default)  (packaging revision 1 available: `mcpp toolchain install llvm 23.1.3`)
+$ mcpp toolchain install llvm 23.1.3
+    Updating llvm@23.1.3  packaging revision 0 → 1
+```
+
+When a revision fixes something every installed payload has, the index also
+raises the version's `floor`, and the next build replaces an installed payload
+below it, saying why. A replacement that fails leaves the installed payload in
+place; `mcpp toolchain install` then fails and names the revision still in use.
+
 ## Switching the Default Toolchain
 
 The default is a *pair* — toolchain axis + target axis (target omitted = host):
@@ -923,7 +946,7 @@ reason it cannot.
 | **an Apple SDK** | located through `xcrun`, never installed | Not redistributable. There is nothing to package, and the refusal says so before any payload is resolved. |
 | **the iOS simulator runtime** | `simctl`, through `xim:apple-simulator-tools` | The same. |
 | **an assembler (`nasm`)** | the pinned `xim:nasm` first; the host's only when that route could not serve, and **named in the build report** when it is used | An offline machine that already has a usable assembler can still build. It used to be the other way round -- see below. |
-| **a C++ compiler on PATH (`$CXX`, else `g++`)** | `mcpp doctor` only | That command's job is to report on the host. The build path sets the compiler from a resolved payload at every branch that reaches the probe, and refuses when the payload cannot be resolved rather than falling through to PATH. |
+| **a C++ compiler on PATH (`$CXX`, else `g++`)** | `mcpp self env` only | That command's job is to report on the host. `mcpp self doctor` reports the toolchain a build in the current directory resolves instead (2026.10.17.1). The build path sets the compiler from a resolved payload at every branch that reaches the probe, and refuses when the payload cannot be resolved rather than falling through to PATH. |
 | **a command interpreter (`/bin/sh`, `cmd.exe` on Windows)** | `run_shell_deadline` for `[hooks]`, `run_streaming_bounded` for the xlings CLI, and the detached codegen command | A hook is a line the USER wrote in shell syntax. Shipping a shell would change the language that line is read in, so the thing mcpp depends on here is not a tool it could package -- it is the host's agreement about what that line means. |
 | **the MSVC toolset and the Windows SDK** | `msvc@system`, which a user names; a pinned `msvc@<toolset>` found installed on the machine; or a managed toolset that has no SDK payload beside it | Not redistributable, the same category as the Apple SDK. A managed toolset BINDS its SDK and ignores `WindowsSdkDir` even when set, because a pin the environment can overwrite is not a pin; the fallback to the machine's SDK works, is not reproducible, and carries a note saying so (`SdkChoice::note`, which the caller must surface). |
 
diff --git a/docs/specs/package-identity.md b/docs/specs/package-identity.md
index a03bc754..fc754ae0 100644
--- a/docs/specs/package-identity.md
+++ b/docs/specs/package-identity.md
@@ -5,8 +5,8 @@
 | **规范编号** | SPEC-001 |
 | **标题** | 包身份(`package.namespace` / `package.name`)、`[dependencies]` 选择器与匹配机制 |
 | **状态** | **评审中(Review)** —— 已实现 |
-| **版本** | 1.6 |
-| **最后修改** | 2026-10-16 |
+| **版本** | 1.7 |
+| **最后修改** | 2026-10-17 |
 | **最低实现版本** | 描述符身份:mcpp **0.0.106**;精确 selector:mcpp **2026.8.10.1**(xlings >= 0.4.69) |
 | **作者/维护** | mcpp-community |
 | **相关设计文档** | `.agents/docs/2026-06-20-package-resolution-architecture.md` §4<br>`.agents/docs/2026-06-26-identity-first-resolution-no-filename.md`<br>`.agents/docs/2026-07-25-issue278-descriptor-name-form-canonicalization-design.md`<br>`.agents/docs/2026-07-25-name-namespace-bidirectional-verification-report.md`<br>`.agents/docs/2026-07-25-name-namespace-canonical-implementation-spec.md` |
@@ -503,11 +503,26 @@ lua = "0.0.3"
 V2 规范。版本回答「装的是哪一个上游版本」,修订号回答「装的是该版本的哪一次打包」;修订号
 不进入地址,也不参与 §10.1 的选择。
 
-- xlings 把安装时的修订号写入载荷的安装记录;已安装载荷的修订号低于索引条目时,xlings 重新
-  安装该载荷。
-- mcpp 以依赖的索引条目的修订号判断一个已安装的依赖是否完整;修订号不同的载荷按未安装处理。
-- 修订号大于 0 的运行时载荷进入运行时契约(`revision=<n>`),因此修订号变化使依赖该载荷的
-  产物重新链接;修订号为 0 时契约的文本不变。
+索引条目还可以声明 `floor`(`0 ≤ floor ≤ revision`,缺省 0):该版本仍可使用的最旧打包修订号
+(xim-pkgindex V2 规范,2026.10.17.1+)。一个已安装载荷相对它的索引条目有两个相互独立的事实,由提供者
+回答(xlings 的 `payload_status`,协议 1.11):
+
+- **可用(usable)**:载荷完整,且记录的修订号不低于 `floor`(未记录修订号的载荷可用);
+- **当前(current)**:载荷完整,且记录的修订号等于 `revision`。
+
+mcpp 侧的使用:
+
+- 工具链、运行时与宿主工具的载荷按意图解析(2026.10.17.1+)。构建、运行、测试、打包与诊断等**使用**命令
+  使用一个可用的载荷,**禁止**因它不是当前修订而替换它;不可用的载荷(缺失、不完整、低于 `floor`)在使用前
+  安装或替换。显式的**供给**命令 `mcpp toolchain install` 把可用而非当前的载荷替换为当前修订。这些载荷的
+  构建输入是载荷本身及其安装时解析出的闭包,不读描述符。
+- 库依赖以依赖的索引条目的修订号判断一个已安装的依赖是否完整;修订号不同的载荷按未安装处理。库依赖的
+  描述符在构建时被读取(链接面、flags),载荷必须与之同修订。
+- 构建身份记录实际使用的修订号:修订号大于 0 的运行时载荷进入运行时契约(`revision=<n>`),修订号大于 0 的
+  工具链载荷进入工具链的驱动身份(`payload-revision: <n>`)。修订号变化使依赖该载荷的产物重新构建;修订号为
+  0 时两者的文本不变。
+- 替换失败时提供者保留原载荷。只有供给命令会替换一个仍可用的载荷,它失败时报错,并说明仍在使用的修订号;
+  使用命令只替换不可用的载荷,失败时没有可退回的载荷,报错。
 
 ### 10.3 载荷的身份与位置(2026.10.16.1+)
 
@@ -516,7 +531,8 @@ V2 规范。版本回答「装的是哪一个上游版本」,修订号回答「
    身份不同(含修订号不同)的载荷**禁止**互相代替。
 2. 载荷所在的 store 由服务它的索引决定:mcpp 所服务的索引的载荷在 `<MCPP_HOME>/xpkgs`(项目索引在
    `<project>/.mcpp/xpkgs`),提供者自己的索引的载荷在提供者 home 的 store 中。
-3. 载荷的完整性由提供者回答(安装记录存在、无失败标记、修订号与索引条目一致、有内容)。mcpp **禁止**写入载荷,
+3. 载荷的完整性由提供者回答(安装记录存在、无失败标记、有内容);可用与当前的判定见 §10.2,同样由提供者回答。
+   修订号与索引条目不一致不使载荷不完整(1.6 把它算入完整性,1.7 起移出)。mcpp **禁止**写入载荷,
    包括标记文件;一个载荷的路径按提供者的回答使用,**禁止**被规范化(链接条目的路径即其身份)。
 
 ---
@@ -526,6 +542,7 @@ V2 规范。版本回答「装的是哪一个上游版本」,修订号回答「
 | 版本 | 日期 | 变更 |
 |---|---|---|
 | 1.5 | 2026-09-27 | 新增 §10.1:版本位的回答与 xlings 一致(安装记录优先,其次按 xlings 版本文法选择;已记录而缺失的载荷不算已安装),mcpp#712、#716;新增 §10.2:打包修订 `revision` 的含义与 mcpp 侧的三处使用(mcpp 2026.9.27.1,xlings 2026.9.27.1) |
+| 1.7 | 2026-10-17 | §10.2:新增 `floor`,区分可用与当前;工具链、运行时与宿主工具按使用/供给两种意图解析,使用命令不因修订号替换可用载荷;工具链载荷的修订号进入驱动身份;替换失败的语义。§10.3 第 3 条把修订号一致移出完整性(mcpp 2026.10.17.1,xlings 2026.10.17.1,libxpkg 0.0.65) |
 | 1.6 | 2026-10-16 | 新增 §10.3:载荷的身份含修订号,身份相同的载荷可以经链接条目在 home 之间共用;载荷所在的 store 由服务它的索引决定;完整性由提供者回答,mcpp 不写入载荷(mcpp 2026.10.16.1,xlings 2026.10.16.1) |
 | 1.4 | 2026-09-14 | 新增 §5.4:`path` 与 `git` 依赖的身份取自其清单,键规范化到另一身份时采用清单声明并告警,同一来源上的两个身份在扫描前拒绝(mcpp 2026.9.14.2) |
 | 1.3 | 2026-09-07 | 新增 §10:同一条身份规则扩展到 xlings 工具地址(mcpp 2026.9.6.6)。此前工具侧有两套定义,同一个包被两处以不同版本声明时两份都装、只用一份 |
diff --git a/docs/specs/toolchain-management.md b/docs/specs/toolchain-management.md
index e2c23fca..5231cbcc 100644
--- a/docs/specs/toolchain-management.md
+++ b/docs/specs/toolchain-management.md
@@ -4,8 +4,8 @@
 |---|---|
 | 规范编号 | SPEC-006 |
 | 标题 | 工具链管理:身份、来源、选择与载荷契约 |
-| 状态 | 草案 v0.8 |
-| 最后修改 | 2026-10-16 |
+| 状态 | 草案 v0.9 |
+| 最后修改 | 2026-10-17 |
 | 对应实现 | 逐条标注;标为「已实现」的条款对应 mcpp >= 2026.9.24.1。标为「未实现」的条款计划与下一批 LLVM 工具链一同落地,届时按实测修订本规范 |
 | 相关设计文档 | `.agents/docs/2026-09-24-toolchain-selection-and-payload-trust-design.md`、`.agents/docs/2026-09-24-685-687-msvc-stl-and-toolchain-payloads.md`、`.agents/docs/2026-09-28-ecosystem-design-and-optimisation-plan.md`、`.agents/docs/2026-10-02-pr-ci-acceleration-and-the-toolchain-specification-design.md` |
 | 相关 issue | mcpp#685、mcpp#687、mcpp#718、mcpp#755 |
@@ -257,6 +257,14 @@ gcc 载荷的 `lib/gcc/<三元组>/<版本>/include-fixed/` **禁止**含带 fix
 
 一个版本在索引中的内容由 sha256 固定。内容有任何变化,**必须**使用新的资产名,因为 GitCode 上的发布资产既不能替换,也不能删除。
 
+### 4.7 已安装的修订 已实现
+
+内容变化时版本项提高 `revision`;修订修复的是每个已装载荷都有的缺陷时,同时把 `floor` 提到该修订
+([SPEC-001](package-identity.md) §10.2)。构建、运行与诊断**禁止**替换一个可用的工具链载荷(完整,且修订号
+不低于 `floor`);`mcpp toolchain install <spec>` 把已安装而非当前修订的载荷替换为当前修订,替换失败时原载荷
+保留并报告。`mcpp toolchain list` 对非当前修订的载荷注明可用的新修订,`mcpp index update` 在刷新后列出它们。
+构建的工具链身份记录载荷实际的修订号(大于 0 时)。(mcpp 2026.10.17.1)
+
 ---
 
 ## 5. 构建
@@ -307,6 +315,11 @@ xim-pkgindex 的准入脚本 `verify-toolchain.sh` 对一个载荷归档做一
 
 `mcpp self doctor` **必须**对已安装的载荷执行 §6.1 中不依赖归档的检查;发现问题时,**必须**给出重装命令。
 
+`mcpp self doctor` **禁止**安装或替换载荷。它报告的工具链是当前上下文中构建实际使用的工具链(在包内为该包的
+解析结果,包外为配置的默认工具链),附其载荷的修订状态;PATH 上的编译器不作为工具链报告。构建需要先安装时,
+doctor 如实报告这一点。它同时报告 mcpp 的包 home 中指向不存在注册的记录数(xlings `system_status` 的
+`binding_state`)。(mcpp 2026.10.17.1)
+
 当前:doctor 执行 §4.2 的检查(gcc 载荷 `include-fixed/` 中带 fixincludes 横幅的文件);§4.1、§4.3、§4.4 的检查未实现。
 
 ---
@@ -330,3 +343,4 @@ xim-pkgindex 的准入脚本 `verify-toolchain.sh` 对一个载荷归档做一
 | v0.6 | 2026-10-02 | §7 移入 SPEC-009(工具链的支持与维护):移动默认版本或 C 库绑定的顺序、门与撤销由 SPEC-009 §10 规定,本节改为引用。 |
 | v0.7 | 2026-10-09 | 随 mcpp 2026.10.8.1:新增 §3.8,使用受管 C 库的构建不隐式搜索宿主的系统头文件;需要时由项目显式写出。 |
 | v0.8 | 2026-10-16 | 随 mcpp 2026.10.16.1:§4.3 改为「安装后不改写」,载荷只由提供者写入;工具链运行在提供者按 home 的运行库钉版本绑定的运行库上。 |
+| v0.9 | 2026-10-17 | 随 mcpp 2026.10.17.1:新增 §4.7,已安装的修订在构建中继续使用,`floor` 决定是否必须替换,`toolchain install` 取当前修订;§6.4 doctor 只读,报告构建实际使用的工具链与包 home 的一致性。 |
diff --git a/docs/zh/09-commands-by-scenario.md b/docs/zh/09-commands-by-scenario.md
index c66437ce..6aa3a2f1 100644
--- a/docs/zh/09-commands-by-scenario.md
+++ b/docs/zh/09-commands-by-scenario.md
@@ -393,12 +393,17 @@ $ mcpp xpkg parse mcpp.plugins.lua --json
 
 `mcpp self doctor` 检查工具链、`std` 模块、registry、缓存健康、最近一次
 运行期闭包判定，以及已安装的 GCC 载荷里是否留有构建它的那台机器自己的
-fixincludes 冻结头文件，并报告它查到了什么，而不只报告失败的部分：
+fixincludes 冻结头文件，并报告它查到了什么，而不只报告失败的部分。它不改变任何东西：报告的工具链是当前目录下
+构建解析出的工具链（包外为配置的默认工具链），附其载荷的打包修订号；构建需要先安装或替换某个包时，doctor 报告
+这一点而不去执行。它还报告 mcpp 的包 home 中是否有指向不存在注册的记录（2026.10.17.1+）：
 
 ```
 $ mcpp self doctor
     Checking toolchain
-          ok gcc 13.3.0 (x86_64-linux-gnu) at /usr/bin/g++
+          ok llvm 23.1.3 (x86_64-unknown-linux-gnu) at ~/.mcpp/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++ (what a build here uses)
+          ok payload llvm@23.1.3, packaging revision 1 (current)
+    Checking package home
+          ok consistent
     Checking cache health
           ok build cache size = 2.5 GiB
 warning: pre-v1 cache at '/home/speak/.mcpp/bmi' occupies 167.5 MiB and is no longer used — `mcpp cache clean --legacy` reclaims it
diff --git a/docs/zh/20-toolchains.md b/docs/zh/20-toolchains.md
index 9614b113..cf04bd87 100644
--- a/docs/zh/20-toolchains.md
+++ b/docs/zh/20-toolchains.md
@@ -89,6 +89,23 @@ mcpp toolchain install gcc 15               # installs the highest 15.x.y versio
 mcpp toolchain install gcc@16               # the @ form works too
 ```
 
+### 已安装工具链的新打包（2026.10.17.1+）
+
+上游版本不变、安装的内容变化时（为新的 glibc 布局重新生成 cfg、为 Android 去掉硬链接），索引提高该版本的打包
+`revision`。已安装的载荷只要*可用*，构建就继续使用它；构建不会为一个已有的工具链下载新打包。`mcpp index update`
+列出刷新后的索引重新打包了的已装载荷，`mcpp toolchain list` 标出它们，按名字安装该工具链即取得新打包：
+
+```text
+$ mcpp toolchain list
+Toolchains:
+  *  llvm 23.1.3             (default)  (packaging revision 1 available: `mcpp toolchain install llvm 23.1.3`)
+$ mcpp toolchain install llvm 23.1.3
+    Updating llvm@23.1.3  packaging revision 0 → 1
+```
+
+修订修复的是每个已装载荷都有的缺陷时，索引同时提高该版本的 `floor`，低于它的已装载荷在下一次构建时被替换，
+并说明原因。替换失败时已装载荷保留；`mcpp toolchain install` 此时报错，并说明仍在使用的修订号。
+
 ## 切换默认工具链
 
 默认值是一*对*——toolchain 轴 + target 轴（省略 target 即宿主）：
@@ -842,7 +859,7 @@ mcpp build --managed-only          # 或 MCPP_MANAGED_ONLY=1
 | **一个 Apple SDK** | 经 `xcrun` 定位，从不安装 | 不可再分发。没有东西可以打包，而拒绝会在解析任何载荷之前就点名它。 |
 | **iOS 模拟器运行时** | `simctl`，经由 `xim:apple-simulator-tools` | 同上。 |
 | **一个汇编器（`nasm`）** | 先取被钉住的 `xim:nasm`；只有那条路服务不了时才取宿主的，且**在构建报告里点名**用到的是哪一个 | 一台离线、但本来就装了可用汇编器的机器仍然能构建。它此前是反过来的——见下文。 |
-| **PATH 上的 C++ 编译器（`$CXX`，否则 `g++`）** | 只有 `mcpp doctor` | 那个命令的职责就是报告宿主的状况。构建这条路上，在每一个到得了这个探针的分支上都从解析出的载荷设定编译器，载荷解析不了时**拒绝**，而不是落到 PATH。 |
+| **PATH 上的 C++ 编译器（`$CXX`，否则 `g++`）** | 只有 `mcpp self env` | 那个命令的职责就是报告宿主的状况。`mcpp self doctor` 报告的是当前目录下构建解析出的工具链（2026.10.17.1）。构建这条路上，在每一个到得了这个探针的分支上都从解析出的载荷设定编译器，载荷解析不了时**拒绝**，而不是落到 PATH。 |
 | **一个命令解释器（`/bin/sh`，Windows 上是 `cmd.exe`）** | `[hooks]` 走 `run_shell_deadline`，xlings CLI 走 `run_streaming_bounded`，还有一个分离式的代码生成命令 | 一条 hook 是**用户自己**用 shell 语法写下的那一行。自带一个 shell 会改变那一行被解读所用的语言，所以这里依赖的不是一个能打包的工具，而是宿主对那一行含义的约定。 |
 | **MSVC 工具集与 Windows SDK** | 用户点名的 `msvc@system`；在机器上找到的 pin 版本 `msvc@<toolset>`；或者一个受管工具集旁边没有 SDK 载荷时 | 不可再分发，与 Apple SDK 同一类。受管工具集**绑定**自己的 SDK，即使 `WindowsSdkDir` 被设置也不理会——一个环境能覆盖的 pin 就不是 pin；回落到机器自己那份能用，但不可复现，因此会带一句说明（`SdkChoice::note`，调用方必须把它呈现出来）。 |
 
diff --git a/mcpp.toml b/mcpp.toml
index ca3ab795..2622ec47 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version = "2026.10.16.3"
+version = "2026.10.17.1"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]
diff --git a/modules/versioning/src/version.cppm b/modules/versioning/src/version.cppm
index eb85b4eb..79590a6f 100644
--- a/modules/versioning/src/version.cppm
+++ b/modules/versioning/src/version.cppm
@@ -31,6 +31,6 @@ import std;
 
 export namespace mcpp {
 
-inline constexpr std::string_view MCPP_VERSION = "2026.10.16.3";
+inline constexpr std::string_view MCPP_VERSION = "2026.10.17.1";
 
 } // namespace mcpp
diff --git a/src/build/prepare/plan.cpp b/src/build/prepare/plan.cpp
index 1fa6eee7..474ff3f8 100644
--- a/src/build/prepare/plan.cpp
+++ b/src/build/prepare/plan.cpp
@@ -1356,7 +1356,7 @@ static std::expected<void, std::string> step13_assembly_units(PrepareState& stat
                 auto nasmTarget = std::format("xim:nasm@{}",
                     mcpp::provider::kNasmVersion);
                 auto payload = nasmFetcher.resolve_xpkg_path(
-                    nasmTarget, /*autoInstall=*/true, &nasmProgress);
+                    nasmTarget, mcpp::fetcher::PayloadIntent::Use, &nasmProgress);
                 if (!payload) {
                     return std::unexpected(std::format(
                         "NASM sources (.asm) present but nasm provisioning "
diff --git a/src/build/prepare/toolchain.cpp b/src/build/prepare/toolchain.cpp
index ee4e20bc..d817caad 100644
--- a/src/build/prepare/toolchain.cpp
+++ b/src/build/prepare/toolchain.cpp
@@ -1376,7 +1376,9 @@ step2_resolve_explicit_spec(PrepareState& state, ToolchainResolveCtx& ctx) {
 
         mcpp::ui::info("Resolving", "toolchain");
         mcpp::fetcher::InstallProgressHandler progress;
-        auto payload = fetcher.resolve_xpkg_path(pkg.target(), /*autoInstall=*/!engineChoseUnservable, &progress);
+        auto payload = fetcher.resolve_xpkg_path(pkg.target(),
+            engineChoseUnservable ? mcpp::fetcher::PayloadIntent::Locate : mcpp::fetcher::PayloadIntent::Use,
+            &progress);
         if (!payload && !state.unservedTargetDiagnosis.empty() && !spec->target.empty()) {
             // The held diagnosis is already the right words for this; releasing
             // it here rather than at its usual site keeps one sentence per cause.
@@ -1633,7 +1635,7 @@ step2_first_run_auto_install(PrepareState& state) {
 
         mcpp::fetcher::InstallProgressHandler progress;
         auto payload = fetcher.resolve_xpkg_path(defaultPkg.target(),
-                            /*autoInstall=*/true, &progress);
+                            mcpp::fetcher::PayloadIntent::Use, &progress);
         if (!payload) {
             return std::unexpected(std::format(
                 "auto-installing default toolchain {} failed: {}\n"
@@ -2045,7 +2047,7 @@ step2_retarget_for_retargetable_driver(PrepareState& state) {
                       //
                       // The row names two things and only one of them used to
                       // be made to exist: `pin` went through
-                      // `resolve_xpkg_path(…, autoInstall=true, …)` while
+                      // `resolve_xpkg_path(…, PayloadIntent::Use, …)` while
                       // `sysroot` was a pure lookup that returned nullopt and
                       // let the whole block below be skipped without a word.
                       //
@@ -2070,7 +2072,7 @@ step2_retarget_for_retargetable_driver(PrepareState& state) {
                       mcpp::fetcher::InstallProgressHandler srProgress;
                       std::optional<std::filesystem::path> dir;
                       if (auto p = srFetcher.resolve_xpkg_path(
-                              want_sysroot, /*autoInstall=*/true, &srProgress))
+                              want_sysroot, mcpp::fetcher::PayloadIntent::Use, &srProgress))
                           dir = p->root;
                       else
                           dir = mcpp::provider::payload(*mcpp::provider::open(xl), ref);
@@ -2208,7 +2210,7 @@ step2_msvc_abi_without_msvc_repair(PrepareState& state) {
           mcpp::fetcher::Fetcher fetcherR(**cfgR);
           mcpp::fetcher::InstallProgressHandler progressR;
           auto payloadR = fetcherR.resolve_xpkg_path(gnuPkg.target(),
-                              /*autoInstall=*/true, &progressR);
+                              mcpp::fetcher::PayloadIntent::Use, &progressR);
           if (!payloadR) {
               return std::unexpected(std::format(
                   "switching to the MinGW-w64 toolchain ({}) failed: {}\n"
diff --git a/src/build/prepare/toolchain_env.cpp b/src/build/prepare/toolchain_env.cpp
index 8e95f140..870a557d 100644
--- a/src/build/prepare/toolchain_env.cpp
+++ b/src/build/prepare/toolchain_env.cpp
@@ -148,7 +148,7 @@ bind_msvc_sysroot(mcpp::toolchain::Toolchain& tc,
         auto pkg = mcpp::toolchain::to_xim_package(pkgSpec);
         mcpp::fetcher::Fetcher fetcher(**cfg);
         mcpp::fetcher::InstallProgressHandler progress;
-        auto payload = fetcher.resolve_xpkg_path(pkg.target(), /*autoInstall=*/true,
+        auto payload = fetcher.resolve_xpkg_path(pkg.target(), mcpp::fetcher::PayloadIntent::Use,
                                                  &progress);
         if (!payload) {
             // `xim:` never looked at the machine, so the refusal does not
diff --git a/src/build/prepare/xlings.cpp b/src/build/prepare/xlings.cpp
index a0c5d61e..8e0b66ac 100644
--- a/src/build/prepare/xlings.cpp
+++ b/src/build/prepare/xlings.cpp
@@ -242,7 +242,7 @@ step3_define_host_tc_closures_and_refresh_index(PrepareState& state) {
         if (!cfgH) return std::unexpected(cfgH.error());
         mcpp::fetcher::Fetcher fetcher(**cfgH);
         mcpp::fetcher::InstallProgressHandler progress;
-        auto payload = fetcher.resolve_xpkg_path(pkg.target(), /*autoInstall=*/true, &progress);
+        auto payload = fetcher.resolve_xpkg_path(pkg.target(), mcpp::fetcher::PayloadIntent::Use, &progress);
         if (!payload) {
             return std::unexpected(std::format(
                 "host toolchain for build.mcpp ('{}'): {}", hostSpecText,
diff --git a/src/doctor.cppm b/src/doctor.cppm
index eee99703..39be4c4a 100644
--- a/src/doctor.cppm
+++ b/src/doctor.cppm
@@ -192,13 +192,145 @@ export int doctor_report() {
     auto warn = [&](std::string_view m) { mcpp::ui::warning(m); ++warns; };
     auto err   = [&](std::string_view m) { mcpp::ui::error(m);   ++errors; };
 
+    auto cfg = mcpp::config::load_or_init(/*quiet=*/false, mcpp::fetcher::make_bootstrap_progress_callback());
+
+    // ONE PREPARE, READ-ONLY, AND THE SECTIONS BELOW REPORT ON IT (design
+    // 2026-10-17 D7).
+    //
+    // doctor ran a full `prepare_build` for its runtime-capabilities line and
+    // reported the PATH compiler as "the toolchain". On a user's home whose
+    // llvm replacement failed on every build, doctor started the same
+    // replacement (22-45 s), called its failure "run inside a package" while
+    // the user was in one, and printed `ok` for `~/.xlings/.../g++`, a
+    // compiler no build there used. A diagnosis that changes what it
+    // diagnoses, and reports something else, is two defects.
+    //
+    // Offline for the call: nothing is downloaded, installed or replaced, so
+    // a build that would install first is reported as exactly that. Planned
+    // to describe, not to build (`plan_only`, as `mcpp emit build-database`
+    // plans): the std module is described rather than compiled, generated
+    // files are compared rather than written, and the lock this planning
+    // produces goes to a scratch directory, not the project.
+    const bool inPackage = mcpp::project::find_manifest_root(std::filesystem::current_path()).has_value();
+    bool prepareWouldInstall = false;
+    auto pctx = [&]() -> decltype(mcpp::build::prepare_build(false)) {
+        if (!inPackage) return std::unexpected(std::string("not inside a package"));
+        mcpp::platform::env::ScopedEnv offline("MCPP_OFFLINE", "1");
+        const bool wasQuiet = mcpp::ui::is_quiet();
+        mcpp::ui::set_quiet(true);
+        (void)mcpp::build::refusal::take();
+        mcpp::build::BuildOverrides ov;
+        ov.plan_only = true;
+        std::error_code tec;
+        ov.work_dir = std::filesystem::temp_directory_path(tec)
+            / std::format("mcpp-doctor-{}", std::chrono::steady_clock::now().time_since_epoch().count());
+        auto r = mcpp::build::prepare_build(/*print_fingerprint=*/false, /*includeDevDeps=*/false, {}, ov);
+        std::filesystem::remove_all(ov.work_dir, tec);
+        prepareWouldInstall = !r && mcpp::build::refusal::take()
+            == mcpp::build::refusal::Code::OfflineDownloadRequired;
+        mcpp::ui::set_quiet(wasQuiet);
+        return r;
+    }();
+    const auto first_line = [](std::string_view text) {
+        return std::string(text.substr(0, text.find('\n')));
+    };
+
+    // What the provider says of the payload a compiler is in: its packaging
+    // against the index (D1/D6). Nothing for a compiler outside mcpp's store.
+    const auto report_payload = [&](const std::filesystem::path& compiler) {
+        if (!cfg) return;
+        const auto entry = mcpp::provider::layout().entry_of(compiler);
+        if (entry.dir.empty()) return;
+        const std::array<mcpp::provider::PackageRef, 1> refs{{{entry.ns, entry.name, entry.version}}};
+        const auto st = mcpp::provider::open(mcpp::config::make_xlings_env(*cfg))->status(refs);
+        if (st.size() != 1 || !st[0].error.empty()) return;
+        const auto& s0 = st[0];
+        if (!s0.complete)
+            err(std::format("payload {}@{} is incomplete; the next build reinstalls it", s0.name, s0.version));
+        else if (s0.current)
+            ok(std::format("payload {}@{}, packaging revision {} (current)", s0.name, s0.version,
+                           s0.installedRevision < 0 ? 0 : s0.installedRevision));
+        else if (s0.usable)
+            ok(std::format("payload {}  (builds keep it; `mcpp toolchain install` takes the new one)",
+                           mcpp::provider::describe_currency(s0)));
+        else
+            warn(std::format("payload {}", mcpp::provider::describe_currency(s0)));
+    };
+
     mcpp::ui::status("Checking", "toolchain");
-    auto tc = mcpp::toolchain::detect();
-    if (!tc) {
-        err(std::format("toolchain detection failed: {}", tc.error().message));
-    } else {
-        ok(std::format("{} at {}", tc->label(), tc->binaryPath.string()));
+    std::optional<mcpp::toolchain::Toolchain> tc;
+    if (pctx) {
+        tc = pctx->tc;
+        ok(std::format("{} at {} (what a build here uses)", tc->label(), tc->binaryPath.string()));
+        report_payload(tc->binaryPath);
+    } else if (inPackage) {
+        if (prepareWouldInstall)
+            warn(std::format("a build here installs or replaces packages first: {}",
+                             first_line(pctx.error())));
+        else
+            err(std::format("a build here fails before it compiles: {}", first_line(pctx.error())));
+    } else if (cfg) {
+        // Outside a package: the configured default, as `mcpp new && mcpp
+        // build` would resolve it.
+        const auto spec = cfg->defaultToolchain;
+        auto parsed = mcpp::toolchain::parse_toolchain_spec(spec);
+        if (spec.empty()) {
+            ok("no default toolchain configured (the first build installs one)");
+        } else if (!parsed) {
+            err(std::format("the configured default toolchain '{}' does not parse", spec));
+        } else {
+            auto pkg = mcpp::toolchain::to_xim_package(*parsed);
+            auto dir = mcpp::provider::open(mcpp::config::make_xlings_env(*cfg))->pinned(pkg.ximName, pkg.ximVersion);
+            auto frontend = mcpp::toolchain::payload_frontend(dir, pkg);
+            std::error_code fec;
+            if (frontend && !frontend->empty() && std::filesystem::exists(*frontend, fec)) {
+                if (auto detected = mcpp::toolchain::detect(*frontend)) {
+                    tc = *detected;
+                    ok(std::format("{} at {} (the configured default)", tc->label(), tc->binaryPath.string()));
+                } else {
+                    err(std::format("the configured default {} does not run: {}", spec,
+                                    detected.error().message));
+                }
+                report_payload(*frontend);
+            } else {
+                warn(std::format("the configured default {} is not installed (the first build installs it)", spec));
+            }
+        }
+    }
 
+    // mcpp's package home, as the provider reads it (X3): records that point
+    // at nothing are dropped by the next install; the rest needs the
+    // provider's own repair, run in that home.
+    if (cfg) {
+        mcpp::ui::status("Checking", "package home");
+        auto provider = mcpp::provider::open(mcpp::config::make_xlings_env(*cfg));
+        std::size_t broken = 0, notices = 0;
+        std::string example;
+        bool answered = false;
+        if (auto r = provider->call("system_status", "{}"); r && r->exitCode == 0) {
+            for (const auto& d : r->dataEvents) {
+                if (d.dataKind != "binding_state") continue;
+                auto j = nlohmann::json::parse(d.payloadJson, nullptr, false);
+                if (!j.is_object() || !j.contains("findings") || !j["findings"].is_array()) continue;
+                answered = true;
+                for (const auto& f : j["findings"]) {
+                    const bool isBroken = f.value("severity", std::string{}) == "broken";
+                    (isBroken ? broken : notices) += 1;
+                    if (isBroken && example.empty())
+                        example = std::format("{}@{}: {}", f.value("target", std::string{}),
+                                              f.value("version", std::string{}), f.value("summary", std::string{}));
+                }
+            }
+        }
+        if (!answered)
+            ok("(the provider reports no binding state)");
+        else if (broken == 0)
+            ok(notices == 0 ? std::string("consistent")
+                            : std::format("consistent ({} notice(s))", notices));
+        else
+            warn(std::format("{} record(s) in mcpp's package home point at nothing (first: {})\n"
+                             "  hint: `{} self doctor --fix` repairs them",
+                             broken, example, provider->command_prefix()));
     }
 
     // Windows: report the system MSVC (msvc@system). Absence is a warning,
@@ -336,7 +468,6 @@ export int doctor_report() {
     }
 
     mcpp::ui::status("Checking", "registry");
-    auto cfg = mcpp::config::load_or_init(/*quiet=*/false, mcpp::fetcher::make_bootstrap_progress_callback());
 
     // Whose sysroot is this? gcc bakes `--sysroot=<...>/subos/default`
     // at build time, and that path is a string, not a reference -- it
@@ -494,9 +625,10 @@ export int doctor_report() {
         // dependency graph's provider packages (e.g. compat.glx-runtime); the
         // search dirs are the resolved runtime library_dirs. The same code path
         // works on every platform — providers carry the platform knowledge.
-        auto pctx = mcpp::build::prepare_build(/*print_fingerprint=*/false);
-        if (!pctx) {
+        if (!inPackage) {
             ok("(run inside a package to check its runtime capabilities)");
+        } else if (!pctx) {
+            ok("(not checked: the toolchain above is not ready)");
         } else if (pctx->plan.runtimeCapabilities.empty()) {
             ok("no host runtime capabilities required");
         } else {
diff --git a/src/fetcher.cppm b/src/fetcher.cppm
index 3fb55a88..38680315 100644
--- a/src/fetcher.cppm
+++ b/src/fetcher.cppm
@@ -31,5 +31,6 @@ using EventHandler  = mcpp::pm::EventHandler;
 using CallError     = mcpp::pm::CallError;
 using CallResult    = mcpp::pm::CallResult;
 using Fetcher       = mcpp::pm::Fetcher;
+using PayloadIntent = mcpp::pm::PayloadIntent;
 
 } // namespace mcpp::fetcher
diff --git a/src/fetcher/progress.cppm b/src/fetcher/progress.cppm
index aa8e3790..f21574e3 100644
--- a/src/fetcher/progress.cppm
+++ b/src/fetcher/progress.cppm
@@ -12,6 +12,7 @@ export module mcpp.fetcher.progress;
 import std;
 import mcpp.config;
 import mcpp.fetcher;
+import mcpp.libs.json;
 import mcpp.log;
 import mcpp.ui;
 
@@ -251,6 +252,20 @@ export struct InstallProgressHandler : mcpp::fetcher::EventHandler {
     }
 
     void on_data(const mcpp::fetcher::DataEvent& d) override {
+        // What the provider repaired in the home it keeps for mcpp while it
+        // installed (xlings protocol 1.11, design 2026-10-17 X2): a record
+        // that pointed at nothing, dropped so it no longer refuses an install.
+        // Said, because it changed the home, and it is not the package asked.
+        if (d.dataKind == "scope_repaired") {
+            auto j = nlohmann::json::parse(d.payloadJson, nullptr, false);
+            if (j.is_object() && j.contains("repairs") && j["repairs"].is_array())
+                for (const auto& r : j["repairs"])
+                    mcpp::ui::status("Repaired", std::format(
+                        "{}@{} in mcpp's package home had no registration; {}",
+                        r.value("target", std::string{}), r.value("version", std::string{}),
+                        r.value("action", std::string{}) == "deactivated" ? "deactivated" : "dropped"));
+            return;
+        }
         if (d.dataKind != "download_progress") return;
         auto files = parse_all_install_files(d.payloadJson);
         if (files.empty()) return;
diff --git a/src/pm/index_management.cppm b/src/pm/index_management.cppm
index 47d14b76..788823aa 100644
--- a/src/pm/index_management.cppm
+++ b/src/pm/index_management.cppm
@@ -143,6 +143,17 @@ export int index_remove(const std::string& name) {
     return 0;
 }
 
+// What the refreshed index packages anew of what is installed (design
+// 2026-10-17 D6): said here, where the index changed, and not by the next
+// build, which keeps every usable payload.
+export void report_newer_packagings(const mcpp::provider::Provider& p) {
+    const auto stale = mcpp::provider::not_current(p);
+    if (stale.empty()) return;
+    mcpp::ui::status("Note", "the index has newer packagings of installed payloads:");
+    for (const auto& st : stale) mcpp::ui::line(std::format("           {}", mcpp::provider::describe_currency(st)));
+    mcpp::ui::line("           builds keep the installed ones; `mcpp toolchain install <toolchain>` takes the new one");
+}
+
 // `mcpp index update [name]` — empty filterName updates everything.
 //
 // NOTE on `name`: it only filters the PROJECT-level custom indices below. The
@@ -173,6 +184,7 @@ export int index_update(const std::string& filterName) {
     auto xlEnv = mcpp::config::make_xlings_env(*cfg);
     int rc = mcpp::provider::open(xlEnv)->update_index();
     if (rc != 0) { mcpp::ui::error("index update failed"); return 1; }
+    report_newer_packagings(*mcpp::provider::open(xlEnv));
 
     // Also update project-level custom indices if present.
     auto root = mcpp::project::find_manifest_root(std::filesystem::current_path());
diff --git a/src/pm/package_fetcher.cppm b/src/pm/package_fetcher.cppm
index 1f727f8d..2c3b12df 100644
--- a/src/pm/package_fetcher.cppm
+++ b/src/pm/package_fetcher.cppm
@@ -53,6 +53,43 @@ struct CallError {
 
 using CallResult = mcpp::provider::CallResult;
 
+// What a caller wants of one payload (design 2026-10-17 D3).
+//
+// A packaging revision the index raised is a newer packaging, not a broken
+// payload: a command that only USES a package keeps an installed payload while
+// the provider calls it usable, and only an explicit request for the package
+// (`mcpp toolchain install`) brings the index's current packaging. 2026.10.16.x
+// replaced every payload whose revision was not the index's inside the build
+// that read it -- a 101.7 MB gcc and a 36.7 MB glibc on a user's next
+// `mcpp run`, and, on a home with one dangling record, a failure on every run.
+enum class PayloadIntent {
+    Locate,     // the installed payload when it is usable; never installs
+    Use,        // a usable payload; installs or replaces only one that is not
+    Provision,  // the index's current packaging; also replaces a usable payload that is not current
+};
+
+// What to do about one payload, from what the provider says of it. Pure: the
+// unit tests pin the whole matrix.
+enum class PayloadAction {
+    Take,       // use the payload that is there
+    Install,    // nothing is there: install it
+    Replace,    // something is there and will not do: replace it
+    Refuse,     // Locate, and nothing usable is there
+};
+PayloadAction payload_action(PayloadIntent intent, bool present, bool usable, bool current);
+
+// What a failed install calls for, by the provider's error code (D5). A
+// deterministic refusal (`E_INTERNAL`: a hook or a metadata transaction that
+// refused; `E_PERMISSION`, `E_DISK_FULL`, `E_CANCELLED`) is said once and not
+// retried, and no index refresh can help it; only a package the provider could
+// not find refreshes the index first. No code at all (a provider that said
+// nothing, #238) keeps the old conservative path.
+struct InstallFailurePolicy {
+    bool refreshIndex = false;   // the index may predate this version
+    bool retry = false;          // a second attempt can succeed
+};
+InstallFailurePolicy install_failure_policy(std::string_view errorCode);
+
 class Fetcher {
 public:
     explicit Fetcher(const config::GlobalConfig& cfg) : cfg_(cfg) {}
@@ -205,15 +242,15 @@ public:
     };
 
     // Resolve a target like "xim:gcc@15.1.0" or "name@1.0" to its xpkg
-    // payload location. Auto-installs via xlings if missing and
-    // autoInstall is true.
+    // payload location, installing through the provider as `intent` allows
+    // (PayloadIntent, design 2026-10-17 D3).
     //
     // Target syntax:
     //   "<index>:<name>@<version>"   explicit index namespace
     //   "<name>@<version>"           uses xim namespace by default
     std::expected<XpkgPayload, CallError>
         resolve_xpkg_path(std::string_view target,
-                          bool autoInstall,
+                          PayloadIntent intent,
                           EventHandler* handler = nullptr);
 
 private:
@@ -1036,6 +1073,11 @@ std::string install_failure_hint(const std::optional<mcpp::provider::ErrorEvent>
     if (code == "E_INVALID_INPUT")
         return "the downloaded archive was damaged and has been dropped; a retry downloads it again";
     if (error && !error->hint.empty()) return error->hint;
+    // A refusal the provider decided (a hook, a metadata transaction): the
+    // same command fails the same way, so retrying is not the advice (D5).
+    if (code == "E_INTERNAL")
+        return "the provider refused the change; `mcpp self doctor` reports the state of mcpp's "
+               "package home, and the whole failure is in ~/.mcpp/log/mcpp.log";
     return "the whole failure is in ~/.mcpp/log/mcpp.log (`mcpp self doctor` checks the "
            "installation); retry, or `mcpp self init --force`";
 }
@@ -1044,7 +1086,7 @@ std::string install_failure_hint(const std::optional<mcpp::provider::ErrorEvent>
 
 std::expected<Fetcher::XpkgPayload, CallError>
 Fetcher::resolve_xpkg_path(std::string_view target,
-                           bool autoInstall,
+                           PayloadIntent intent,
                            EventHandler* handler)
 {
     // Default to xim namespace for tools/toolchain. Modular libs use
@@ -1100,103 +1142,170 @@ Fetcher::resolve_xpkg_path(std::string_view target,
         return payload;
     };
 
-    // What the provider says of this payload, nothing installed: there and
-    // complete is the only "installed" (a directory that merely exists may
-    // be an interrupted install, or a success that installed nothing, #533).
-    const auto complete_here = [&]() -> std::optional<std::filesystem::path> {
+    // What the provider says of this payload, nothing installed (D1): the
+    // provider decides completeness, usability against the recipe's floor and
+    // currency; this function only maps them through the caller's intent.
+    struct Here {
+        std::filesystem::path dir;      // empty: nothing there
+        bool complete = false, usable = false, current = false;
+        int installed = -1, revision = 0, floor = 0;
+    };
+    const auto here = [&]() -> Here {
         const std::array<mcpp::provider::PackageRef, 1> refs{ref};
         auto st = provider->status(refs);
-        if (st.size() == 1) {
-            if (st[0].complete && !st[0].dir.empty()) return st[0].dir;
-            // Present but not complete (an interrupted install, a success
-            // that installed nothing): not installed.
-            if (st[0].origin != "absent") return std::nullopt;
+        if (st.size() == 1 && st[0].origin != "absent" && !st[0].dir.empty()) {
+            // Present: a complete one (usable / current as the provider says),
+            // or an interrupted install, or a success that installed nothing
+            // (#533) -- the provider's verdicts say which.
+            return {st[0].dir, st[0].complete, st[0].usable, st[0].current,
+                    st[0].installedRevision, st[0].revision, st[0].floor};
         }
         // The provider could not say, or has nothing where the index's store
         // is: what is installed elsewhere in the home, by its version grammar,
         // holding something -- a payload installed before its index had a
         // store of its own (COMPAT(internal:legacy-registry-store), design
-        // 2026-10-16 §5.3).
+        // 2026-10-16 §5.3). Nothing to judge it by: it is taken as it is.
         auto dir = provider->payload(ref);
         std::error_code ec;
-        if (!dir.empty() && std::filesystem::is_directory(dir, ec) && !std::filesystem::is_empty(dir, ec)) return dir;
-        return std::nullopt;
+        if (!dir.empty() && std::filesystem::is_directory(dir, ec) && !std::filesystem::is_empty(dir, ec))
+            return {dir, true, true, true};
+        return {};
     };
 
-    if (auto dir = complete_here()) {
-        mcpp::log::debug("fetcher", "payload complete in the store");
-        return make_payload(*dir);
+    const auto label = std::format("{}@{}", parsed.packageName, parsed.version);
+    auto now = here();
+    const auto action = payload_action(intent, !now.dir.empty(), now.usable, now.current);
+    if (action == PayloadAction::Take) {
+        if (!now.current)
+            mcpp::log::verbose("fetcher", std::format(
+                "{}: packaging revision {} in use; the index has {} (floor {})",
+                label, now.installed, now.revision, now.floor));
+        return make_payload(now.dir);
+    }
+    if (action == PayloadAction::Refuse) {
+        return std::unexpected(CallError{std::format(
+            "payload of '{}' is not installed\n"
+            "  hint: `mcpp toolchain install` installs a toolchain; a build installs what it needs",
+            mcpp::provider::to_string(ref))});
     }
 
-    if (autoInstall) {
-        // Offline is checked HERE, after the "already installed" fast path
-        // above: a build whose packages are all present stays functional
-        // offline. Only an actual download is refused, naming the package.
-        if (mcpp::platform::env::offline_mode()) {
-            mcpp::build::refusal::record(
-                mcpp::build::refusal::Code::OfflineDownloadRequired);
-            return std::unexpected(CallError{ std::format(
-                "offline mode: `{}@{}` is not installed and cannot be downloaded\n"
-                "       run without --offline (or unset MCPP_OFFLINE) to fetch it",
-                parsed.packageName, parsed.version) });
-        }
-        if (parsed.indexName == "xim") {
-            // A descriptor missing from the local xim index may be one the
-            // remote index has. Whether that miss refreshes is the refresh
-            // policy's decision (#648 A5).
-            if (!provider->official_package_present(parsed.packageName)) {
-                auto decision = mcpp::pm::decide_for_miss(
-                    mcpp::pm::policy_for(cfg_), location_of(cfg_),
-                    std::format("xim:{}", parsed.packageName));
-                if (auto r = mcpp::pm::apply(decision, location_of(cfg_)); !r)
-                    mcpp::ui::warning(r.error());
-            }
-        }
+    // Offline is checked HERE, after the "already usable" fast path above: a
+    // build whose packages are all usable stays functional offline. Only an
+    // actual download is refused, naming the package.
+    if (mcpp::platform::env::offline_mode()) {
+        mcpp::build::refusal::record(
+            mcpp::build::refusal::Code::OfflineDownloadRequired);
+        return std::unexpected(CallError{ std::format(
+            "offline mode: `{}` is not installed and cannot be downloaded\n"
+            "       run without --offline (or unset MCPP_OFFLINE) to fetch it",
+            label) });
+    }
 
-        std::vector<std::string> targets { mcpp::provider::to_string(ref) };
-        mcpp::log::verbose("fetcher", std::format("install: {}", targets[0]));
-        auto inst = install(targets, handler);
-        if (!inst) return std::unexpected(inst.error());
-        if (inst->exitCode == 0) {
-            if (auto dir = complete_here()) return make_payload(*dir);
-            // Reported a success and left nothing complete (mcpp#533's shape):
-            // said, not stamped over.
-            return std::unexpected(CallError{std::format(
-                "'{}' reported a successful install, but its payload is not complete\n"
-                "  hint: {}", targets[0], install_failure_hint(inst->error, cfg_.xlingsHome()))});
-        }
+    // A replacement says why, once, before it starts (D3): the user sees a
+    // download in a command that only builds, so the reason is part of it.
+    const bool replacing = action == PayloadAction::Replace;
+    const bool replacingUsable = replacing && now.usable;
+    if (replacing) {
+        if (now.usable)
+            mcpp::ui::status("Updating", std::format("{}  packaging revision {} → {}",
+                                                     label, now.installed, now.revision));
+        else if (now.complete && now.installed >= 0 && now.installed < now.floor)
+            mcpp::ui::status("Updating", std::format(
+                "{}  packaging revision {} → {} (revision {} is below the index's floor {})",
+                label, now.installed, now.revision, now.installed, now.floor));
+        else if (now.installed >= 0 && now.installed != now.revision)
+            // A provider before 1.11 calls an older packaging incomplete.
+            mcpp::ui::status("Updating", std::format("{}  packaging revision {} → {}",
+                                                     label, now.installed, now.revision));
+        else
+            mcpp::ui::status("Reinstalling", std::format("{}  (the installed payload is incomplete)", label));
+    }
 
-        // The install failed. The index may predate this version: the refresh
-        // policy decides whether to refresh once, then the provider's own
-        // command line tries again -- more robust for a large toolchain, and
-        // its output stays visible when it still fails.
-        if (parsed.indexName == "xim") {
-            mcpp::log::verbose("fetcher",
-                std::format("install failed for {}; asking the refresh policy before retry", targets[0]));
-            auto decision = mcpp::pm::decide_for_miss(
-                mcpp::pm::policy_for(cfg_), location_of(cfg_), targets[0]);
-            if (auto r = mcpp::pm::apply(decision, location_of(cfg_)); !r)
-                mcpp::log::verbose("fetcher", r.error());
-        }
+    if (parsed.indexName == "xim" && !provider->official_package_present(parsed.packageName)) {
+        // A descriptor missing from the local xim index may be one the
+        // remote index has. Whether that miss refreshes is the refresh
+        // policy's decision (#648 A5).
+        auto decision = mcpp::pm::decide_for_miss(
+            mcpp::pm::policy_for(cfg_), location_of(cfg_),
+            std::format("xim:{}", parsed.packageName));
+        if (auto r = mcpp::pm::apply(decision, location_of(cfg_)); !r)
+            mcpp::ui::warning(r.error());
+    }
+
+    // Satisfied: what the intent asks of the payload now there.
+    const auto satisfied = [&]() -> std::optional<std::filesystem::path> {
+        auto after = here();
+        if (after.dir.empty()) return std::nullopt;
+        if (intent == PayloadIntent::Provision ? after.current : after.usable) return after.dir;
+        return std::nullopt;
+    };
+
+    std::vector<std::string> targets { mcpp::provider::to_string(ref) };
+    mcpp::log::verbose("fetcher", std::format("install: {}", targets[0]));
+    auto inst = install(targets, handler);
+    if (!inst) return std::unexpected(inst.error());
+    if (inst->exitCode == 0) {
+        if (auto dir = satisfied()) return make_payload(*dir);
+        // Reported a success and left nothing complete (mcpp#533's shape):
+        // said, not stamped over.
+        return std::unexpected(CallError{std::format(
+            "'{}' reported a successful install, but its payload is not complete\n"
+            "  hint: {}", targets[0], install_failure_hint(inst->error, cfg_.xlingsHome()))});
+    }
+
+    // The install failed. What happens next depends on why (D5).
+    const std::string code = inst->error ? inst->error->code : std::string{};
+    const auto policy = install_failure_policy(code);
+    int directRc = -1;
+    if (policy.refreshIndex && parsed.indexName == "xim") {
+        auto decision = mcpp::pm::decide_for_miss(
+            mcpp::pm::policy_for(cfg_), location_of(cfg_), targets[0],
+            mcpp::pm::RefreshReason::InstallMiss);
+        if (auto r = mcpp::pm::apply(decision, location_of(cfg_)); !r)
+            mcpp::log::verbose("fetcher", r.error());
+    }
+    if (policy.retry) {
+        // The provider's own command line: more robust for a large toolchain,
+        // and its output stays visible when it fails again.
         mcpp::log::verbose("fetcher", std::format("retrying {} through the provider's command line", targets[0]));
-        int directRc = provider->install_direct(targets[0]);
+        directRc = provider->install_direct(targets[0]);
         if (directRc == 0)
-            if (auto dir = complete_here()) return make_payload(*dir);
+            if (auto dir = satisfied()) return make_payload(*dir);
+    }
 
-        std::string installError = std::format(
-            "install of '{}' failed (interface exit {}, direct exit {})",
-            targets[0], inst->exitCode, directRc);
-        if (inst->error)
-            installError += ": " + inst->error->message;
-        return std::unexpected(CallError{std::format(
-            "{}\n  hint: {}", installError,
-            install_failure_hint(inst->error, cfg_.xlingsHome()))});
+    std::string installError = std::format("install of '{}' failed (interface exit {}{})", targets[0],
+        inst->exitCode, policy.retry ? std::format(", direct exit {}", directRc) : std::string{});
+    if (inst->error)
+        installError += ": " + inst->error->message;
+
+    // A replacement that failed leaves the previous payload where it was (the
+    // provider's replacement is a transaction). Only a provisioning command
+    // replaces a payload that is still usable, so only it can fail with one
+    // left in place: it says which revision stays in use. A build replaces
+    // only a payload that is not usable, and has nothing to fall back to.
+    if (replacingUsable) {
+        auto after = here();
+        if (!after.dir.empty() && after.usable)
+            return std::unexpected(CallError{std::format(
+                "{}\n  packaging revision {} is still installed and in use\n  hint: {}",
+                installError, after.installed, install_failure_hint(inst->error, cfg_.xlingsHome()))});
     }
+    return std::unexpected(CallError{std::format(
+        "{}\n  hint: {}", installError,
+        install_failure_hint(inst->error, cfg_.xlingsHome()))});
+}
+
+PayloadAction payload_action(PayloadIntent intent, bool present, bool usable, bool current) {
+    if (present && usable && (intent != PayloadIntent::Provision || current)) return PayloadAction::Take;
+    if (intent == PayloadIntent::Locate) return PayloadAction::Refuse;
+    return present ? PayloadAction::Replace : PayloadAction::Install;
+}
 
-    return std::unexpected(CallError{
-        std::format("payload of '{}' is not installed\n"
-                    "  hint: check network and retry, or `mcpp self init --force`",
-                    mcpp::provider::to_string(ref))});
+InstallFailurePolicy install_failure_policy(std::string_view errorCode) {
+    if (errorCode == "E_NOT_FOUND") return {.refreshIndex = true, .retry = true};
+    if (errorCode.empty()) return {.refreshIndex = true, .retry = true};
+    if (errorCode == "E_NETWORK" || errorCode == "E_INVALID_INPUT") return {.refreshIndex = false, .retry = true};
+    return {};
 }
 
 // ─── Namespace-aware install_path (canonical, 0.0.10+) ──────────────
diff --git a/src/pm/refresh_policy.cppm b/src/pm/refresh_policy.cppm
index 785fa58e..b6bf660f 100644
--- a/src/pm/refresh_policy.cppm
+++ b/src/pm/refresh_policy.cppm
@@ -33,6 +33,7 @@ enum class RefreshReason {
     None,                   // resolvable locally — the steady state, zero network
     IndexAbsent,            // no local index at all (cold start)
     DescriptorMiss,         // package unknown locally, and the index can say so
+    InstallMiss,            // the provider could not find what the local index names
     VersionMiss,            // package known, constraint unsatisfiable locally
     SuppressedOffline,      // --offline / MCPP_OFFLINE
     SuppressedDisabled,     // [index] auto_refresh = false
@@ -66,9 +67,14 @@ RefreshPolicy policy_for(const mcpp::config::GlobalConfig& cfg);
 // `lookup_descriptor` (that is `mcpp add`): only the policy half of the
 // judgement is left to make. Keeps the opt-outs in one place rather than
 // re-tested at each call site.
+//
+// `why` is what the status line says: DescriptorMiss for a descriptor the
+// local index lacks, InstallMiss after an install the provider failed for
+// want of the package (the descriptor is local; the index may predate it).
 RefreshDecision decide_for_miss(const RefreshPolicy&     policy,
                                 const mcpp::provider::Location& env,
-                                std::string_view         subject);
+                                std::string_view         subject,
+                                RefreshReason            why = RefreshReason::DescriptorMiss);
 
 // Run the sync a decision asked for. At most ONE per process: a build whose
 // deps miss for the same reason should pay one sync, not one per dep.
@@ -110,6 +116,7 @@ std::string_view reason_text(RefreshReason r) {
         case RefreshReason::None:                   return "resolvable locally";
         case RefreshReason::IndexAbsent:            return "no local package index";
         case RefreshReason::DescriptorMiss:         return "not found locally";
+        case RefreshReason::InstallMiss:            return "could not be installed; the index may predate it";
         case RefreshReason::VersionMiss:            return "not satisfiable locally";
         case RefreshReason::SuppressedOffline:      return "offline mode";
         case RefreshReason::SuppressedDisabled:     return "[index] auto_refresh = false";
@@ -132,7 +139,8 @@ RefreshPolicy policy_for(const mcpp::config::GlobalConfig& cfg) {
 
 RefreshDecision decide_for_miss(const RefreshPolicy&     policy,
                                 const mcpp::provider::Location& env,
-                                std::string_view         subject) {
+                                std::string_view         subject,
+                                RefreshReason            why) {
     RefreshDecision d;
     d.subject = std::string(subject);
     // See decide(): a refresh cannot fix an index this binary cannot read.
@@ -151,7 +159,7 @@ RefreshDecision decide_for_miss(const RefreshPolicy&     policy,
         d.reason = RefreshReason::SuppressedDebounce;
         return d;
     }
-    d.reason = RefreshReason::DescriptorMiss;
+    d.reason = why;
     d.shouldRefresh = true;
     return d;
 }
@@ -168,6 +176,12 @@ std::expected<void, std::string> run_sync(const mcpp::provider::Location& env,
     auto after = mcpp::provider::open(env)->default_index_status(0).rev;
     if (before && after && *before != *after)
         mcpp::ui::status("Updated", std::format("package index {} → {}", *before, *after));
+    // A refresh inside a build changes nothing the build uses (design
+    // 2026-10-17 D6): newer packagings are recorded, and `mcpp index update`
+    // and `mcpp toolchain list` say them.
+    if (mcpp::log::is_verbose())
+        for (const auto& st : mcpp::provider::not_current(*mcpp::provider::open(env)))
+            mcpp::log::verbose("index", std::format("newer packaging: {}", mcpp::provider::describe_currency(st)));
     else if (after)
         mcpp::log::verbose("index", std::format("package index still at {}", *after));
     return {};
@@ -189,7 +203,7 @@ std::expected<void, std::string> apply(const RefreshDecision& d,
         return {};
     }
     g_refreshed_this_process = true;
-    return run_sync(env, std::format("package index — `{}` {} (one-time)",
+    return run_sync(env, std::format("package index — `{}` {}",
                                      d.subject, reason_text(d.reason)));
 }
 
diff --git a/src/provider/provider.cppm b/src/provider/provider.cppm
index f42840ff..a5f7716d 100644
--- a/src/provider/provider.cppm
+++ b/src/provider/provider.cppm
@@ -365,17 +365,27 @@ public:
 };
 
 // What a provider says of a package's payload without installing anything
-// (its `payload_status`, design §7.1 / X4): where it is, whether it is
-// complete (there, holding something, no recorded failure, the recipe's
-// revision), and whether it is this home's own or an upstream's link entry.
+// (its `payload_status`, design 2026-10-16 §7.1 / X4, 2026-10-17 D1): where it
+// is, whether it is this home's own or an upstream's link entry, and three
+// verdicts the provider decides -- mcpp repeats none of their rules:
+//
+//   complete  there, holding something, no recorded failure (integrity only);
+//   usable    complete, and recorded at or above the recipe's `floor`;
+//   current   complete, and recorded at the recipe's revision.
+//
+// A command that uses a payload acts on `usable`; one that provisions it acts
+// on `current`.
 struct PayloadStatus {
     std::string request;            // the address as asked
     std::string ns, name, version;  // what it resolved to
     int revision = 0;               // the recipe's
+    int floor = 0;                  // the oldest installed revision the recipe calls usable
     std::filesystem::path dir;      // the payload directory (empty: does not resolve)
     std::string origin;             // "local" | "upstream" | "absent"
     int installedRevision = -1;     // what the payload's stamp records; -1: none
     bool complete = false;
+    bool usable = false;
+    bool current = false;
     std::string error;              // non-empty: the request did not resolve
 };
 
diff --git a/src/provider/select.cppm b/src/provider/select.cppm
index 65aa0a50..2bfc29e7 100644
--- a/src/provider/select.cppm
+++ b/src/provider/select.cppm
@@ -66,6 +66,30 @@ std::optional<std::filesystem::path> payload(const Provider& p, const PackageRef
 }
 // The nasm a build may use (the host's first, then the provider's), and the
 // one the provider placed.
+// The installed payloads of the provider's own store whose packaging is not
+// the index's current one, as the provider reports them (design 2026-10-17
+// D6). Shown where the index changes and where a person looks at what is
+// installed (`index update`, `toolchain list`, doctor), never inside a build:
+// a build keeps a usable payload. Empty when the provider cannot say.
+std::vector<PayloadStatus> not_current(const Provider& p) {
+    std::vector<PackageRef> refs;
+    for (const auto& e : layout().entries(p.store()))
+        if (!e.ns.empty() && !e.name.empty() && !e.version.empty()) refs.push_back({e.ns, e.name, e.version});
+    std::vector<PayloadStatus> out;
+    for (auto& st : p.status(refs))
+        if (st.error.empty() && st.complete && !st.current) out.push_back(std::move(st));
+    return out;
+}
+
+// "llvm@23.1.3 (revision 0 → 1)", and what using it means when it is below the
+// index's floor.
+std::string describe_currency(const PayloadStatus& st) {
+    auto text = std::format("{}@{} (packaging revision {} → {})", st.name, st.version,
+                            st.installedRevision, st.revision);
+    if (!st.usable) text += std::format(" — below the index's floor {}; the next build replaces it", st.floor);
+    return text;
+}
+
 std::optional<std::filesystem::path> usable_nasm(const Provider& p) { return detail::some(p.usable_nasm()); }
 std::optional<std::filesystem::path> placed_nasm(const Provider& p) { return detail::some(p.placed_nasm()); }
 
diff --git a/src/provider/xlings/provider.cppm b/src/provider/xlings/provider.cppm
index bd882975..afc983e1 100644
--- a/src/provider/xlings/provider.cppm
+++ b/src/provider/xlings/provider.cppm
@@ -246,6 +246,15 @@ public:
                 if (t.contains("installed_revision") && t["installed_revision"].is_number_integer())
                     ps.installedRevision = t["installed_revision"].get<int>();
                 ps.complete = t.value("complete", false);
+                if (t.contains("floor") && t["floor"].is_number_integer()) ps.floor = t["floor"].get<int>();
+                // COMPAT(internal:provider-protocol-1.10): an xlings before
+                // 2026.10.17.1 reports no `usable` / `current`, and its
+                // `complete` already required the recipe's revision -- so it
+                // is both, read as 1.10 meant it. A vendored xlings that cannot
+                // be updated (no newer source beside this mcpp) keeps the
+                // behaviour it had.
+                ps.usable = t.contains("usable") ? t.value("usable", false) : ps.complete;
+                ps.current = t.contains("current") ? t.value("current", false) : ps.complete;
                 ps.error = str(t, "error");
                 out.push_back(std::move(ps));
             }
diff --git a/src/provider/xlings/xlings.cppm b/src/provider/xlings/xlings.cppm
index 7a24b742..fe8dfc0f 100644
--- a/src/provider/xlings/xlings.cppm
+++ b/src/provider/xlings/xlings.cppm
@@ -133,7 +133,16 @@ namespace pinned {
     // besides its upstream, so a borrowed payload had no entry in the store
     // mcpp reads. A runtime's own install now makes the home's runtime links;
     // `pin_runtime` still asks for them after it (idempotent).
-    inline constexpr std::string_view kXlingsVersion   = "2026.10.16.2";
+    //
+    // Tenth, at 2026.10.17.1 (openxlings/xlings#678). Below it, `payload_status`
+    // called a payload of an older packaging revision incomplete, so a build
+    // replaced llvm, gcc and glibc after every revision the index raised, and
+    // a replacement was refused for good by another package's dangling record
+    // in the home. It now reports integrity, `usable` and `current` apart
+    // (`payload_currency`), drops dangling records in every transaction and
+    // says so (`scope_repaired`), and summarizes the binding state
+    // (`binding_state`) for `mcpp self doctor` (design 2026-10-17).
+    inline constexpr std::string_view kXlingsVersion   = "2026.10.17.1";
     inline constexpr std::string_view kNasmVersion     = "3.02";
 }
 
@@ -534,7 +543,7 @@ void ensure_ninja(const Env& env, bool quiet,
 // images ship one), the mcpp sandbox second. NEVER triggers an install —
 // pure lookup. A build that needs to *provision* nasm goes through the
 // toolchain's synchronous fetcher gate
-// (mcpp::pm::Fetcher::resolve_xpkg_path("xim:nasm@<version>", autoInstall,
+// (mcpp::pm::Fetcher::resolve_xpkg_path("xim:nasm@<version>", PayloadIntent::Use,
 // ...)) from mcpp.build.prepare, the same gate the compiler toolchain uses:
 // this module is a LEAF dependency and must not import mcpp.config /
 // mcpp.fetcher (#232 — the old bespoke `ensure_nasm` install path skipped
@@ -929,7 +938,8 @@ std::string unmet(const mcpp::provider::ProviderInfo& info) {
     if (!info.answered) return "answers no handshake (an xlings before 2026.10.16.1)";
     if (mcpp::xpkg_version::compare_keys(info.version, pinned::kXlingsVersion) < 0)
         return std::format("is {}, older than {}", info.version, pinned::kXlingsVersion);
-    for (auto feature : {"index_dir", "index_store", "upstreams", "payload_status", "sync_index"})
+    for (auto feature : {"index_dir", "index_store", "upstreams", "payload_status", "sync_index",
+                         "payload_currency", "binding_state"})
         if (std::ranges::find(info.features, feature) == info.features.end())
             return std::format("does not offer `{}`", feature);
     if (std::ranges::find(info.capabilities, "install_packages") == info.capabilities.end())
diff --git a/src/toolchain/detect.cppm b/src/toolchain/detect.cppm
index 9c5a15bd..0e1b148e 100644
--- a/src/toolchain/detect.cppm
+++ b/src/toolchain/detect.cppm
@@ -70,6 +70,16 @@ detect(const std::filesystem::path& explicit_compiler,
 
     const auto& vstr = *ver_r;
     tc.driverIdent = normalize_driver_output(vstr);
+    // The packaging revision of the payload this compiler is in (design
+    // 2026-10-17 D8). A build keeps an installed revision while the provider
+    // calls it usable, so one version can be present in two packagings -- two
+    // homes, or one home before and after `mcpp toolchain install` -- whose
+    // `--version` reads the same; their artifacts and caches must not mix.
+    // Revision 0 adds nothing: a payload from before revisions keeps the
+    // identity, and the caches, it had.
+    if (const auto entry = mcpp::provider::layout().entry_of(tc.binaryPath); !entry.dir.empty())
+        if (const int r = mcpp::provider::revision_of(entry.dir).value_or(0); r > 0)
+            tc.driverIdent += std::format("\npayload-revision: {}", r);
     auto head = first_line_of(vstr);
     auto headLower = lower_copy(head);
     auto fullLower = lower_copy(vstr);
diff --git a/src/toolchain/lifecycle.cppm b/src/toolchain/lifecycle.cppm
index 67ea87e4..403bfc2b 100644
--- a/src/toolchain/lifecycle.cppm
+++ b/src/toolchain/lifecycle.cppm
@@ -463,6 +463,7 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
         mcpp::toolchain::PayloadIdentity id;
         std::string version;
         std::filesystem::path bin;
+        mcpp::provider::PackageRef ref;
     };
     std::vector<Payload> payloads;
     std::error_code ec;
@@ -488,7 +489,7 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
                 // runs to find out what is installed.
                 if (!bin) { mcpp::ui::warning(bin.error()); continue; }
                 if (bin->empty()) continue;
-                payloads.push_back({ *id, s.version, *bin });
+                payloads.push_back({ *id, s.version, *bin, {entry.ns, entry.name, entry.version} });
             }
         }
     }
@@ -507,6 +508,24 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
         return version_greater(a.version, b.version);
     });
 
+    // Each payload's packaging against the index (design 2026-10-17 D6),
+    // asked once for all of them: a build keeps a usable payload of an older
+    // packaging, so this list is where a newer one is said.
+    std::vector<mcpp::provider::PayloadStatus> currency;
+    {
+        std::vector<mcpp::provider::PackageRef> refs;
+        for (auto& p : payloads) refs.push_back(p.ref);
+        currency = mcpp::provider::open(mcpp::config::make_xlings_env(cfg))->status(refs);
+        if (currency.size() != payloads.size()) currency.clear();
+    }
+    const auto newer_of = [&](const FamVer& f) -> const mcpp::provider::PayloadStatus* {
+        for (std::size_t i = 0; i < currency.size(); ++i)
+            if (payloads[i].id.family == f.family && payloads[i].version == f.version
+                && currency[i].complete && !currency[i].current)
+                return &currency[i];
+        return nullptr;
+    };
+
     if (payloads.empty()) {
         std::println("(no toolchains installed — run `mcpp toolchain install gcc 16.1.0` "
                      "or just `mcpp build` to auto-install the default)");
@@ -515,16 +534,30 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
         for (auto& f : famvers) {
             bool isDefault = defSpec
                 && mcpp::toolchain::spec_matches_payload(*defSpec, { f.family, {} }, f.version);
-            jsonToolchains.push_back({
+            const auto* newer = newer_of(f);
+            nlohmann::json row{
                 {"family",  std::string(mcpp::toolchain::family_name(f.family))},
                 {"version", f.version},
                 {"default", isDefault},
-            });
+            };
+            if (newer) {
+                row["installedRevision"] = newer->installedRevision;
+                row["availableRevision"] = newer->revision;
+                row["usable"] = newer->usable;
+            }
+            jsonToolchains.push_back(std::move(row));
             if (json) continue;
-            std::println("  {:<3}{:<22}{}",
+            std::string currencyNote;
+            if (newer)
+                currencyNote = newer->usable
+                    ? std::format("  (packaging revision {} available: `mcpp toolchain install {} {}`)",
+                                  newer->revision, mcpp::toolchain::family_name(f.family), f.version)
+                    : std::format("  (revision {} is below the index's floor {}; the next build replaces it)",
+                                  newer->installedRevision, newer->floor);
+            std::println("  {:<3}{:<22}{}{}",
                 isDefault ? "*" : "",
                 std::format("{} {}", mcpp::toolchain::family_name(f.family), f.version),
-                isDefault ? "  (default)" : "");
+                isDefault ? "  (default)" : "", currencyNote);
         }
         if (!json && effective.fromProject) {
             std::println("  (* = effective toolchain from project mcpp.toml "
@@ -886,7 +919,7 @@ ensure_declared_runtime(const mcpp::config::GlobalConfig& cfg,
         binding.runtimeId, target));
     mcpp::fetcher::Fetcher fetcher(cfg);
     mcpp::fetcher::InstallProgressHandler progress;
-    if (auto installed = fetcher.resolve_xpkg_path(target, /*autoInstall=*/true, &progress); !installed)
+    if (auto installed = fetcher.resolve_xpkg_path(target, mcpp::fetcher::PayloadIntent::Use, &progress); !installed)
         return std::unexpected(std::format(
             "the C runtime the toolchain runs on, {}, is not installed: {}", target, installed.error().message));
     provider->pin_runtime(binding.runtimeId, /*relink=*/true);
@@ -992,7 +1025,10 @@ export int toolchain_install(const mcpp::config::GlobalConfig& cfg,
             auto vdir = mcpp::provider::open(mcpp::config::make_xlings_env(cfg))->pinned(pkg.ximName, pkg.ximVersion);
             sweep_parked_payloads(vdir.parent_path(), vdir);
         }
-        auto payload = fetcher.resolve_xpkg_path(pkg.target(), /*autoInstall=*/true, &progress);
+        // Provision (design 2026-10-17 D3): the command that asks for this
+        // toolchain by name brings the index's current packaging; a build
+        // keeps the installed one while it is usable.
+        auto payload = fetcher.resolve_xpkg_path(pkg.target(), mcpp::fetcher::PayloadIntent::Provision, &progress);
         mcpp::log::verbose("toolchain", std::format("main install result: {}",
             payload ? ("ok → " + payload->root.string()) : payload.error().message));
         if (!payload) {
diff --git a/tests/e2e/22_doctor_cache_publish.sh b/tests/e2e/22_doctor_cache_publish.sh
index c33960d2..b10bc4db 100755
--- a/tests/e2e/22_doctor_cache_publish.sh
+++ b/tests/e2e/22_doctor_cache_publish.sh
@@ -12,10 +12,6 @@ trap "rm -rf $TMP" EXIT
 export MCPP_HOME="$TMP/mcpp-home"
 
 # 0) cache list on a genuinely empty cache: friendly message.
-#    This has to come BEFORE doctor — doctor resolves a build plan, which
-#    precompiles the std module, and `cache list` now reports std entries too.
-#    Hiding them is how 16 GB of duplicated std BMIs went unnoticed, so listing
-#    them is the fix, not a regression.
 out=$("$MCPP" cache list 2>&1)
 [[ "$out" == *"empty"* ]] || { echo "cache list on empty cache: '$out'"; exit 1; }
 
@@ -29,8 +25,17 @@ grep -q 'Checking registry'       doctor.log || { cat doctor.log; echo "no regis
 grep -q 'Checking cache health'   doctor.log || { cat doctor.log; echo "no cache check"; exit 1; }
 grep -q 'Doctor result'             doctor.log || { cat doctor.log; echo "no result line"; exit 1; }
 
-# 2) after doctor, the std module it precompiled must be VISIBLE. std entries
+# 1b) doctor changes nothing (2026.10.17.1): its plan is prepared offline and
+#     builds nothing, so the cache is still empty after it.
+out=$("$MCPP" cache list 2>&1)
+[[ "$out" == *"empty"* ]] || { echo "doctor wrote to the build cache: '$out'"; exit 1; }
+
+# 2) after a build, the std module it precompiled must be VISIBLE. std entries
 #    dominate the cache's size, and `cache list` used to walk only dep entries.
+#    Hiding them is how 16 GB of duplicated std BMIs went unnoticed, so listing
+#    them is the fix, not a regression.
+( cd "$TMP" && "$MCPP" new stdprobe >/dev/null && cd stdprobe && "$MCPP" build > "$TMP/stdprobe.log" 2>&1 ) \
+    || { cat "$TMP/stdprobe.log"; echo "the build that precompiles std failed"; exit 1; }
 out=$("$MCPP" cache list 2>&1)
 [[ "$out" == *"std"* ]] || { echo "cache list omits the std entry: '$out'"; exit 1; }
 # The age column must be plausible: file_time_type's epoch is not the Unix
diff --git a/tests/e2e/52_local_path_namespaced_index.sh b/tests/e2e/52_local_path_namespaced_index.sh
index 100f5585..799839cd 100755
--- a/tests/e2e/52_local_path_namespaced_index.sh
+++ b/tests/e2e/52_local_path_namespaced_index.sh
@@ -117,7 +117,7 @@ fi
 cat > "$TMP/fake-bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 set -e
 
 if [[ "${1:-}" == "self" && "${2:-}" == "init" ]]; then
diff --git a/tests/e2e/58_preinstall_mcpp_deps_for_hooks.sh b/tests/e2e/58_preinstall_mcpp_deps_for_hooks.sh
index 36467432..ae8d2b1f 100644
--- a/tests/e2e/58_preinstall_mcpp_deps_for_hooks.sh
+++ b/tests/e2e/58_preinstall_mcpp_deps_for_hooks.sh
@@ -88,7 +88,7 @@ fi
 cat > "$TMP/fake-bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 set -e
 
 if [[ "${1:-}" == "self" && "${2:-}" == "init" ]]; then
diff --git a/tests/e2e/60_stale_xpkg_cache_reinstall.sh b/tests/e2e/60_stale_xpkg_cache_reinstall.sh
index 29093523..6699ecde 100644
--- a/tests/e2e/60_stale_xpkg_cache_reinstall.sh
+++ b/tests/e2e/60_stale_xpkg_cache_reinstall.sh
@@ -46,7 +46,7 @@ FAKE_INSTALL_LOG="$TMP/fake-install.log"
 cat > "$TMP/fake-bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 set -e
 
 if [[ "${1:-}" == "self" && "${2:-}" == "init" ]]; then
diff --git a/tests/e2e/732_xlings_refresh_is_bounded_and_owned.sh b/tests/e2e/732_xlings_refresh_is_bounded_and_owned.sh
index f3e20100..c054edcb 100755
--- a/tests/e2e/732_xlings_refresh_is_bounded_and_owned.sh
+++ b/tests/e2e/732_xlings_refresh_is_bounded_and_owned.sh
@@ -34,7 +34,7 @@ mkdir -p "$TMP/bin" "$TMP/home"
 cat > "$TMP/bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 case "${1:-}:${2:-}" in
   update:*|interface:update_packages) echo "$$" > "${STUB_PID:?}"; exec sleep 1000 ;;
 esac
diff --git a/tests/e2e/733_envelope_reports_observed_network_access.sh b/tests/e2e/733_envelope_reports_observed_network_access.sh
index bc08b3cf..0a195b09 100755
--- a/tests/e2e/733_envelope_reports_observed_network_access.sh
+++ b/tests/e2e/733_envelope_reports_observed_network_access.sh
@@ -24,7 +24,7 @@ mkdir -p "$TMP/bin"
 cat > "$TMP/bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 echo "$*" >> "${STUB_LOG:?}"
 exit 0
 EOF
diff --git a/tests/e2e/734_auto_refresh_false_governs_first_index_sync.sh b/tests/e2e/734_auto_refresh_false_governs_first_index_sync.sh
index e536fc72..b6f51dca 100755
--- a/tests/e2e/734_auto_refresh_false_governs_first_index_sync.sh
+++ b/tests/e2e/734_auto_refresh_false_governs_first_index_sync.sh
@@ -22,7 +22,7 @@ mkdir -p "$TMP/bin"
 cat > "$TMP/bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 echo "$*" >> "${STUB_LOG:?}"
 exit 0
 EOF
diff --git a/tests/e2e/812_an_index_floor_is_a_closing_tip.sh b/tests/e2e/812_an_index_floor_is_a_closing_tip.sh
index d2d287cf..5d653c59 100755
--- a/tests/e2e/812_an_index_floor_is_a_closing_tip.sh
+++ b/tests/e2e/812_an_index_floor_is_a_closing_tip.sh
@@ -35,7 +35,7 @@ mkdir -p "$TMP/bin"
 cat > "$TMP/bin/xlings" <<EOF
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "\${1:-}" == "interface" && "\${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "\${1:-}" == "interface" && "\${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 case " \$* " in
     *" sync_index "*)
         dest=\$(printf '%s' "\$4" | sed -n 's/.*"dest":"\([^"]*\)".*/\1/p')
diff --git a/tests/e2e/817_emit_writes_no_xlings_json_under_private_work_dir.sh b/tests/e2e/817_emit_writes_no_xlings_json_under_private_work_dir.sh
index f6c801b7..269df416 100755
--- a/tests/e2e/817_emit_writes_no_xlings_json_under_private_work_dir.sh
+++ b/tests/e2e/817_emit_writes_no_xlings_json_under_private_work_dir.sh
@@ -40,7 +40,7 @@ mkdir -p "$OUT/bin"
 cat > "$OUT/bin/xlings" <<'EOF'
 #!/usr/bin/env bash
 # The handshake mcpp asks of every xlings (docs/25 §5).
-[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.10","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index"]}'; exit 0; }
+[[ "${1:-}" == "interface" && "${2:-}" == "--version" ]] && { echo '{"protocol_version":"1.11","version":"9999.1.1.1","capabilities":["install_packages"],"home_layouts":[2],"features":["index_dir","index_store","upstreams","payload_status","sync_index","payload_currency","binding_state"]}'; exit 0; }
 echo "$*" >> "${STUB_LOG:?}"
 exit 0
 EOF
diff --git a/tests/e2e/916_a_home_from_before_keeps_working.sh b/tests/e2e/916_a_home_from_before_keeps_working.sh
index 56688cf2..7d29a8a5 100755
--- a/tests/e2e/916_a_home_from_before_keeps_working.sh
+++ b/tests/e2e/916_a_home_from_before_keeps_working.sh
@@ -1,9 +1,13 @@
 #!/usr/bin/env bash
 # requires: unix-shell python3
-# 916 -- a home an earlier mcpp made keeps working (docs/25 §1).
+# 916 -- the index layout of a home an earlier mcpp made is migrated
+# (docs/25 §1).
 #
 # An earlier mcpp kept the data of its own index under the provider's data
-# directory and wrote markers into payloads. Criteria:
+# directory and wrote markers into payloads. This home is written by hand and
+# holds no toolchain: whether a home the previous release made goes on
+# building is the upgrade lane's question (.github/workflows/ci-upgrade.yml),
+# which builds that home with the previous release itself. Criteria:
 #   A. The first run moves the index data to <home>/indices/<name>, once, and
 #      records its place and its store in the provider's configuration.
 #   B. The index is read from there (doctor lists it), and the copy is not
diff --git a/tests/e2e/918_an_older_packaging_is_used_not_replaced.sh b/tests/e2e/918_an_older_packaging_is_used_not_replaced.sh
new file mode 100755
index 00000000..03334a57
--- /dev/null
+++ b/tests/e2e/918_an_older_packaging_is_used_not_replaced.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# requires: unix-shell python3
+# 918 -- a toolchain payload of another packaging revision is used by a build,
+# not replaced inside it (design 2026-10-17 D3, D6, D7).
+#
+# A raised `revision` in the index is a newer packaging, not a broken payload.
+# mcpp 2026.10.16.x replaced every payload whose recorded revision was not the
+# index's inside the build that read it: a user's next `mcpp run` downloaded
+# llvm, gcc (101.7 MB) and glibc (36.7 MB), and on a home with one dangling
+# record the replacement failed on every run. Criteria, on the toolchain this
+# home builds with, its payload re-recorded at another revision:
+#   A. `mcpp new && mcpp build` succeeds and installs, updates or downloads
+#      nothing (no `install_packages` call reaches the provider).
+#   B. `mcpp toolchain list` says another packaging revision is available.
+#   C. `mcpp self doctor` in the project reports the toolchain the build uses
+#      and its payload's revision, and starts no install either.
+# Fails on 2026.10.16.3: A replaces the payload.
+set -e
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+fail() { echo "FAIL: $1"; [ -n "${2:-}" ] && cat "$2"; exit 1; }
+
+export MCPP_HOME="$TMP/home"
+source "$(dirname "$0")/_inherit_toolchain.sh"
+export MCPP_LOG_LEVEL=info
+LOG="$MCPP_HOME/log/mcpp.log"
+
+cd "$TMP"
+"$MCPP" new probe > new.log 2>&1 || fail "mcpp new failed" new.log
+cd probe
+"$MCPP" build -v > first.log 2>&1 || fail "the first build failed" first.log
+
+# The payload the build resolved: `Resolved <tc> → <payload>/bin/<driver>`.
+COMPILER=$(sed -n 's/.*Resolved [^ ]* → \(.*\)$/\1/p' first.log | tail -1)
+[ -n "$COMPILER" ] || { echo "SKIP: the build resolved no managed toolchain payload"; exit 0; }
+case "$COMPILER" in @mcpp/*) COMPILER="$MCPP_HOME/${COMPILER#@mcpp/}" ;; esac
+PAYLOAD=$(cd "$(dirname "$COMPILER")/.." && pwd)
+STAMP="$PAYLOAD/.xpkg-install.json"
+[ -f "$STAMP" ] || { echo "SKIP: $PAYLOAD carries no install record"; exit 0; }
+
+# The payload in this home becomes a directory of its own whose children link
+# to the inherited one, with a record of its own: the inherited payload (the
+# developer's or the runner's) is never written.
+if [ -L "$PAYLOAD" ]; then
+    SRC=$(readlink -f "$PAYLOAD")
+    rm "$PAYLOAD"
+    mkdir "$PAYLOAD"
+    for child in "$SRC"/* "$SRC"/.[!.]*; do
+        [ -e "$child" ] || continue
+        name=$(basename "$child")
+        [ "$name" = ".xpkg-install.json" ] && continue
+        ln -s "$child" "$PAYLOAD/$name"
+    done
+    cp "$SRC/.xpkg-install.json" "$STAMP"
+fi
+python3 - "$STAMP" <<'PY' > "$TMP/revision"
+import json, sys
+path = sys.argv[1]
+stamp = json.load(open(path))
+recorded = int(stamp.get("revision", 0))
+other = recorded - 1 if recorded > 0 else recorded + 1
+stamp["revision"] = other
+open(path, "w").write(json.dumps(stamp, indent=2) + "\n")
+print(other)
+PY
+OTHER=$(cat "$TMP/revision")
+echo "ok: $PAYLOAD re-recorded at packaging revision $OTHER"
+
+# ── A ─────────────────────────────────────────────────────────────────
+rm -f "$LOG"
+cd "$TMP"
+"$MCPP" new probe2 > new2.log 2>&1 || fail "A: mcpp new failed" new2.log
+cd probe2
+"$MCPP" build > a.log 2>&1 || fail "A: the build failed" a.log
+if grep -Eq "Updating|Reinstalling|Downloading|Installing" a.log; then
+    fail "A: the build replaced or installed something" a.log
+fi
+if [ -f "$LOG" ] && grep -q "install_packages" "$LOG"; then
+    fail "A: an install reached the provider" "$LOG"
+fi
+python3 - "$STAMP" "$OTHER" <<'PY' || fail "A: the payload's record changed" "$STAMP"
+import json, sys
+assert int(json.load(open(sys.argv[1])).get("revision", 0)) == int(sys.argv[2])
+PY
+echo "ok: A. the build used packaging revision $OTHER and installed nothing"
+
+# ── B ─────────────────────────────────────────────────────────────────
+"$MCPP" toolchain list > b.log 2>&1 || fail "B: toolchain list failed" b.log
+grep -q "packaging revision .* available\|below the index's floor" b.log \
+    || fail "B: toolchain list does not say another packaging is available" b.log
+echo "ok: B. toolchain list names the other packaging"
+
+# ── C ─────────────────────────────────────────────────────────────────
+rm -f "$LOG"
+"$MCPP" self doctor > c.log 2>&1 || true
+grep -q "what a build here uses" c.log || fail "C: doctor does not report the build's toolchain" c.log
+grep -q "packaging revision $OTHER" c.log || fail "C: doctor does not report the payload's revision" c.log
+if [ -f "$LOG" ] && grep -q "install_packages" "$LOG"; then
+    fail "C: doctor started an install" "$LOG"
+fi
+echo "ok: C. doctor reports the toolchain and its payload, and installs nothing"
diff --git a/tests/unit/test_pm_package_fetcher.cpp b/tests/unit/test_pm_package_fetcher.cpp
index 46694e3d..e080261d 100644
--- a/tests/unit/test_pm_package_fetcher.cpp
+++ b/tests/unit/test_pm_package_fetcher.cpp
@@ -307,3 +307,66 @@ TEST(PackageFetcher, AnIndexThatRequiresANewerMcppIsRecordedNotPrinted) {
     mcpp::pm::reset_unusable_indexes_for_test();
     std::filesystem::remove_all(root);
 }
+
+// ─── What a caller's intent does with a payload (design 2026-10-17 D3) ───
+//
+// The user's home: llvm@23.1.3 recorded at packaging revision 0, the index at
+// revision 1 with no floor -- complete, usable, not current. A build USES it;
+// only `mcpp toolchain install` replaces it. 2026.10.16.x replaced it inside
+// the build (and, with one dangling record in the home, failed every run).
+TEST(PmPayloadIntent, AnOlderPackagingIsUsedByABuildAndReplacedOnlyWhenProvisioned) {
+    using mcpp::pm::PayloadAction;
+    using mcpp::pm::PayloadIntent;
+    using mcpp::pm::payload_action;
+    // present, usable, current
+    EXPECT_EQ(payload_action(PayloadIntent::Use,       true, true, false), PayloadAction::Take);
+    EXPECT_EQ(payload_action(PayloadIntent::Locate,    true, true, false), PayloadAction::Take);
+    EXPECT_EQ(payload_action(PayloadIntent::Provision, true, true, false), PayloadAction::Replace);
+    EXPECT_EQ(payload_action(PayloadIntent::Provision, true, true, true),  PayloadAction::Take);
+}
+
+// Below the recipe's floor, or incomplete: not usable, so even a build
+// replaces it -- the author said the old packaging must go.
+TEST(PmPayloadIntent, AnUnusablePayloadIsReplacedByEveryIntentThatMayInstall) {
+    using mcpp::pm::PayloadAction;
+    using mcpp::pm::PayloadIntent;
+    using mcpp::pm::payload_action;
+    EXPECT_EQ(payload_action(PayloadIntent::Use,       true, false, false), PayloadAction::Replace);
+    EXPECT_EQ(payload_action(PayloadIntent::Provision, true, false, false), PayloadAction::Replace);
+    EXPECT_EQ(payload_action(PayloadIntent::Locate,    true, false, false), PayloadAction::Refuse);
+}
+
+TEST(PmPayloadIntent, NothingThereIsInstalledUnlessOnlyLocated) {
+    using mcpp::pm::PayloadAction;
+    using mcpp::pm::PayloadIntent;
+    using mcpp::pm::payload_action;
+    EXPECT_EQ(payload_action(PayloadIntent::Use,       false, false, false), PayloadAction::Install);
+    EXPECT_EQ(payload_action(PayloadIntent::Provision, false, false, false), PayloadAction::Install);
+    EXPECT_EQ(payload_action(PayloadIntent::Locate,    false, false, false), PayloadAction::Refuse);
+}
+
+// ─── What a failed install calls for (D5) ───
+//
+// The user's failure was `E_INTERNAL` (a metadata transaction refused): mcpp
+// refreshed the index with the reason "not found locally (one-time)" for a
+// descriptor that was local, retried the same doomed replacement through the
+// command line, and told the user to retry. A deterministic refusal is said
+// once; only a package the provider could not find refreshes the index.
+TEST(PmInstallFailurePolicy, ADeterministicRefusalIsNeitherRefreshedNorRetried) {
+    for (std::string_view code : {"E_INTERNAL", "E_PERMISSION", "E_DISK_FULL", "E_CANCELLED"}) {
+        const auto p = mcpp::pm::install_failure_policy(code);
+        EXPECT_FALSE(p.refreshIndex) << code;
+        EXPECT_FALSE(p.retry) << code;
+    }
+}
+
+TEST(PmInstallFailurePolicy, OnlyAMissingPackageRefreshesTheIndex) {
+    EXPECT_TRUE(mcpp::pm::install_failure_policy("E_NOT_FOUND").refreshIndex);
+    EXPECT_TRUE(mcpp::pm::install_failure_policy("E_NOT_FOUND").retry);
+    EXPECT_FALSE(mcpp::pm::install_failure_policy("E_NETWORK").refreshIndex);
+    EXPECT_TRUE(mcpp::pm::install_failure_policy("E_NETWORK").retry);
+    EXPECT_TRUE(mcpp::pm::install_failure_policy("E_INVALID_INPUT").retry);
+    // A provider that said nothing (#238): the old conservative path.
+    EXPECT_TRUE(mcpp::pm::install_failure_policy("").refreshIndex);
+    EXPECT_TRUE(mcpp::pm::install_failure_policy("").retry);
+}
diff --git a/upgrade-lane-logs/new-doctor.log b/upgrade-lane-logs/new-doctor.log
new file mode 100644
index 00000000..243d393b
--- /dev/null
+++ b/upgrade-lane-logs/new-doctor.log
@@ -0,0 +1,34 @@
+    Checking toolchain
+          ok clang 23.1.3 (x86_64-unknown-linux-gnu) at /tmp/lane/upgrade-lane/home/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++ (what a build here uses)
+          ok payload llvm@23.1.3 (packaging revision 0 → 1)  (builds keep it; `mcpp toolchain install` takes the new one)
+    Checking package home
+          ok consistent
+    Checking std module
+          ok /tmp/lane/upgrade-lane/home/build-cache/v1/std/d74c7107fd501d77  (entry 36.8 MiB)
+    Checking registry
+          ok xlings at /tmp/lane/upgrade-lane/home/registry/bin/xlings
+          ok default index = 'mcpplibs'
+    Checking package indexes
+          ok index 'mcpplibs' requires mcpp >= 2026.9.18.3
+          ok index 'xim-pkgindex' declares no mcpp floor
+    Checking home
+          ok self-contained: no upstream ([xlings] upstream)
+          ok /tmp/lane/upgrade-lane/home on ext4: every write is the filesystem's own
+    Checking cache health
+          ok build cache size = 36.8 MiB
+    Checking last runtime closure verdict
+          ok /tmp/lane/upgrade-lane/p-new/target/x86_64-linux-gnu/6fca180a97c5f98c/bin/p-new (RuntimeBinding f3b2c2d035013bc2): pass
+    Checking runtime capabilities
+          ok no host runtime capabilities required
+    Checking toolchain runtime deps
+          ok all installed toolchain RUNPATH dirs present
+          ok vendored xlings 2026.10.17.1 (pinned 2026.10.17.1)
+          ok subos lib symlinks all resolve (/tmp/lane/upgrade-lane/home/registry/subos/default/lib)
+    Checking gcc include-fixed headers
+          ok no installed gcc-family payloads to check
+    Checking build policy
+          ok module interfaces: .cppm  (built-in only)
+          ok build.mcpp run bound: 600s  (from built-in default)
+          ok process deadlines: enforced (POSIX SIGKILL / Windows job object)
+
+Doctor result: all checks passed
diff --git a/upgrade-lane-logs/new-index-update.log b/upgrade-lane-logs/new-index-update.log
new file mode 100644
index 00000000..dd00904c
--- /dev/null
+++ b/upgrade-lane-logs/new-index-update.log
@@ -0,0 +1,15 @@
+    Updating all index repos
+    Updating package index xim done in 1.8s
+ Downloading xim done, 1.5 MB in 0.6s
+    Updating package index awesome done in 1.2s
+ Downloading awesome done, 10 KB in 0.0s
+    Updating package index scode done in 1.1s
+ Downloading scode done, 11 KB in 0.0s
+    Updating package index d2x done in 1.1s
+ Downloading d2x done, 9 KB in 0.0s
+    Updating package index (rebuild) done in 0.2s
+        Note the index has newer packagings of installed payloads:
+           llvm@23.1.3 (packaging revision 0 → 1)
+           glibc@2.44.3 (packaging revision 2 → 4)
+           builds keep the installed ones; `mcpp toolchain install <toolchain>` takes the new one
+     Updated index refresh complete
diff --git a/upgrade-lane-logs/new-provision.log b/upgrade-lane-logs/new-provision.log
new file mode 100644
index 00000000..dac05bba
--- /dev/null
+++ b/upgrade-lane-logs/new-provision.log
@@ -0,0 +1,10 @@
+  Installing llvm@23.1.3 via mcpp's xlings
+    Updating llvm@23.1.3  packaging revision 0 → 1
+ Downloading xim:glibc@2.44.3 done in 0.3s
+ Downloading xim:patchelf@0.18.0 done in 1.3s
+ Downloading xim:llvm@23.1.3 done in 0.7s
+    Repaired c++@16.1.0 in mcpp's package home had no registration; deactivated
+    Repaired c++@16.1.0 in mcpp's package home had no registration; dropped
+   Installed llvm@23.1.3 → /tmp/lane/upgrade-lane/home/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++
+
+Tip: `mcpp toolchain default llvm@23.1.3` to make this the default.
diff --git a/upgrade-lane-logs/new-run-after-provision.log b/upgrade-lane-logs/new-run-after-provision.log
new file mode 100644
index 00000000..3cc595b6
--- /dev/null
+++ b/upgrade-lane-logs/new-run-after-provision.log
@@ -0,0 +1,13 @@
+   Resolving toolchain
+    Resolved llvm@23.1.3 → @mcpp/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++
+      Target x86_64-unknown-linux-gnu
+    Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
+    Inferred target p-new (bin from src/main.cpp)
+   Compiling p-new v0.1.0 (.)
+warning: fingerprint changed (a1e8361286e00ca7 → 35bfb92762f36cca), full rebuild; `mcpp clean --stale` drops the directories no build still uses
+
+    Finished dev [unoptimized + debuginfo] in 2.12s
+     Running `target/x86_64-linux-gnu/35bfb92762f36cca/bin/p-new`
+
+Hello from p-new!
+Built with import std + std::println on modular C++23.
diff --git a/upgrade-lane-logs/new-run-old-project.log b/upgrade-lane-logs/new-run-old-project.log
new file mode 100644
index 00000000..ef5a3ea5
--- /dev/null
+++ b/upgrade-lane-logs/new-run-old-project.log
@@ -0,0 +1,4 @@
+     Running `target/x86_64-linux-gnu/6fca180a97c5f98c/bin/p-old`
+
+Hello from p-old!
+Built with import std + std::println on modular C++23.
diff --git a/upgrade-lane-logs/new-run-on-old-index.log b/upgrade-lane-logs/new-run-on-old-index.log
new file mode 100644
index 00000000..cb90de84
--- /dev/null
+++ b/upgrade-lane-logs/new-run-on-old-index.log
@@ -0,0 +1,14 @@
+    Updating vendored xlings 2026.10.16.2 -> 2026.10.17.1 from the release of this mcpp (pinned 2026.10.17.1)
+   Resolving toolchain
+    Resolved llvm@23.1.3 → @mcpp/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++
+      Target x86_64-unknown-linux-gnu
+    Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
+    Inferred target p-old (bin from src/main.cpp)
+   Compiling p-old v0.1.0 (.)
+warning: fingerprint changed (f24dd8c55f72810d → 6fca180a97c5f98c), full rebuild; `mcpp clean --stale` drops the directories no build still uses
+
+    Finished dev [unoptimized + debuginfo] in 1.72s
+     Running `target/x86_64-linux-gnu/6fca180a97c5f98c/bin/p-old`
+
+Hello from p-old!
+Built with import std + std::println on modular C++23.
diff --git a/upgrade-lane-logs/new-run1.log b/upgrade-lane-logs/new-run1.log
new file mode 100644
index 00000000..b5a4c43b
--- /dev/null
+++ b/upgrade-lane-logs/new-run1.log
@@ -0,0 +1,12 @@
+   Resolving toolchain
+    Resolved llvm@23.1.3 → @mcpp/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++
+      Target x86_64-unknown-linux-gnu
+    Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
+    Inferred target p-new (bin from src/main.cpp)
+   Compiling p-new v0.1.0 (.)
+
+    Finished dev [unoptimized + debuginfo] in 1.14s
+     Running `target/x86_64-linux-gnu/6fca180a97c5f98c/bin/p-new`
+
+Hello from p-new!
+Built with import std + std::println on modular C++23.
diff --git a/upgrade-lane-logs/new-run2.log b/upgrade-lane-logs/new-run2.log
new file mode 100644
index 00000000..3756ef79
--- /dev/null
+++ b/upgrade-lane-logs/new-run2.log
@@ -0,0 +1,4 @@
+     Running `target/x86_64-linux-gnu/6fca180a97c5f98c/bin/p-new`
+
+Hello from p-new!
+Built with import std + std::println on modular C++23.
diff --git a/upgrade-lane-logs/new-toolchain-list.log b/upgrade-lane-logs/new-toolchain-list.log
new file mode 100644
index 00000000..0c835ad8
--- /dev/null
+++ b/upgrade-lane-logs/new-toolchain-list.log
@@ -0,0 +1,33 @@
+Toolchains:
+     llvm 23.1.3             (packaging revision 1 available: `mcpp toolchain install llvm 23.1.3`)
+
+Targets:
+     TARGET                  NOTE                  TOOLCHAIN         STATUS
+     x86_64-linux-gnu        host                  llvm 23.1.3       installed
+     aarch64-linux-android   cross                 android-ndk 30.0.16248370available
+     aarch64-linux-gnu       cross                 llvm 23.1.3       via dependency graph
+     aarch64-linux-musl      static, cross         gcc 16.1.0        available
+     aarch64-none-elf        bare, static, cross   llvm 23.1.3       available
+     armv7a-none-eabi        bare, static, cross   llvm 23.1.3       available
+     armv7a-none-eabihf      bare, static, cross   llvm 23.1.3       available
+     riscv32-none-elf        bare, static, cross   llvm 23.1.3       available
+     riscv64-none-elf        bare, static, cross   llvm 23.1.3       available
+     thumbv6m-none-eabi      bare, static, cross   llvm 23.1.3       available
+     thumbv7em-none-eabi     bare, static, cross   llvm 23.1.3       available
+     thumbv7em-none-eabihf   bare, static, cross   llvm 23.1.3       available
+     thumbv7m-none-eabi      bare, static, cross   llvm 23.1.3       available
+     thumbv8m.base-none-eabi bare, static, cross   llvm 23.1.3       available
+     thumbv8m.main-none-eabi bare, static, cross   llvm 23.1.3       available
+     thumbv8m.main-none-eabihfbare, static, cross   llvm 23.1.3       available
+     wasm32-emscripten       wasm, static, cross   emsdk 6.0.9       available
+     x86_64-linux-android    cross                 android-ndk 30.0.16248370available
+     x86_64-linux-musl       static                gcc 16.1.0        available
+     x86_64-none-elf         bare, static, cross   llvm 23.1.3       available
+     x86_64-windows-gnu      PE, static, cross     gcc 16.1.0        available
+     x86_64-windows-musl     PE, static, cross     llvm 23.1.3       via dependency graph
+     riscv64-linux-musl      static, cross         —                 planned
+     x86_64-macos            cross                 —                 planned
+
+Available toolchains (run `mcpp toolchain install <family> <version>`):
+     gcc 16.1.0 / 15.1.0 / 13.3.0 / 11.5.0 / 9.4.0
+     llvm 22.1.8 / 20.1.7
diff --git a/upgrade-lane-logs/old-env.log b/upgrade-lane-logs/old-env.log
new file mode 100644
index 00000000..6b47703c
--- /dev/null
+++ b/upgrade-lane-logs/old-env.log
@@ -0,0 +1,21 @@
+     Bundled xlings 2026.10.16.2 (from the release of this mcpp: /tmp/lane/upgrade-lane/old/registry/bin/xlings)
+  Initialize mcpp sandbox layout (one-time)
+    Fetching package index (one-time)
+   Bootstrap patchelf into mcpp sandbox (one-time)
+  Installing xim:patchelf@0.18.0 done in 5.6s
+   Bootstrap ninja into mcpp sandbox (one-time)
+  Installing xim:ninja@1.12.1 done in 6.6s
+MCPP_HOME           = /tmp/lane/upgrade-lane/home
+xlings binary       = /tmp/lane/upgrade-lane/home/registry/bin/xlings
+xlings pinned       = 2026.10.16.2
+xlings home         = /tmp/lane/upgrade-lane/home/registry
+config              = /tmp/lane/upgrade-lane/home/config.toml
+build cache         = /tmp/lane/upgrade-lane/home/build-cache/v1
+meta cache          = /tmp/lane/upgrade-lane/home/cache
+default toolchain   = (none — run `mcpp toolchain install gcc 16.1.0`)
+
+Index repos:
+  mcpplibs https://github.com/mcpplibs/mcpp-index.git  [artifact]  (default)
+
+Toolchain       = gcc 13.3.0 (x86_64-linux-gnu)
+std module src  = 
diff --git a/upgrade-lane-logs/old-run.log b/upgrade-lane-logs/old-run.log
new file mode 100644
index 00000000..4f9d189b
--- /dev/null
+++ b/upgrade-lane-logs/old-run.log
@@ -0,0 +1,12 @@
+   Resolving toolchain
+    Resolved llvm@23.1.3 → @mcpp/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++
+      Target x86_64-unknown-linux-gnu
+    Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
+    Inferred target p-old (bin from src/main.cpp)
+   Compiling p-old v0.1.0 (.)
+
+    Finished dev [unoptimized + debuginfo] in 2.09s
+     Running `target/x86_64-linux-gnu/f24dd8c55f72810d/bin/p-old`
+
+Hello from p-old!
+Built with import std + std::println on modular C++23.
diff --git a/upgrade-lane-logs/old-tc-gcc.log b/upgrade-lane-logs/old-tc-gcc.log
new file mode 100644
index 00000000..822563f5
--- /dev/null
+++ b/upgrade-lane-logs/old-tc-gcc.log
@@ -0,0 +1,6 @@
+  Installing gcc@16.1.0 via mcpp's xlings
+ Downloading xim:binutils@2.42.1 done, 27.4 MB in 24.0s
+ Downloading xim:gcc@16.1.0 done, 101.7 MB in 9.9s
+   Installed gcc@16.1.0 → /tmp/lane/upgrade-lane/home/registry/data/xpkgs/xim-x-gcc/16.1.0/bin/g++
+
+Tip: `mcpp toolchain default gcc@16.1.0` to make this the default.
diff --git a/upgrade-lane-logs/old-tc.log b/upgrade-lane-logs/old-tc.log
new file mode 100644
index 00000000..3d4a6fa9
--- /dev/null
+++ b/upgrade-lane-logs/old-tc.log
@@ -0,0 +1,5 @@
+  Installing llvm@23.1.3 via mcpp's xlings
+ Downloading xim:glibc@2.44.3 done, 36.4 MB in 69.0s
+   Installed llvm@23.1.3 → /tmp/lane/upgrade-lane/home/registry/data/xpkgs/xim-x-llvm/23.1.3/bin/clang++
+
+Tip: `mcpp toolchain default llvm@23.1.3` to make this the default.