fix: bound split compilation and track active download progress

Author: Sunrisepeak

.agents/docs/2026-11-06-bmi-publication-and-compiler-cap-closeout.md

@@ -0,0 +1,132 @@
+---
+subject: build-progress-and-scheduling
+status: active
+---
+
+# BMI publication, compiler capacity and active download budgets
+
+Audience: maintainers closing the 2026.11.5.2 candidate and reviewing PR #889.
+This record separates three failures exposed during candidate validation.
+It does not qualify a diagnostic object substitution as a released binary.
+
+## Failure boundaries
+
+| Failure | Confirmed cause | Owner |
+|---|---|---|
+| An importer cannot find a BMI after its interface is touched | GCC unlinks the old final path before renaming the new BMI; an absent identity was accepted as publication | Core detached compilation |
+| A build exceeds its requested compiler count | Extra Ninja slots serve publication and join edges, while ordinary compilers bypass the detached semaphore | Core Ninja scheduling |
+| A newly activated download is immediately considered stalled | Its queued state was observed earlier; starting without a source attempt or byte change retained the queue-entry timestamp | Core provider progress tracking |
+
+No compiler toolchain payload, plugin semantic or timeout constant is changed
+by these corrections.
+
+## BMI publication
+
+GCC 16.1 tracing shows an `unlink(final)` immediately before
+`rename(temporary, final)`. The observed interval was approximately 26
+microseconds. A changed identity alone is therefore insufficient: publication
+requires a present file with a changed identity. The adapter still preserves
+the previous BMI for equivalence checking and failure recovery.
+
+The causal control amplifies only that existing unlink interval to 200
+milliseconds. The previous core reproduces the candidate failure: the middle
+module cannot read the core module. Replacing only the detached-compilation
+implementation makes the same real GCC workload succeed. A separate
+deterministic publisher confirms the boundary: the old phase returns zero
+while the BMI is absent; the corrected phase returns only after publication.
+
+An exit status of zero without the required BMI is diagnosed as a failure.
+The previous BMI is restored. E2E 234 retains its cold execution, graph-shape,
+incremental build and stale-token assertions, and adds both publication cases.
+
+## Shared compiler permits
+
+The candidate generated `sched_cap = 8`, while its scheduling policy allows
+48 Ninja slots. The BMI supervisor used that semaphore; ordinary C/C++
+compilation and compiler-driven scanning did not. A full local candidate
+build exceeded eight compiler processes and encountered memory-pressure
+kills. Its interrupted output is not build qualification.
+
+The selected correction retains one actual compiler budget. Under the
+detached strategy, ordinary built-in compilation and scanning use an internal
+argv executor holding the same permit until the real child exits. BMI
+supervisors continue to hold their permit across early publication and code
+generation. Join edges acquire no permit. A holder never waits for another
+permit, so waiting joins cannot form a permit dependency cycle.
+
+The internal executor introduces no user mode and no argument serialization.
+It receives the compiler's actual argv, inherits the existing streams and
+returns its status. Existing response files retain their original owner and
+encoding. Ordinary completion and interrupt cleanup release a permit once;
+release cannot remove a permit already acquired by another compiler.
+Failure to create or acquire the semaphore is reported rather than followed
+by an unbounded compile. A failed supervisor start releases its permit.
+
+The mixed control uses a real generated Ninja graph and GCC 16.1. A driver
+records active invocations and remains alive briefly after BMI publication,
+amplifying overlap with ordinary C and C++ units. With a requested cap of
+one, the previous graph reaches six active drivers. Corrected controls use
+caps of one and two, retain the extra Ninja slots, and observe peaks of
+exactly one and two. They also check no-op builds, ordinary compiler failure,
+a module failure after BMI publication, subsequent recovery, ordinary
+compiler cancellation, child termination and permit cleanup. E2E 234 retains
+the full-set stale-token reclamation check.
+
+These local controls use selected recompiled objects and an extracted copy of
+the production dispatch branch. They establish causality and small-load
+behavior. The complete current sources still require the ordinary CI build
+and all required checks before release.
+
+## Download activation and deadline reasons
+
+The pinned xlings 2026.10.26.1 provider reports queued files in each batch
+with `started = false`. Once a worker obtains a slot, `started` becomes true
+before a source attempt or byte count necessarily changes. That transition
+starts the active budget. Waiting in the queue consumes no active budget;
+repeated samples of an already active file do not renew it. A byte increase
+or source change retains its existing renewal semantics.
+
+An isolated provider invocation retained raw NDJSON from one download stream.
+Replaying the same 347 snapshots through the actual C++ provider modules gives:
+
+| Module | Expired snapshots | First expiration |
+|---|---:|---:|
+| Previous state machine | 11 | 95.751 seconds |
+| Corrected activation transition | 0 | none |
+
+The first false expiration belongs to a queued entry activated at 95.751
+seconds with source attempt zero. Its inherited age was 95.651 seconds.
+With queue time excluded, the maximum active idle interval at the observed
+snapshots is 7.735 seconds. The isolated network invocation reached its
+150-second observer budget; it was stopped by the experiment, not by a
+provider progress deadline, and does not establish a completed graphics run.
+
+The failed candidate CI log contains rendered status rather than raw NDJSON.
+Its timing is consistent with activation of the final queued entries. It
+does not identify which raw file state first expired, and is not presented as
+proof of a particular file's network behavior. Progress on an independent
+download remains insufficient to renew a genuinely stalled file.
+
+The provider source was followed through its HTTP implementation: the
+connect and idle environment budgets are consumed below the downloader
+wrapper. They remain eight and thirty seconds, respectively; the parent's
+per-file budget remains forty-five seconds. No budget is increased to hide
+the state error. Progress timeouts now identify the file, interval and source
+attempt; process deadlines remain distinct. Time-injected unit cases cover
+queue waits longer than forty-five seconds, genuine per-file stalls, source
+fallback and completion.
+
+## Qualification sequence
+
+The local controls precede the complete PR CI. The graphics job is accepted
+only after its shader, rendered-image and pixel assertions actually run.
+After every required check succeeds, an independent ecosystem review
+precedes merge and release. Published tags remain unchanged.
+
+Plugin PR #52 has independently passed all six jobs against the published
+2026.11.5.1 core. Its final public core pin and real subproject-sidecar fixture
+follow ordinary installation of the new release, in the same plugin PR.
+
+Public records contain synthetic assertions and aggregate evidence. Raw
+provider streams, user logs, usernames and private paths remain outside the
+repository and pull-request description.

.agents/docs/README.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-349 records.
+350 records.
 
 ## By subject
 
@@ -34,6 +34,10 @@ Records that declare one. Everything else is listed by date below.
 - [构建依赖的一条管线：配置与产物两轴、包的实例、库接口、兼容系统与工作空间收尾（#797）](2026-10-11-build-dependencies-one-pipeline-design.md) — active
 - [Four upstream asks from a UI framework: what each one is under mcpp's design, and the combined plan](2026-09-13-four-upstream-asks-from-a-ui-framework.md) — landed
 
+### build-progress-and-scheduling
+
+- [BMI publication, compiler capacity and active download budgets](2026-11-06-bmi-publication-and-compiler-cap-closeout.md) — active
+
 ### design
 
 - [升级的连续性：打包修订不在使用路径上替换载荷、替换失败不拆掉可用状态、home 中的悬空记录自愈、真实的升级 lane](2026-10-17-upgrade-continuity-design.md) — active
@@ -167,6 +171,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-11
 
+- [BMI publication, compiler capacity and active download budgets](2026-11-06-bmi-publication-and-compiler-cap-closeout.md) — active
 - [异构构建语义与插件边界补充方案（mcpp#885、mcpp#887）](2026-11-05-heterogeneous-build-semantics-and-plugin-boundaries-supplement.md) — active
 - [异构构建补充方案的第二轮调研与实验](2026-11-05-heterogeneous-build-research-and-experiments.md) — active
 - [生态 885 与异构构建补充方案的实现依赖](2026-11-05-heterogeneous-build-implementation-plan.md) — active

CHANGELOG.md

@@ -18,6 +18,15 @@
   an installation that the same subproject has yet to produce.
 - The macOS clean bootstrap keeps its stage-one compiler outside the output tree
   removed by the second stage.
+- GCC BMI publication requires a present replacement file; its unlink-before-rename
+  interval no longer releases importers. A successful compiler that produces no
+  BMI fails with a diagnostic and restores the previous BMI.
+- Ordinary compiler invocations share the detached GCC compilers' concurrency
+  permits, so the additional Ninja scheduling slots do not exceed `--jobs`.
+- Queued downloads begin their progress budget when a worker starts them,
+  rather than inheriting time spent waiting for a slot.
+- Provider progress timeouts identify the stalled download and source attempt,
+  independently of progress on other files and provider process deadlines.
 
 ### Changed
 

docs/04-mcpp-toml.md

@@ -1048,6 +1048,10 @@ with two behaviours has to be.
 
 `bmi_schedule` decides when importers are unblocked.
 
+With GCC and `bmi_schedule = "on"`, ordinary compilation and detached code
+generation share the same total `jobs` limit (2026.11.5.2+). Additional
+scheduling and join tasks do not increase the number of compiler processes.
+
 | value | |
 |---|---|
 | `"auto"` | **the default, and it currently means OFF** |

docs/25-home-indices-and-store.md

@@ -87,6 +87,14 @@ rules are in [SPEC-010](specs/home-initialization.md).
 without installing tools. `self config --mirror auto|CN|GLOBAL` updates only local
 configuration, so it remains usable while the network is broken.
 
+An install tracks byte progress and source changes separately for each active
+download. Time spent waiting for a download slot does not consume that budget.
+Progress on another file does not renew a stalled file's budget.
+From 2026.11.5.2, a stalled-download diagnostic names the file, elapsed interval
+and source attempt. Provider preparation and process timeouts are reported
+separately. Mirror selection
+uses `mcpp self config --mirror auto`, `CN` or `GLOBAL`.
+
 ### Retention of build outputs (2026.10.31.3+)
 
 The build cache under `build-cache/v1/` is shared by every project of the home;

docs/zh/04-mcpp-toml.md

@@ -972,6 +972,9 @@ bmi_schedule = "off"     # auto (default, = off) | on | off
 
 `bmi_schedule` 决定 importer 何时被解除阻塞。
 
+使用 GCC 且 `bmi_schedule = "on"` 时，普通编译与分离的代码生成共用同一个 `jobs` 总上限
+（2026.11.5.2+）。额外的调度和等待任务不增加编译器进程数量。
+
 | 取值 | |
 |---|---|
 | `"auto"` | **默认值，目前意味着关闭** |

docs/zh/25-home-indices-and-store.md

@@ -71,6 +71,11 @@ Windows 首次显式 `self init` 时，若 D 是可写的本地固定磁盘，
 `self env`、`self config`、`self doctor` 和 `toolchain list` 读取本地状态，不安装工具。
 `self config --mirror auto|CN|GLOBAL` 仅更新本地配置，因此网络故障时仍可使用。
 
+安装过程分别跟踪每个活动下载的字节进度与来源切换，等待下载槽位的时间不消耗该预算。
+其他文件取得进度不会延长停滞文件的预算。
+从 2026.11.5.2 起，下载停滞诊断会标明文件、停滞时长与来源尝试次数；provider 准备阶段与进程超时单独报告。
+镜像选择使用 `mcpp self config --mirror auto`、`CN` 或 `GLOBAL`。
+
 ### 构建产物的保留期（2026.10.31.3+）
 
 `build-cache/v1/` 下的构建缓存由 home 中所有工程共享；工程的 `target/` 属于工程自身。两者各有保留期，