docs: an older payload needs an index refresh before a reinstall names its runner

The sandbox verification of 2026.9.12.2 measured that removing and reinstalling an emsdk payload installed before openxlings/xim-pkgindex#823 reproduces the missing runner: mcpp refreshes its index copy when a resolution misses, not because a recipe changed. After 'mcpp index update' the snapshot's recipe writes the descriptor, the reinstalled payload names its runner, and the program prints its output. docs/20, its Chinese copy, the CHANGELOG entry and the #617 record now state the three steps and point at #621 for the missing diagnostic; the engine-gaps record adds the two findings the verification produced.

Author: speak-agent

.agents/docs/2026-09-12-a-verified-web-run-that-asked-the-host-for-node.md

@@ -97,7 +97,11 @@ states it. `.mcpp-toolchain.json` gains a fourth key.
 Both directions hold without coordination. An mcpp that predates the key ignores
 it, so the recipe ships first. A payload installed before the recipe wrote the
 descriptor has none, and its artefact runs through its own shebang exactly as
-before; reinstalling the payload adds the descriptor.
+before. Reinstalling the payload is not sufficient by itself: mcpp refreshes its
+index copy when a resolution misses, not because a recipe changed, so a remove
+and install reach the same recipe again. Measured during the sandbox
+verification of 2026.9.12.2 -- `mcpp index update` first, then remove and
+install, and the payload then carries the descriptor.
 
 ## Criteria
 
@@ -119,5 +123,6 @@ not found" and said nothing about runners. The reading above used a
 ## What remains
 
 An emsdk payload already installed on a machine keeps running through PATH until
-it is reinstalled. The published-artefact check is the sandbox verification
+the index is refreshed and the payload reinstalled, and mcpp does not say so
+when it happens (#621). The published-artefact check is the sandbox verification
 script's Web section, run again after this release.

.agents/docs/2026-09-12-engine-gaps-after-the-sdk-batch.md

@@ -603,3 +603,25 @@ code, and what was built instead.
     decline predates this change (#400). 645 distinguishes the two causes by the
     `toolchain=` lines the two builds record: identical lines report the host as
     not measured, and differing lines fail.
+
+12. **The sandbox verification of the release, and two findings outside it.**
+    Sections 1 to 15 held for the published 2026.9.12.2 installed from the
+    index, except the Web section, and openkal-emscripten 0.1.1's own check
+    held (the feature refused without the root table, and a task starting,
+    running and joining under node).
+    - **A home inside a subos cannot install a toolchain.** With the published
+      tarball extracted into the verification subos directory, the first
+      `mcpp build` failed at `gcc installed but registered none of the programs
+      it declares`, from xlings' post-install ledger check. 2026.9.11.4 failed
+      identically from the same placement, so the placement causes it. From the
+      xlings store, which is how a release is installed, the same section held.
+    - **A recipe change needs an index refresh, not a reinstall.** The Web
+      section failed with `/usr/bin/env: 'node'` because the sandbox home's
+      emsdk payload predates openxlings/xim-pkgindex#823. Removing and
+      reinstalling reproduced it: the index copy still held the old recipe, and
+      mcpp refreshes on a resolution miss rather than on a recipe change. After
+      `mcpp index update`, the snapshot's recipe writes the descriptor, the
+      reinstalled payload names its runner, and the program prints its output.
+      docs/20, its Chinese copy, the CHANGELOG and the #617 record now state the
+      three steps; mcpp#621 tracks the diagnostic that would make the failure
+      self-explaining.

CHANGELOG.md

@@ -33,8 +33,10 @@ Emscripten 链接产出的是首行为 `#!/usr/bin/env node` 的 JavaScript 启
 - 结构错误的 `runner`(非字符串、为空、含反斜杠、含 `.` 或 `..` 分量)按描述文件的既有
   规则拒绝,并点名该文件。
 - `xim:emsdk` 的配方写出 `runner`(openxlings/xim-pkgindex#823)。早于这个键的 mcpp
-  忽略它,所以配方可以先发;在此之前安装的 emsdk 载荷没有描述文件,行为与之前相同,重新
-  安装后获得。
+  忽略它,所以配方可以先发;在此之前安装的 emsdk 载荷没有描述文件,行为与之前相同。要让它获得
+  描述文件,需先 `mcpp index update` 再 `mcpp toolchain remove emsdk@<版本>` 与
+  `mcpp toolchain install emsdk <版本>`:仅重装会再次按同一份配方安装,因为索引只在解析未命中
+  时刷新。2026.9.12.2 的沙箱验证实测了这三步;mcpp 目前不会对这种失败作出解释(#621)。
 
 ### Windows GUI 可执行文件:`windows_subsystem` 与 `windows_entry`(#618)
 

docs/20-toolchains.md

@@ -596,7 +596,14 @@ so no `node` on PATH is involved. A payload's runner is one program with the
 artefact path appended; it is either relative to the payload or absolute inside
 the package store that holds the payload, and a path outside that store is
 ignored. A payload installed before its recipe wrote the key has no descriptor,
-and its artefact runs through its own `#!/usr/bin/env node` line as before.
+and its artefact runs through its own `#!/usr/bin/env node` line as before. To
+give such a payload a descriptor, refresh the index first and then reinstall:
+`mcpp index update`, then `mcpp toolchain remove <spec>` and
+`mcpp toolchain install <spec>`. A reinstall alone installs from the same recipe
+again, because the index is refreshed when a resolution misses and not because a
+recipe changed; measured in the sandbox verification of 2026.9.12.2. Until then
+the failure is the interpreter's own (`/usr/bin/env: 'node': No such file or
+directory`), which mcpp does not yet explain (#621).
 
 For a target whose artifact runs elsewhere, the `runner` key is an argv prefix
 and the session belongs to a package rather than to the engine:

docs/zh/20-toolchains.md

@@ -541,7 +541,11 @@ macos_deployment_target = "14.0" # Apple
 使用这个程序,因此不涉及 PATH 上的 `node`。载荷的 runner 是一个程序,产物路径追加在后;
 它或是载荷内的相对路径,或是持有该载荷的包存储之内的绝对路径,存储之外的路径一律忽略。
 在配方写出这个键之前安装的载荷没有描述文件,其产物仍按自身的 `#!/usr/bin/env node`
-一行运行,与之前相同。
+一行运行,与之前相同。要让这样的载荷获得描述文件,先刷新索引再重装:`mcpp index update`,
+然后 `mcpp toolchain remove <spec>` 与 `mcpp toolchain install <spec>`。仅重装会再次按同一份
+配方安装,因为索引只在解析未命中时刷新,而不因配方变化而刷新;这一点在 2026.9.12.2 的沙箱
+验证中实测。在此之前,失败信息来自解释器自身(`/usr/bin/env: 'node': No such file or
+directory`),mcpp 尚未对它作出解释(#621)。
 
 对于产物在别处运行的目标,`runner` 键是一个 argv 前缀,而那个会话属于一个**包**而不属于引擎: