# Implementation Plan: Hook API UI State Verification (hook_api_ui_state_verification_20260302)

> **TEST DEBT FIX:** This track replaces fragile `time.sleep()` and string-matching assertions in simulations (like `test_visual_sim_mma_v2.py`) with deterministic UI state queries. This is critical for stabilizing the test suite after the GUI decoupling.

## Phase 1: API Endpoint Implementation [checkpoint: 9967fbd]
- [x] Task: Initialize MMA Environment `activate_skill mma-orchestrator` [6b4c626]
- [x] Task: Implement `/api/gui/state` GET Endpoint [a783ee5]
    - [x] WHERE: `gui_2.py` (or `app_controller.py` if decoupled), inside `create_api()`.
    - [x] WHAT: Add a FastAPI route that serializes allowed UI state variables into JSON.
    - [x] HOW: Define a set of safe keys (e.g., `_gettable_fields`) and extract them from the App instance.
    - [x] SAFETY: Use thread-safe reads or deepcopies if accessing complex dictionaries.
- [x] Task: Update `ApiHookClient` [a783ee5]
    - [x] WHERE: `api_hook_client.py`
    - [x] WHAT: Add a `get_gui_state(self)` method that hits the new endpoint.
    - [x] HOW: Standard `requests.get`.
    - [x] SAFETY: Include error handling/timeouts.
- [x] Task: Conductor - User Manual Verification 'Phase 1: API Endpoint' (Protocol in workflow.md) [9967fbd]

## Phase 2: State Wiring & Integration Tests [checkpoint: 9967fbd]
- [x] Task: Wire Critical UI States [a783ee5]
    - [x] WHERE: `gui_2.py`
    - [x] WHAT: Ensure fields like `ui_focus_agent`, `active_discussion`, `_track_discussion_active` are included in the exposed state.
    - [x] HOW: Update the mapping definition.
    - [x] SAFETY: None.
- [x] Task: Write `live_gui` Integration Tests [a783ee5]
    - [x] WHERE: `tests/test_live_gui_integration.py`
    - [x] WHAT: Add a test that changes the provider/model or focus agent via actions, then asserts `client.get_gui_state()` reflects the change.
    - [x] HOW: Use `pytest` and `live_gui` fixture.
    - [x] SAFETY: Ensure robust wait conditions for GUI updates.
- [x] Task: Conductor - User Manual Verification 'Phase 2: State Wiring & Tests' (Protocol in workflow.md) [9967fbd]

## Phase 3: Final Validation [checkpoint: f42bee3]
- [x] Task: Full Suite Validation & Warning Cleanup [f42bee3]
    - [x] WHERE: Project root
    - [x] WHAT: `uv run pytest`
    - [x] HOW: Ensure 100% pass rate.
    - [x] SAFETY: Ensure the hook server gracefully stops.
- [x] Task: Conductor - User Manual Verification 'Phase 3: Final Validation' (Protocol in workflow.md) [f42bee3]