--play-game reads keys only in the terminal's foreground, and a key sequence with parameters is decoded whole

A background job that changed the terminal's mode would be stopped by
SIGTTOU; the game is off there and the line that says so names the
foreground. The key decoder reads the parameter bytes of a control sequence
before its final byte, so Ctrl-Up is Up and F5 is no key, where the tail of
either was read as keys; the decoder is exported and has unit tests.
MCPP_PROGRESS is compared without case when a game is chosen, as it is when
an animation is chosen.

Author: speak-agent

CHANGELOG.md

@@ -28,8 +28,10 @@ records one lock entry per identity again.
   a speed of its own. The best round is stated after `Finished`. Keys are
   read without echo; Ctrl-C still stops the build, and the terminal's mode is
   restored when the build ends or is interrupted. Where standard input or
-  output is not a terminal, one line says why and the build proceeds
-  (e2e 845).
+  output is not a terminal, or mcpp runs as a background job, one line says
+  why and the build proceeds (e2e 845). An arrow with a modifier is read as
+  the arrow, and a sequence for any other key is skipped whole
+  (`TerminalKeys` unit tests).
 - **`last N running`.** Once ninja has no step left to start (its `%u`
   reaches 0), the status row states how many steps remain, all of them
   running.

docs/09-commands-by-scenario.md

@@ -324,8 +324,8 @@ The game runs at its own speed; the counts beside it state the build. Keys
 are read without echo, and Ctrl-C still stops the build. The terminal's mode
 is restored when the build ends or is interrupted; a process killed outright
 cannot restore it, and `stty sane` does. The game needs standard input and
-standard output on a terminal; otherwise one line says why, and the build
-proceeds.
+standard output on a terminal, with mcpp in its foreground (not a background
+job); otherwise one line says why, and the build proceeds.
 
 `--verbose` names every package: `Fresh` for those with nothing to do, and
 `Compiled` with the steps and span of each that did work. It also states each

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

@@ -285,7 +285,7 @@ $ mcpp build --play-game=snake
 - **速度与计数**：游戏以自身的速度运行，旁边的计数陈述构建的进展。
 - **按键读取**：按键不回显；Ctrl-C 仍然中断构建。
 - **终端模式**：构建结束或被中断时，终端模式会恢复；被强制杀死的进程无法恢复，此时可执行 `stty sane`。
-- **使用条件**：游戏要求标准输入和标准输出都是终端；否则写出一行说明原因，构建照常进行。
+- **使用条件**：游戏要求标准输入和标准输出都是终端，且 mcpp 位于该终端的前台（不是后台作业）；否则写出一行说明原因，构建照常进行。
 
 `--verbose` 列出每个包：无事可做的包记为 `Fresh`，做了事的包记为 `Compiled`，并给出其步骤数和耗时跨度。它还给出每个构建程序的编译与运行时间，并按 ninja 的报告打印每个步骤（`[f/t] <命令>` 及其输出）。`--quiet` 不输出以上内容。机器输出（`--message-format json`）不变。
 

modules/platform/src/terminal.cppm

@@ -114,9 +114,17 @@ bool unicode_capable();
 // the space bar, and `wasd` as a second set of arrows.
 enum class Key { Up, Down, Left, Right, Space };
 
+// The keys in `pending`, the bytes a POSIX terminal sent: an arrow is
+// `ESC [ A` to `ESC [ D`, `ESC O A` to `ESC O D` in application mode, or
+// `ESC [ 1 ; 5 A` and the like with a modifier; a sequence for any other key
+// is skipped whole. An incomplete sequence at the end is left in `pending`.
+std::vector<Key> decode_keys(std::string& pending);
+
 // KEYS READ FROM THE TERMINAL FOR THE LIFETIME OF THE OBJECT, without echo and
 // without waiting for a line end; Ctrl-C still interrupts. Active only when
-// standard input and standard output are both terminals. The mode the
+// standard input and standard output are both terminals and, on POSIX, mcpp
+// is in the terminal's foreground process group: a background job that
+// changed the terminal's mode would be stopped by SIGTTOU. The mode the
 // terminal had is restored when the object is destroyed, and by the signal
 // handler if a signal ends mcpp first (POSIX: `unixproc::guard_terminal_mode`;
 // Windows: a console control handler).
@@ -368,28 +376,32 @@ BOOL WINAPI restore_input_mode(DWORD) {
 }
 #endif
 
-// The keys in `bytes` (POSIX): an arrow is `ESC [ A` to `ESC [ D`, or with
-// `O` in place of `[` in application mode. An incomplete sequence at the end
-// is left in `pending`.
+} // namespace
+
 std::vector<Key> decode_keys(std::string& pending) {
     std::vector<Key> keys;
     std::size_t i = 0;
     while (i < pending.size()) {
         const char c = pending[i];
         if (c == '\x1b') {
-            if (i + 2 >= pending.size()) break;   // wait for the rest
-            if (pending[i + 1] == '[' || pending[i + 1] == 'O') {
-                switch (pending[i + 2]) {
-                case 'A': keys.push_back(Key::Up);    break;
-                case 'B': keys.push_back(Key::Down);  break;
-                case 'C': keys.push_back(Key::Right); break;
-                case 'D': keys.push_back(Key::Left);  break;
-                default: break;
-                }
-                i += 3;
-                continue;
+            if (i + 1 >= pending.size()) break;   // wait for the rest
+            if (pending[i + 1] != '[' && pending[i + 1] != 'O') { ++i; continue; }
+            // Parameter and intermediate bytes (0x20 to 0x3F), then one final
+            // byte (0x40 to 0x7E) that names the key.
+            std::size_t end = i + 2;
+            while (end < pending.size()
+                   && static_cast<unsigned char>(pending[end]) >= 0x20
+                   && static_cast<unsigned char>(pending[end]) <= 0x3F)
+                ++end;
+            if (end >= pending.size()) break;     // wait for the final byte
+            switch (pending[end]) {
+            case 'A': keys.push_back(Key::Up);    break;
+            case 'B': keys.push_back(Key::Down);  break;
+            case 'C': keys.push_back(Key::Right); break;
+            case 'D': keys.push_back(Key::Left);  break;
+            default: break;
             }
-            ++i;
+            i = end + 1;
             continue;
         }
         switch (c) {
@@ -406,8 +418,6 @@ std::vector<Key> decode_keys(std::string& pending) {
     return keys;
 }
 
-} // namespace
-
 KeyInput::KeyInput() {
     if (!is_terminal(Stream::Out)) return;
 #if defined(_WIN32)
@@ -422,7 +432,7 @@ KeyInput::KeyInput() {
     if (!::SetConsoleMode(h, mode & ~(ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT))) return;
     active_ = true;
 #elif defined(__unix__) || defined(__APPLE__)
-    if (::isatty(0) == 0) return;
+    if (::isatty(0) == 0 || ::tcgetpgrp(0) != ::getpgrp()) return;
     struct termios mode{};
     if (::tcgetattr(0, &mode) != 0) return;
     mcpp::platform::unixproc::guard_terminal_mode(0);

src/build/progress.cppm

@@ -1053,8 +1053,8 @@ std::unique_ptr<screen::Animation> choose_animation() {
 
 // `--play-game[=NAME]` (revision 3, §5.14): the CLI publishes the request as
 // MCPP_PLAY_GAME (`random` or a name). The game needs what the screen needs,
-// and keys: standard input and standard output on a terminal. Otherwise it is
-// off, and one line says why.
+// and keys: standard input and standard output on a terminal, with mcpp in
+// its foreground. Otherwise it is off, and one line says why.
 void choose_game(Report& r, std::vector<std::string>& notes) {
     auto want = mcpp::platform::env::get("MCPP_PLAY_GAME").value_or("");
     if (want.empty()) return;
@@ -1068,7 +1068,8 @@ void choose_game(Report& r, std::vector<std::string>& notes) {
                                     want, known));
         want = "random";
     }
-    const auto progress = mcpp::platform::env::get("MCPP_PROGRESS").value_or("");
+    auto progress = mcpp::platform::env::get("MCPP_PROGRESS").value_or("");
+    for (auto& c : progress) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
     if (mcpp::ui::is_quiet() || !mcpp::ui::live_progress() || progress == "plain" || progress == "off"
         || !mcpp::platform::terminal::unicode_capable()) {
         notes.push_back("--play-game: the status row's screen is off here (a terminal that "
@@ -1077,7 +1078,8 @@ void choose_game(Report& r, std::vector<std::string>& notes) {
     }
     auto keys = std::make_unique<mcpp::platform::terminal::KeyInput>();
     if (!keys->active()) {
-        notes.push_back("--play-game: standard input is not a terminal, so no key can be read");
+        notes.push_back("--play-game: standard input is not a terminal in the foreground, "
+                        "so no key can be read");
         return;
     }
     const auto seed = static_cast<std::uint64_t>(

tests/unit/test_platform_terminal.cpp

@@ -0,0 +1,45 @@
+#include <gtest/gtest.h>
+
+import std;
+import mcpp.platform.terminal;
+
+// The keys a game reads from a POSIX terminal
+// (.agents/docs/2026-09-30-build-output-refinement-design.md, §5.14): the
+// decoder turns the bytes the terminal sent into keys, skips a sequence for
+// any other key whole, and keeps an incomplete sequence for the next read.
+
+using mcpp::platform::terminal::Key;
+using mcpp::platform::terminal::decode_keys;
+
+TEST(TerminalKeys, ArrowsInBothModesAndTheSecondSet) {
+    std::string in = "\x1b[A\x1b[B\x1bOC\x1bOD wasd";
+    const auto keys = decode_keys(in);
+    const std::vector<Key> want = {Key::Up, Key::Down, Key::Right, Key::Left, Key::Space,
+                                   Key::Up, Key::Left, Key::Down, Key::Right};
+    EXPECT_EQ(keys, want);
+    EXPECT_TRUE(in.empty());
+}
+
+TEST(TerminalKeys, AModifiedArrowIsOneKeyAndOtherSequencesAreSkippedWhole) {
+    // Ctrl-Up, then F5 (`ESC [ 1 5 ~`), then Home in application mode.
+    std::string in = "\x1b[1;5A\x1b[15~\x1bOH";
+    const auto keys = decode_keys(in);
+    const std::vector<Key> want = {Key::Up};
+    EXPECT_EQ(keys, want) << "a parameter byte or a final byte was read as a key";
+    EXPECT_TRUE(in.empty());
+}
+
+TEST(TerminalKeys, AnIncompleteSequenceWaitsForTheNextRead) {
+    std::string in = "d\x1b[1;";
+    EXPECT_EQ(decode_keys(in), std::vector<Key>{Key::Right});
+    EXPECT_EQ(in, "\x1b[1;");
+    in += "2B";
+    EXPECT_EQ(decode_keys(in), std::vector<Key>{Key::Down});
+    EXPECT_TRUE(in.empty());
+
+    std::string esc = "\x1b";
+    EXPECT_TRUE(decode_keys(esc).empty());
+    EXPECT_EQ(esc, "\x1b");
+    esc += "w";   // escape on its own, then a key
+    EXPECT_EQ(decode_keys(esc), std::vector<Key>{Key::Up});
+}