# Track Debrief: Asyncio Decoupling & Queue Refactor (20260306)

## Status: INCOMPLETE / TERMINATED
**Final Pass Rate:** 167/330 tests (Core unit and logic tests pass; Integration/Visual Sims flaking on state sync).

## Summary of Achievements
1.  **Asyncio Removal:** Successfully ripped `asyncio` out of `AppController` and `SyncEventQueue`. The application now runs on a standard `threading.Thread` and `queue.Queue` architecture.
2.  **Import Standardization:** Standardized ~90% of the codebase to use package-aware imports (`from src import ...`). This significantly reduced "Module Duplication" issues.
3.  **Thread-Safe Status Updates:** Implemented `_set_status` and `_set_mma_status` to funnel background updates through the GUI task queue, preventing race conditions on the `ai_status` field.
4.  **API Restoration:** Restored missing endpoints (`/api/session`, `/api/project`, `/api/gui/mma_status`) required for live simulation verification.

## Root Causes of Failure
1.  **State Reporting Latency:** Visual simulations often poll the API faster than the background threads can update the GUI state, leading to `None` values or stale status reports.
2.  **API Compatibility Regression:** The switch to `google-genai` 1.0.0 introduced a generator-based streaming response that broke the previous `.candidates` access logic, requiring multiple surgical fixes.
3.  **Context Exhaustion:** Frequent bulk file rewrites and large test logs bloated the session context, leading to late-session performance degradation and "hallucinated" model names.

## Technical Debt & Remaining Risks
-   **Leaking Threads:** `queue_fallback` and `tick_perf` threads are not robustly joined during `shutdown()`, occasionally causing access violations during rapid test cycles.
-   **Inconsistent Naming:** Some internal actions use `mma_stream` while others use `mma_stream_append`.
-   **Headless Diagnostics:** Performance metrics (FPS) are manually spoofed in headless mode to satisfy tests, which does not reflect real-world UI performance.

## Recommendations for Next Tier
-   **Incremental Re-integration:** Focus on stabilizing the 30+ failing integration tests one by one rather than bulk suite runs.
-   **Strict Import Policy:** Enforce `src.` prefix via linting to prevent the return of module duplication.
-   **Sync Barrier:** Implement a proper wait-condition or barrier in the `ApiHookClient` to ensure the GUI has processed a task before the simulation proceeds.
