Bound real-client E2E wall-clock and reap orphan process trees #196

Outcome

Make the real-client E2E test and runner boundaries provably bounded: a failed or abandoned child process cannot leave pytest, GUI fixtures, Gateway fixtures, or descendants running indefinitely.

Observed evidence

On 2026-07-22, the Issue #190 worktree contained an orphaned command:

• python -m pytest -q tests/test_real_client_e2e.py had been alive for more than 24 hours.
• Its parent process no longer existed, CPU time was unchanged at 4.12 seconds, and all three threads were waiting.
• An orphan ping.exe 127.0.0.1 -t from the expanding-process-tree fixture remained alive with a dead parent.
• The relevant fixture path exercises tests/test_real_client_e2e.py::test_manual_timeout_cleanup_is_bounded_and_still_writes_one_summary.

This is a harness failure, not evidence that a real twelve-case E2E legitimately needs multiple days.

Scope

• Put an outer wall-clock deadline around every unattended pytest/runner invocation.
• Make timeout cleanup own and terminate the full Windows process tree, including descendants that outlive or detach from an intermediate parent.
• Ensure inherited stdout/stderr handles cannot leave Python subprocess communication waiting forever after the direct child exits or is killed.
• On timeout, write one bounded sanitized failure record and return non-zero promptly.
• Document the distinction between automated deadlines and the explicit Desktop/ZCode human-evidence window.
• Do not weaken real-client isolation, evidence binding, or fail-closed behavior.

Acceptance criteria

• A deterministic regression launches an expanding descendant tree containing a long-lived ping process, removes an intermediate parent, and proves the test returns within its deadline with no surviving descendant.
• A subprocess timeout cannot hang while draining inherited stdout/stderr pipes.
• The Issue test module has an external watchdog; an unattended validation command cannot remain alive after its supervising agent exits.
• Manual evidence timeout is explicit and bounded; it is never silently converted into an infinite automated wait.
• Timeout diagnostics contain the failed phase and bounded process counts, but no credentials, prompts, absolute private paths, or process command secrets.
• Existing Add pinned real-client E2E qualification foundation for Gateway candidates #190 positive, timeout, GUI-cleanup, candidate-startup, and isolation tests remain green.

Verification

python -m pytest -q tests/test_real_client_e2e.py
python -m pytest -q
git diff --check
python scripts/report_quality_gates.py

The report-quality command is report-only. Verification class is strict because this changes process lifecycle, cancellation, and release-gate evidence.

Relationships

• Blocks completion of Add pinned real-client E2E qualification foundation for Gateway candidates #190.
• Related to Preserve OpenCode tool-result history on third-party transparent Responses routes #193 and the release roadmap Wayfinder: CodexHub 0.1.6–0.3.0 Gateway and release roadmap #147.