diff --git a/conductor/tracks/asyncio_decoupling_refactor_20260306/debrief.md b/conductor/tracks/asyncio_decoupling_refactor_20260306/debrief.md new file mode 100644 index 0000000..e6cb087 --- /dev/null +++ b/conductor/tracks/asyncio_decoupling_refactor_20260306/debrief.md @@ -0,0 +1,25 @@ +# 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.