fix(test): make --build-timeout opt-in, and put the e2e's requires on line 2

Two defects in the previous commits, both caught by asking what the change does
to projects that are not this one.

--build-timeout defaulted to 900s. That would have turned slow-but-CORRECT
builds red: one mcpp-index member builds OpenCV from source and measures 1019s
on Linux and 1289s on Windows, so a fifteen-minute ceiling fails it and blames
mcpp. The asymmetry with --timeout is real and measured, not stylistic — a test
binary running over five minutes is unusual, a cold dependency build running
over fifteen is ordinary. How long a build may take is a property of the
project, so the project says it; mcpp only has to make saying it possible, and
that is what was missing. --timeout keeps its 300s default.

178_test_observability.sh carried `# requires: gcc unix-shell` inside the header
block. run_all.sh reads that line with `sed -n '2p'`, so it was inert: the test
ran on Windows, where <unistd.h> does not exist and where the deadline runner
has no kill-by-handle path, and failed for both reasons. Moved to line 2, and
narrowed to `unix-shell` — macOS is the platform this file exists for and it has
no GCC. The fixture's sleep is now <chrono>/<thread> so the fixture can never be
the reason a run fails.

Author: Sunrisepeak

.agents/docs/2026-07-31-test-observability-implementation-plan.md

@@ -14,7 +14,7 @@
 
 **做法(两条腿,因为 setvbuf 在 Windows 上不成立)**:
 
-1. `main.cpp` 入口 `std::setvbuf(stdout, nullptr, _IOLBF, 0)` —— 覆盖 POSIX,兜住所有不走 ui 的直接输出。
+1. `mcpp::ui::set_line_buffered()`(POSIX 上 `setvbuf(_IOLBF)`),由 `main()` 调用 —— 兜住所有不走 ui 的直接输出。**不能放 `main.cpp` 里**:非模块 TU 不允许开 global module fragment 引 `<cstdio>`(Clang 直接拒绝,GCC 静默接受)。**Windows 上不调用**:UCRT 的 `size` 合法范围是 `2..INT_MAX`,0 会走 invalid-parameter handler 直接 abort(0xC0000409 → git-bash 报 exit 127),而 MSVCRT 本来就把 `_IOLBF` 当 `_IOFBF`,靠 `ui::flush()` 即可。
 2. `mcpp::ui` 新增 `flush()`,并在 **每个写 stdout 的 ui 函数**末尾调用(`status` / `info` / `finished` / `plain` / `diagnostic` 的 stdout 分支)。这条在 Windows 上也确定有效,不依赖 `_IOLBF` 语义。
 3. `execute.cppm` 中 `mcpp test` 的裸 `std::println` 结果行(`... ok` / `FAIL (...)`)改走 `ui::plain`,从而继承 flush。
 
@@ -37,11 +37,13 @@
 **问题**:`--timeout` 只包住测试进程的**运行**。三处 `backend->build()`(`execute.cppm:1056` Phase A / `:1103` bulk / `:1126` per-test)全无期限。macOS 上 `modules/jsc` 卡在 14 次可执行链接上,`--timeout` 设多少都无效。
 
 **做法**:
-- `BuildOptions` 加 `buildTimeoutSecs`(0 = 不限,默认 **900**)。
+- `BuildOptions` 加 `buildTimeoutSecs`(0 = 不限,**默认 0 —— 见下**)。
 - `ninja_backend` 把 `capture_exec` 换成 `capture_exec_deadline`,超时返回 `BuildError{"build timed out after Ns", ...}`。
 - `run_tests` 三处 build 各自独立计时;超时报成**该成员的构建失败**,扇出继续下一个成员。
 - **平台限制如实写明**:`capture_exec_deadline` 在 Windows 上忽略 deadline(`process.cppm:96-99`),因此 `--build-timeout` 目前是 POSIX-only。文档标注,不假装跨平台。
 
+**默认为什么是关的**(与 `--timeout` 不对称,实测而非风格):单个测试跑过 5 分钟不寻常,冷依赖构建跑过 15 分钟很平常 —— mcpp-index 有成员要从源码建 OpenCV,linux 1019s / windows 1289s。默认上限会把「慢但正确」的构建判红。构建能跑多久是工程的性质,由工程来说。
+
 **验收**:e2e —— 一个故意慢的编译边在 `--build-timeout 1` 下被判超时且信息里带成员名。
 
 ---
@@ -101,4 +103,4 @@
 
 S1 → S2 → S4 → S5 → S7 → S3 → S6 → S8,每步自带测试。
 
-版本:`2026.7.31.2`(`2026.7.31.1` 已发布)。真源 `src/toolchain/fingerprint.cppm::MCPP_VERSION` + `mcpp.toml`,由 `.github/tools/check_version_pins.sh` 机器校验。
+版本:`2026.8.1.1`(`2026.7.31.1` 已发布)。真源 `src/toolchain/fingerprint.cppm::MCPP_VERSION` + `mcpp.toml`,由 `.github/tools/check_version_pins.sh` 机器校验。

CHANGELOG.md

@@ -21,7 +21,9 @@
 
 - **`mcpp test` 默认有界。** `--timeout` 的默认值从 `0`(不限)改为 **300 秒**;`--timeout 0` 仍然表示不限,只是现在要显式要求。无人值守的 CI 不该被一个挂住的测试吃掉整个 job,而「不限」作为默认值恰恰保证了它可以。
 
-- **`--build-timeout`(默认 900 秒)—— `--timeout` 覆盖不到的另一半。** 此前 `--timeout` 只包住测试**进程的运行**,而 `mcpp test` 的三次 ninja 驱动(包级构建、批量测试构建、逐测试构建)**全都没有期限**。实测一个 macOS lane 卡在某成员的 14 次可执行链接上超过 44 分钟,`--timeout` 设多大都无效。现在每次驱动各自独立计时,超时报成该成员的构建失败并继续下一个成员,失败行明确写「build timeout」而非笼统的 compile 失败。
+- **`--build-timeout`(默认关闭)—— `--timeout` 覆盖不到的另一半。** 此前 `--timeout` 只包住测试**进程的运行**,而 `mcpp test` 的三次 ninja 驱动(包级构建、批量测试构建、逐测试构建)**全都没有期限**。实测一个 macOS lane 卡在某成员的 14 次可执行链接上超过 44 分钟,`--timeout` 设多大都无效。现在每次驱动各自独立计时,超时报成该成员的构建失败并继续下一个成员,失败行明确写「build timeout」而非笼统的 compile 失败。
+
+  **它与 `--timeout` 不同,默认不开,这个不对称是实测出来的而非风格选择**:单个测试跑过 5 分钟不寻常,而冷依赖构建跑过 15 分钟很平常 —— mcpp-index 有一个成员要从源码建 OpenCV,实测 linux 1019s、windows 1289s。给它一个默认上限会把「慢但正确」的构建判红并让人以为是 mcpp 的错。构建可以跑多久是工程自身的性质,所以由工程来说;mcpp 只需要让「说得出来」成为可能 —— 而这正是原先缺的东西。
 
   平台限制如实说明:deadline 执行器在 Windows 上没有 kill-by-handle 路径,该值被忽略(POSIX only)。
 

docs/00-getting-started.md

@@ -87,15 +87,22 @@ mcpp test               # compile and run tests/**/*.cpp — one binary per file
 mcpp test <pattern>     # only tests whose name contains <pattern>
 mcpp test --list        # enumerate tests without building
 mcpp test --timeout 30  # kill a test still RUNNING after 30s (default 300; 0 = no limit)
-mcpp test --build-timeout 120   # kill a compile/link still running after 120s (default 900)
+mcpp test --build-timeout 120   # kill a compile/link still running after 120s (off by default)
 ```
 
-`mcpp test` is bounded by default so an unattended CI run cannot be consumed by a
-single hung test. The two deadlines cover different halves and neither implies the
-other: `--timeout` bounds the test *process*, `--build-timeout` bounds one ninja
-drive (the package build, the bulk test build, and each per-test build are timed
-separately). A link that never returns is a `--build-timeout` case, not a
-`--timeout` one. `--build-timeout` is POSIX-only — the deadline runner has no
+The *run* half is bounded by default so an unattended CI job cannot be consumed by
+a single hung test. The two deadlines cover different halves and neither implies
+the other: `--timeout` bounds the test *process*, `--build-timeout` bounds one
+ninja drive (the package build, the bulk test build, and each per-test build are
+timed separately). **A link that never returns is a `--build-timeout` case; no
+`--timeout` value stops it.**
+
+`--build-timeout` is off by default, and the asymmetry is measured rather than
+stylistic: a test binary running over five minutes is unusual, a cold dependency
+build running over fifteen is ordinary (one mcpp-index member builds OpenCV from
+source in 1019s on Linux and 1289s on Windows). A default ceiling would turn
+slow-but-correct builds red. How long a build may take is a property of the
+project, so the project says it. POSIX-only — the deadline runner has no
 kill-by-handle path on Windows, where the value is ignored.
 
 ## Adding Dependencies

docs/06-workspace.md

@@ -221,7 +221,7 @@ moment two members both have a `smoke`.
 
 ```bash
 mcpp test --workspace --timeout 60        # per-test RUN deadline (default 300)
-mcpp test --workspace --build-timeout 300 # per-ninja-drive deadline (default 900)
+mcpp test --workspace --build-timeout 300 # per-ninja-drive deadline (default 0 = no limit)
 mcpp test --workspace --workspace-timeout 1800   # whole fan-out (default 0 = no limit)
 ```
 

docs/zh/00-getting-started.md

@@ -88,14 +88,19 @@ mcpp test               # 编译并运行 tests/**/*.cpp —— 每文件一个
 mcpp test <pattern>     # 只运行名字包含 <pattern> 的测试
 mcpp test --list        # 只枚举测试,不构建
 mcpp test --timeout 30  # 单个测试**运行**超过 30s 被终止(默认 300;0 = 不限)
-mcpp test --build-timeout 120   # 单次编译/链接超过 120s 被终止(默认 900)
+mcpp test --build-timeout 120   # 单次编译/链接超过 120s 被终止(默认关闭)
 ```
 
-`mcpp test` 默认是**有界**操作 —— 无人值守的 CI 不该被一个挂住的测试吃掉整个 job。
-两个期限覆盖的是不同的一半,互不蕴含:`--timeout` 约束测试**进程的运行**,
-`--build-timeout` 约束**单次 ninja 驱动**(包级构建、批量测试构建、每个测试各自
-独立计时)。**链接卡死属于 `--build-timeout`,`--timeout` 设多大都无效。**
-`--build-timeout` 仅 POSIX 有效 —— Windows 上没有 kill-by-handle 路径,该值被忽略。
+**运行**那一半默认有界 —— 无人值守的 CI 不该被一个挂住的测试吃掉整个 job。两个期限
+覆盖的是不同的一半,互不蕴含:`--timeout` 约束测试**进程的运行**,`--build-timeout`
+约束**单次 ninja 驱动**(包级构建、批量测试构建、每个测试各自独立计时)。
+**链接卡死属于 `--build-timeout`,`--timeout` 设多大都无效。**
+
+`--build-timeout` 默认关闭,这个不对称是**实测**出来的而非风格选择:单个测试跑过 5 分钟
+不寻常,而冷依赖构建跑过 15 分钟很平常(mcpp-index 有一个成员要从源码建 OpenCV,
+linux 1019s、windows 1289s)。给它一个默认上限会把「慢但正确」的构建判红。构建可以跑多久
+是工程自身的性质,所以由工程来说。仅 POSIX 有效 —— Windows 上没有 kill-by-handle 路径,
+该值被忽略。
 
 ## 添加依赖
 

docs/zh/06-workspace.md

@@ -216,7 +216,7 @@ test_paths ... ok (0.31s)
 
 ```bash
 mcpp test --workspace --timeout 60        # 单测试**运行**期限(默认 300)
-mcpp test --workspace --build-timeout 300 # 单次 ninja 驱动期限(默认 900)
+mcpp test --workspace --build-timeout 300 # 单次 ninja 驱动期限(默认 0 = 不限)
 mcpp test --workspace --workspace-timeout 1800   # 整条扇出(默认 0 = 不限)
 ```
 

src/build/execute.cppm

@@ -806,7 +806,16 @@ export struct TestOptions {
     // Per-ninja-invocation deadline (Phase A, the bulk pass, and each per-test
     // drive are timed separately). Covers the half `--timeout` never could:
     // a compile or link that never returns. POSIX only — see BuildOptions.
-    int                buildTimeoutSecs = 900;
+    //
+    // Unlike timeoutSecs this defaults to OFF, and the asymmetry is measured,
+    // not stylistic. A single test binary running longer than five minutes is
+    // unusual; a cold dependency build taking longer than fifteen is ordinary —
+    // one mcpp-index member (OpenCV from source) measures 1019s on Linux and
+    // 1289s on Windows. A default ceiling would turn those slow-but-correct
+    // builds red and blame mcpp for it. "How long may a build take" is a
+    // property of the project, so the project says it; mcpp only has to make
+    // saying it possible, which is what was missing.
+    int                buildTimeoutSecs = 0;
 };
 
 // What one member's `run_tests` actually did. `--workspace` fans out over

src/cli.cppm

@@ -278,7 +278,7 @@ int run(int argc, char** argv) {
             .option(cl::Option("timeout").takes_value().value_name("SECS")
                 .help("Kill a test still RUNNING after SECS seconds (default 300; 0 = no limit)"))
             .option(cl::Option("build-timeout").takes_value().value_name("SECS")
-                .help("Kill a compile/link drive still running after SECS seconds (default 900; 0 = no limit; POSIX only)"))
+                .help("Kill a compile/link drive still running after SECS seconds (default 0 = no limit; POSIX only)"))
             .option(cl::Option("workspace-timeout").takes_value().value_name("SECS")
                 .help("Stop the --workspace fan-out after SECS seconds and report what did run (default 0 = no limit)"))
             .option(cl::Option("profile").takes_value().value_name("NAME")

tests/e2e/178_test_observability.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# requires: unix-shell
 # 178_test_observability.sh — `mcpp test` is streamed, timed and bounded.
 #
 # Four properties, each of which used to be absent and each of which cost a real
@@ -16,9 +17,15 @@
 #   4. `--build-timeout` bounds a hung compile/link — the half `--timeout`
 #      never covered, and the one that actually fires in practice.
 #
-# See .agents/docs/2026-07-31-test-workspace-observability-analysis.md.
+# The `# requires:` line above must stay on line 2 — run_all.sh reads it with
+# `sed -n '2p'`, so a requires buried in this block is silently inert (which is
+# how an earlier revision of this file ran on Windows and failed there).
+# unix-shell, not gcc: macOS is the platform this whole file exists for, and it
+# has no GCC. Windows is excluded on purpose — the deadline runner has no
+# kill-by-handle path there (mcpp.platform.process), so --timeout and
+# --build-timeout are documented POSIX-only and cannot be asserted.
 #
-# requires: gcc unix-shell
+# See .agents/docs/2026-07-31-test-workspace-observability-analysis.md.
 set -uo pipefail
 
 TMP=$(mktemp -d)
@@ -40,8 +47,9 @@ cat > fast/tests/quick.cpp <<'EOF'
 int main() { return 0; }
 EOF
 cat > slow/tests/hang.cpp <<'EOF'
-#include <unistd.h>
-int main() { sleep(30); return 0; }
+#include <chrono>
+#include <thread>
+int main() { std::this_thread::sleep_for(std::chrono::seconds(30)); return 0; }
 EOF
 
 # ── 1. streaming: output arrives while the process is still running ───────

tests/unit/test_test_options.cpp

@@ -6,17 +6,26 @@ import mcpp.build.execute;
 
 using namespace mcpp::build;
 
-// `mcpp test` has to be a BOUNDED operation. It was not: the per-test deadline
-// defaulted to 0 (no limit) and no deadline existed for the build drives at all,
-// so a single hung test or link could consume an entire unattended CI job with
-// nothing to show for it. These defaults are the contract; asserting them here
-// means "make it unbounded again" cannot happen by an unnoticed edit.
-TEST(TestOptions, DefaultsAreBounded) {
+// `mcpp test` has to be BOUNDABLE, and its run half bounded by default. It was
+// neither: the per-test deadline defaulted to 0 (no limit) and no deadline
+// existed for the build drives at all, so a single hung test or link could
+// consume an entire unattended CI job with nothing to show for it. These
+// defaults are the contract; asserting them here means neither half can drift
+// back by an unnoticed edit.
+TEST(TestOptions, RunIsBoundedByDefault) {
     TestOptions to;
     EXPECT_GT(to.timeoutSecs, 0) << "per-test run deadline must default to a limit";
-    EXPECT_GT(to.buildTimeoutSecs, 0) << "per-build-drive deadline must default to a limit";
     EXPECT_EQ(to.timeoutSecs, 300);
-    EXPECT_EQ(to.buildTimeoutSecs, 900);
+}
+
+// The build deadline deliberately does NOT default on, and the asymmetry is
+// measured: a test binary running over five minutes is unusual, a cold
+// dependency build running over fifteen is ordinary (one mcpp-index member
+// builds OpenCV from source in 1019s on Linux, 1289s on Windows). A default
+// ceiling would turn slow-but-correct builds red and blame mcpp for it.
+TEST(TestOptions, BuildDeadlineIsOptIn) {
+    TestOptions to;
+    EXPECT_EQ(to.buildTimeoutSecs, 0) << "a default build ceiling would fail legitimate cold builds";
 }
 
 // 0 is still reachable — "no limit" did not disappear, it just has to be asked