manual_slop/conductor/archive/mma_pipeline_fix_20260301/spec.md

Track Specification: MMA Pipeline Fix & Worker Stream Verification

Overview

The MMA pipeline has a verified code path from run_worker_lifecycle → _queue_put("response", ...) → _process_event_queue → _pending_gui_tasks("handle_ai_response") → mma_streams[stream_id] = text. However, the robust_live_simulation track's session compression (2026-02-28) documented that Tier 3 worker output never appears in mma_streams during actual GUI operation. The simulation only ever sees 'Tier 1' in mma_streams keys.

This track diagnoses and fixes the pipeline break, then verifies end-to-end that worker output flows from ai_client.send() through to the GUI's mma_streams dict.

Root Cause Candidates (from code analysis)

1. run_in_executor positional arg ordering: run_worker_lifecycle has 7 parameters. The call at multi_agent_conductor.py:118-127 passes them positionally. If the order is wrong, loop could be None and _queue_put would silently fail (the if loop: branch is skipped, falling to event_queue._queue.put_nowait() which may not work from a thread-pool thread because asyncio.Queue.put_nowait is not thread-safe when called from outside the event loop).

2. asyncio.Queue thread safety: _queue_put uses asyncio.run_coroutine_threadsafe() which IS thread-safe. But the else branch (event_queue._queue.put_nowait(...)) is NOT — asyncio.Queue is NOT thread-safe for cross-thread access. If loop is None, this branch silently corrupts or drops the event.

3. ai_client.reset_session() side effects: Called at the start of run_worker_lifecycle, this resets the global _gemini_cli_adapter.session_id = None. If the adapter is shared state and the GUI's Tier 2 call is still in-flight, this could corrupt the provider state.

4. Token stats stub: engine.tier_usage update uses stats = {} (empty dict, commented "ai_client.get_token_stats() is not available"), so prompt_tokens and candidates_tokens are always 0. Not a stream bug but a data bug.

Goals

1. Fix Tier 3 worker responses reaching mma_streams in the GUI.
2. Fix token usage tracking for Tier 3 workers.
3. Verify via ApiHookClient.get_mma_status() that mma_streams contains Tier 3 output after a mock MMA run.

Architecture Reference

• Threading model: docs/guide_architecture.md — see "Cross-Thread Data Structures" and "Pattern A: AsyncEventQueue"
• Worker lifecycle: docs/guide_mma.md — see "Tier 3: Worker Lifecycle"
• Frame-sync: docs/guide_architecture.md — see "Frame-Sync Mechanism" action catalog (handle_ai_response with stream_id)