From d0bc67ad6c33c0c127c3e4a59fcb0e28fd15fdf5 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Thu, 8 Oct 2026 15:30:14 +0800
Subject: [PATCH] Exit 1 from the legacy CLI flags when an action failed

The executor records a failed action and runs the next one, so the
process ended with status 0 whatever happened. The executor now counts
the actions that failed, and the entry point compares the count before
and after the legacy dispatch and exits 1 with "N action(s) failed".
---
 README.md                               |  2 ++
 README.zh-CN.md                         |  2 ++
 README.zh-TW.md                         |  2 ++
 architecture.md                         |  5 +++-
 automation_file/__main__.py             |  8 +++++-
 automation_file/core/action_executor.py | 18 +++++++++++++
 docs/source/Eng/usage/cli.rst           |  7 +++++
 docs/source/Zh-CN/usage/cli.rst         |  7 +++++
 docs/source/Zh-TW/usage/cli.rst         |  7 +++++
 docs/updates/2026-10.md                 | 10 +++++++
 docs/updates/README.md                  |  3 ++-
 tests/test_cli_main.py                  | 35 +++++++++++++++++++++++++
 tests/test_legacy_cli_contract.py       | 33 +++++++++++++++++++++++
 13 files changed, 136 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ed85aee..dd12ffc 100644
--- a/README.md
+++ b/README.md
@@ -929,6 +929,8 @@ python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
 python -m automation_file --create_project ./my_project
 ```
 
+The legacy flags exit with status 1 when an action of the list failed, after the rest of the list has run, and print `error: N action(s) failed` on stderr.
+
 ## JSON action format
 
 Each entry is either a bare command name, a `[name, kwargs]` pair, or a
diff --git a/README.zh-CN.md b/README.zh-CN.md
index ce4e224..4df9eae 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -910,6 +910,8 @@ python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
 python -m automation_file --create_project ./my_project
 ```
 
+旧式标志在清单中有动作失败时，会在其余动作执行完之后以状态 1 结束，并在 stderr 打印 `error: N action(s) failed`。
+
 ## JSON 动作格式
 
 每一项动作可以是单纯的命令名称、`[name, kwargs]` 组合，或 `[name, args]`
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 49352f4..dc2e3de 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -910,6 +910,8 @@ python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
 python -m automation_file --create_project ./my_project
 ```
 
+舊式旗標在清單中有動作失敗時，會在其餘動作執行完之後以狀態 1 結束，並在 stderr 印出 `error: N action(s) failed`。
+
 ## JSON 動作格式
 
 每一項動作可以是單純的指令名稱、`[name, kwargs]` 組合，或 `[name, args]`
diff --git a/architecture.md b/architecture.md
index bf590df..59f2092 100644
--- a/architecture.md
+++ b/architecture.md
@@ -134,7 +134,10 @@ ActionExecutor() → build_default_registry(): local + http + utils + drive comm
   contract, guarded by `tests/test_legacy_cli_contract.py`. PyBreeze also declares `automation-file` as
   a dependency.
 - **TestPioneer** imports `download_file` and `unzip_all` from the facade in-process
-  (`test_pioneer/executor/file/file_processing.py`). Its `parallel_run` does not spawn this package.
+  (`test_pioneer/executor/file/file_processing.py`). Its `file-runner` runs an action file through
+  `execute_action` in-process, and `parallel_run` spawns `python -m automation_file --execute_file <script>`
+  and reads the exit status: 1 when an action failed (`ActionExecutor.failure_count`, compared by
+  `__main__.main`), guarded by `tests/test_legacy_cli_contract.py`.
 - **Names inherited from AutoControl**: the TCP starter is still called `start_autocontrol_socket_server`
   and the action-dict key is `auto_control`. MailThunder has renamed both (`start_mail_thunder_socket_server`, `mail_thunder` key) and keeps the old names as deprecated aliases. MailThunder's
   socket-server default is 9942, so it runs next to this package's servers (TCP 9943, HTTP 9944,
diff --git a/automation_file/__main__.py b/automation_file/__main__.py
index 5e48c92..8d350be 100644
--- a/automation_file/__main__.py
+++ b/automation_file/__main__.py
@@ -19,7 +19,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from automation_file.core.action_executor import execute_action, execute_files
+from automation_file.core.action_executor import execute_action, execute_files, executor
 from automation_file.core.json_store import read_action_json
 from automation_file.exceptions import ArgparseException
 from automation_file.local.file_ops import create_file
@@ -235,6 +235,7 @@ def main(argv: list[str] | None = None) -> int:
         return args.handler(args)
 
     ran = False
+    failed_before = executor.failure_count
     for key, handler in _LEGACY_DISPATCH.items():
         value = getattr(args, key, None)
         if value is None:
@@ -243,6 +244,11 @@ def main(argv: list[str] | None = None) -> int:
         ran = True
     if not ran:
         raise ArgparseException("no argument supplied; try --help")
+    # A failed action does not stop the batch, so it is reported once the batch is done.
+    failed = executor.failure_count - failed_before
+    if failed:
+        print(f"error: {failed} action(s) failed", file=sys.stderr)
+        return 1
     return 0
 
 
diff --git a/automation_file/core/action_executor.py b/automation_file/core/action_executor.py
index 460be8a..95f3786 100644
--- a/automation_file/core/action_executor.py
+++ b/automation_file/core/action_executor.py
@@ -15,6 +15,7 @@
 
 from __future__ import annotations
 
+import threading
 import time
 from collections.abc import Mapping
 from concurrent.futures import ThreadPoolExecutor
@@ -62,6 +63,8 @@ class ActionExecutor(_CoreActionExecutor):
 
     def __init__(self, registry: ActionRegistry | None = None) -> None:
         super().__init__(_SETTINGS, registry or build_default_registry())
+        self._failures = 0
+        self._failures_lock = threading.Lock()
         self.registry.register_many(
             {
                 "FA_execute_action": self.execute_action,
@@ -84,6 +87,18 @@ def _parse_action(action: list) -> ParsedAction:
         return _PARSER.parse(action)
 
     # Public API --------------------------------------------------------
+    @property
+    def failure_count(self) -> int:
+        """How many actions have failed in this executor since it was created.
+
+        A failed action is recorded as ``repr(error)`` and the batch goes on, so
+        the return value of ``execute_action`` does not say whether anything
+        failed. A caller that must know (the CLI, for its exit status) compares
+        this count before and after. Dry runs are not counted.
+        """
+        with self._failures_lock:
+            return self._failures
+
     def validate(self, action_list: list | Mapping[str, Any]) -> list[str]:
         """Validate shape and resolve every name; return the list of action names.
 
@@ -179,6 +194,9 @@ def _run_one(self, action: list, dry_run: bool, display: list | None = None) ->
             return repr(error)
         finally:
             record_action(name, time.monotonic() - started, ok)
+            if not ok:
+                with self._failures_lock:
+                    self._failures += 1
 
     def _run_dry(self, action: list, display: list | None = None) -> Any:
         display_action = action if display is None else display
diff --git a/docs/source/Eng/usage/cli.rst b/docs/source/Eng/usage/cli.rst
index 1b5c543..02787e8 100644
--- a/docs/source/Eng/usage/cli.rst
+++ b/docs/source/Eng/usage/cli.rst
@@ -23,3 +23,10 @@ Subcommands for one-shot operations::
 The ``mcp`` subcommand starts a Model Context Protocol server over stdio so
 hosts such as Claude Desktop can call ``FA_*`` actions as MCP tools — see
 :doc:`mcp` for the full integration guide.
+
+Exit status of the legacy flags
+-------------------------------
+
+``-e``, ``-d`` and ``--execute_str`` exit with status 1 when an action of the list failed. A failed
+action does not stop the list: the rest runs first, and ``error: N action(s) failed`` is printed on
+stderr at the end. A script that cannot be read exits with 1 as before.
diff --git a/docs/source/Zh-CN/usage/cli.rst b/docs/source/Zh-CN/usage/cli.rst
index 1de5e1b..a4b1351 100644
--- a/docs/source/Zh-CN/usage/cli.rst
+++ b/docs/source/Zh-CN/usage/cli.rst
@@ -23,3 +23,10 @@ CLI
 ``mcp`` 子命令通过 stdio 启动 Model Context Protocol 服务器，
 让 Claude Desktop 这类宿主可以把 ``FA_*`` 动作当作 MCP 工具调用——完整集成
 说明请见 :doc:`mcp`。
+
+旧式标志的结束状态
+------------------
+
+``-e``、``-d`` 与 ``--execute_str`` 在清单中有动作失败时以状态 1 结束。失败的动作不会中止清单：
+其余动作会先执行完，最后在 stderr 打印 ``error: N action(s) failed``。
+无法读取的脚本和以前一样以 1 结束。
diff --git a/docs/source/Zh-TW/usage/cli.rst b/docs/source/Zh-TW/usage/cli.rst
index fec45d0..712fa85 100644
--- a/docs/source/Zh-TW/usage/cli.rst
+++ b/docs/source/Zh-TW/usage/cli.rst
@@ -23,3 +23,10 @@ CLI
 ``mcp`` 子指令以 stdio 啟動 Model Context Protocol 伺服器，
 讓 Claude Desktop 之類的宿主可把 ``FA_*`` 動作當成 MCP 工具呼叫——
 完整整合說明請見 :doc:`mcp`。
+
+舊式旗標的結束狀態
+------------------
+
+``-e``、``-d`` 與 ``--execute_str`` 在清單中有動作失敗時以狀態 1 結束。失敗的動作不會中止清單：
+其餘動作會先執行完，最後在 stderr 印出 ``error: N action(s) failed``。
+無法讀取的腳本和以前一樣以 1 結束。
diff --git a/docs/updates/2026-10.md b/docs/updates/2026-10.md
index ac8c919..de1cc07 100644
--- a/docs/updates/2026-10.md
+++ b/docs/updates/2026-10.md
@@ -192,3 +192,13 @@ Index and query commands: [README.md](README.md). New entries go at the end.
 - **Docs**: `CLAUDE.md` › Branching & CI and `architecture.md` §2 and §3 say how the jobs build and what to regenerate when the build requirement changes. The READMEs and the Sphinx pages do not describe the publish jobs, so they are unchanged.
 - **Files**: `.github/requirements/publish.in`, `.github/requirements/publish.txt`, `.github/workflows/ci-dev.yml`, `.github/workflows/publish.yml`, `tests/test_workflow_actions.py`, `tests/test_dev_release.py`, `CLAUDE.md`, `architecture.md`, `progress.md`.
 - **Open items**: none. `publish.yml` runs only on `main`, so its build step takes effect, and is first exercised, when `dev` is merged.
+
+## U-20261008-01 · 2026-10-08 · The legacy CLI flags exit 1 when an action failed · #feature #cli #testpioneer
+
+- **What**: `python -m automation_file` with `-e`, `-d` or `--execute_str` ended with status 0 whatever happened, because the executor records a failed action as `repr(error)` and runs the next one. `ActionExecutor` now counts the actions that failed (`failure_count`, thread-safe, dry runs excluded), `__main__.main` compares the count before and after the legacy dispatch, and the process exits 1 with `error: N action(s) failed` on stderr. The rest of the list still runs first.
+- **Why**: TestPioneer's `parallel_run` starts `--execute_file` and reads the exit status (its `docs/artifacts.rst`, "Native Support"), and a CI job does the same. LoadDensity made the same change in its PR #118.
+- **Effect on callers**: a script with a failing action ends with status 1 where it ended with 0. PyBreeze only displays the status. `execute_action` and its return value are unchanged.
+- **Also**: `architecture.md` §6 said TestPioneer's `parallel_run` does not spawn this package; it does, for its `file-runner`.
+- **Tests**: `tests/test_legacy_cli_contract.py` +4 (real child processes), `tests/test_cli_main.py` +3.
+- **Docs**: `README.md`, `README.zh-TW.md`, `README.zh-CN.md`, `docs/source/{Eng,Zh-TW,Zh-CN}/usage/cli.rst`, `architecture.md` §6.
+- **Files**: `automation_file/core/action_executor.py`, `automation_file/__main__.py`, the tests and docs above.
diff --git a/docs/updates/README.md b/docs/updates/README.md
index 5308af4..75f76b4 100644
--- a/docs/updates/README.md
+++ b/docs/updates/README.md
@@ -58,6 +58,7 @@ In the same commit: delete the item from `progress.md`, add a `#done` entry here
 
 | ID | Date | Title | Tags | Batch |
 |---|---|---|---|---|
+| U-20261008-01 | 2026-10-08 | The legacy CLI flags exit 1 when an action failed | #feature #cli #testpioneer | [2026-10](2026-10.md) |
 | U-20261001-11 | 2026-10-01 | The publish jobs build with the locked setuptools | #done #ci #security #X-13 | [2026-10](2026-10.md) |
 | U-20261001-10 | 2026-10-01 | The publish jobs install hash-locked build tools | #done #ci #security #deps | [2026-10](2026-10.md) |
 | U-20261001-09 | 2026-10-01 | The source distributions stop carrying the tests | #done #packaging #tests | [2026-10](2026-10.md) |
@@ -95,5 +96,5 @@ In the same commit: delete the item from `progress.md`, add a `#done` entry here
 
 | File | Period | Entries |
 |---|---|---:|
-| [2026-10.md](2026-10.md) | 2026-10 | 11 |
+| [2026-10.md](2026-10.md) | 2026-10 | 12 |
 | [2026-09.md](2026-09.md) | 2026-09 | 21 |
diff --git a/tests/test_cli_main.py b/tests/test_cli_main.py
index a0c9389..2277431 100644
--- a/tests/test_cli_main.py
+++ b/tests/test_cli_main.py
@@ -95,3 +95,38 @@ def test_execute_str_accepts_double_encoded_payload(
 
     assert rc == 0
     assert received == [actions]
+
+
+def test_legacy_flag_returns_1_when_an_action_failed(
+    tmp_path: Any, capsys: pytest.CaptureFixture[str]
+) -> None:
+    actions = tmp_path / "actions.json"
+    actions.write_text(json.dumps([["FA_no_such_action"], ["FA_no_such_action"]]), encoding="utf-8")
+
+    assert cli_main.main(["--execute_file", str(actions)]) == 1
+    assert "error: 2 action(s) failed" in capsys.readouterr().err
+
+
+def test_legacy_flag_returns_0_when_every_action_passed(tmp_path: Any) -> None:
+    target = tmp_path / "created.txt"
+    actions = tmp_path / "actions.json"
+    actions.write_text(
+        json.dumps([["FA_create_file", {"file_path": str(target), "content": "x"}]]),
+        encoding="utf-8",
+    )
+
+    assert cli_main.main(["--execute_file", str(actions)]) == 0
+    assert target.exists()
+
+
+def test_failures_of_an_earlier_run_are_not_counted_again(tmp_path: Any) -> None:
+    bad = tmp_path / "bad.json"
+    bad.write_text(json.dumps([["FA_no_such_action"]]), encoding="utf-8")
+    good = tmp_path / "good.json"
+    good.write_text(
+        json.dumps([["FA_create_file", {"file_path": str(tmp_path / "x.txt"), "content": "x"}]]),
+        encoding="utf-8",
+    )
+
+    assert cli_main.main(["--execute_file", str(bad)]) == 1
+    assert cli_main.main(["--execute_file", str(good)]) == 0
diff --git a/tests/test_legacy_cli_contract.py b/tests/test_legacy_cli_contract.py
index c1285f7..f5f1789 100644
--- a/tests/test_legacy_cli_contract.py
+++ b/tests/test_legacy_cli_contract.py
@@ -90,6 +90,39 @@ def test_create_project(tmp_path, flag):
     assert any(project.rglob("*.json")), result.stdout + result.stderr
 
 
+def _failing_actions(target: Path) -> list:
+    """An action that fails (no command has that name), then one that writes *target*."""
+    return [["FA_no_such_action"], *_actions(target)]
+
+
+@pytest.mark.parametrize("flag", ["-e", "--execute_file"])
+def test_a_failed_action_exits_1_after_the_rest_ran(tmp_path, flag):
+    target = tmp_path / "created.txt"
+    action_file = tmp_path / "actions.json"
+    action_file.write_text(json.dumps(_failing_actions(target)), encoding="utf-8")
+    result = _run_cli(tmp_path, flag, str(action_file))
+    assert result.returncode == 1
+    assert "error: 1 action(s) failed" in result.stderr
+    assert target.exists(), result.stdout + result.stderr
+
+
+def test_a_failed_action_in_a_directory_exits_1(tmp_path):
+    action_dir = tmp_path / "actions"
+    action_dir.mkdir()
+    (action_dir / "a_ok.json").write_text(
+        json.dumps(_actions(tmp_path / "a.txt")), encoding="utf-8"
+    )
+    (action_dir / "b_bad.json").write_text(
+        json.dumps(_failing_actions(tmp_path / "b.txt")), encoding="utf-8"
+    )
+    assert _run_cli(tmp_path, "--execute_dir", str(action_dir)).returncode == 1
+
+
+def test_a_failed_action_in_execute_str_exits_1(tmp_path):
+    payload = _pybreeze_execute_str(_failing_actions(tmp_path / "created.txt"))
+    assert _run_cli(tmp_path, "--execute_str", payload).returncode == 1
+
+
 def test_no_flag_exits_non_zero(tmp_path):
     assert _run_cli(tmp_path).returncode != 0