fix(test): CLITestHelper timeout 後直接讀 terminationStatus — process 未退出時拋 NSInvalidArgumentException (sibling concern from #131)

[kiki830621]

Problem

Tests/MacDocCLITests/CLITestHelper.swift 的 run(_:timeout:)：timeout 到期時呼叫 process.terminate() 後立即讀 process.terminationStatus。terminate() 只送 SIGTERM、不等待——process 還沒真正退出時讀 terminationStatus 會拋 ObjC 例外。

Type

bug

Expected

timeout 後 terminate() → waitUntilExit()（或有界輪詢 isRunning）→ 再讀 terminationStatus；測試以「逾時失敗」收場而非 crash 整個 test process。

Actual

實證（2026-07-08）：.note 轉換在 clean build 後首次執行冷啟超過 30s timeout → *** -[NSConcreteTask terminationStatus]: task still running (NSInvalidArgumentException)，XCTest 以 signal 6 中止，整個 suite 的其餘測試沒跑。

Impact

任何 CLI e2e 測試偶發變慢（冷啟、CI 負載）就會把 test process 整個炸掉，掩蓋真正的結果。單行修正 + 低風險。

---

Sibling concern surfaced during #131 filing (session 2026-07-08); parent context: #131

---

Current Status

Phase: closed
Last updated: 2026-07-16 by idd-close

Key Decisions

• Complexity = Simple；next: /idd-implement fix(test): CLITestHelper timeout 後直接讀 terminationStatus — process 未退出時拋 NSInvalidArgumentException (sibling concern from #131) #133

Scope Changes

• (none)

Blocking

• (none)

Closing

• fix(test): CLITestHelper timeout 後直接讀 terminationStatus — process 未退出時拋 NSInvalidArgumentException (sibling concern from #131) #133 (comment)

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

（superpowers:systematic-debugging pre-flight OK；root cause 已由 issue repro 確立，證據充分）

我認為 root cause 是 Tests/MacDocCLITests/CLITestHelper.swift 的 run(_:timeout:) 在 timeout 後違反 Process.terminationStatus 的前置條件，因為：

• Line 56 process.terminate() 只送 SIGTERM、不阻塞等 process 退出；
• Line 63 隨即讀 process.terminationStatus——此時 process 仍在跑（SIGTERM 尚未生效 / 進程正在清理），terminationStatus 對「still running」的 process 拋 NSInvalidArgumentException。

實證（2026-07-08）：*** -[NSConcreteTask terminationStatus]: task still running (NSInvalidArgumentException)，XCTest 以 signal 6 中止，suite 其餘測試沒跑。

觸發條件：.note 冷啟轉換 > 30s timeout（clean build 後首次執行）。既有的 timeout 迴圈（line 53-55）正常路徑會等到 !process.isRunning 才離開，只有走 terminate 分支才缺 wait。

Impact

• 影響檔案：Tests/MacDocCLITests/CLITestHelper.swift（單一函式）
• 影響流程：任何 CLI e2e 測試偶發變慢（冷啟 / CI 負載）就炸掉整個 test process，掩蓋真正結果

Strategy

• terminate() + pipe-drain 後補 waitUntilExit() 再讀 terminationStatus（b78e0f2）
• TDD regression test：/bin/sleep + tiny timeout 確定性打中 terminate 分支，斷言回傳 result 而非 crash（b78e0f2）

Conflict Class

A_parallel_safe —— 單檔 test helper，無共享資源。

Complexity

Simple

Clear root cause + self-contained 單檔 fix，跟既有 timeout-loop pattern 一致。

Risks

• waitUntilExit() 理論上可 hang（若 process 忽略 SIGTERM）——SIGTERM 對 macdoc CLI 一般會退；若要保險可 SIGKILL fallback，但屬 over-engineering，先用 waitUntilExit

Residue

(none)

---

Hard-gate: not triggered — 單檔單函式 fix，無散佈概念、無 shared abstraction。

Vagueness Pre-check

• V1: 2 — WHAT 明確：terminate 後補 waitUntilExit
• V4: 2 — 驗收明確：逾時以測試失敗收場而非 crash
• Triggered: no — both axes ≤ 3

[kiki830621]

Verify: #133（quick — codex 單引擎）

Engine

codex-call (gpt-5.5, xhigh, fast) — 跨模型盲驗；diff = 36bb0fd..b78e0f2（CLITestHelper.swift + CLITestHelperTimeoutTests.swift），FROZEN_SHA b78e0f2

Aggregate

PASS — 0 blocking，1 LOW advisory（已採納）

確認

1. 崩潰窗關閉：是 —— terminationStatus 一定在 waitUntilExit()（reap）之後讀，即使 terminate() 只非同步送 SIGTERM，也先等子行程被 reap，避免「task still running」NSInvalidArgumentException
2. pipe drain / waitUntilExit 順序合理 —— 先 drain pipe 再 wait 比反過來安全（先 wait 可能在 pipe 滿時死鎖）
3. regression test 穩定 —— /bin/sleep 5 + timeout 0.3 確定性打中 terminate 分支，不依賴 macdoc 啟動時序
4. 正常退出路徑未破壞 —— /bin/echo 覆蓋，對已退出 process 呼叫 waitUntilExit() 立即返回

Findings

#	Severity	Finding	Source	Action
1	LOW	「deadlock-safe」註解措辭太絕對——SIGTERM-ignoring child / 繼承 FD 的孫行程仍可能 hang（既有 pipe-capture 限制，非本修補新增）	codex	✅ 已採納（def33a8 軟化註解措辭，behavior 不變）

Scope Check

改動限 Tests/MacDocCLITests/（test infra），未觸 production code；無 scope creep。

[kiki830621]

Closing Summary

Problem

Tests/MacDocCLITests/CLITestHelper.swift 的 run(_:timeout:) 在 timeout 後 terminate()（只送 SIGTERM、不等退出）隨即讀 terminationStatus，對未 reap 的 process 拋 NSInvalidArgumentException（「task still running」），signal 6 中止整個 XCTest process，掩蓋 suite 其餘測試結果。

Root Cause

terminate() 是非同步的——SIGTERM 送出後 process 尚未被 reap 時，Process.terminationStatus 的前置條件（process 已終止）未滿足即讀取。既有 timeout 迴圈只在正常退出路徑等到 !isRunning，terminate 分支缺 reap。

Solution

• 抽出可測的 runProcess(executableURL:arguments:currentDirectory:timeout:)，run 變薄 wrapper
• terminate + pipe-drain 後補 waitUntilExit() 才讀 terminationStatus——reap 子行程，關閉崩潰窗；drain-before-wait 避免 pipe 滿死鎖

Verification

• TDD：先寫 RED（runProcess 不存在）→ 實作 → GREEN
• regression test 用 /bin/sleep 5 + timeout 0.3 確定性打中 terminate 分支（不依賴 macdoc 冷啟時序），斷言逾時路徑回傳 result 而非 crash；/bin/echo 覆蓋正常路徑
• codex 跨模型盲驗 PASS（0 blocking）：確認崩潰窗關閉、順序合理、測試穩定、正常路徑未破壞——verify report
• macdoc 全 suite 19 tests 綠（含新 2 個 timeout regression）

Changes

• b78e0f2 fix(test): reap child before reading terminationStatus in CLITestHelper timeout path
• def33a8 docs: soften absolute 'deadlock-safe' comment（codex LOW advisory 採納，comment-only）

Residue Acknowledgement

Diagnosis residue = (none)。（codex 提的「支援任意惡意/大量輸出程序需並行 drain + SIGKILL escalation」屬既有 pipe-capture 一般限制，非本 test-helper fix 的 scope。）