2026.9.29.5: a build reports each step once, with its outcome, and a status line states the build while it runs

The validation project's cross-verification of this pull request printed
nothing for 40 minutes between the last `Compiling` line and `Finished`:
ninja ran with `--quiet` and its output was examined after it exited.
Design: .agents/docs/2026-09-29-build-progress-display-design.md.

- ninja runs without `--quiet` and is read line by line (stream_exec). Its
  status lines (NINJA_STATUS, with an escape-sequence prefix that a nested
  ninja's relayed copy loses) give the counts; its log gives which step
  finished and when it started and ended; a step record written beside
  build.ninja (steps.tsv) names each step's package and identity; the
  `__action` wrapper reports when a check or prepare action starts.
- A package's line is written when every step the graph assigns to it has
  run, or when the build ends: `done <span>`, `cached N units`, `failed`, or
  the steps that ran. Requested packages are listed, dependencies folded into
  one line; --verbose lists every package and each step as `[f/t] <command>`.
- A build program has one line: `ran <time>`, `cached`, `failed`; `waiting`,
  `compiling` and `running` while live.
- On a terminal the live lines and one status line are drawn below the output
  (mcpp.ui's region, one writer for every line, ten frames a second at most);
  in a log the status line is written after a minute of silence.
- A failed step is reported when it fails, not after ninja exits.
- `Finished` states the whole command's time and, for ten seconds or more,
  how it was spent and the dominant step.
- Terminal detection works on macOS and Windows; a Windows console receives
  UTF-16. mcpp.log stays a leaf: mcpp.ui installs the terminal sink for its
  verbose records, and the model logs its events to the log file.
- e2e 842 (log medium) and 843 (a pseudo-terminal); unit tests of the
  readers, the record, the text measures, the region and the completion rule;
  the e2e tests that read the old lines follow them, and those that read a
  `Compiling` line as "the build planned" ask build.ninja's time instead.
- docs/00, 09, 30, 40 in both languages; CHANGELOG.

Author: speak-agent

.agents/docs/2026-09-29-build-progress-display-design.md

@@ -10,10 +10,42 @@ This release completes the workspace build graph in the commands around the
 build, from the validation project's post-release run of 2026.9.29.4: build
 programs are reused across selections and run dependencies first, the build
 database and `--configure-only` plan by configuration, and the output names
-what it reports.
+what it reports. A build now reports each step when its outcome is known, and
+shows what runs while it runs (`.agents/docs/2026-09-29-build-progress-display-design.md`).
+
+### Added
+
+- **A build reports each step once, with its outcome.** A package's line is
+  written when every step the graph assigns to it has run (`done` with the
+  span of its steps, read from ninja's log), when the global cache supplied it
+  (`cached N units`), when a step of it failed (`failed`), or when the build
+  ends. A package with nothing to do has no line. The packages the command was
+  asked to build are listed; their dependencies are folded into one line, and
+  a dependency that fails is named. `--verbose` lists every package and prints
+  each step as ninja reports it (e2e 842).
+- **A status line states the build.** On a terminal the steps still running
+  and one status line, `Building 612/1203 · 14:32 · gpp.gui: vcpkg install
+  6:10`, are drawn below the output and updated in place; the status line
+  names the longest-running `check` or `prepare` action, which the engine's
+  action wrapper reports when it starts. In a log (CI, a pipe) only final lines
+  are written, and the status line is written when the log has been silent for
+  a minute (e2e 842, 843).
+- **`Finished` states the whole command's time**, and for a command of ten
+  seconds or more how it was spent (`plan`, `programs`, `build`) and the step
+  that took at least a quarter of the build.
 
 ### Fixed
 
+- **A failed step is reported when it fails.** Its diagnostics were printed
+  after ninja exited, that is, after every step still running had finished:
+  a compile error beside a twenty-minute vcpkg install appeared twenty minutes
+  late (e2e 842).
+- **macOS and Windows terminals are terminals.** Terminal detection was
+  compiled only under `__unix__`, which Apple's compilers do not define, so
+  the download bar and colours were drawn on Linux alone. A Windows console
+  now receives mcpp's lines as UTF-16, so `·`, `→` and non-ASCII paths appear
+  as written whatever its code page.
+
 - **A member's build program is reused whichever members a command selects.**
   Its graph document listed every requester in the plan, the virtual root
   included, so the program's re-run key followed the selection: `-p`, `mcpp
@@ -37,9 +69,16 @@ what it reports.
 
 ### Behaviour changes
 
-- **The build program status lines name the package**:
-  `build.mcpp compiling <package>`, `running <package>`,
-  `up to date <package> (cached)` (e2e 839).
+- **A build program has one line, which names its package and states its
+  outcome**: `build.mcpp <package>  ran <time>`, `cached` or `failed`, in
+  place of `build.mcpp compiling <package>` and `running <package>`, and of
+  `up to date <package> (cached)` (e2e 839, 842). The programs of the
+  requested packages are listed, and those of their dependencies are folded
+  into one line.
+- **`Compiling <package>` is written when the package's steps have run**, with
+  their outcome, rather than for every direct dependency before ninja starts;
+  the per-dependency `Cached <package> (N units)` line is `--verbose` output,
+  as `cached N units` (e2e 842).
 - **A selected member is announced by its directory** in a `--workspace`
   build, also where another member depends on it (e2e 839).
 - **`mcpp pack` summarises many outputs.** A format that reports more than

CHANGELOG.md

@@ -144,7 +144,8 @@ int main() {
 ```console
 $ mcpp run
     Inferred target hello (bin from src/main.cpp)
-   Compiling hello v0.1.0 (.)
+   Compiling hello v0.1.0 (.)  done 0.61s
+
     Finished dev [unoptimized + debuginfo] in 0.64s
      Running `target/x86_64-linux-gnu/0946988e9e4b52ba/bin/hello`
 

docs/00-what-mcpp-is.md

@@ -227,6 +227,56 @@ An index refresh is reported step by step when the xlings that mcpp drives
 emits progress events for it (xlings 2026.9.28.1+). With an older xlings it
 shows its status line and finishes silently, as before.
 
+## What a build prints
+
+A build reports each step once, when its outcome is known (2026.9.29.5+):
+
+```console
+$ mcpp build --workspace
+  build.mcpp gpp.core                     ran 16.00s
+  build.mcpp gpp.gui                      ran 6.70s
+   Compiling gpp.core (GalTranslPP)       done 3m12s
+   Compiling 23 dependencies              done 6m20s
+   Compiling gpp.gui (GPPGUI)             done 38m05s
+
+    Finished fast-release [unoptimized + debuginfo] in 41m53s · plan 1m13s · programs 32s · build 40m08s · longest gpp.gui: vcpkg install 22m10s
+```
+
+- A package's line names the package and states its outcome: `done` with the
+  span of its steps, `cached` when the global cache supplied it, `failed`, or
+  the number of its steps that ran when a failed build stopped before the
+  package completed. A package with nothing to do has no line.
+- The packages the command was asked to build (the root package, or the
+  selected members) are listed. The packages they depend on are folded into
+  one line, and a dependency that fails is named.
+- A build program's line states `ran` with its time, `cached`, or `failed`.
+- A failed step is reported when it fails, with its diagnostics, while ninja
+  waits for the steps still running.
+- `Finished` states the whole command's time. A command of ten seconds or
+  more also states how the time was spent, and names the step that took at
+  least a quarter of the build when there is one.
+
+On a terminal, the steps still running and one status line are drawn below
+the output and updated in place:
+
+```
+   Compiling gpp.gui (GPPGUI)             61 steps
+
+Building 612/1203 · 14:32 · gpp.gui: vcpkg install 6:10
+```
+
+The status line counts the build's steps, shows the time since the command
+started, and names the longest-running `check` or `prepare` action; ninja
+reports every other step only when it finishes. When the output is not a
+terminal (a CI log, a pipe), only final lines are written, and the status line
+is written when the output has been silent for a minute. `TERM=dumb` selects
+that form on a terminal too.
+
+`--verbose` lists every package, including those with nothing to do (`fresh`),
+states each build program's compile and run times, and prints every step as
+ninja reports it (`[f/t] <command>` and its output). `--quiet` prints none of
+it. Machine output (`--message-format json`) is unchanged.
+
 ## Validating a descriptor before publishing
 
 `mcpp xpkg parse` reads a descriptor with the resolver's own grammar, so what

docs/09-commands-by-scenario.md

@@ -1518,9 +1518,13 @@ variable, emit `mcpp:rerun-if-changed=config.h` / `mcpp:rerun-if-env-changed=USE
 This replaces the old "process exited 0, so assume it's fine" guesswork with an
 explicit input/output contract — incremental builds stay correct.
 
-When nothing changed the output is `build.mcpp up to date <package> (cached)`;
-otherwise `build.mcpp compiling <package>` / `running <package>` (the package
-is named from 2026.9.29.5 on).
+Each program has one line, written when it finishes (2026.9.29.5+):
+`build.mcpp <package>  cached` when nothing changed, `build.mcpp <package>  ran
+<time>` when it was compiled or run (with `--verbose`, `compiled <time> · ran
+<time>`), and `failed` when it failed. On a terminal the line shows `waiting`,
+`compiling` or `running` with a clock while the program is pending or running.
+The programs of the packages the command was asked to build are listed; those of
+their dependencies are folded into one line, `build.mcpp N dependencies`.
 
 ## Host tools from a dependency (mcpp 2026.8.5.1+)
 

docs/30-build-mcpp.md

@@ -200,18 +200,18 @@ cd blinky
 mcpp run
 ```
 
-Measured output:
+Output (2026.9.29.5; the times vary by machine):
 
 ```
    Resolving toolchain
     Resolved llvm@22.1.8 → riscv64-none-elf → @mcpp/registry/data/xpkgs/xim-x-llvm/22.1.8/bin/clang++
     Resolved host toolchain for build.mcpp: clang 22.1.8 (x86_64-unknown-linux-gnu)
-  build.mcpp compiling blinky
-  build.mcpp running blinky
+  build.mcpp blinky  ran 0.41s
     Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
     Inferred target blinky (bin from src/main.cpp)
-   Compiling blinky v0.1.0 (.)
-      Cached riscv-virt-rt v0.3.0 (1 unit)
+   Compiling blinky v0.1.0 (.)  done 0.04s
+   Compiling 1 dependency       cached
+
     Finished dev [unoptimized + debuginfo] in 0.05s
         Size blinky  text 8572  data 80  bss 5668  total 14320
      Running `…/xim-x-qemu-riscv/9.2.4-1/bin/qemu-system-riscv64 … target/riscv64-none-elf/…/bin/blinky`

docs/40-baremetal.md

@@ -125,7 +125,8 @@ int main() {
 ```console
 $ mcpp run
     Inferred target hello (bin from src/main.cpp)
-   Compiling hello v0.1.0 (.)
+   Compiling hello v0.1.0 (.)  done 0.61s
+
     Finished dev [unoptimized + debuginfo] in 0.64s
      Running `target/x86_64-linux-gnu/0946988e9e4b52ba/bin/hello`
 

docs/zh/00-what-mcpp-is.md

@@ -209,6 +209,48 @@ commit 记进 `mcpp.toml`;`mcpp index unpin` 移除它。
 当 mcpp 驱动的 xlings 为索引刷新发出进度事件时（xlings 2026.9.28.1+），索引刷新
 逐步报告。较旧的 xlings 下，它显示其状态行，然后安静地结束，与以前相同。
 
+## 构建输出
+
+构建在每一步的结果已知时报告一次（2026.9.29.5+）：
+
+```console
+$ mcpp build --workspace
+  build.mcpp gpp.core                     ran 16.00s
+  build.mcpp gpp.gui                      ran 6.70s
+   Compiling gpp.core (GalTranslPP)       done 3m12s
+   Compiling 23 dependencies              done 6m20s
+   Compiling gpp.gui (GPPGUI)             done 38m05s
+
+    Finished fast-release [unoptimized + debuginfo] in 41m53s · plan 1m13s · programs 32s · build 40m08s · longest gpp.gui: vcpkg install 22m10s
+```
+
+- 包的行写出包名与结果：`done` 后接其各步骤的跨度，`cached` 表示由全局缓存提供，
+  `failed`，或者在失败的构建于该包完成前停止时，写出它已运行的步骤数。没有工作
+  的包不写行。
+- 命令被要求构建的包（根包或被选中的成员）逐个列出；它们依赖的包折叠为一行，
+  失败的依赖单独写出名字。
+- 构建程序的行写出 `ran` 及其耗时、`cached` 或 `failed`。
+- 一个步骤失败时立即报告，连同其诊断；ninja 此时仍在等待正在运行的步骤。
+- `Finished` 写出整条命令的耗时。十秒及以上的命令还写出时间的分布，并在某一步
+  占构建阶段四分之一以上时写出这一步。
+
+在终端上，仍在运行的步骤与一行状态行绘制在输出下方，并原地更新：
+
+```
+   Compiling gpp.gui (GPPGUI)             61 steps
+
+Building 612/1203 · 14:32 · gpp.gui: vcpkg install 6:10
+```
+
+状态行给出构建的步骤计数、自命令开始以来的时间，以及运行最久的 `check` 或
+`prepare` 动作；其他步骤 ninja 只在完成时报告。输出不是终端时（CI 日志、管道），
+只写最终的行，并在输出静默一分钟时写一次状态行。`TERM=dumb` 在终端上也选择
+这种形式。
+
+`--verbose` 列出每个包（包括没有工作的包，记为 `fresh`），写出每个构建程序的编译
+与运行耗时，并按 ninja 的报告打印每一步（`[f/t] <命令>` 及其输出）。`--quiet`
+不打印这些。机器输出（`--message-format json`）不变。
+
 ## 发布前校验描述符
 
 `mcpp xpkg parse` 用解析器自己的文法读一个描述符，所以它报告的就是解析时

docs/zh/09-commands-by-scenario.md

@@ -1276,8 +1276,11 @@ mcpp **不会**每次构建都重跑 `build.mcpp`。它会缓存程序产出的
 `mcpp:rerun-if-changed=config.h` / `mcpp:rerun-if-env-changed=USE_FAST`。这用一份明确的
 输入/输出契约取代了过去「进程退出码为 0 就当成功」的猜测——让增量构建保持正确。
 
-无变化时输出 `build.mcpp up to date <包名> (cached)`；否则是 `build.mcpp compiling <包名>` /
-`running <包名>`(自 2026.9.29.5 起写出包名)。
+每个程序一行，在程序结束时写出（2026.9.29.5+）：无变化时是 `build.mcpp <包名>  cached`，
+编译或运行过时是 `build.mcpp <包名>  ran <耗时>`（`--verbose` 下为 `compiled <耗时> · ran
+<耗时>`），失败时是 `failed`。在终端上，程序等待或运行期间该行显示 `waiting`、`compiling`
+或 `running` 及计时。命令被要求构建的包的程序逐个列出；其依赖的程序折叠为一行
+`build.mcpp N dependencies`。
 
 ## 依赖产出的 host 工具（mcpp 2026.8.5.1+）
 

docs/zh/30-build-mcpp.md

@@ -170,18 +170,18 @@ cd blinky
 mcpp run
 ```
 
-实测输出：
+输出（2026.9.29.5；耗时因机器而异）：
 
 ```
    Resolving toolchain
     Resolved llvm@22.1.8 → riscv64-none-elf → @mcpp/registry/data/xpkgs/xim-x-llvm/22.1.8/bin/clang++
     Resolved host toolchain for build.mcpp: clang 22.1.8 (x86_64-unknown-linux-gnu)
-  build.mcpp compiling blinky
-  build.mcpp running blinky
+  build.mcpp blinky  ran 0.41s
     Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
     Inferred target blinky (bin from src/main.cpp)
-   Compiling blinky v0.1.0 (.)
-      Cached riscv-virt-rt v0.3.0 (1 unit)
+   Compiling blinky v0.1.0 (.)  done 0.04s
+   Compiling 1 dependency       cached
+
     Finished dev [unoptimized + debuginfo] in 0.05s
         Size blinky  text 8572  data 80  bss 5668  total 14320
      Running `…/xim-x-qemu-riscv/9.2.4-1/bin/qemu-system-riscv64 … target/riscv64-none-elf/…/bin/blinky`