From 4859c7ebc02e1d98db1f06b63a3e12072baee100 Mon Sep 17 00:00:00 2001
From: Sunrisepeak <speakshen@163.com>
Date: Sat, 17 Oct 2026 12:15:20 +0900
Subject: [PATCH 1/4] 2026.10.17.1: an upgrade does not replace installed
 payloads inside a build; a dangling record does not fail every build; doctor
 reads, it does not change
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## What changes

- **Intent (D3).** `Fetcher::resolve_xpkg_path` takes a `PayloadIntent`:
  `Use` (build, run, test, pack, the runtime, host tools) takes a payload the
  provider calls usable and installs or replaces only one that is not;
  `Provision` (`mcpp toolchain install`) takes the index's current packaging;
  `Locate` never installs. A replacement says why (`Updating llvm@23.1.3
  packaging revision 0 → 1 (revision 0 is below the index's floor 1)`).
- **Failure (D5).** By the provider's error code: a deterministic refusal is
  neither retried through the command line nor followed by an index refresh,
  and its hint does not say retry; only `E_NOT_FOUND` refreshes, with a reason
  that is true (`could not be installed; the index may predate it`). A failed
  replacement of a usable payload names the revision still in use.
- **Currency where a person looks (D6).** `mcpp index update` lists installed
  payloads the refreshed index packages anew; `mcpp toolchain list` marks them
  (JSON `installedRevision` / `availableRevision`).
- **doctor (D7).** Read-only: one offline `prepare_build`; the toolchain it
  reports is what a build here uses (the configured default outside a package)
  with its payload's revision; a build that would install first is reported as
  that; mcpp's package home is summarized from xlings `binding_state`.
- **Identity (D8).** A toolchain payload's revision above 0 enters the driver
  identity (`payload-revision: <n>`).
- **xlings 2026.10.17.1** (openxlings/xlings#678): `payload_status` reports
  `complete` / `usable` / `current` apart; `unmet()` requires
  `payload_currency` and `binding_state`; `scope_repaired` events are shown
  (`Repaired c++@16.1.0 in mcpp's package home had no registration;
  deactivated`).
- **CI (D9).** `ci-upgrade.yml`: the previous release (read from GitHub at run
  time) builds a home; this commit's mcpp, laid out as a release, runs in it on
  Linux x86_64/aarch64, macOS and Windows; Linux adds an old-index variant
  (xim-pkgindex of 2026-10-07) and a dangling-record variant.

## Why

After `xlings self update && xlings update mcpp -y`, a user's every
`mcpp new && mcpp run` failed: `install of 'xim:llvm@23.1.3' failed ...
sysroot update refused before metadata changed: c++@16.1.0: installed asset
registration missing`. 2026.10.16.1 folded "is the packaging revision the
index's" into "is the payload complete", and mcpp treated "not complete" as
"not installed" inside the build; the replacement then met a dangling record
of another package and failed on every run, while `mcpp self doctor` started
the same replacement and reported `ok`. Measured on probe PR #814: a home of
the previous release downloads gcc (101.7 MB), glibc (36.7 MB) and llvm on its
first run after the upgrade, and the reported home fails with rc 101 on every
run on x86_64 and aarch64. Design: .agents/docs/2026-10-17-upgrade-continuity-design.md.

## Tests

- unit: `PmPayloadIntent.*` (the intent × usable × current matrix),
  `PmInstallFailurePolicy.*` (error code → refresh / retry).
- e2e 918: a toolchain payload re-recorded at another revision builds with no
  install call, `toolchain list` offers the other packaging, doctor installs
  nothing. Fails on 2026.10.16.3 (it downloads glibc, binutils, linux-headers
  and fails).
- ci-upgrade lane, run locally before push: orphan (the reported home) passes
  -- first run no download, `toolchain install` replaces llvm and reports the
  repaired record; snapshot passes -- `index update` names llvm 0 → 1 and
  glibc 2 → 4, no run downloads.

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
---
 .../2026-10-17-upgrade-continuity-design.md   | 266 +++++++++++++++++
 .agents/docs/README.md                        |   4 +-
 .github/actions/bootstrap-mcpp/action.yml     |   2 +-
 .github/actions/setup-macos-llvm/action.yml   |   2 +-
 .github/tools/upgrade_lane.sh                 | 197 +++++++++++++
 .github/workflows/bootstrap-macos.yml         |   2 +-
 .github/workflows/ci-bootstrap.yml            |   6 +-
 .github/workflows/ci-fresh-install.yml        |   6 +-
 .github/workflows/ci-linux-e2e.yml            |   2 +-
 .github/workflows/ci-upgrade.yml              |  64 +++++
 .github/workflows/ci.yml                      |   6 +
 .github/workflows/cross-build-test.yml        |   4 +-
 .github/workflows/release.yml                 |  14 +-
 CHANGELOG.md                                  |  50 ++++
 docs/09-commands-by-scenario.md               |  12 +-
 docs/20-toolchains.md                         |  25 +-
 docs/specs/package-identity.md                |  33 ++-
 docs/specs/toolchain-management.md            |  18 +-
 docs/zh/09-commands-by-scenario.md            |   9 +-
 docs/zh/20-toolchains.md                      |  19 +-
 mcpp.toml                                     |   2 +-
 modules/versioning/src/version.cppm           |   2 +-
 src/build/prepare/plan.cpp                    |   2 +-
 src/build/prepare/toolchain.cpp               |  12 +-
 src/build/prepare/toolchain_env.cpp           |   2 +-
 src/build/prepare/xlings.cpp                  |   2 +-
 src/doctor.cppm                               | 138 ++++++++-
 src/fetcher.cppm                              |   1 +
 src/fetcher/progress.cppm                     |  15 +
 src/pm/index_management.cppm                  |  12 +
 src/pm/package_fetcher.cppm                   | 267 ++++++++++++------
 src/pm/refresh_policy.cppm                    |  22 +-
 src/provider/provider.cppm                    |  16 +-
 src/provider/select.cppm                      |  24 ++
 src/provider/xlings/provider.cppm             |   3 +
 src/provider/xlings/xlings.cppm               |  16 +-
 src/toolchain/detect.cppm                     |  10 +
 src/toolchain/lifecycle.cppm                  |  50 +++-
 tests/e2e/52_local_path_namespaced_index.sh   |   2 +-
 .../e2e/58_preinstall_mcpp_deps_for_hooks.sh  |   2 +-
 tests/e2e/60_stale_xpkg_cache_reinstall.sh    |   2 +-
 ...732_xlings_refresh_is_bounded_and_owned.sh |   2 +-
 ...nvelope_reports_observed_network_access.sh |   2 +-
 ..._refresh_false_governs_first_index_sync.sh |   2 +-
 .../812_an_index_floor_is_a_closing_tip.sh    |   2 +-
 ...s_no_xlings_json_under_private_work_dir.sh |   2 +-
 .../916_a_home_from_before_keeps_working.sh   |   8 +-
 ...an_older_packaging_is_used_not_replaced.sh | 101 +++++++
 tests/unit/test_pm_package_fetcher.cpp        |  63 +++++
 upgrade-lane-logs/new-doctor.log              |  34 +++
 upgrade-lane-logs/new-index-update.log        |  15 +
 upgrade-lane-logs/new-provision.log           |  10 +
 upgrade-lane-logs/new-run-after-provision.log |  13 +
 upgrade-lane-logs/new-run-old-project.log     |   4 +
 upgrade-lane-logs/new-run-on-old-index.log    |  14 +
 upgrade-lane-logs/new-run1.log                |  12 +
 upgrade-lane-logs/new-run2.log                |   4 +
 upgrade-lane-logs/new-toolchain-list.log      |  33 +++
 upgrade-lane-logs/old-env.log                 |  21 ++
 upgrade-lane-logs/old-run.log                 |  12 +
 upgrade-lane-logs/old-tc-gcc.log              |   6 +
 upgrade-lane-logs/old-tc.log                  |   5 +
 62 files changed, 1546 insertions(+), 162 deletions(-)
 create mode 100644 .agents/docs/2026-10-17-upgrade-continuity-design.md
 create mode 100644 .github/tools/upgrade_lane.sh
 create mode 100644 .github/workflows/ci-upgrade.yml
 create mode 100755 tests/e2e/918_an_older_packaging_is_used_not_replaced.sh
 create mode 100644 upgrade-lane-logs/new-doctor.log
 create mode 100644 upgrade-lane-logs/new-index-update.log
 create mode 100644 upgrade-lane-logs/new-provision.log
 create mode 100644 upgrade-lane-logs/new-run-after-provision.log
 create mode 100644 upgrade-lane-logs/new-run-old-project.log
 create mode 100644 upgrade-lane-logs/new-run-on-old-index.log
 create mode 100644 upgrade-lane-logs/new-run1.log
 create mode 100644 upgrade-lane-logs/new-run2.log
 create mode 100644 upgrade-lane-logs/new-toolchain-list.log
 create mode 100644 upgrade-lane-logs/old-env.log
 create mode 100644 upgrade-lane-logs/old-run.log
 create mode 100644 upgrade-lane-logs/old-tc-gcc.log
 create mode 100644 upgrade-lane-logs/old-tc.log

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 000000000..ff5fc91a3
--- /dev/null
+++ b/.agents/docs/2026-10-17-upgrade-continuity-design.md
@@ -0,0 +1,266 @@
+---
+subject: design
+status: active
+---
+
+# 升级的连续性：打包修订不在使用路径上替换载荷、替换失败不拆掉可用状态、home 中的悬空记录自愈、真实的升级 lane
+
+- 日期：2026-10-17。状态：修订 2，O1、O2 按推荐项确定，实施中（§11）。
+- 起因：用户报告。`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 的同一个函数
+  规范化候选工作区：引用不存在注册的 `installed[]` 条目删除，悬空 active 按 O1 处理；规范化随事务提交，并以
+  事件报告（mcpp 原样显示）。投影预检只对本事务注册与移除的成员严格。
+- **X3** doctor：悬空记录的检测与 X2 的规范化是同一个函数；remedy 文本不再把 target 当包名（`xlings install c++`），
+  拥有者可知时给出 `xlings install <namespace>:<package>@<version>`，否则给出 `xlings use`；以 `interface` 提供
+  一致性摘要，供 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 de9396ca4..d039868d6 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 6d5efab51..b6366ab53 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 807df7ce2..e31d38365 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 000000000..74f133154
--- /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 0953ae26b..abd2f95d0 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 811a52f4d..05cdc6546 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 e27940be7..c6decda34 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 e4cf916a8..6add974f1 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 000000000..277f4bcdc
--- /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 3722d4a9c..7bd559a3f 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 fac33d54a..11752564d 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 a723324dc..9e0e73282 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 4039ae9ea..c60258300 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 9b23e7dd7..afef5b656 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 a7e763f38..77ed724df 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 a03bc7546..fc754ae02 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 e2c23fca4..5231cbcc5 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 c66437ce1..6aa3a2f13 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 9614b1135..cf04bd879 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 ca3ab7952..2622ec479 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 eb85b4eb8..79590a6ff 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 1fa6eee7e..474ff3f85 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 ee4e20bc2..d817caade 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 8e95f1409..870a557d2 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 a0c5d61e6..8e0b66acc 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 eee997038..babb6304d 100644
--- a/src/doctor.cppm
+++ b/src/doctor.cppm
@@ -192,13 +192,135 @@ 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.
+    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();
+        auto r = mcpp::build::prepare_build(/*print_fingerprint=*/false);
+        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 +458,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 +615,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 3fb55a88d..386803159 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 aa8e37907..f21574e34 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 47d14b764..788823aa0 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 1f727f8dd..1b53a3bd7 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,166 @@ 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 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].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};
+        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.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
+            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 785fa58e5..b6bf660f0 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 f42840ffb..a5f7716d6 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 65aa0a503..2bfc29e7d 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 bd882975d..ed646c276 100644
--- a/src/provider/xlings/provider.cppm
+++ b/src/provider/xlings/provider.cppm
@@ -246,6 +246,9 @@ 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>();
+                ps.usable = t.value("usable", false);
+                ps.current = t.value("current", false);
                 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 7a24b7428..fe8dfc0f2 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 9c5a15bd1..0e1b148ed 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 67ea87e4c..403bfc2b0 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/52_local_path_namespaced_index.sh b/tests/e2e/52_local_path_namespaced_index.sh
index 100f55856..799839cd4 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 36467432b..ae8d2b1ff 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 29093523a..6699ecde0 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 f3e20100d..c054edcbb 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 bc08b3cf3..0a195b09f 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 e536fc72e..b6f51dca9 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 d2d287cf2..5d653c597 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 f6c801b79..269df4167 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 56688cf29..7d29a8a56 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 000000000..03334a573
--- /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 46694e3d7..e080261d1 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 000000000..243d393b0
--- /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 000000000..dd00904c6
--- /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 000000000..dac05bba7
--- /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 000000000..3cc595b69
--- /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 000000000..ef5a3ea58
--- /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 000000000..cb90de84a
--- /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 000000000..b5a4c43b4
--- /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 000000000..3756ef791
--- /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 000000000..0c835ad87
--- /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 000000000..6b47703c6
--- /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 000000000..4f9d189be
--- /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 000000000..822563f55
--- /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 000000000..3d4a6fa91
--- /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.

From 6434a6040ec0571b1d60318d58739b8869e69bbb Mon Sep 17 00:00:00 2001
From: Sunrisepeak <speakshen@163.com>
Date: Sat, 17 Oct 2026 13:41:41 +0900
Subject: [PATCH 2/4] fix(provider): read an xlings 1.10 payload_status as it
 meant it

A build whose vendored xlings cannot be updated (no newer source beside the
mcpp binary; the hermetic container lane) talks to xlings 2026.10.16.2,
whose payload_status reports no usable/current. Read as absent, every
payload was unusable and a fresh install reported success and then
'payload is not complete'. 1.10's complete already required the recipe's
revision, so it is both usable and current; the 1.10 behaviour is kept.
A payload of another revision is announced as an update, not as
incomplete.

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
---
 src/pm/package_fetcher.cppm       | 12 ++++++++----
 src/provider/xlings/provider.cppm | 10 ++++++++--
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/pm/package_fetcher.cppm b/src/pm/package_fetcher.cppm
index 1b53a3bd7..2c3b12dff 100644
--- a/src/pm/package_fetcher.cppm
+++ b/src/pm/package_fetcher.cppm
@@ -1147,7 +1147,7 @@ Fetcher::resolve_xpkg_path(std::string_view target,
     // currency; this function only maps them through the caller's intent.
     struct Here {
         std::filesystem::path dir;      // empty: nothing there
-        bool usable = false, current = false;
+        bool complete = false, usable = false, current = false;
         int installed = -1, revision = 0, floor = 0;
     };
     const auto here = [&]() -> Here {
@@ -1157,7 +1157,7 @@ Fetcher::resolve_xpkg_path(std::string_view target,
             // 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].usable, st[0].current,
+            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
@@ -1168,7 +1168,7 @@ Fetcher::resolve_xpkg_path(std::string_view target,
         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, true, true};
+            return {dir, true, true, true};
         return {};
     };
 
@@ -1209,10 +1209,14 @@ Fetcher::resolve_xpkg_path(std::string_view target,
         if (now.usable)
             mcpp::ui::status("Updating", std::format("{}  packaging revision {} → {}",
                                                      label, now.installed, now.revision));
-        else if (now.installed >= 0 && now.installed < now.floor)
+        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));
     }
diff --git a/src/provider/xlings/provider.cppm b/src/provider/xlings/provider.cppm
index ed646c276..afc983e16 100644
--- a/src/provider/xlings/provider.cppm
+++ b/src/provider/xlings/provider.cppm
@@ -247,8 +247,14 @@ public:
                     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>();
-                ps.usable = t.value("usable", false);
-                ps.current = t.value("current", false);
+                // 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));
             }

From 0373bf759aa623950daeddbd7f91cba3365ec647 Mon Sep 17 00:00:00 2001
From: Sunrisepeak <speakshen@163.com>
Date: Sat, 17 Oct 2026 13:43:03 +0900
Subject: [PATCH 3/4] docs(design): X2/X3 as implemented

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
---
 .../docs/2026-10-17-upgrade-continuity-design.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/.agents/docs/2026-10-17-upgrade-continuity-design.md b/.agents/docs/2026-10-17-upgrade-continuity-design.md
index ff5fc91a3..75961a04b 100644
--- a/.agents/docs/2026-10-17-upgrade-continuity-design.md
+++ b/.agents/docs/2026-10-17-upgrade-continuity-design.md
@@ -5,7 +5,7 @@ status: active
 
 # 升级的连续性：打包修订不在使用路径上替换载荷、替换失败不拆掉可用状态、home 中的悬空记录自愈、真实的升级 lane
 
-- 日期：2026-10-17。状态：修订 2，O1、O2 按推荐项确定，实施中（§11）。
+- 日期：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` 不报错。
@@ -189,12 +189,14 @@ xlings（一次发布，mcpp 的 PR 把内置 xlings 钉到它）：
   它的依赖必须同为当前修订（llvm revision 1 的 cfg 指向 glibc revision 4 的 `lib64`，配上 revision 3 的 glibc
   就不自洽）。使用路径不受影响：按 P1，使用意图对一个 usable 的载荷根本不发起安装。（修订 1 曾写「依赖按
   usable 判断」，实施前的审读发现上述不自洽，改为此条。）
-- **X2** 元数据事务（`process_xvm_operations_`、`publish_removal_state_`）在计算投影之前，以 doctor 的同一个函数
-  规范化候选工作区：引用不存在注册的 `installed[]` 条目删除，悬空 active 按 O1 处理；规范化随事务提交，并以
-  事件报告（mcpp 原样显示）。投影预检只对本事务注册与移除的成员严格。
-- **X3** doctor：悬空记录的检测与 X2 的规范化是同一个函数；remedy 文本不再把 target 当包名（`xlings install c++`），
-  拥有者可知时给出 `xlings install <namespace>:<package>@<version>`，否则给出 `xlings use`；以 `interface` 提供
-  一致性摘要，供 mcpp doctor 读取。
+- **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 上必须失败。
 

From cdd3facb60946e4228d7c7178ff0575e062ecf50 Mon Sep 17 00:00:00 2001
From: Sunrisepeak <speakshen@163.com>
Date: Sat, 17 Oct 2026 14:16:59 +0900
Subject: [PATCH 4/4] fix(doctor): plan to describe, not to build

doctor's prepare is offline, and now plan_only with a scratch work_dir, as
`mcpp emit build-database` plans: the std module is described rather than
compiled, generated files are compared rather than written, and the lock
goes to the scratch directory. e2e 22 relied on doctor precompiling std as a
side effect; it now asserts the cache is still empty after doctor and makes
the std entry it lists with a build.

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
---
 src/doctor.cppm                      | 14 ++++++++++++--
 tests/e2e/22_doctor_cache_publish.sh | 15 ++++++++++-----
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/src/doctor.cppm b/src/doctor.cppm
index babb6304d..39be4c4ac 100644
--- a/src/doctor.cppm
+++ b/src/doctor.cppm
@@ -206,7 +206,11 @@ export int doctor_report() {
     // 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.
+    // 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)) {
@@ -215,7 +219,13 @@ export int doctor_report() {
         const bool wasQuiet = mcpp::ui::is_quiet();
         mcpp::ui::set_quiet(true);
         (void)mcpp::build::refusal::take();
-        auto r = mcpp::build::prepare_build(/*print_fingerprint=*/false);
+        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);
diff --git a/tests/e2e/22_doctor_cache_publish.sh b/tests/e2e/22_doctor_cache_publish.sh
index c33960d24..b10bc4db3 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