fix: redraw action snapshots between Ninja status lines

Author: Sunrisepeak

.agents/docs/2026-11-05-heterogeneous-build-implementation-plan.md

@@ -507,3 +507,25 @@ latest，实际执行输出 `mcpp 2026.11.5.1`；安装后的 ELF 与公开安
 修复也明确要求 PR、新版本及原发布门禁。新最终提交仍须完成完整 CI 和随后
 生态审查；仅在通过后合入并创建新 tag，按用户指定顺序优先 release，及时用
 本地 gtc 补 GitCode，完成索引和实际安装后再恢复 main CI。
+
+## 21. 内部快照与界面刷新之间的通知（2026-11-05）
+
+最终版本提交 `08fb971f` 的 CI `42025082619` 在原 1013 E2E 首次终端输出
+断言失败。缓存归属记录的首次读取修正仍有效；这次进一步核对发现，异步轮询
+接受内部快照后并未请求界面刷新。无 Ninja 输出和其他叙述时，界面依靠一秒
+时钟刷新，而原 fixture 的阶段只持续 0.75 秒，因而可能在实际绘制前结束。
+此前同一测试通过不能排除该时序缺口，也不能用原样重试代替修正。
+
+快照读取现在报告是否接受了新的序号，轮询在释放模型锁后请求现有 UI frame。
+各构建的结果采用非短路聚合，仍读取全部活跃动作；无更新、无效或旧序号不
+请求额外 frame。原十帧每秒上限、命令完成、快照非权威性以及锁顺序均保持。
+
+新增回归检查实际渲染输出：先绘制初始 frame，再发布快照，在一秒时钟刷新
+之前结束观察；既不提供 Ninja stdout，也不补充其他叙述。仅替换进度模块的
+固定对象对照中，上一模块在此检查失败，修正后完整 26 项进度检查通过。
+正常 1013 E2E 保持原 0.25 秒更新间隔及全部断言，并通过修正后的诊断二进制。
+另有 0.001 秒的历史短动作探针，其失败不代表原 1013 测试失败；局部探针的
+时序结果不能替代实际输出回归与最终完整 CI。正式 E2E 未加入等待观察的握手。
+
+该补充继续使用 PR #889 与 2026.11.5.2。新的最终提交仍须完整 CI 以及其后
+独立生态审查，通过后才合入和发布；CLion 两仓库的兼容性结果不受此门禁替代。

CHANGELOG.md

@@ -11,6 +11,8 @@
 - Cached builds load action ownership when an action starts, so internal progress
   appears while Ninja is still buffering stdout. Idle builds retain lazy loading;
   command results and output checks remain authoritative.
+- New action snapshots request a normal UI frame, so short phases can appear
+  between Ninja status lines without waiting for the clock redraw.
 - The macOS clean bootstrap keeps its stage-one compiler outside the output tree
   removed by the second stage.
 

src/build/progress.cppm

@@ -1035,14 +1035,18 @@ void read_starts(Report& r, Build::Impl& b, std::vector<std::string>& out) {
 
 // Read only active graph actions. Snapshot counts never complete an action;
 // the ninja log removes it from running only after the command has finished.
-void read_action_progress(Build::Impl& build) {
-    if (build.progressDir.empty()) return;
+bool read_action_progress(Build::Impl& build) {
+    if (build.progressDir.empty()) return false;
+    bool changed = false;
     for (auto& action : build.running) {
         auto snapshot = action_progress::read(
             action_progress::channel(build.progressDir, action.stamp));
-        if (snapshot && (!action.snapshot || snapshot->seq > action.snapshot->seq))
+        if (snapshot && (!action.snapshot || snapshot->seq > action.snapshot->seq)) {
             action.snapshot = std::move(snapshot);
+            changed = true;
+        }
     }
+    return changed;
 }
 
 // The builds whose Build object is alive: the frame, the poll and the status
@@ -1178,6 +1182,7 @@ mcpp::ui::Frame frame() {
 void poll() {
     auto& r = report();
     std::vector<std::string> out;
+    bool progressChanged = false;
     {
         std::lock_guard lock(r.m);
         if (r.game && r.keys)
@@ -1191,10 +1196,13 @@ void poll() {
         for (auto const& b : live_builds(r)) {
             read_starts(r, *b, out);
             read_log(r, *b, out);
-            read_action_progress(*b);
+            progressChanged |= read_action_progress(*b);
         }
     }
     write_lines(out);
+    // A snapshot can arrive between Ninja status lines. Wake the normal
+    // frame writer instead of waiting for its one-second clock redraw.
+    if (progressChanged) mcpp::ui::touch_region();
 }
 
 // The status row's screen, as MCPP_PROGRESS asks: `random` (the default) or

tests/unit/test_build_progress.cpp

@@ -369,6 +369,40 @@ TEST(ProgressModel, AnActionStartLoadsTheFastPathRecordBeforeNinjaWritesStdout)
     // No Build::status() or completed ninja-log entry was supplied.
 }
 
+TEST(ProgressModel, ANewSnapshotRedrawsBeforeTheClockHeartbeat) {
+    namespace telemetry = mcpp::build::action_progress;
+    Tmp tmp;
+    Record rec;
+    rec.packages = {{"progress-redraw", true, "r", 0, 1, "", "project"}};
+    rec.owner = {{"gen/redraw.stamp", 0}};
+    rec.actions = {{"gen/redraw.stamp", "a"}};
+    Build build(tmp.path);
+    build.set_record(rec);
+    build.pass_begin();
+    const auto env = build.environment();
+    const auto root = std::ranges::find(env, telemetry::kRootEnv, &decltype(env)::value_type::first);
+    ASSERT_NE(root, env.end());
+    const auto unixMs = std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::system_clock::now().time_since_epoch()).count();
+    append(tmp.path / kStartsFile, std::format("gen/redraw.stamp\t{}\n", unixMs));
+    const bool wasLive = mcpp::ui::live_progress();
+    mcpp::ui::set_live_progress(true);
+    testing::internal::CaptureStderr();
+    open(false);
+    // Let the initial half-second display guard pass. This line then draws
+    // the frame immediately before publication, resetting the clock redraw.
+    std::this_thread::sleep_for(std::chrono::milliseconds(550));
+    mcpp::ui::info("Probe", "before snapshot publication");
+    std::ofstream(telemetry::channel(root->second, "gen/redraw.stamp"))
+        << R"({"v":1,"seq":1,"phase":"snapshot-redraw","done":1,"total":2})";
+    std::this_thread::sleep_for(std::chrono::milliseconds(500));
+    close();
+    const auto out = testing::internal::GetCapturedStderr();
+    mcpp::ui::set_live_progress(wasLive);
+    EXPECT_NE(out.find("snapshot-redraw 1/2"), std::string::npos) << out;
+    // No Ninja stdout, completion or other narration requested a redraw.
+}
+
 TEST(ProgressModel, APackageIsNamedOnceWhenItsFirstStepFinishes) {
     mcpp::ui::disable_color();
     Tmp tmp;