# Live GUI Test Infrastructure Fixes — Plan

## Phase 1: Investigation

Focus: Find the root causes of the 2 issues.

- [ ] **Task 1.1: Read the relevant code for Issue 1 (GUI subprocess crash)**
  - WHERE: `tests/test_extended_sims.py:59::test_execution_sim_live`, `src/extended_sims.py` (or wherever `ExecutionSimulation` is), `src/gui_2.py`, `src/app_controller.py`
  - WHAT: Read the test trigger (`sim.run()`), the simulation setup, the GUI subprocess management, and the script generation flow.
  - HOW: Use `manual-slop_read_file` for the test; `manual-slop_py_get_skeleton` for the production code; `manual-slop_py_find_usages` to find where the GUI subprocess is started.
  - SAFETY: Read-only.
  - NO COMMIT (investigation only).

- [ ] **Task 1.2: Reproduce the GUI subprocess crash in isolation**
  - WHERE: `tests/test_extended_sims.py:59::test_execution_sim_live`
  - WHAT: Run the test in isolation with `-v` to confirm the failure mode matches the report (90s timeout, no AI text).
  - HOW: `uv run pytest tests/test_extended_sims.py::test_execution_sim_live -v --timeout=120`
  - SAFETY: Read-only. If the test passes in isolation, the failure is environmental (xdist, parallel load); investigate differently.

- [ ] **Task 1.3: Read the relevant code for Issue 2 (xdist race)**
  - WHERE: `tests/test_live_gui_workspace_fixture.py:10::test_live_gui_workspace_exists`, `tests/conftest.py:727::live_gui_workspace`, the `live_gui` fixture (parent)
  - WHAT: Read the fixture chain. Identify what cleans up the workspace.
  - HOW: Use `manual-slop_read_file` and `manual-slop_py_find_usages`.
  - SAFETY: Read-only.

- [ ] **Task 1.4: Verify Issue 2 on parent commit `4ab7c732` in isolation**
  - WHERE: Parent commit `4ab7c732`
  - WHAT: Check out the parent commit, run the test in isolation, record pass/fail.
  - HOW: `git checkout 4ab7c732` (whole commit; per AGENTS.md HARD BAN on `git checkout -- <file>`), then `uv run pytest tests/test_live_gui_workspace_fixture.py::test_live_gui_workspace_exists -v`. Then `git checkout tier2/result_migration_small_files_20260617` to return.
  - SAFETY: HARD BAN on `git checkout -- <file>`. Use `git checkout <commit>` and `git checkout <branch>`. The branch is the working track; switching to a commit and back is safe.
  - RECORD: Save the result to `tests/artifacts/PHASE14_PARENT_VERIFICATION.log` (continuation of `PHASE13_PARENT_COMMIT_RESULTS.log`).
  - COMMIT: `chore(audit): Phase 14.1 - verify Issue 2 on parent commit 4ab7c732 (recorded result)`

---

## Phase 2: Fix Issue 2 (xdist race)

Focus: Fix the `test_live_gui_workspace_exists` failure. This is the smaller of the 2 issues.

- [ ] **Task 2.1: Add a TDD test that captures the race**
  - WHERE: `tests/test_live_gui_workspace_fixture.py` (extend the existing test file)
  - WHAT: Add a new test that captures the race condition. E.g., `test_live_gui_workspace_stable_under_xdist` that runs the assertion in a loop and checks the workspace exists for a few iterations.
  - HOW: Use `manual-slop_edit_file` to add the new test. Follow the existing test style (1-space indent, type hints, docstring).
  - SAFETY: TDD-first. The test should FAIL on the current commit (without the fix) and PASS after the fix.
  - VERIFY: `uv run pytest tests/test_live_gui_workspace_fixture.py::test_live_gui_workspace_stable_under_xdist -v` should FAIL on current.
  - COMMIT: `test(tests): TDD for test_live_gui_workspace_exists xdist race (failing test)`
  - GIT NOTE: "Phase 2.1. TDD test for xdist race. Passes in isolation, fails in batch. Root cause: workspace cleanup timing under xdist."

- [ ] **Task 2.2: Fix the root cause of the race**
  - WHERE: The fixture or cleanup code identified in Task 1.3
  - WHAT: Apply the fix. The likely fix is to make the workspace creation more robust against xdist cleanup (e.g., create the workspace lazily, hold a reference, or coordinate cleanup across workers).
  - HOW: Use `manual-slop_edit_file`. The exact change depends on the root cause found in Task 1.3.
  - SAFETY: TDD: the test from 2.1 must PASS after the fix. The audit's 0 violations in sub-track 2 scope MUST be preserved. No new `@pytest.mark.skip` markers.
  - VERIFY: `uv run pytest tests/test_live_gui_workspace_fixture.py -v` should PASS.
  - COMMIT: `fix(tests): test_live_gui_workspace_exists xdist race — root cause: [description]`
  - GIT NOTE: "Phase 2.2. xdist race fix. [verified pre-existing on parent / regression fix]. Root cause: [description]."

- [ ] **Task 2.3: Verify the fix in batched run**
  - WHERE: `tier-1-unit-gui` tier
  - WHAT: Run the full tier-1-unit-gui tier to confirm the fix works in batched (xdist) execution.
  - HOW: `uv run python scripts/run_tests_batched.py` (the full runner) or just the tier-1-unit-gui files.
  - VERIFY: The test `test_live_gui_workspace_exists` passes in the batched run.
  - COMMIT: (no commit — just verification)

---

## Phase 3: Fix Issue 1 (GUI subprocess crash)

Focus: Fix the `test_execution_sim_live` failure. This is the larger of the 2 issues.

- [ ] **Task 3.1: Add diagnostic logging to find the crash point**
  - WHERE: `src/gui_2.py` (or wherever the script generation flow is)
  - WHAT: Add temporary `sys.stderr.write(f"[GUI_SUBPROC_DIAG] ...")` lines at the suspected crash points (script generation start, AI request, response handling, modal display, etc.).
  - HOW: Use `manual-slop_edit_file`.
  - SAFETY: This is diagnostic noise. **MUST be removed in Task 3.5.** Per AGENTS.md "No Diagnostic Noise in Production" rule.
  - VERIFY: Run the test; capture the output; identify the last `[GUI_SUBPROC_DIAG]` line printed before the crash.
  - NO COMMIT (or commit as WIP and amend later).

- [ ] **Task 3.2: Add a TDD test that captures the crash**
  - WHERE: `tests/test_extended_sims.py` (extend the existing test file)
  - WHAT: Add a new test that captures the GUI subprocess crash mode. E.g., a simpler test that just calls `sim.run()` and checks the GUI subprocess is alive after.
  - HOW: Use `manual-slop_edit_file`.
  - SAFETY: TDD-first. The test should FAIL on the current commit (without the fix) and PASS after the fix.
  - VERIFY: The new test should FAIL on current.
  - COMMIT: `test(tests): TDD for test_execution_sim_live GUI subprocess crash (failing test)`
  - GIT NOTE: "Phase 3.2. TDD test for GUI subprocess crash. 90s timeout. Root cause: [description]."

- [ ] **Task 3.3: Fix the root cause of the crash**
  - WHERE: The crash point identified in Task 3.1
  - WHAT: Apply the fix. The likely fix is to make the script generation flow more robust (e.g., handle the case where the GUI dies, retry the AI call, or fix the deadlock/memory issue/signal handling).
  - HOW: Use `manual-slop_edit_file`. The exact change depends on the root cause.
  - SAFETY: TDD: the test from 3.2 must PASS after the fix. The audit's 0 violations in sub-track 2 scope MUST be preserved.
  - VERIFY: `uv run pytest tests/test_extended_sims.py::test_execution_sim_live -v --timeout=120` should PASS.
  - COMMIT: `fix(src): test_execution_sim_live GUI subprocess crash — root cause: [description]`
  - GIT NOTE: "Phase 3.3. GUI subprocess (port 8999) crash fix. Same failure with both gemini_cli and gemini. NOT provider-specific. Root cause: [description]."

- [ ] **Task 3.4: Verify the fix in batched run**
  - WHERE: `tier-3-live_gui` tier
  - WHAT: Run the full tier-3-live_gui tier to confirm the fix works in batched execution.
  - HOW: `uv run python scripts/run_tests_batched.py` (the full runner).
  - VERIFY: The test `test_execution_sim_live` passes in the batched run.
  - COMMIT: (no commit — just verification)

- [ ] **Task 3.5: Remove diagnostic logging**
  - WHERE: `src/gui_2.py` (or wherever the diagnostic was added)
  - WHAT: Remove all `[GUI_SUBPROC_DIAG]` lines added in Task 3.1.
  - HOW: Use `manual-slop_edit_file`. Verify the production code is clean.
  - SAFETY: Per AGENTS.md "No Diagnostic Noise in Production" rule. **No `sys.stderr.write(f"[XYZ_DIAG] ...")` lines in production.**
  - VERIFY: `grep -r "DIAG" src/` should return nothing. (Or `rg "DIAG" src/` on Linux/macOS.)
  - COMMIT: `chore(src): remove diagnostic logging from test_execution_sim_live fix`
  - GIT NOTE: "Phase 3.5. Removed [GUI_SUBPROC_DIAG] lines per AGENTS.md No Diagnostic Noise rule."

---

## Phase 4: Final verification

Focus: Verify all 11 test tiers pass clean. Document the results.

- [ ] **Task 4.1: Run the full 11-tier test suite**
  - WHERE: Project root
  - WHAT: `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.
  - RECORD: Save the test run output to `tests/artifacts/PHASE14_TEST_RUN_RESULTS.log`.
  - COMMIT: (no commit — just verification)

- [ ] **Task 4.2: Update the per-site report and completion report**
  - WHERE: `docs/reports/RESULT_MIGRATION_SMALL_FILES_20260617.md` (per-site report) and `docs/reports/TRACK_COMPLETION_result_migration_small_files_20260617.md` (completion report)
  - WHAT: Add a "Phase 14 (Live GUI Test Fixes) Addendum" section that:
    - Documents the 2 fixes (Issue 1 and Issue 2)
    - References this track (`live_gui_test_fixes_20260618`)
    - States the final test pass count: 11/11 tiers PASS clean
  - COMMIT: `docs(reports): Phase 14 addendum — 2 documented test issues fixed; 11/11 tiers PASS clean`
  - GIT NOTE: "Phase 14 addendum. The 2 documented test issues from sub-track 2 Phase 13 are fixed. All 11 tiers PASS clean."

- [ ] **Task 4.3: Update tracks.md to add the new track entry**
  - WHERE: `conductor/tracks.md`
  - WHAT: Add a new row for this track in the "Active Tracks" section. Mark it as `shipped` (after Phase 4.1 verification) and document the 2 fixes.
  - COMMIT: `docs(tracks): add live_gui_test_fixes_20260618 to tracks.md (shipped)`

- [ ] **Task 4.4: Update umbrella spec.md to note the fixes**
  - WHERE: `conductor/tracks/result_migration_20260616/spec.md`
  - WHAT: Add a "Phase 14 Update" callout that documents the 2 fixes and the final test pass count.
  - COMMIT: `docs(track): update umbrella with sub-track 2 Phase 14 addendum (11/11 tiers PASS clean)`

- [ ] **Task 4.5: Conductor - User Manual Verification**
  - Per workflow.md: User manually verifies the 2 fixes, the test pass count, and the report's claims.

---

## Risks at the Plan Level

| Risk | Mitigation |
|---|---|
| Tier-2 adds a `@pytest.mark.skip` for Issue 1 or Issue 2 | The plan EXPLICITLY says "no new skip markers". User directive: investigate and fix. If the fix is too large, escalate to a follow-up track (do not skip). |
| Tier-2 miscounts test tiers (claiming 10 instead of 11) | The plan EXPLICITLY says "all 11 test tiers PASS". This is the sixth time. |
| Tier-2 leaves diagnostic logging in production | The plan EXPLICITLY says "MUST be removed in Task 3.5". Per AGENTS.md "No Diagnostic Noise in Production" rule. The verification step (grep for DIAG) catches this. |
| The GUI subprocess crash root cause is in a 3rd-party library (imgui, etc.) | The fix is a workaround in our code (e.g., retry, error handling). Document the workaround. |
| 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`, run the full 11-tier test suite after the fix. |
| The fixes regress the 4 Gemini 503 skip markers | The 4 skip markers are network-dependent (Gemini 503). The fixes are in test infrastructure, not in `summarize.summarise_file`. The skip markers should still be needed. Verify by re-running the 4 tests. |

---

## Verification Snapshot (capture in the report)

After Phase 4, capture in `docs/reports/RESULT_MIGRATION_SMALL_FILES_20260617.md` and `docs/reports/TRACK_COMPLETION_result_migration_small_files_20260617.md`:

- Phase 14 (Live GUI Test Fixes) addendum with the 2 fixes
- Final test pass count: **11/11 tiers PASS clean** (not 10, not 9, not "10+1-fail")
- The 4 Gemini 503 skip markers remain (out of scope; deferred to a follow-up track)
- Sub-track 2 (`result_migration_small_files_20260617`) is now FULLY ready for merge with no documented issues from this track
- Sub-track 3 (`result_migration_app_controller`) is unblocked
