ninja: the command-length guard measures a literal command, not its edge line

check_inline_command_lengths read each build line as a proxy for the
command. That is right for a rule that expands $in and $out and wrong for
an action rule, whose command is a literal argv and whose inputs and
outputs exist only so that ninja can order and re-run it. e2e 659's first
run on the Windows shard refused an action with 200 outputs and 200 inputs
with the whole edge line counted as argv.

The guard now measures a literal command's own text. The refusal names the
edge by its first output and the count of the rest, instead of printing
every output. e2e 659 declares 600 inputs and 600 outputs, so the edge
line crosses the POSIX 128 KiB limit as well as Windows's 32767 and the
guard is measured on every shard; its negative leg declares a 140800-byte
literal command and expects the refusal to name the edge.

Author: speak-agent

.agents/docs/2026-09-13-four-upstream-asks-from-a-ui-framework.md

@@ -519,10 +519,22 @@ Four additions came from the review and are folded in above:
   content.** The help now states the shape the docs/30 row quotes. The
   subcommand stays out of the top-level usage list, since nobody types it;
   the contract is the argument shape, not its place in `--help`.
-- **The long-command leg of M5 is skipped on Windows only**, and the reason is
-  §2.4's last row: ninja runs every command through `cmd /c` there, whose
-  8191-character cap is the operating system's limit on the tool's argv. The
-  wide-list leg runs on every shard.
+- **The long-command leg of M5 runs on POSIX hosts only**, because its
+  command is `true`, a program that accepts any argv, and Windows has none.
+  An earlier draft of this bullet said ninja runs every command through
+  `cmd /c` on Windows; it does not (#261 removed the last rule that needed a
+  shell), and a plain argv goes through `CreateProcess` with its 32767
+  characters. The wide-list leg runs on every shard.
+- **The engine's command-length guard refused the wide action on the Windows
+  shard.** `check_inline_command_lengths` read each `build` line as a proxy
+  for the command, which is right for a rule that expands `$in` and `$out`
+  and wrong for an action rule, whose command is a literal argv; 200 outputs
+  and 200 inputs of Windows temp paths put the line over 32767. That is
+  §2.4's claim ("edge lists, never an argv") not holding inside one guard.
+  The guard now measures a literal command's own text; e2e 659's N was
+  raised to 600 so that the edge line also crosses the POSIX 128 KiB limit,
+  and the fixture holds the guard on every shard. Reverse leg: the raised
+  fixture is refused by the engine before the guard fix on Linux too.
 
 One observation stands as recorded and not acted on: `options::resources`
 as a single directory declared as an input (§3.4). It affects HuxerUI

CHANGELOG.md

@@ -22,8 +22,14 @@ outputs 的 depfile。六个数组换成模块内部基于 `realloc` 增长的 s
 --verify content --output <dst> <src>` 即每条 `stage_file` 边已在执行的那次拷贝。
 `mcpp stage` 的参数形状自此成为契约,其帮助文本改为陈述真实的默认值(content)。
 
-- 判据:`tests/e2e/659`(200 个输入与 200 个输出的 action 整体进入 build.ninja,
-  缓存回放后仍完整;在 2026.9.12.4 上同一夹具被拒绝),`tests/e2e/660`
+顺带修正引擎的命令长度守卫:它此前把每条 `build` 行读成命令的代理,这对展开
+`$in`/`$out` 的规则成立,对命令是字面 argv 的 action 规则不成立 —— 一个 200 个
+输出的 action 在 Windows 分片上被整条边行当 argv 计数而拒绝。守卫现在对字面命令
+量它自己的文本。
+
+- 判据:`tests/e2e/659`(600 个输入与 600 个输出的 action 整体进入 build.ninja,
+  边行越过每个宿主的 argv 上限而不被守卫误拒,缓存回放后仍完整;在 2026.9.12.4
+  上同一夹具被拒绝),`tests/e2e/660`
   (`${mcpp.self}` 在每个分片上完成一次拷贝,空转重建不再拷贝;在 2026.9.12.4
   上 token 原样落入 build.ninja)。
 - 设计记录:`.agents/docs/2026-09-13-four-upstream-asks-from-a-ui-framework.md`。

docs/30-build-mcpp.md

@@ -560,10 +560,12 @@ list in a fixed array (8192 bytes of serialised JSON for `inputs` and
 `outputs`) and refused a declaration that did not fit, so a consumer's
 checkout depth decided whether a list of forty files was accepted. What
 remains bounded is the **command at run time**, by the operating system's
-limit on a process's arguments (about 128 KiB per argument on Linux, 32767
-characters on Windows, 8191 through `cmd.exe`); that is a limit on the tool's
-own command line, and a tool that takes hundreds of files takes them through
-a response file or a directory argument of its own.
+limit on a process's arguments (128 KiB per argument on Linux, 32767
+characters for a Windows `CreateProcess`); that is a limit on the tool's own
+command line, and a tool that takes hundreds of files takes them through a
+response file or a directory argument of its own. The engine's own guard
+against it measures the command, not the edge: an action's inputs and
+outputs are graph edges, never argv.
 
 For a generated **module interface**, declare its interface too:
 

docs/zh/30-build-mcpp.md

@@ -475,9 +475,10 @@ mcpp 为那条边写出 `depfile =` 与 `deps = gcc`,ninja 读取该文件并把
 内置模块把每个列表放在定长数组里(`inputs` 与 `outputs` 各 8192 字节的序列化
 JSON),放不下的声明会被拒绝,于是一个消费者的 checkout 深度决定了四十个文件的
 列表能否被接受。仍然有上限的是**运行期的命令**,由操作系统对进程参数的限制决定
-(Linux 上每个参数约 128 KiB,Windows 上 32767 个字符,经 `cmd.exe` 则是 8191);
-那是工具自己命令行的上限,一个要接收几百个文件的工具用它自己的 response file
-或目录参数来接收。
+(Linux 上每个参数 128 KiB,Windows 的 `CreateProcess` 是 32767 个字符);那是
+工具自己命令行的上限,一个要接收几百个文件的工具用它自己的 response file 或目录
+参数来接收。引擎自己针对它的守卫量的是命令而不是边:action 的输入与输出是图上的
+边,从不进入 argv。
 
 生成**模块接口**时,把它的接口也声明出来:
 

src/build/ninja_backend.cppm

@@ -2838,6 +2838,15 @@ std::optional<std::string> check_rule_commands_name_a_program(
 
 std::optional<std::string> check_inline_command_lengths(const std::string& manifest) {
     std::set<std::string> rspRules;
+    // A rule whose command names neither `$in` nor `$out` puts a FIXED string
+    // on the command line, however many files its edges list: the declared
+    // action rules (`mcpp_action_<k>`) are built this way, their argv baked
+    // into the rule and their inputs and outputs present only so that ninja
+    // can order and re-run them. For those the edge line is not a proxy for
+    // the command -- an action with two hundred outputs was refused on
+    // Windows with the whole list counted as argv (e2e 659, 2026-09-13) --
+    // so the command text itself is what gets measured.
+    std::map<std::string, std::string> literalCommand;
     std::string current;
     for (auto line : manifest | std::views::split('\n')) {
         std::string_view l{line.begin(), line.end()};
@@ -2846,6 +2855,11 @@ std::optional<std::string> check_inline_command_lengths(const std::string& manif
         } else if (!current.empty() && l.find("rspfile") != std::string_view::npos
                    && l.find("rspfile_content") == std::string_view::npos) {
             rspRules.insert(current);
+        } else if (!current.empty() && l.starts_with("  command = ")) {
+            auto cmd = l.substr(std::string_view("  command = ").size());
+            if (cmd.find("$in") == std::string_view::npos
+                && cmd.find("$out") == std::string_view::npos)
+                literalCommand[current] = std::string(cmd);
         } else if (l.empty()) {
             current.clear();
         }
@@ -2867,13 +2881,26 @@ std::optional<std::string> check_inline_command_lengths(const std::string& manif
         if (rule == "phony") continue;
 
         // `sh -c` on POSIX; on windows nothing needs a shell since #261.
+        std::string_view measured = l;
+        if (auto lit = literalCommand.find(rule); lit != literalCommand.end())
+            measured = lit->second;
         auto over = mcpp::build::cmdlimits::check_inline(
-            l, mcpp::platform::is_windows, /*needsShell=*/!mcpp::platform::is_windows);
+            measured, mcpp::platform::is_windows, /*needsShell=*/!mcpp::platform::is_windows);
         if (!over) continue;
 
+        // The edge is named by its FIRST output and the count of the rest:
+        // an edge with hundreds of outputs would otherwise print every one
+        // of them into a diagnostic whose point is to name the edge.
         auto out = l.substr(6, colon - 6);
+        std::size_t nOut = 0;
+        for (auto tok : out | std::views::split(' '))
+            if (!std::string_view{tok.begin(), tok.end()}.empty()) ++nOut;
+        std::string_view first = out.substr(0, out.find(' '));
+        std::string named = nOut > 1
+            ? std::format("{} (and {} more outputs)", first, nOut - 1)
+            : std::string(first);
         return mcpp::build::cmdlimits::explain(
-            std::format("build edge '{}' (rule {})", out, rule), *over);
+            std::format("build edge '{}' (rule {})", named, rule), *over);
     }
     return std::nullopt;
 }

tests/e2e/659_an_action_declaration_has_no_size_limit.sh

@@ -26,11 +26,23 @@
 # producing files is the command's business, covered by 188. What is under
 # test here is the declaration channel.
 #
-# A second action carries a command past 16384 bytes on the hosts whose OS
-# allows it. Windows is skipped for that leg only: ninja runs every command
-# through `cmd /c` there, which caps a command line at 8191 characters, and
-# that is the operating system's limit on the tool's own argv, not the
-# engine's on the declaration (the design record's section 2.4).
+# N is chosen so that the action's EDGE LINE in build.ninja (outputs, rule,
+# inputs) is longer than the POSIX per-argument limit of 128 KiB as well as
+# Windows's 32767-character CreateProcess limit. That is the second thing this
+# fixture measures: the engine's command-length guard used to read the edge
+# line as a proxy for the command, which is right for a rule that expands
+# `$in` and `$out` and wrong for an action rule, whose command is a literal
+# argv and whose inputs and outputs exist only so that ninja can order and
+# re-run it. Its first run on the Windows shard refused this fixture with the
+# whole list counted as argv; the guard now measures a literal command's own
+# text, and the same fixture is what holds that on every shard.
+#
+# A second action carries a command past 16384 bytes, the old bound of the
+# command list, on the POSIX hosts: its command is `true`, a program that
+# accepts any argv and exits 0, which Windows does not have. 19200 bytes is
+# under every operating system's limit on a process's arguments; what remains
+# bounded at run time is the tool's own argv, by the OS (the design record's
+# section 2.4), and that is not the engine's bound on the declaration.
 set -e
 
 source "$(dirname "$0")/_host_path.sh"
@@ -39,7 +51,7 @@ TMP=$(mktemp -d)
 trap "rm -rf $TMP" EXIT
 cd "$TMP"
 
-readonly N=200
+readonly N=600
 
 mkdir -p app/src app/in
 cd app
@@ -61,17 +73,19 @@ EOF
 
 # N input files, so that ninja finds every declared input on disk. Each path
 # is padded to a fixed width with a long directory name, so the serialised
-# list crosses the old bound regardless of where this fixture runs:
-# N * (width + 3) > 8192 whenever width >= 40.
-PAD="a-directory-name-long-enough-to-make-the-list-cross-the-old-bound"
+# lists cross the old 8192-byte bound and the edge line crosses 128 KiB
+# regardless of where this fixture runs: with a 100-byte directory name each
+# path is at least 115 bytes, and 600 inputs plus 600 outputs put more than
+# 138000 bytes on the one edge line.
+PAD="a-directory-name-long-enough-to-make-the-edge-line-cross-the-per-argument-limit-of-the-host-os-xxxx"
 mkdir -p "in/$PAD"
 for i in $(seq 1 $N); do : > "in/$PAD/input-$i.txt"; done
 
 ROOT_HOST=$(host_path "$PWD")
 MCPP_HOST=$(host_path "$(cd "$(dirname "$MCPP")" && pwd)/$(basename "$MCPP")")
 
-# The long-command leg: a program that accepts any argv and exits 0. Not on
-# Windows (see the header).
+# The long-command leg: a program that accepts any argv and exits 0. POSIX
+# hosts only (see the header).
 TRUE_HOST=""
 case "$(uname -s)" in
     MINGW* | MSYS* | CYGWIN*) ;;
@@ -158,4 +172,38 @@ outs=$(count_in_edge "output-[0-9]*\.txt")
 [ "$outs" = "$N" ] || { echo "FAIL: after a replay build.ninja names $outs of $N declared outputs"; exit 1; }
 echo "ok: the replayed record carries all $N outputs"
 
+# The negative direction of the guard: a LITERAL command that really is too
+# long for the host is still refused, before anything is compiled, and the
+# refusal names the edge by its first output rather than by every output.
+# 2200 arguments of 64 bytes is 140800 bytes, over the POSIX 128 KiB
+# per-argument limit and over Windows's 32767 alike, so this leg runs on
+# every shard. The program named does not have to exist: the guard fires
+# while build.ninja is being written.
+mkdir -p ../too-long/src
+cp mcpp.toml ../too-long/ && cp src/main.cpp ../too-long/src/
+cd ../too-long
+cat > build.mcpp <<EOF
+import std;
+import mcpp;
+int main() {
+    mcpp::action c;
+    c.id   = "too-long";
+    c.role = "check";
+    c.arg("$MCPP_HOST");
+    const std::string word(64, 'y');
+    for (int i = 0; i < 2200; ++i) c.arg(word.c_str());
+    c.output((std::string(mcpp::out_dir()) + "/too-long.stamp").c_str());
+    c.submit();
+}
+EOF
+if "$MCPP" build > b4.log 2>&1; then
+    cat b4.log; echo "FAIL: a 140800-byte literal command was accepted"; exit 1
+fi
+grep -q "over the .* byte limit" b4.log || { cat b4.log; echo "FAIL: the refusal is not the command-length guard's"; exit 1; }
+grep -q "too-long.stamp" b4.log || { cat b4.log; echo "FAIL: the refusal does not name the edge"; exit 1; }
+# One output, so no "(and N more outputs)" suffix; the whole message stays
+# short enough to read.
+[ "$(wc -c < b4.log)" -lt 4000 ] || { wc -c b4.log; echo "FAIL: the refusal printed the whole edge line"; exit 1; }
+echo "ok: a command over the host limit is refused, naming the edge"
+
 echo "OK"