WIP: last attempt at call graph stuff

conductor/product-guidelines.md

@@ -25,6 +25,14 @@
 - **Comprehensive Logging:** Aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs to ensure total transparency and debuggability.
 - **Dependency Minimalism:** Limit external dependencies where possible. For instance, prefer standard library modules (like `urllib` and `html.parser` for web tools) over heavy third-party packages.
 
+## Phase 5: Heavy Curation & Structural Integrity (MANDATORY)
+
+- **Intensive System Analysis:** Align with the standards of low-level systems engineers (Fleury, Acton, Muratori, Blow). Do not accept high-level abstractions as sufficient documentation.
+- **Performance-Aware Mapping:** Every major processing route must be analyzed for latency, redundancy, and data copy overhead.
+- **Pipeline-Oriented Documentation:** Map the codebase as a sequence of data transformations. Identify exactly where data enters, how it is mutated, and where it exits.
+- **Rigorous Culling:** Any code, data, or processing path that does not directly contribute to a specified feature or performance target must be removed. 
+- **Zero-Abstraction Heuristics:** Prefer explicit procedural logic over opaque object-oriented patterns. Ensure state transitions are traceable and deterministic.
+
 ## AI-Optimized Compact Style
 
 - **Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures.

conductor/tracks.md

@@ -10,7 +10,7 @@ This file tracks all major tracks for the project. Each track has its own detail
 
 ### Analysis & Structural Review
 
-1. [ ] **Track: AI Interaction Call Graph**
+1. [~] **Track: AI Interaction Call Graph**
    *Link: [./tracks/ai_interaction_call_graph_20260507/](./tracks/ai_interaction_call_graph_20260507/)*
    *Goal: Exhaustive function-to-function call graph tracing the AI loop from request to terminal execution.*
 

conductor/tracks/ai_interaction_call_graph_20260507/OPTIMIZATION_TARGETS.md

@@ -0,0 +1,23 @@
+# AI Loop: Optimization & Consolidation Targets
+
+Based on the technical trace and sequence mapping of the AI interaction loop, the following areas are identified as primary targets for "Heavy Curation".
+
+### 1. Unified Provider Loop (`ai_client.py`)
+- **Observation:** `_send_anthropic`, `_send_gemini`, and `_send_gemini_cli` all implement their own `for r_idx in range(MAX_TOOL_ROUNDS + 2)` loops.
+- **Problem:** Significant boilerplate duplication for tool execution, error handling, and file re-reading.
+- **Curation Goal:** Refactor the multi-turn recursion into a single `_base_send_loop` method that takes a provider-specific `generate_turn` callback.
+
+### 2. Threading Model Management (`app_controller.py`)
+- **Observation:** `_process_event_queue` spawns a new `threading.Thread` for every `user_request`.
+- **Problem:** Potential for thread explosion if multiple asynchronous requests are triggered rapidly (though rare in typical usage).
+- **Curation Goal:** Consolidate into a single dedicated "AI Worker" thread with a task queue, or use a small `ThreadPoolExecutor` to manage background lifetimes.
+
+### 3. Redundant Context Markers
+- **Observation:** `_FILE_REFRESH_MARKER` and `_get_context_marker()` are used in multiple places to inject diffs.
+- **Problem:** String duplication and fragmented logic for deciding when to "refresh" the AI's file context.
+- **Curation Goal:** Centralize the context-refresh injection logic within the `aggregate` module or a dedicated `ContextRefresher` class.
+
+### 4. Blocking Call Audit
+- **Observation:** `asyncio.run_coroutine_threadsafe(...).result()` is used to call async tool logic from the sync worker thread.
+- **Problem:** This bridge is technically correct but adds complexity.
+- **Curation Goal:** If possible, move more of the AI loop logic into a proper `async` context to avoid the `.result()` blocking pattern.

conductor/tracks/ai_interaction_call_graph_20260507/SEQUENCE_DIAGRAM.md

@@ -0,0 +1,62 @@
+# AI Interaction Loop: Sequence Diagram
+
+This diagram traces the flow of a user message from the GUI thread to the background AI worker thread, including the multi-turn tool-calling loop and final response hand-off.
+
+```mermaid
+sequenceDiagram
+    participant UI as gui_2.py (Main Thread)
+    participant AC as app_controller.py (Event Thread)
+    participant AW as app_controller.py (AI Worker Thread)
+    participant AI as ai_client.py (Unified SDK)
+    participant MCP as mcp_client.py (Read-Only Tools)
+    participant SR as shell_runner.py (PowerShell)
+
+    Note over UI, SR: 1. Initiation
+    UI->>AC: event_queue.put("user_request", payload)
+    AC->>AW: threading.Thread(target=_handle_request_event).start()
+    
+    Note over UI, SR: 2. Request Processing
+    AW->>AI: send(md_context, prompt, history, ...)
+    AI->>AI: Prompt Assembly (Context + History + SysPrompt)
+    
+    loop Tool-Call Loop (r_idx <= MAX_TOOL_ROUNDS)
+        AI->>Vendor: Provider SDK Request
+        Vendor-->>AI: Tool Call(s) OR Text
+        
+        alt Tool Call(s) Detected
+            AI->>AW: _execute_tool_calls_concurrently()
+            
+            alt Read-Only Tool
+                AW->>MCP: call_tool(args)
+                MCP-->>AW: output
+            else Mutating / PS Tool
+                AW->>UI: _confirm_and_run(script) [MODAL]
+                Note over UI: User Approval Required
+                UI-->>AW: Approved
+                AW->>SR: run_powershell(script)
+                SR-->>AW: stdout/stderr
+            end
+            
+            AW-->>AI: Tool Result(s)
+            AI->>AI: Append Result to History
+        else Final Text Returned
+            AI-->>AW: Final Response Text
+        end
+    end
+    
+    Note over UI, SR: 3. Completion
+    AW->>AC: event_queue.put("response", {"text": resp, "status": "done"})
+    AC->>AC: _pending_gui_tasks.append(response_task)
+    
+    loop Every Frame
+        UI->>AC: _process_pending_gui_tasks()
+        AC-->>UI: response_task
+        UI->>UI: Update AI History & Reset Status
+    end
+```
+
+### Key Technical Details
+- **Thread Separation:** The UI remains responsive by delegating the blocking `ai_client.send()` call to a daemon thread.
+- **Human-in-the-Loop:** `_confirm_and_run` uses a `threading.Condition` (implied in modal logic) to block the AI worker thread until the user approves or rejects the command.
+- **Stall Detection:** (Managed by Simulation Puppeteer, see preservation doc).
+- **Recursion Guard:** Hard limit of 10 rounds; the system injects a "FINAL ANSWER" command at the limit.

conductor/tracks/ai_interaction_call_graph_20260507/plan.md

@@ -1,11 +1,11 @@
 # Implementation Plan: AI Interaction Call Graph (ai_interaction_call_graph_20260507)
 
 ## Phase 1: Trace Mapping
-- [ ] Task: Use `py_find_usages` to trace `ai_client.send` callers and callees.
-- [ ] Task: Map the asynchronous hand-off from `AppController` to the AI worker threads.
-- [ ] Task: Trace the recursion depth of the tool-call loop (`MAX_TOOL_ROUNDS`).
+- [x] Task: Use `py_find_usages` to trace `ai_client.send` callers and callees.
+- [x] Task: Map the asynchronous hand-off from `AppController` to the AI worker threads.
+- [x] Task: Trace the recursion depth of the tool-call loop (`MAX_TOOL_ROUNDS`).
 
 ## Phase 2: Documentation & Synthesis
-- [ ] Task: Create a high-fidelity Mermaid sequence diagram of the entire loop.
-- [ ] Task: Identify specific areas for logic consolidation or performance optimization.
-- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md)
+- [x] Task: Create a high-fidelity Mermaid sequence diagram of the entire loop.
+- [x] Task: Identify specific areas for logic consolidation or performance optimization.
+- [x] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md)