# Live GUI Test Infrastructure Fixes (2026-06-18)

## 0. Overview

This track addresses 2 test failures reported as "documented issues" by the `result_migration_small_files_20260617` sub-track Phase 13 (commit `30ca3265`). The failures are in test infrastructure (not Result[T] migration) and block full sub-track 2 closure.

**The 2 issues:**

1. **`tests/test_extended_sims.py:59::test_execution_sim_live`** (tier-3-live_gui)
   - GUI subprocess (port 8999) crashes mid-test during script generation flow.
   - Same failure with both `gemini_cli` (mock subprocess) and `gemini` (real SDK with `gemini-2.5-flash-lite`).
   - 90s timeout reached without AI text. The GUI dies before the AI can respond.
   - NOT provider-specific.
   - Documented in `docs/reports/TRACK_COMPLETION_result_migration_small_files_20260617.md` Phase 13 Addendum.

2. **`tests/test_live_gui_workspace_fixture.py:10::test_live_gui_workspace_exists`** (tier-1-unit-gui)
   - xdist race condition. Workspace can be cleaned up between fixture setup and test assertion.
   - Passes in isolation on both parent (`4ab7c732`) and current commit.
   - Documented in `docs/reports/TRACK_COMPLETION_result_migration_small_files_20260617.md` Phase 13 Addendum.

**Both issues are NOT regressions from the Result[T] migration.** They are pre-existing test infrastructure issues that surface in batched parallel test runs.

**This track is small:** 2 issues, 1 test file + 1 conftest change (likely), 11 tiers verified.

## 1. Current State Audit (as of 2026-06-18, base commit `30ca3265`)

### Already Implemented (DO NOT re-implement)

- **Phase 13 of `result_migration_small_files_20260617`** (commit `30ca3265`) — the migration track is shipped with 2 documented issues for diff tracks. This track picks up the 2 issues.
- **`scripts/run_tests_batched.py:207-214`** (commit `0c62ab9d`) — `sys.stdout.reconfigure(encoding="utf-8", errors="replace")` fix for the UnicodeEncodeError crash.
- **`tests/artifacts/PHASE13_PARENT_COMMIT_RESULTS.log`** (commit `b96252e9`) — parent commit investigation log. Documents that 0 of the 3 reported Phase 12 failures are regressions; 2 are pre-existing flakies (Gemini 503); 1 is a parallel-execution flake.

### Gaps to Fill (This Track's Scope)

1. **Issue 1 (`test_execution_sim_live`):** investigate the GUI subprocess crash on port 8999. Find the root cause. Fix it. Add a TDD test that captures the failure mode. Verify the test passes.
2. **Issue 2 (`test_live_gui_workspace_exists`):** investigate the xdist race in the `live_gui_workspace` fixture. Find the root cause. Fix it. Add a TDD test that captures the race. Verify the test passes.
3. **Verify all 11 tiers pass clean** (no documented issues) after both fixes.

### Out of Scope (Explicit)

- The 4 `@pytest.mark.skip` markers for Gemini 503 pre-existing failures (`test_auto_aggregate_skip`, `test_view_mode_summary`, `test_view_mode_default_summary`, `test_view_mode_custom_empty_default_to_summary`). These depend on the live Gemini API. To remove them, mock the Gemini API in `summarize.summarise_file` for tests. This is a separate concern; deferred to a follow-up track.
- Sub-track 3 (`result_migration_app_controller`) and beyond. This track is a precondition for sub-track 2's full closure; sub-track 3 is a separate track.
- The 4 audit-script bug fixes from sub-track 2 Phase 1 (already done in commit `4c536e79`).
- The 27 sites migrated in sub-track 2 (already done in Phases 3-8 and Phase 12).
- Phase 13 state.toml cleanup (the `phase_13_all_11_tiers_actually_pass = false` flag inconsistency). This is a small cleanup task; will be done in a separate commit, not in this track.

## 2. Goals

- Fix the 2 documented test infrastructure issues.
- Verify all 11 test tiers pass clean (no documented issues, no skip markers from this track).
- Re-verify Issue 2 on the parent commit `4ab7c732` to confirm it is a pre-existing race, not a Phase 12 regression.
- Unblock sub-track 2's full closure (the 2 issues are removed; the only remaining skip markers are the 4 Gemini 503 pre-existing failures, which are out of scope for this track).

## 3. Functional Requirements

### FR-1: Fix `test_execution_sim_live` GUI subprocess crash

- **File:** `tests/test_extended_sims.py:59::test_execution_sim_live`
- **Symptom:** GUI subprocess (port 8999) crashes mid-test during script generation flow. 90s timeout reached without AI text.
- **Failure observed with both providers:** `gemini_cli` (mock subprocess) and `gemini` (real SDK, `gemini-2.5-flash-lite`).
- **Investigation steps:**
  1. Read `src/gui_2.py` to find the script generation flow.
  2. Read `src/app_controller.py` to find the GUI subprocess management.
  3. Read `src/extended_sims.py` (or wherever the `ExecutionSimulation` is) to find the `sim.run()` implementation.
  4. Read the test (`tests/test_extended_sims.py`) to understand the trigger.
  5. Reproduce the crash in isolation. Add diagnostic logging temporarily to identify where the GUI dies.
  6. Find the root cause (deadlock, memory issue, signal handling bug, port conflict, etc.).
- **Fix approach:** TDD. Add a failing test that captures the crash mode. Fix the root cause. Verify the test passes. Remove diagnostic logging.
- **Commit:** `fix(src): test_execution_sim_live GUI subprocess crash — root cause: [description]`
- **Git note:** "Phase FR-1. The GUI subprocess (port 8999) crashes mid-test during script generation. Root cause: [description]. Same failure with both gemini_cli and gemini. NOT provider-specific. Fixed by [approach]."

### FR-2: Fix `test_live_gui_workspace_exists` xdist race

- **File:** `tests/test_live_gui_workspace_fixture.py:10::test_live_gui_workspace_exists`
- **Symptom:** xdist race condition. Workspace can be cleaned up between fixture setup and test assertion. Passes in isolation.
- **Investigation steps:**
  1. **Verify on parent commit `4ab7c732` first** (per AGENTS.md: pre-existing claims must be backed by parent-commit run, not assertion). Run the test on parent in isolation. If it passes on parent in isolation, it's pre-existing. If it fails on parent in isolation, it's a Phase 12 regression.
  2. Read `tests/conftest.py:727::live_gui_workspace` to understand the fixture.
  3. Read the `live_gui` fixture (parent of `live_gui_workspace`) to understand cleanup behavior.
  4. Identify what cleans up the workspace between fixture setup and test assertion under xdist.
  5. Find the root cause (likely a session-level cleanup that fires asynchronously).
- **Fix approach:** TDD. Add a failing test that captures the race. Fix the root cause. Verify the test passes under xdist.
- **Commit:** `fix(tests): test_live_gui_workspace_exists xdist race — root cause: [description]`
- **Git note:** "Phase FR-2. xdist race condition. [verified on parent commit / regression if not]. Root cause: [description]. Fixed by [approach]."

### FR-3: Verify all 11 test tiers pass clean

- **Run:** `uv run python scripts/run_tests_batched.py`
- **Verify:** The script runs to completion (no UnicodeEncodeError crash). All 11 tiers show `<<< tier-X PASS`. The summary table shows 11/11 PASS.
- **Per-tier checks:**
  - 9 tiers: 0 failures, 0 errors.
  - 2 tiers (tier-1-unit-gui, tier-3-live_gui): 0 failures after the fixes in FR-1 and FR-2.
- **Document:** Save the test run output to `tests/artifacts/PHASE14_TEST_RUN_RESULTS.log`.
- **Commit:** (no commit — just verification)

### FR-4: Re-verify Issue 2 on parent commit

- **File:** `tests/test_live_gui_workspace_fixture.py:10::test_live_gui_workspace_exists`
- **Action:** Run the test on the parent commit `4ab7c732` in isolation. Record pass/fail.
- **Save:** Update `tests/artifacts/PHASE13_PARENT_COMMIT_RESULTS.log` with the Issue 2 verification.
- **Commit:** `chore(audit): Phase 14.2 - verify Issue 2 on parent commit (record result)`

## 4. Non-Functional Requirements

- **No day estimates, no T-shirt sizes.** Per AGENTS.md HARD BAN.
- **Atomic per-task commits.** Each fix is one commit. No batching of FR-1 and FR-2 into one commit.
- **Per-task git notes.** Each commit has a 1-3 sentence git note summarizing the change.
- **All 11 test tiers must pass.** The test count is 11, NOT 10, NOT 9. (This is the sixth time this is being emphasized across sub-track 2.)
- **No new `@pytest.mark.skip` markers.** Per user directive: do not add skip markers for flaky tests. Investigate and fix the root cause. If the fix is too large for this track, escalate to a follow-up track (do not skip).
- **AGENTS.md HARD BAN on `git restore` and `git checkout -- <file>`.** Use `git checkout <commit>` (whole commit) and return via `git checkout <branch>`.

## 5. Architecture Reference

- **`docs/guide_testing.md`** — the project's testing standard. 251 test files, 5 categories, 7 conftest fixtures (`isolate_workspace`, `reset_paths`, `reset_ai_client`, `vlogger`, `kill_process_tree`, `mock_app`, `live_gui` session-scoped), Puppeteer pattern, mock provider, structural testing contract.
- **`conductor/code_styleguides/workspace_paths.md`** — workspace path rules. Test workspaces live in `tests/artifacts/`. Conftest creates them. Never use `tmp_path_factory.mktemp` (it lives in `%TEMP%` and the user cannot find it).
- **`docs/AGENTS.md` §"Critical Anti-Patterns"** — the rules this track follows: TDD, no comments, atomic commits, per-task git notes, 1-space indentation, no diagnostic noise in production.
- **`docs/AGENTS.md` §"Skip-Marker Policy"** — `@pytest.mark.skip(reason=...)` is documentation of a known failure, not an excuse. The 4 existing skip markers from sub-track 2 Phase 13 are documented; this track does NOT add new ones.

## 6. Risks

| Risk | Mitigation |
|---|---|
| The GUI subprocess crash root cause is hard to find | Add diagnostic logging temporarily; remove in the final commit. If the root cause is found but the fix is too large for this track, escalate to a follow-up track. Do NOT add a skip marker. |
| The xdist race fix requires a fundamental change to the `live_gui` fixture | Investigate the fixture carefully. If the fix touches `src/app_controller.py` or `src/gui_2.py`, the change may need cross-tier verification. Run the full 11-tier test suite after the fix. |
| Tier-2 re-adds a skip marker for Issue 1 or Issue 2 | The plan EXPLICITLY says "no new `@pytest.mark.skip` markers". User directive: switch provider and report if fails. If the fix is too large, escalate — do not skip. |
| Tier-2 miscounts test tiers (claiming 10 instead of 11) | The plan EXPLICITLY says "all 11 test tiers PASS". The 11th tier is `tier-1-unit-comms`. This is the sixth time. |
| Tier-2 makes a destructive edit (e.g., `write` tool to plan.md) | Use `manual-slop_edit_file` for plan.md. Never use destructive `write` on tracked files. |

## 7. Verification Criteria

- [ ] FR-1: `test_execution_sim_live` passes in isolation AND in batched run.
- [ ] FR-2: `test_live_gui_workspace_exists` passes in isolation AND in batched run. Verified on parent commit `4ab7c732` first.
- [ ] FR-3: All 11 test tiers pass clean (no documented issues from this track). 9/11 tiers remain passing clean. 2/11 tiers (tier-1-unit-gui, tier-3-live_gui) now pass clean (after the fixes).
- [ ] FR-4: Issue 2 parent-commit verification recorded.
- [ ] No new `@pytest.mark.skip` markers added by this track.
- [ ] Sub-track 2 `state.toml` cleanup: `phase_13_all_11_tiers_actually_pass = false` flag is fixed (in a separate commit, not in this track).
- [ ] Atomic per-task commits with git notes.
- [ ] No day estimates, no T-shirt sizes in any artifact.

## 8. Plan Reference

See `plan.md` for the executable plan (per-task WHERE / WHAT / HOW / SAFETY / COMMIT / GIT NOTE).

## 9. Notes for the Tier 2 Implementer

1. **Verify Issue 2 on parent commit FIRST** (per AGENTS.md skip-marker policy and the user's emphatic directive that "pre-existing" claims must be backed by parent-commit run). If it fails on parent in isolation, it's a Phase 12 regression — fix in FR-2. If it passes on parent in isolation, it's pre-existing — fix in FR-2 anyway (the user wants the test to pass in batch).
2. **Add diagnostic logging temporarily** to find the GUI subprocess crash root cause. **REMOVE the diagnostic logging in the final commit** (per AGENTS.md "No Diagnostic Noise in Production" rule). No `sys.stderr.write(f"[XYZ_DIAG] ...")` lines left in `src/*.py` after the fix.
3. **Use the 1-space indentation** for Python code (per AGENTS.md CRITICAL rule).
4. **Do NOT add new `@pytest.mark.skip` markers** for Issue 1 or Issue 2. The 4 existing skip markers from sub-track 2 Phase 13 are documented; do not add more.
5. **The test count is 11, NOT 10, NOT 9.** The 11th tier is `tier-1-unit-comms`. This is the **SIXTH** time this is being emphasized across the result_migration sub-tracks.
6. **The 4 Gemini 503 skip markers are out of scope.** They depend on the live Gemini API. To remove them, mock the Gemini API in `summarize.summarise_file` for tests. This is a separate concern; deferred to a follow-up track.
