Feat/run level timeout

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: Device Test Runner CI
 on:
     push:
         branches:
-            - main
+            - "**"
     pull_request:
         branches:
             - main
@@ -12,8 +12,8 @@ permissions:
     contents: read
 
 jobs:
-    test:
-        name: Code Quality and Tests
+    code-quailiry:
+        name: Code Quality
         runs-on: ubuntu-latest
         steps:
             - name: Checkout repository
@@ -27,20 +27,48 @@ jobs:
             - name: Install Poetry
               run: python -m pip install "poetry>=2,<3"
 
-            - name: Show Python version
-              run: python --version
+            - name: Install dependencies
+              run: poetry install --no-interaction
 
-            - name: Show Poetry version
-              run: poetry --version
+            - name: Run pre-commit
+              run: poetry run pre-commit run --all-files
+    unit-tests:
+        name: Unit Tests
+        runs-on: ubuntu-latest
+        steps:
+          - name: Checkout repository
+            uses: actions/checkout@v7
 
-            - name: Check dependency lock file
-              run: poetry check --lock
+          - name: Set up Python
+            uses: actions/setup-python@v7
+            with:
+              python-version: "3.14"
 
-            - name: Install dependencies
-              run: poetry install --no-interaction
+          - name: Install Poetry
+            run: python -m pip install "poetry>=2,<3"
+
+          - name: Install dependencies
+            run: poetry install --no-interaction
+
+          - name: Run Unit Test
+            run: poetry run pytest tests/test_unit
+    integration-tests:
+        name: Integration Tests
+        runs-on: ubuntu-latest
+        steps:
+          - name: Checkout repository
+            uses: actions/checkout@v7
+
+          - name: Set up Python
+            uses: actions/setup-python@v7
+            with:
+              python-version: "3.14"
+
+          - name: Install Poetry
+            run: python -m pip install "poetry>=2,<3"
 
-            - name: Code Quality
-              run: poetry run pre-commit run --all-files --show-diff-on-failure
+          - name: Install dependencies
+            run: poetry install --no-interaction
 
-            - name: Run tests
-              run: poetry run pytest
+          - name: Run Integration Test
+            run: poetry run pytest tests/test_integration

.gitignore

@@ -12,4 +12,4 @@ env/
 *.pyc
 
 artifact/
-.coverage
+.coverage

.pre-commit-config.yaml

@@ -22,6 +22,7 @@ repos:
       - id: isort
         exclude: migrations/
         args:
+          - --profile=black
           - --line-length=100
 
   - repo: https://github.com/psf/black

.vscode/launch.json

@@ -1,7 +1,4 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
 
@@ -27,7 +24,7 @@
             "args": [
                 "tests/test_unit/test_runner.py",
                 "-k",
-                "test_artifact_missing_retries"
+                "test_cancelled_step_is_not_retried"
 
             ]
         }

CHANGELOG.md

@@ -1,12 +1,38 @@
 # Changelog
 
-## [Unreleased]
+## [1.6.2]
+
+Version scope: Run-level Timeout. Distribution, runtime and report versions are synchronized to 1.6.2. This entry describes the working tree, not a verified release.
+
+### Added
+
+- Optional top-level `run_timeout_seconds`, validated as a finite positive number; omitted/null means unlimited run time.
+- Monotonic watchdog shared across normal steps and retries; cancellation reasons preserve the first request.
+- `TIMED_OUT` run status and metadata `cancel_reason`, `run_timeout_seconds`, `run_timed_out`.
+- Configuration, cancellation reason, watchdog, status, setup timeout, retry delay, serialized attempt history and orphan process regression tests.
+- v1.6.2 architecture, test matrix, acceptance criteria, completion checklist and testing-guide cases.
 
 ### Changed
 
-- Reorganized the README around setup, execution, configuration and reports.
-- Edited versioned documentation for clearer headings, shorter explanations and readable acceptance conditions.
-- Expanded the commit checklist with concrete documentation and release checks.
+- Consolidated README, lifecycle documentation, testing guidance and release checks for v1.6.2.
+
+- `RunResult.passed` follows summary status; `StepAttemptResult.passed` is removed in favor of `success`.
+- Run timeout interrupts normal work without retrying cancelled attempts; reachable cleanup uses fresh tokens and final validation still runs.
+
+### Fixed
+
+- Standardized run timeout report metadata on `run_timed_out`, with explicit JSON regression assertions.
+
+- Omitted timeout returns None; watchdog uses Event.wait instead of the misspelled method.
+- Terminator checks the original process group even after the direct child is reaped.
+- Missing existence-rule targets report ARTIFACT_MISSING; size diagnostics no longer contain indentation spaces.
+- Tests correct empty-directory classification, fixture paths, imports, report access and unordered status parameters.
+
+### Verification and limitations
+
+- Current commands and results: [v1.6.2 Definition of Done](docs/definition_of_done/definition_of_done_v1.6.2.md).
+- CLI TIMED_OUT currently returns 0; cleanup has no independent total deadline. Exception finalization, platform checks and detached-process handling remain open.
+- Package version is synchronized; tag and GitHub Release remain pending.
 
 ## [1.6.1]
 

CommitManual.md

@@ -4,11 +4,11 @@
 
 ## 提交前
 
-- [ ] 確認版本號；需要升版時，同步套件、runtime 與報告版本。
+- [ ] 確認版本號；需要升版時，依下方「版本號更新步驟」同步套件、runtime 與報告版本。
 - [ ] 檢查程式變更是否符合需求，移除暫存程式與除錯輸出。
 - [ ] 更新受影響的測試，執行相關測試並記錄結果。
 - [ ] 檢查 `tests/` 下每個 Python 測試函式的 docstring，使用具體的 `Given`、`When`、`Then` 行說明前提、操作與預期結果。
-- [ ] 更新 [README](README.md) 的使用方式、範例與限制。
+- [ ] 依下方「README 撰寫條件」更新 [README](README.md)，確認外部使用者無須閱讀舊版或 diff 即可理解專案並開始使用。
 - [ ] 更新對應版本的架構文件，確認介面與資料流。
 - [ ] 在版本架構文件中加入或更新 Mermaid UML：使用 `classDiagram` 說明主要類別與關係，使用 `sequenceDiagram` 說明關鍵執行流程。圖中的名稱、呼叫順序與分支須符合該版本實作；規劃中的設計須另外標示。
 - [ ] 在 [CHANGELOG](CHANGELOG.md) 記錄使用者可觀察的變更。
@@ -23,6 +23,30 @@
 - [ ] 檢查文件：先說用途，使用短句與具體動詞；保留必要術語，刪除空泛宣傳與重複結論。
 - [ ] 執行 `git diff --check`，檢查連結、命令與範例。
 
+## README 撰寫條件
+
+README 面向第一次接觸專案的外部使用者，必須能獨立閱讀。依目前實作說明用途與操作，不要求讀者先了解上一版、Git diff 或內部開發進度。
+
+- [ ] 內容依序涵蓋專案簡介、解決的痛點、專案架構、安裝、使用手冊（User Manual）與文件導覽；測試、CI、限制與後續規劃等補充內容保持精簡。
+- [ ] 簡介說明專案用途、適用情境與主要能力；痛點對應實際功能，不將規劃中的功能寫成已支援。
+- [ ] 架構提供主要元件、資料流與目錄用途，詳細介面與 UML 連結至對應版本架構文件。
+- [ ] 安裝列出環境需求、取得專案與安裝命令。使用手冊提供可操作的入門範例，說明設定儲存位置、執行方式、輸出位置與結果判讀。
+- [ ] 範例交代外部工具、裝置需求與需替換的值；區分可直接執行、示意資料與刻意失敗的範例。重要限制放在相關操作附近。
+- [ ] 使用現在式描述目前行為。版本號可用於標示目前版本與文件連結，不以「本版新增」、「相較上一版」、「已移除」或逐版差異作為功能教學。
+- [ ] 版本差異記錄於 CHANGELOG；升級與介面相容性細節放在對應版本文件；歷史測試結果、驗收與發佈狀態保留於測試矩陣、驗收或完成條件；未來計畫放在 Roadmap。README 提供入口，避免複製維護紀錄。
+- [ ] 保留使用者需要知道的現有限制與替代操作，不因移除版本比較而刪除必要資訊。
+- [ ] 文件導覽連結有效，並清楚區分使用教學、架構、測試、歷史變更及維護流程。
+- [ ] 以首次使用者角度通讀：能回答「這是什麼、解決什麼問題、如何安裝與使用、去哪裡看結果與更多文件」，且不需對照上一版。
+
+## 版本號更新步驟
+
+1. 修改 `pyproject.toml` 的 `[project].version`，使用不含 `v` 的版本號，例如 `version = "1.6.2"`。
+2. 核對 `runner/runner.py` 的 `DeviceTestRunner.VERSION` 與套件版本一致。報告的 `metadata.runner_version` 由此值產生。
+3. 同步 README、CHANGELOG、Roadmap 及該版本架構、驗收與完成條件中的版本狀態；保留舊版文件的歷史紀錄。
+4. 執行 `poetry check --lock` 確認設定與 lock file 一致。僅修改專案版本時，不需手動改寫依賴版本或 lock file；若另有依賴設定變更，重新產生並檢查 lock diff。
+5. 執行 `poetry version --short` 核對套件版本，並確認 `DeviceTestRunner.VERSION` 與報告建構程式使用的版本一致。更新已安裝套件時，另執行 `poetry install --no-interaction`。
+6. 執行相關檢查及 `git diff --check`，提交時納入 `pyproject.toml`、必要的 runtime 修改與文件。版本同步不代表已建立 tag 或發布 GitHub Release。
+
 ## 發佈前
 
 - [ ] 確認該版本的完成條件與驗收條件已滿足。
@@ -48,7 +72,7 @@ Codex 必須先完整閱讀本清單，並核對下列文件。`<version>` 代
 
 | 文件 | 核對內容 |
 | --- | --- |
-| `README.md` | 使用方式、範例與限制 |
+| `README.md` | 依「README 撰寫條件」核對專案簡介、痛點、架構、安裝、使用手冊、文件導覽與必要限制；以目前行為說明 |
 | `docs/architecture/architecture_v<version>.md` | 架構、介面、資料流，以及符合該版本實作的 UML 類別圖與循序圖 |
 | `docs/test_matrix/test_matrix_v<version>.md` | 測試覆蓋、證據與 AI 協作新增或補強的案例，連結至測試指南的對應版本 |
 | `docs/test_guide.md` | Pytest 用法大綱、工具分類、版本索引與各版實際案例 |

Makefile

@@ -8,4 +8,4 @@ test:
 test_cov:
 	@pytest -v ./tests \
 			--cov=runner \
-			--cov-report=term-missing 
+			--cov-report=term-missing