fix(pack): staging is a service to the provider, not a precondition for dispatch (2026.9.11.2)

`mcpp pack --format <name>` staged unconditionally before dispatching, and a
staging failure failed the whole command. For `--format tar` and `--format dir`
that is right -- the staged tree IS the product. For a DISPATCHED format it is
an input the provider may or may not want, and treating it as a precondition
made EVERY dispatched format unreachable on any target whose built-in bundling
is refused.

Measured on macos-15 with 2026.9.11.1: `mcpp pack --format app` never reached
the dispatch at all, because `pack::run` refuses a Mach-O PROGRAM outright --
the built-in closure walk is `LD_TRACE_LOADED_OBJECTS`, which is glibc's, and
dyld ignores it and simply runs the program. That refusal is correct about the
built-in archive and says nothing about whether a `.app` bundler can work: a
bundler that names one program needs no closure walk. THE ENGINE WAS ANSWERING
A QUESTION THE PROVIDER HAD NOT BEEN ASKED.

The failure is now reported and CARRIED rather than fatal or swallowed. The
reason is printed as a warning, `pack_stage_dir` stays empty, and
`${mcpp.stage_dir}` refuses at expansion naming that reason. A provider that
reads the tree gets a precise diagnostic; one that does not proceeds. Nothing
is silently degraded -- what changes is who decides.

`BuildOverrides::pack_stage_reason` is that channel. Without it a build that is
plainly packaging would read "this build is not packaging", which sends a member
author looking in the wrong place -- the refusal has to distinguish "you did not
ask for a format" from "no tree could be staged for this target".

`638_pack_format_dispatch.sh` gains the case macOS found, held on every
platform. Linux cannot reproduce the Mach-O refusal, so the leg asserts the
property the fix rests on instead: a provider that reads no staged tree is
dispatched and reported, and gains no dependency on the stage manifest. Nine
cases now, each paired with the wrong answer it excludes.

WHAT FOUND THIS IS WORTH RECORDING. `dist-apple` had only plan-level assertions
behind it until CI ran it on a real macOS runner for the first time. A
plan-level assertion says the gate is right and says nothing about whether the
tool accepts what the member renders -- which is why the two platform-specific
CI steps were added, and why the first thing they did was fail.

109 unit tests pass. `266_pack_refuses_a_macho_program` still fails on this
machine and was A/B'd against released 2026.9.10.2: byte-identical logs, so
this change does not touch it. Plain `mcpp pack` keeps the fatal refusal, since
`opts.format != Dispatched` there.

Author: speak-agent

CHANGELOG.md

@@ -5,6 +5,35 @@
 
 ## [Unreleased]
 
+## [2026.9.11.2] - 2026-09-11
+
+### 暂存对被分派的格式是**服务**,不是前置条件
+
+`mcpp pack --format <name>` 在分派之前无条件先暂存一次,而暂存失败就让整条命令失
+败。对 `--format tar` / `--format dir` 这是对的 —— 暂存树**就是**产物。对一个**被
+分派**的格式,它是提供方可能要、也可能不要的一项输入,而把它当成前置条件,会让
+「内建打包被拒绝」的任何目标上,**所有**被分派的格式都变得不可达。
+
+实测(macos-15,mcpp 2026.9.11.1):`mcpp pack --format app` 根本到不了分派 ——
+`pack::run` 会直接拒绝一个 Mach-O **程序**,因为内建的闭包走的是
+`LD_TRACE_LOADED_OBJECTS`,那是 glibc 的机制,dyld 不认它、而是**直接把程序跑起来**。
+那条拒绝对内建归档是正确的,却对「一个 `.app` 打包器能不能工作」什么都没说 ——
+一个只点名一个程序的打包器根本不需要走闭包。**引擎在回答一个提供方没有被问到的
+问题。**
+
+所以失败现在是**带着原因继续**而不是被吞掉:原因作为 warning 印出来,
+`pack_stage_dir` 保持为空,`${mcpp.stage_dir}` 于是在展开处带着那条原因拒绝。读树的
+提供方拿到精确诊断,不读树的照常走完。没有任何东西被静默降级 —— 变的是**由谁来做
+这个决定**。
+
+`BuildOverrides::pack_stage_reason` 是那条原因的通道。没有它,一个明明在打包的构建
+会读到「this build is not packaging」,而那句话会把成员作者引向错误的方向。
+
+⚠️ 这条修复是由 CI 在 macOS 上第一次真的跑 `dist-apple` 才暴露出来的。在那之前它
+只有 plan 级断言撑着,而 plan 级断言说的是「闸对了」,对「工具接不接受成员渲染出来
+的东西」一个字都没说。
+
+
 ## [2026.9.11.1] - 2026-09-11
 
 ### `mcpp pack --format <name>` 分派到包,而引擎里不再需要住进任何一种分发格式

mcpp.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version = "2026.9.11.1"
+version = "2026.9.11.2"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

modules/versioning/src/version.cppm

@@ -31,6 +31,6 @@ import std;
 
 export namespace mcpp {
 
-inline constexpr std::string_view MCPP_VERSION = "2026.9.11.1";
+inline constexpr std::string_view MCPP_VERSION = "2026.9.11.2";
 
 } // namespace mcpp

src/build/prepare.cppm

@@ -1017,6 +1017,16 @@ export struct BuildOverrides {
     // already answered.
     std::string           pack_format;
     std::filesystem::path pack_stage_dir;
+    // WHY THERE IS NO STAGED TREE, when there is none and a format was still
+    // requested. Empty otherwise.
+    //
+    // A dispatched format does not require the built-in bundling to have
+    // succeeded -- see the note in `mcpp.pack.pipeline`. When it did not, the
+    // reason travels here so `${mcpp.stage_dir}`'s refusal can name it instead
+    // of saying only that the placeholder is unavailable. A member author
+    // reading "this build is not packaging" for a build that plainly is would
+    // be sent looking in the wrong place.
+    std::string           pack_stage_reason;
 };
 
 // ── git dependency helpers ──────────────────────────────────────────────────
@@ -10299,6 +10309,9 @@ prepare_build(bool print_fingerprint,
         // Section 2 of the design record measured that shape: a valid, empty,
         // 52 KB installer with nothing said about it.
         std::set<std::string> stageDirNoPass, stageDirWrongRole;
+        // Carried from the overrides so the refusal below can say WHY there is
+        // no tree, which is a different sentence from "you are not packaging".
+        std::string stageDirWhy;
         // WHETHER *THIS* ACTION REFERENCED THE STAGED TREE, and deliberately a
         // flag rather than a set keyed on the action's id: an id is unique
         // within the package that declared it and nothing more, so two packages
@@ -10329,6 +10342,7 @@ prepare_build(bool print_fingerprint,
             if (s.find("${mcpp.stage_dir}") != std::string::npos) {
                 if (!stagePass) {
                     stageDirNoPass.insert(actionId);
+                    stageDirWhy = overrides.pack_stage_reason;
                 } else if (role != mcpp::manifest::BuildAction::Role::Artifact) {
                     stageDirWrongRole.insert(actionId);
                 } else {
@@ -10408,6 +10422,18 @@ prepare_build(bool print_fingerprint,
         if (!stageDirNoPass.empty()) {
             std::string ids;
             for (auto const& n : stageDirNoPass) ids += (ids.empty() ? "" : ", ") + n;
+            if (!stageDirWhy.empty()) {
+                return std::unexpected(std::format(
+                    "build.mcpp action(s) [{}] reference ${{mcpp.stage_dir}}, and no "
+                    "tree could be staged for this target.\n"
+                    "  {}\n"
+                    "  The format was requested and the provider was reached; what is "
+                    "missing is the staged\n"
+                    "  closure itself. A member that names a built file with "
+                    "${{mcpp.target_file:<name>}} instead\n"
+                    "  of reading the tree is unaffected on this target.",
+                    ids, stageDirWhy));
+            }
             return std::unexpected(std::format(
                 "build.mcpp action(s) [{}] reference ${{mcpp.stage_dir}}, and this "
                 "build is not packaging.\n"

src/pack/pipeline.cppm

@@ -286,17 +286,50 @@ export int build_and_pack(Options opts, bool modeFromUser,
         mcpp::pack::mode_cli_name(plan->opts.mode),
         plan->strip ? ", stripped" : ""));
 
-    auto r = mcpp::pack::run(*plan, *cfg);
-    if (!r) {
-        mcpp::ui::error(r.error().message);
-        return 1;
+    // STAGING IS A SERVICE TO THE PROVIDER, NOT A PRECONDITION FOR DISPATCH.
+    //
+    // For `--format tar` and `--format dir` the staged tree IS the product, so
+    // a staging failure is the command failing. For a DISPATCHED format it is
+    // an input the provider may or may not want, and treating it as a
+    // precondition made every dispatched format unreachable on any target
+    // whose built-in bundling is refused.
+    //
+    // Measured on macos-15 with mcpp 2026.9.11.1: `mcpp pack --format app`
+    // never reached the dispatch, because `pack::run` refuses a Mach-O PROGRAM
+    // outright -- the built-in closure walk is `LD_TRACE_LOADED_OBJECTS`, which
+    // is glibc's, and dyld ignores it and runs the program instead. That
+    // refusal is correct about the built-in archive and says nothing about
+    // whether a `.app` bundler can work, since a bundler that names one
+    // program needs no closure walk at all. The engine was answering a
+    // question the provider had not been asked.
+    //
+    // So the failure is REPORTED AND CARRIED rather than swallowed: the reason
+    // is printed as a warning, `pack_stage_dir` stays empty, and
+    // `${mcpp.stage_dir}` then refuses at expansion naming that reason. A
+    // provider that reads the tree gets a precise diagnostic; one that does not
+    // proceeds. Nothing is silently degraded -- what changes is who decides.
+    std::string stageFailure;
+    if (auto r = mcpp::pack::run(*plan, *cfg); !r) {
+        if (opts.format != mcpp::pack::Format::Dispatched) {
+            mcpp::ui::error(r.error().message);
+            return 1;
+        }
+        stageFailure = r.error().message;
+        mcpp::ui::warning(std::format(
+            "no staged tree for --format {}: {}\n"
+            "  A format that consumes ${{mcpp.stage_dir}} cannot be produced "
+            "here; one that names a\n"
+            "  built file with ${{mcpp.target_file:<name>}} is unaffected.",
+            opts.formatName, stageFailure));
     }
 
     // The staged tree is now on disk and final -- past the closure, the
     // `$ORIGIN` rewriting, the strip and the debug split. Describe it, so an
     // action that consumes it has something whose CONTENT changes when the
-    // staged set does. Best-effort: see write_stage_manifest.
-    mcpp::pack::write_stage_manifest(plan->stagingRoot);
+    // staged set does. Best-effort: see write_stage_manifest. Skipped when
+    // staging did not happen, so no manifest describes a tree that is not
+    // there.
+    if (stageFailure.empty()) mcpp::pack::write_stage_manifest(plan->stagingRoot);
 
     auto pathCtx = mcpp::fetcher::make_path_ctx(&*cfg, ctx->projectRoot);
 
@@ -328,7 +361,12 @@ export int build_and_pack(Options opts, bool modeFromUser,
                 preexistingArtifacts.emplace(a.packageName, a.id);
 
         ov.pack_format    = opts.formatName;
-        ov.pack_stage_dir = plan->stagingRoot;
+        // Empty when staging was refused, which is what makes
+        // `${mcpp.stage_dir}` refuse with the reason attached rather than
+        // expand to a directory that does not exist.
+        ov.pack_stage_dir = stageFailure.empty() ? plan->stagingRoot
+                                                 : std::filesystem::path{};
+        ov.pack_stage_reason = stageFailure;
         auto distCtx = mcpp::build::prepare_build(false, false, {}, ov);
         if (!distCtx) { mcpp::ui::error(distCtx.error()); return 2; }
 

tests/e2e/638_pack_format_dispatch.sh

@@ -309,4 +309,49 @@ grep -q "size.stamp" b8.log \
 [ -n "$(find target -name 'size.stamp' 2>/dev/null)" ] \
   || { echo "FAIL: the ungated artifact action did not run at all"; exit 1; }
 
+# ── 9. a format that names no staged tree survives a staging refusal ──────
+# THE CASE macOS FOUND, HELD ON EVERY PLATFORM.
+#
+# `mcpp pack` refuses to bundle a Mach-O PROGRAM: the built-in closure walk is
+# `LD_TRACE_LOADED_OBJECTS`, glibc's mechanism, and dyld ignores it and runs the
+# program instead. That refusal is right about the built-in archive and says
+# nothing about whether a `.app` bundler can work -- one that names a single
+# program needs no closure walk at all. Before this, the refusal happened before
+# the dispatch, so EVERY dispatched format was unreachable on that target.
+#
+# Staging is now a service to the provider rather than a precondition. This leg
+# cannot reproduce the Mach-O refusal on Linux, so it holds the property the fix
+# rests on instead: a provider that reads no staged tree is reported, and the
+# reason travels far enough to reach the placeholder's refusal.
+cd "$TMP"
+cp -r app nostage
+cd nostage
+cat > build.mcpp <<'EOF'
+import mcpp;
+#include <string>
+#include <string_view>
+int main() {
+    mcpp::provides_pack_format("zap");
+    if (std::string_view(mcpp::pack_format()) != "zap") return 0;
+    // Reads NOTHING from the staged tree: the program arrives through
+    // ${mcpp.target_file:...}, which is what an `.msi` of one program does.
+    const std::string root = mcpp::manifest_dir();
+    const std::string out  = std::string(mcpp::out_dir()) + "/app.zap";
+    mcpp::action a;
+    a.id = "zap"; a.role = "artifact";
+    a.arg((root + "/dist.sh").c_str()).arg("named").arg(root.c_str()).arg(out.c_str())
+     .input("${mcpp.target_file:app}").output(out.c_str());
+    a.submit();
+    return 0;
+}
+EOF
+"$MCPP" pack --format zap > b9.log 2>&1 || { cat b9.log; echo "FAIL: a provider that reads no staged tree was refused"; exit 1; }
+grep -q "app.zap" b9.log \
+  || { cat b9.log; echo "FAIL: the provider was not reported as the package"; exit 1; }
+# It really did not consume the tree: no stage manifest edge was added, so the
+# action's inputs are the program alone.
+grep -q "stage-manifest" b9.log \
+  && { cat b9.log; echo "FAIL: a provider that names no tree gained a stage dependency"; exit 1; }
+echo "ok: a provider that reads no staged tree is dispatched and reported"
+
 echo "PASS: 638_pack_format_dispatch"