docs: append test performance track to backlog based on timeout evaluation

- Implement Live Worker Streaming: wire ai_client.comms_log_callback to Tier 3 streams
- Add Parallel DAG Execution using asyncio.gather for non-dependent tickets
- Implement Automatic Retry with Model Escalation (Flash-Lite -> Flash -> Pro)
- Add Tier Model Configuration UI to MMA Dashboard with project TOML persistence
- Fix FPS reporting in PerformanceMonitor to prevent transient 0.0 values
- Update Ticket model with retry_count and dictionary-like access
- Stabilize Gemini CLI integration tests and handle script approval events in simulations
- Finalize and verify all 6 phases of the implementation plan

.claude/commands/conductor-implement.md

@@ -0,0 +1,108 @@
+---
+description: Execute a conductor track — follow TDD workflow, delegate to Tier 3/4 workers
+---
+
+# /conductor-implement
+
+Execute a track's implementation plan. This is a Tier 2 (Tech Lead) operation.
+You maintain PERSISTENT context throughout the track — do NOT lose state.
+
+## Startup
+
+1. Read `.claude/commands/mma-tier2-tech-lead.md` — load your role definition and hard rules FIRST
+2. Read `conductor/workflow.md` for the full task lifecycle protocol
+3. Read `conductor/tech-stack.md` for technology constraints
+4. Read the target track's `spec.md` and `plan.md`
+5. Identify the current task: first `[ ]` or `[~]` in `plan.md`
+
+If no track name is provided, run `/conductor-status` first and ask which track to implement.
+
+## Task Lifecycle (per task)
+
+Follow this EXACTLY per `conductor/workflow.md`:
+
+### 1. Mark In Progress
+Edit `plan.md`: change `[ ]` → `[~]` for the current task.
+
+### 2. Research Phase (High-Signal)
+Before touching code, use context-efficient tools IN THIS ORDER:
+1. `py_get_code_outline` — FIRST call on any Python file. Maps functions/classes with line ranges.
+2. `py_get_skeleton` — signatures + docstrings only, no bodies
+3. `get_git_diff` — understand recent changes before modifying touched files
+4. `Grep`/`Glob` — cross-file symbol search
+5. `Read` (targeted, offset+limit only) — ONLY after outline identifies specific ranges
+
+**NEVER** call `Read` on a full Python file >50 lines without a prior `py_get_code_outline` call.
+
+### 3. Write Failing Tests (Red Phase — TDD)
+**DELEGATE to Tier 3 Worker** — do NOT write tests yourself:
+```powershell
+uv run python scripts\claude_mma_exec.py --role tier3-worker "Write failing tests for: {TASK_DESCRIPTION}. Focus files: {FILE_LIST}. Spec: {RELEVANT_SPEC_EXCERPT}"
+```
+Run the tests. Confirm they FAIL. This is the Red phase.
+
+### 4. Implement to Pass (Green Phase)
+**DELEGATE to Tier 3 Worker**:
+```powershell
+uv run python scripts\claude_mma_exec.py --role tier3-worker "Implement minimum code to pass these tests: {TEST_FILE}. Focus files: {FILE_LIST}"
+```
+Run tests. Confirm they PASS. This is the Green phase.
+
+### 5. Refactor (Optional)
+With passing tests as safety net, refactor if needed. Rerun tests.
+
+### 6. Verify Coverage
+Use `run_powershell` MCP tool (not Bash — Bash is a mingw sandbox on Windows):
+```powershell
+uv run pytest --cov=. --cov-report=term-missing {TEST_FILE}
+```
+Target: >80% for new code.
+
+### 7. Commit
+Stage changes. Message format:
+```
+feat({scope}): {description}
+```
+
+### 8. Attach Git Notes
+```powershell
+$sha = git log -1 --format="%H"
+git notes add -m "Task: {TASK_NAME}`nSummary: {CHANGES}`nFiles: {FILE_LIST}" $sha
+```
+
+### 9. Update plan.md
+Change `[~]` → `[x]` and append first 7 chars of commit SHA:
+```
+[x] Task description. abc1234
+```
+Commit: `conductor(plan): Mark task '{TASK_NAME}' as complete`
+
+### 10. Next Task or Phase Completion
+- If more tasks in current phase: loop to step 1 with next task
+- If phase complete: run `/conductor-verify`
+
+## Error Handling
+
+### Tier 3 delegation fails (credit limit, API error, timeout)
+**STOP** — do NOT implement inline as a fallback. Ask the user:
+> "Tier 3 Worker is unavailable ({reason}). Should I continue with a different provider, or wait?"
+Never silently absorb Tier 3 work into Tier 2 context.
+
+### Tests fail with large output — delegate to Tier 4 QA:
+```powershell
+uv run python scripts\claude_mma_exec.py --role tier4-qa "Analyze this test failure: {ERROR_SUMMARY}. Test file: {TEST_FILE}"
+```
+Maximum 2 fix attempts. If still failing: STOP and ask the user.
+
+## Deviations from Tech Stack
+If implementation requires something not in `tech-stack.md`:
+1. **STOP** implementation
+2. Update `tech-stack.md` with justification
+3. Add dated note
+4. Resume
+
+## Important
+- You are Tier 2 — delegate heavy implementation to Tier 3
+- Maintain persistent context across the entire track
+- Use Research-First Protocol before reading large files
+- The plan.md is the SOURCE OF TRUTH for task state

.claude/commands/conductor-new-track.md

@@ -0,0 +1,174 @@
+---
+description: Initialize a new conductor track with spec, plan, and metadata
+---
+
+# /conductor-new-track
+
+Create a new track in the conductor system. This is a Tier 1 (Orchestrator) operation.
+The quality of the spec and plan directly determines whether Tier 3 workers can execute
+without confusion. Vague specs produce vague implementations.
+
+## Prerequisites
+- Read `conductor/product.md` and `conductor/product-guidelines.md` for product alignment
+- Read `conductor/tech-stack.md` for technology constraints
+- Consult architecture docs in `docs/` when the track touches core systems:
+  - `docs/guide_architecture.md`: Threading, events, AI client, HITL mechanism
+  - `docs/guide_tools.md`: MCP tools, Hook API, ApiHookClient
+  - `docs/guide_mma.md`: Tickets, tracks, DAG engine, worker lifecycle
+  - `docs/guide_simulations.md`: Test framework, mock provider, verification patterns
+
+## Steps
+
+### 1. Gather Information
+Ask the user for:
+- **Track name**: descriptive, snake_case (e.g., `add_auth_system`)
+- **Track type**: `feat`, `fix`, `refactor`, `chore`
+- **Description**: one-line summary
+- **Requirements**: functional requirements for the spec
+
+### 2. MANDATORY: Deep Codebase Audit
+
+**This step is what separates useful specs from useless ones.**
+
+Before writing a single line of spec, you MUST audit the actual codebase to understand
+what already exists. Use the Research-First Protocol:
+
+1. **Map the target area**: Use `py_get_code_outline` on every file the track will touch.
+   Identify existing functions, classes, and their line ranges.
+2. **Read key implementations**: Use `py_get_definition` on functions that are relevant
+   to the track's goals. Understand their signatures, data structures, and control flow.
+3. **Search for existing work**: Use `Grep` to find symbols, patterns, or partial
+   implementations that may already address some requirements.
+4. **Check recent changes**: Use `get_git_diff` on target files to understand what's
+   been modified recently and by which tracks.
+
+**Output of this step**: A "Current State Audit" section listing:
+- What already exists (with file:line references)
+- What's missing (the actual gaps this track fills)
+- What's partially implemented and needs enhancement
+
+### 3. Create Track Directory
+```
+conductor/tracks/{track_name}_{YYYYMMDD}/
+```
+Use today's date in YYYYMMDD format.
+
+### 4. Create metadata.json
+```json
+{
+  "track_id": "{track_name}_{YYYYMMDD}",
+  "type": "{feat|fix|refactor|chore}",
+  "status": "new",
+  "created_at": "{ISO8601}",
+  "updated_at": "{ISO8601}",
+  "description": "{description}"
+}
+```
+
+### 5. Create index.md
+```markdown
+# Track {track_name}_{YYYYMMDD} Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)
+```
+
+### 6. Create spec.md — The Surgical Specification
+
+The spec MUST include these sections:
+
+```markdown
+# Track Specification: {Title}
+
+## Overview
+{What this track delivers and WHY — 2-3 sentences max}
+
+## Current State Audit (as of {latest_commit_sha})
+### Already Implemented (DO NOT re-implement)
+- **{Feature}** (`{function_name}`, {file}:{lines}): {what it does}
+- ...
+
+### Gaps to Fill (This Track's Scope)
+1. **{Gap}**: {What's missing, with reference to where it should go}
+2. ...
+
+## Goals
+{Numbered list — crisp, no fluff}
+
+## Functional Requirements
+### {Requirement Group}
+- {Specific requirement referencing actual data structures, function names, dict keys}
+- ...
+
+## Non-Functional Requirements
+- Thread safety constraints (reference guide_architecture.md if applicable)
+- Performance targets
+- No new dependencies unless justified
+
+## Architecture Reference
+- {Link to relevant docs/guide_*.md section}
+
+## Out of Scope
+- {Explicit exclusions}
+```
+
+**Critical rules for specs:**
+- NEVER describe a feature to implement without first checking if it exists
+- ALWAYS include the "Current State Audit" section with line references
+- ALWAYS link to relevant architecture docs
+- Reference actual variable names, dict keys, and class names from the codebase
+
+### 7. Create plan.md — The Surgical Plan
+
+Each task must be specific enough that a Tier 3 worker on a lightweight model
+can execute it without needing to understand the overall architecture.
+
+```markdown
+# Implementation Plan: {Title}
+
+Architecture reference: [docs/guide_architecture.md](../../docs/guide_architecture.md)
+
+## Phase 1: {Phase Name}
+Focus: {One-sentence scope}
+
+- [ ] Task 1.1: {SURGICAL description — see rules below}
+- [ ] Task 1.2: ...
+- [ ] Task 1.N: Write tests for {what Phase 1 changed}
+- [ ] Task 1.X: Conductor - User Manual Verification (Protocol in workflow.md)
+```
+
+**Rules for writing tasks:**
+
+1. **Reference exact locations**: "In `_render_mma_dashboard` (gui_2.py:2700-2701)"
+   not "in the dashboard."
+2. **Specify the API**: "Use `imgui.progress_bar(value, ImVec2(-1, 0), label)`"
+   not "add a progress bar."
+3. **Name the data**: "Read from `self.mma_streams` dict, keys prefixed with `'Tier 3'`"
+   not "display the streams."
+4. **Describe the change shape**: "Replace the single text box with four collapsible sections"
+   not "improve the display."
+5. **State thread safety**: "Push via `_pending_gui_tasks` with lock" when the task
+   involves cross-thread data.
+6. **For bug fixes**: List specific root cause candidates with code-level reasoning,
+   not "investigate and fix."
+7. **Each phase ends with**: A test task and a verification task.
+
+### 8. Commit
+```
+conductor(track): Initialize track '{track_name}'
+```
+
+## Anti-Patterns (DO NOT do these)
+
+- **Spec that describes features without checking if they exist** → produces duplicate work
+- **Task that says "implement X" without saying WHERE or HOW** → worker guesses wrong
+- **Plan with no line references** → worker wastes tokens searching
+- **Spec with no architecture doc links** → worker misunderstands threading/data model
+- **Tasks scoped too broadly** → worker tries to do too much, fails
+- **No "Current State Audit"** → entire track may be re-implementing existing code
+
+## Important
+- Do NOT start implementing — track initialization only
+- Implementation is done via `/conductor-implement`
+- Each task should be scoped for a single Tier 3 Worker delegation

.claude/commands/conductor-setup.md

@@ -0,0 +1,46 @@
+---
+description: Initialize conductor context — read product docs, verify structure, report readiness
+---
+
+# /conductor-setup
+
+Bootstrap a Claude Code session with full conductor context. Run this at session start.
+
+## Steps
+
+1. **Read Core Documents:**
+   - `conductor/index.md` — navigation hub
+   - `conductor/product.md` — product vision
+   - `conductor/product-guidelines.md` — UX/code standards
+   - `conductor/tech-stack.md` — technology constraints
+   - `conductor/workflow.md` — task lifecycle (skim; reference during implementation)
+
+2. **Check Active Tracks:**
+   - List all directories in `conductor/tracks/`
+   - Read each `metadata.json` for status
+   - Read each `plan.md` for current task state
+   - Identify the track with `[~]` in-progress tasks
+
+3. **Check Session Context:**
+   - Read `TASKS.md` if it exists — check for IN_PROGRESS or BLOCKED tasks
+   - Read last 3 entries in `JOURNAL.md` for recent activity
+   - Run `git log --oneline -10` for recent commits
+
+4. **Report Readiness:**
+   Present a session startup summary:
+   ```
+   ## Session Ready
+
+   **Active Track:** {track name} — Phase {N}, Task: {current task description}
+   **Recent Activity:** {last journal entry title}
+   **Last Commit:** {git log -1 oneline}
+
+   Ready to:
+   - `/conductor-implement` — resume active track
+   - `/conductor-status` — full status overview
+   - `/conductor-new-track` — start new work
+   ```
+
+## Important
+- This is READ-ONLY — do not modify files
+- This replaces Gemini's `activate_skill mma-orchestrator` + `/conductor:setup`

.claude/commands/conductor-status.md

@@ -0,0 +1,32 @@
+---
+description: Show current conductor track status — active tracks, phases, pending tasks
+---
+
+# /conductor-status
+
+Read the conductor track registry and all active tracks, then report current project state.
+
+## Steps
+
+1. Read `conductor/tracks.md` for the track registry
+2. For each track directory in `conductor/tracks/`:
+   - Read `metadata.json` for status
+   - Read `plan.md` and count: total tasks, completed `[x]`, in-progress `[~]`, pending `[ ]`
+   - Identify the current phase (first phase with `[~]` or `[ ]` tasks)
+3. Read `JOURNAL.md` last 3 entries for recent activity context
+
+## Output Format
+
+Present a summary table:
+
+```
+| Track | Status | Phase | Progress | Last SHA |
+|-------|--------|-------|----------|----------|
+```
+
+Then for each in-progress track, list the specific next pending task.
+
+## Important
+- This is READ-ONLY — do not modify any files
+- Report exactly what the plan.md files say
+- Flag any discrepancies (e.g., metadata says "new" but plan.md has [x] tasks)

.claude/commands/conductor-verify.md

@@ -0,0 +1,85 @@
+---
+description: Run phase completion verification — tests, coverage, checkpoint commit
+---
+
+# /conductor-verify
+
+Execute the Phase Completion Verification and Checkpointing Protocol.
+Run this when all tasks in a phase are marked `[x]`.
+
+## Protocol
+
+### 1. Announce
+Tell the user: "Phase complete. Running verification and checkpointing protocol."
+
+### 2. Verify Test Coverage for Phase
+
+Find the phase scope:
+- Read `plan.md` to find the previous phase's checkpoint SHA
+- If no previous checkpoint: scope is all changes since first commit
+- Run: `git diff --name-only {previous_checkpoint_sha} HEAD`
+- For each changed code file (exclude `.json`, `.md`, `.yaml`, `.toml`):
+  - Check if a corresponding test file exists
+  - If missing: create one (analyze existing test style first)
+
+### 3. Run Automated Tests
+
+**ANNOUNCE the exact command before running:**
+> "I will now run the automated test suite. Command: `uv run pytest --cov=. --cov-report=term-missing -x`"
+
+Execute the command.
+
+**If tests fail with large output:**
+- Pipe output to `logs/phase_verify.log`
+- Spawn Tier 4 QA for analysis:
+```powershell
+uv run python scripts\claude_mma_exec.py --role tier4-qa "Analyze test failures from logs/phase_verify.log"
+```
+- Maximum 2 fix attempts
+- If still failing: **STOP**, report to user, await guidance
+
+### 4. API Hook Verification (if applicable)
+
+If the track involves UI changes:
+- Check if GUI test hooks are available on port 8999
+- Run relevant simulation tests from `tests/visual_sim_*.py`
+- Log results
+
+### 5. Present Results and WAIT
+
+Display:
+- Test results (pass/fail count)
+- Coverage report
+- Any verification logs
+
+**PAUSE HERE.** Do NOT proceed without explicit user confirmation.
+
+### 6. Create Checkpoint Commit
+
+After user confirms:
+```powershell
+git add -A
+git commit -m "conductor(checkpoint): Checkpoint end of Phase {N} - {Phase Name}"
+```
+
+### 7. Attach Verification Report via Git Notes
+```powershell
+$sha = git log -1 --format="%H"
+git notes add -m "Phase Verification Report`nCommand: {test_command}`nResult: {pass/fail}`nCoverage: {percentage}`nConfirmed by: user" $sha
+```
+
+### 8. Update plan.md
+
+Update the phase heading to include checkpoint SHA:
+```markdown
+## Phase N: {Name} [checkpoint: {sha_7}]
+```
+Commit: `conductor(plan): Mark phase '{Phase Name}' as complete`
+
+### 9. Announce Completion
+Tell the user the phase is complete with a summary of the verification report.
+
+## Context Reset
+After phase checkpointing, treat the checkpoint as ground truth.
+Prior conversational context about implementation details can be dropped.
+The checkpoint commit and git notes preserve the audit trail.

.claude/commands/mma-tier1-orchestrator.md

@@ -0,0 +1,72 @@
+---
+description: Tier 1 Orchestrator — product alignment, high-level planning, track initialization
+---
+
+STRICT SYSTEM DIRECTIVE: You are a Tier 1 Orchestrator. Focused on product alignment, high-level planning, and track initialization. ONLY output the requested text. No pleasantries.
+
+# MMA Tier 1: Orchestrator
+
+## Primary Context Documents
+Read at session start: `conductor/product.md`, `conductor/product-guidelines.md`
+
+## Architecture Fallback
+When planning tracks that touch core systems, consult the deep-dive docs:
+- `docs/guide_architecture.md`: Thread domains, event system, AI client, HITL mechanism, frame-sync action catalog
+- `docs/guide_tools.md`: MCP Bridge security, 26-tool inventory, Hook API endpoints, ApiHookClient
+- `docs/guide_mma.md`: Ticket/Track data structures, DAG engine, ConductorEngine, worker lifecycle
+- `docs/guide_simulations.md`: live_gui fixture, Puppeteer pattern, mock provider, verification patterns
+
+## Responsibilities
+- Maintain alignment with the product guidelines and definition
+- Define track boundaries and initialize new tracks (`/conductor-new-track`)
+- Set up the project environment (`/conductor-setup`)
+- Delegate track execution to the Tier 2 Tech Lead
+
+## The Surgical Methodology
+
+When creating or refining tracks, follow this protocol to produce specs that
+lesser-reasoning models can execute without confusion:
+
+### 1. Audit Before Specifying
+NEVER write a spec without first reading the actual code. Use `py_get_code_outline`,
+`py_get_definition`, `Grep`, and `get_git_diff` to build a map of what exists.
+Document existing implementations with file:line references in a "Current State Audit"
+section. This prevents specs that ask to re-implement existing features.
+
+### 2. Identify Gaps, Not Features
+The spec should focus on what's MISSING, not what the track "will build."
+Frame requirements as: "The existing `_render_mma_dashboard` (gui_2.py:2633-2724)
+has a token usage table but no cost estimation column. Add cost tracking."
+Not: "Build a metrics dashboard with token and cost tracking."
+
+### 3. Write Worker-Ready Tasks
+Each task in the plan must be executable by a Tier 3 worker on a lightweight model
+(gemini-2.5-flash-lite) without needing to understand the overall architecture.
+This means every task must specify:
+- **WHERE**: Exact file and line range to modify
+- **WHAT**: The specific change (add function, modify dict, extend table)
+- **HOW**: Which API calls, data structures, or patterns to use
+- **SAFETY**: Thread-safety constraints if cross-thread data is involved
+
+### 4. Reference Architecture Docs
+Every spec should link to the relevant `docs/guide_*.md` section so implementing
+agents have a fallback when confused about threading, data flow, or module interactions.
+
+### 5. Map Dependencies
+Explicitly state which tracks must complete before this one, and which tracks
+this one blocks. Include execution order in the spec.
+
+### 6. Root Cause Analysis (for fix tracks)
+Don't write "investigate and fix X." Instead, read the code, trace the data flow,
+and list specific root cause candidates with code-level reasoning:
+"Candidate 1: `_queue_put` (line 138) uses `asyncio.run_coroutine_threadsafe` but
+the `else` branch uses `put_nowait` which is NOT thread-safe from a thread-pool thread."
+
+## Limitations
+- Read-only tools only: Read, Glob, Grep, WebFetch, WebSearch, Bash (read-only ops)
+- Do NOT execute tracks or implement features
+- Do NOT write code or edit files (except track spec/plan/metadata)
+- Do NOT perform low-level bug fixing
+- Keep context strictly focused on product definitions and high-level strategy
+- To delegate track execution: instruct the human operator to run:
+  `uv run python scripts\claude_mma_exec.py --role tier2-tech-lead "[PROMPT]"`

.claude/commands/mma-tier2-tech-lead.md

@@ -0,0 +1,72 @@
+---
+description: Tier 2 Tech Lead — track execution, architectural oversight, delegation to Tier 3/4
+---
+
+STRICT SYSTEM DIRECTIVE: You are a Tier 2 Tech Lead. Focused on architectural design and track execution. ONLY output the requested text. No pleasantries.
+
+# MMA Tier 2: Tech Lead
+
+## Primary Context Documents
+Read at session start: `conductor/tech-stack.md`, `conductor/workflow.md`
+
+## Responsibilities
+- Manage the execution of implementation tracks (`/conductor-implement`)
+- Ensure alignment with `tech-stack.md` and project architecture
+- Break down tasks into specific technical steps for Tier 3 Workers
+- Maintain PERSISTENT context throughout a track's implementation phase (NO Context Amnesia)
+- Review implementations and coordinate bug fixes via Tier 4 QA
+
+## Delegation Commands (PowerShell)
+
+```powershell
+# Spawn Tier 3 Worker for implementation tasks
+uv run python scripts\claude_mma_exec.py --role tier3-worker "[PROMPT]"
+
+# Spawn Tier 4 QA Agent for error analysis
+uv run python scripts\claude_mma_exec.py --role tier4-qa "[PROMPT]"
+```
+
+### @file Syntax for Tier 3 Context Injection
+`@filepath` anywhere in the prompt string is detected by `claude_mma_exec.py` and the file is automatically inlined into the Tier 3 context. Use this so Tier 3 has what it needs WITHOUT Tier 2 reading those files first.
+
+```powershell
+# Example: Tier 3 gets api_hook_client.py and the styleguide injected automatically
+uv run python scripts\claude_mma_exec.py --role tier3-worker "Apply type hints to @api_hook_client.py following @conductor/code_styleguides/python.md. ..."
+```
+
+## Tool Use Hierarchy (MANDATORY — enforced order)
+
+Claude has access to all tools and will default to familiar ones. This hierarchy OVERRIDES that default.
+
+**For any Python file investigation, use in this order:**
+1. `py_get_code_outline` — structure map (functions, classes, line ranges). Use this FIRST.
+2. `py_get_skeleton` — signatures + docstrings, no bodies
+3. `get_file_summary` — high-level prose summary
+4. `py_get_definition` / `py_get_signature` — targeted symbol lookup
+5. `Grep` / `Glob` — cross-file symbol search and pattern matching
+6. `Read` (targeted, with offset/limit) — ONLY after outline identifies specific line ranges
+
+**`run_powershell` (MCP tool)** — PRIMARY shell execution on Windows. Use for: git, tests, scan scripts, any shell command. This is native PowerShell, not bash/mingw.
+
+**Bash** — LAST RESORT only when MCP server is not running. Bash runs in a mingw sandbox on Windows and may produce no output. Prefer `run_powershell` for everything.
+
+## Hard Rules (Non-Negotiable)
+
+- **NEVER** call `Read` on a file >50 lines without calling `py_get_code_outline` or `py_get_skeleton` first.
+- **NEVER** write implementation code, refactor code, type hint code, or test code inline in this context. If it goes into the codebase, Tier 3 writes it.
+- **NEVER** write or run inline Python scripts via Bash. If a script is needed, it already exists or Tier 3 creates it.
+- **NEVER** process raw bash output for large outputs inline — write to a file and Read, or delegate to Tier 4 QA.
+- **ALWAYS** use `@file` injection in Tier 3 prompts rather than reading and summarizing files yourself.
+
+## Refactor-Heavy Tracks (Type Hints, Style Sweeps)
+
+For tracks with no new logic — only mechanical code changes (type hints, style fixes, renames):
+- **No TDD cycle required.** Skip Red/Green phases. The verification is: scan report shows 0 remaining items.
+- Tier 2 role: scope the batch, write a precise Tier 3 prompt, delegate, verify with scan script.
+- Batch by file group. One Tier 3 call per group (e.g., all scripts/, all simulation/).
+- Verification command: `uv run python scripts\scan_all_hints.py` then read `scan_report.txt`
+
+## Limitations
+- Do NOT perform heavy implementation work directly — delegate to Tier 3
+- Do NOT write test or implementation code directly
+- For large error logs, always spawn Tier 4 QA rather than reading raw stderr

.claude/commands/mma-tier3-worker.md

@@ -0,0 +1,22 @@
+---
+description: Tier 3 Worker — stateless TDD implementation, surgical code changes
+---
+
+STRICT SYSTEM DIRECTIVE: You are a stateless Tier 3 Worker (Contributor). Your goal is to implement specific code changes or tests based on the provided task. You have access to tools for reading and writing files (Read, Write, Edit), codebase investigation (Glob, Grep), version control (Bash git commands), and web tools (WebFetch, WebSearch). You CAN execute PowerShell scripts via Bash for verification and testing. Follow TDD and return success status or code changes. No pleasantries, no conversational filler.
+
+# MMA Tier 3: Worker
+
+## Context Model: Context Amnesia
+Treat each invocation as starting from zero. Use ONLY what is provided in this prompt plus files you explicitly read during this session. Do not reference prior conversation history.
+
+## Responsibilities
+- Implement code strictly according to the provided prompt and specifications
+- Write failing tests FIRST (Red phase), then implement code to pass them (Green phase)
+- Ensure all changes are minimal, surgical, and conform to the requested standards
+- Utilize tool access (Read, Write, Edit, Glob, Grep, Bash) to implement and verify
+
+## Limitations
+- No architectural decisions — if ambiguous, pick the minimal correct approach and note the assumption
+- No modifications to unrelated files beyond the immediate task scope
+- Stateless — always assume a fresh context per invocation
+- Rely on dependency skeletons provided in the prompt for understanding module interfaces

.claude/commands/mma-tier4-qa.md

@@ -0,0 +1,30 @@
+---
+description: Tier 4 QA Agent — stateless error analysis, log summarization, no fixes
+---
+
+STRICT SYSTEM DIRECTIVE: You are a stateless Tier 4 QA Agent. Your goal is to analyze errors, summarize logs, or verify tests. Read-only access only. Do NOT implement fixes. Do NOT modify any files. ONLY output the requested analysis. No pleasantries.
+
+# MMA Tier 4: QA Agent
+
+## Context Model: Context Amnesia
+Stateless — treat each invocation as a fresh context. Use only what is provided in this prompt and files you explicitly read.
+
+## Responsibilities
+- Compress large stack traces or log files into concise, actionable summaries
+- Identify the root cause of test failures or runtime errors
+- Provide a brief, technical description of the required fix (description only — NOT the implementation)
+- Utilize diagnostic tools (Read, Glob, Grep, Bash read-only) to verify failures
+
+## Output Format
+
+```
+ROOT CAUSE: [one sentence]
+AFFECTED FILE: [path:line if identifiable]
+RECOMMENDED FIX: [one sentence description for Tier 2 to action]
+```
+
+## Limitations
+- Do NOT implement the fix directly
+- Do NOT write or modify any files
+- Ensure output is extremely brief and focused
+- Always operate statelessly — assume fresh context each invocation

.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "outputStyle": "default"
+}

.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__manual-slop__run_powershell",
+      "mcp__manual-slop__py_get_definition",
+      "mcp__manual-slop__read_file",
+      "mcp__manual-slop__py_get_code_outline",
+      "mcp__manual-slop__get_file_slice",
+      "mcp__manual-slop__py_find_usages",
+      "mcp__manual-slop__set_file_slice",
+      "mcp__manual-slop__py_check_syntax",
+      "mcp__manual-slop__get_file_summary",
+      "mcp__manual-slop__get_tree",
+      "mcp__manual-slop__list_directory"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "manual-slop"
+  ]
+}

.dockerignore

@@ -0,0 +1,21 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.git
+.gitignore
+logs
+gallery
+md_gen
+credentials.toml
+manual_slop.toml
+manual_slop_history.toml
+manualslop_layout.ini
+dpg_layout.ini
+.pytest_cache
+scripts/generated
+.gemini
+conductor/archive
+.editorconfig
+*.log

.editorconfig

@@ -2,7 +2,7 @@ root = true
 
 [*.py]
 indent_style = space
-indent_size  = 2
+indent_size  = 1
 
 [*.s]
 indent_style = tab

.gemini/agents/tier1-orchestrator.md

@@ -0,0 +1,100 @@
+---
+name: tier1-orchestrator
+description: Tier 1 Orchestrator for product alignment and high-level planning.
+model: gemini-3.1-pro-preview
+tools:
+  - read_file
+  - list_directory
+  - discovered_tool_search_files
+  - grep_search
+  - discovered_tool_get_file_summary
+  - discovered_tool_get_python_skeleton
+  - discovered_tool_get_code_outline
+  - discovered_tool_get_git_diff
+  - discovered_tool_web_search
+  - discovered_tool_fetch_url
+  - activate_skill
+  - discovered_tool_run_powershell
+  - discovered_tool_py_find_usages
+  - discovered_tool_py_get_imports
+  - discovered_tool_py_check_syntax
+  - discovered_tool_py_get_hierarchy
+  - discovered_tool_py_get_docstring
+  - discovered_tool_get_tree
+  - discovered_tool_py_get_definition
+---
+STRICT SYSTEM DIRECTIVE: You are a Tier 1 Orchestrator.
+Focused on product alignment, high-level planning, and track initialization.
+ONLY output the requested text. No pleasantries.
+
+## Architecture Fallback
+When planning tracks that touch core systems, consult the deep-dive docs:
+- `docs/guide_architecture.md`: Thread domains, event system, AI client, HITL mechanism, frame-sync action catalog
+- `docs/guide_tools.md`: MCP Bridge security, 26-tool inventory, Hook API endpoints, ApiHookClient
+- `docs/guide_mma.md`: Ticket/Track data structures, DAG engine, ConductorEngine, worker lifecycle
+- `docs/guide_simulations.md`: live_gui fixture, Puppeteer pattern, mock provider, verification patterns
+
+## The Surgical Methodology
+
+When creating or refining tracks, you MUST follow this protocol:
+
+### 1. MANDATORY: Audit Before Specifying
+NEVER write a spec without first reading the actual code using your tools.
+Use `get_code_outline`, `py_get_definition`, `grep_search`, and `get_git_diff`
+to build a map of what exists. Document existing implementations with file:line
+references in a "Current State Audit" section in the spec.
+
+**WHY**: Previous track specs asked to implement features that already existed
+(Track Browser, DAG tree, approval dialogs) because no code audit was done first.
+This wastes entire implementation phases.
+
+### 2. Identify Gaps, Not Features
+Frame requirements around what's MISSING relative to what exists:
+GOOD: "The existing `_render_mma_dashboard` (gui_2.py:2633-2724) has a token
+usage table but no cost estimation column."
+BAD: "Build a metrics dashboard with token and cost tracking."
+
+### 3. Write Worker-Ready Tasks
+Each plan task must be executable by a Tier 3 worker on gemini-2.5-flash-lite
+without understanding the overall architecture. Every task specifies:
+- **WHERE**: Exact file and line range (`gui_2.py:2700-2701`)
+- **WHAT**: The specific change (add function, modify dict, extend table)
+- **HOW**: Which API calls or patterns (`imgui.progress_bar(...)`, `imgui.collapsing_header(...)`)
+- **SAFETY**: Thread-safety constraints if cross-thread data is involved
+
+### 4. For Bug Fix Tracks: Root Cause Analysis
+Don't write "investigate and fix." Read the code, trace the data flow, list
+specific root cause candidates with code-level reasoning.
+
+### 5. Reference Architecture Docs
+Link to relevant `docs/guide_*.md` sections in every spec so implementing
+agents have a fallback for threading, data flow, or module interactions.
+
+### 6. Map Dependencies Between Tracks
+State execution order and blockers explicitly in metadata.json and spec.
+
+## Spec Template (REQUIRED sections)
+```
+# Track Specification: {Title}
+
+## Overview
+## Current State Audit (as of {commit_sha})
+### Already Implemented (DO NOT re-implement)
+### Gaps to Fill (This Track's Scope)
+## Goals
+## Functional Requirements
+## Non-Functional Requirements
+## Architecture Reference
+## Out of Scope
+```
+
+## Plan Template (REQUIRED format)
+```
+## Phase N: {Name}
+Focus: {One-sentence scope}
+
+- [ ] Task N.1: {Surgical description with file:line refs and API calls}
+- [ ] Task N.2: ...
+- [ ] Task N.N: Write tests for Phase N changes
+- [ ] Task N.X: Conductor - User Manual Verification (Protocol in workflow.md)
+```

.gemini/agents/tier2-tech-lead.md

@@ -0,0 +1,29 @@
+---
+name: tier2-tech-lead
+description: Tier 2 Tech Lead for architectural design and execution.
+model: gemini-3-flash-preview
+tools:
+  - read_file
+  - write_file
+  - replace
+  - list_directory
+  - discovered_tool_search_files
+  - grep_search
+  - discovered_tool_get_file_summary
+  - discovered_tool_get_python_skeleton
+  - discovered_tool_get_code_outline
+  - discovered_tool_get_git_diff
+  - discovered_tool_web_search
+  - discovered_tool_fetch_url
+  - activate_skill
+  - discovered_tool_run_powershell
+  - discovered_tool_py_find_usages
+  - discovered_tool_py_get_imports
+  - discovered_tool_py_check_syntax
+  - discovered_tool_py_get_hierarchy
+  - discovered_tool_py_get_docstring
+  - discovered_tool_get_tree
+---
+STRICT SYSTEM DIRECTIVE: You are a Tier 2 Tech Lead.
+Focused on architectural design and track execution.
+ONLY output the requested text. No pleasantries.

.gemini/agents/tier3-worker.md

@@ -0,0 +1,31 @@
+---
+name: tier3-worker
+description: Stateless Tier 3 Worker for code implementation and TDD.
+model: gemini-3-flash-preview
+tools:
+  - read_file
+  - write_file
+  - replace
+  - list_directory
+  - discovered_tool_search_files
+  - grep_search
+  - discovered_tool_get_file_summary
+  - discovered_tool_get_python_skeleton
+  - discovered_tool_get_code_outline
+  - discovered_tool_get_git_diff
+  - discovered_tool_web_search
+  - discovered_tool_fetch_url
+  - activate_skill
+  - discovered_tool_run_powershell
+  - discovered_tool_py_find_usages
+  - discovered_tool_py_get_imports
+  - discovered_tool_py_check_syntax
+  - discovered_tool_py_get_hierarchy
+  - discovered_tool_py_get_docstring
+  - discovered_tool_get_tree
+---
+STRICT SYSTEM DIRECTIVE: You are a stateless Tier 3 Worker (Contributor).
+Your goal is to implement specific code changes or tests based on the provided task.
+You have access to tools for reading and writing files, codebase investigation, and web tools.
+You CAN execute PowerShell scripts or run shell commands via discovered_tool_run_powershell for verification and testing.
+Follow TDD and return success status or code changes. No pleasantries, no conversational filler.

.gemini/agents/tier4-qa.md

@@ -0,0 +1,29 @@
+---
+name: tier4-qa
+description: Stateless Tier 4 QA Agent for log analysis and diagnostics.
+model: gemini-2.5-flash-lite
+tools:
+  - read_file
+  - list_directory
+  - discovered_tool_search_files
+  - grep_search
+  - discovered_tool_get_file_summary
+  - discovered_tool_get_python_skeleton
+  - discovered_tool_get_code_outline
+  - discovered_tool_get_git_diff
+  - discovered_tool_web_search
+  - discovered_tool_fetch_url
+  - activate_skill
+  - discovered_tool_run_powershell
+  - discovered_tool_py_find_usages
+  - discovered_tool_py_get_imports
+  - discovered_tool_py_check_syntax
+  - discovered_tool_py_get_hierarchy
+  - discovered_tool_py_get_docstring
+  - discovered_tool_get_tree
+---
+STRICT SYSTEM DIRECTIVE: You are a stateless Tier 4 QA Agent.
+Your goal is to analyze errors, summarize logs, or verify tests.
+You have access to tools for reading files, exploring the codebase, and web tools.
+You CAN execute PowerShell scripts or run shell commands via discovered_tool_run_powershell for diagnostics.
+ONLY output the requested analysis. No pleasantries.

.gemini/policies/99-agent-full-autonomy.toml

@@ -0,0 +1,269 @@
+[[rule]] 
+toolName = "discovered_tool_fetch_url"
+decision = "allow"
+priority = 100
+description = "Allow discovered fetch_url tool."
+
+[[rule]]
+toolName = "discovered_tool_get_file_slice"
+decision = "allow"
+priority = 100
+description = "Allow discovered get_file_slice tool."
+
+[[rule]]
+toolName = "discovered_tool_get_file_summary"
+decision = "allow"
+priority = 100
+description = "Allow discovered get_file_summary tool."
+
+[[rule]]
+toolName = "discovered_tool_get_git_diff"
+decision = "allow"
+priority = 100
+description = "Allow discovered get_git_diff tool."
+
+[[rule]]
+toolName = "discovered_tool_get_tree"
+decision = "allow"
+priority = 100
+description = "Allow discovered get_tree tool."
+
+[[rule]]
+toolName = "discovered_tool_get_ui_performance"
+decision = "allow"
+priority = 100
+description = "Allow discovered get_ui_performance tool."
+
+[[rule]]
+toolName = "discovered_tool_list_directory"
+decision = "allow"
+priority = 100
+description = "Allow discovered list_directory tool."
+
+[[rule]]
+toolName = "discovered_tool_py_check_syntax"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_check_syntax tool."
+
+[[rule]]
+toolName = "discovered_tool_py_find_usages"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_find_usages tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_class_summary"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_class_summary tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_code_outline"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_code_outline tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_definition"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_definition tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_docstring"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_docstring tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_hierarchy"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_hierarchy tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_imports"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_imports tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_signature"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_signature tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_skeleton"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_skeleton tool."
+
+[[rule]]
+toolName = "discovered_tool_py_get_var_declaration"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_get_var_declaration tool."
+
+[[rule]]
+toolName = "discovered_tool_py_set_signature"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_set_signature tool."
+
+[[rule]]
+toolName = "discovered_tool_py_set_var_declaration"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_set_var_declaration tool."
+
+[[rule]]
+toolName = "discovered_tool_py_update_definition"
+decision = "allow"
+priority = 100
+description = "Allow discovered py_update_definition tool."
+
+[[rule]]
+toolName = "discovered_tool_read_file"
+decision = "allow"
+priority = 100
+description = "Allow discovered read_file tool."
+
+[[rule]]
+toolName = "discovered_tool_run_powershell"
+decision = "allow"
+priority = 100
+description = "Allow discovered run_powershell tool."
+
+[[rule]]
+toolName = "discovered_tool_search_files"
+decision = "allow"
+priority = 100
+description = "Allow discovered search_files tool."
+
+[[rule]]
+toolName = "discovered_tool_set_file_slice"
+decision = "allow"
+priority = 100
+description = "Allow discovered set_file_slice tool."
+
+[[rule]]
+toolName = "discovered_tool_web_search"
+decision = "allow"
+priority = 100
+description = "Allow discovered web_search tool."
+
+[[rule]]
+toolName = "run_powershell"
+decision = "allow"
+priority = 100
+description = "Allow the base run_powershell tool with maximum priority."
+
+[[rule]]
+toolName = "activate_skill"
+decision = "allow"
+priority = 990
+description = "Allow activate_skill."
+
+[[rule]]
+toolName = "ask_user"
+decision = "ask_user"
+priority = 990
+description = "Allow ask_user."
+
+[[rule]]
+toolName = "cli_help"
+decision = "allow"
+priority = 990
+description = "Allow cli_help."
+
+[[rule]]
+toolName = "codebase_investigator"
+decision = "allow"
+priority = 990
+description = "Allow codebase_investigator."
+
+[[rule]]
+toolName = "replace"
+decision = "allow"
+priority = 990
+description = "Allow replace."
+
+[[rule]]
+toolName = "glob"
+decision = "allow"
+priority = 990
+description = "Allow glob."
+
+[[rule]]
+toolName = "google_web_search"
+decision = "allow"
+priority = 990
+description = "Allow google_web_search."
+
+[[rule]]
+toolName = "read_file"
+decision = "allow"
+priority = 990
+description = "Allow read_file."
+
+[[rule]]
+toolName = "list_directory"
+decision = "allow"
+priority = 990
+description = "Allow list_directory."
+
+[[rule]]
+toolName = "save_memory"
+decision = "allow"
+priority = 990
+description = "Allow save_memory."
+
+[[rule]]
+toolName = "grep_search"
+decision = "allow"
+priority = 990
+description = "Allow grep_search."
+
+[[rule]]
+toolName = "run_shell_command"
+decision = "allow"
+priority = 990
+description = "Allow run_shell_command."
+
+[[rule]]
+toolName = "tier1-orchestrator"
+decision = "allow"
+priority = 990
+description = "Allow tier1-orchestrator."
+
+[[rule]]
+toolName = "tier2-tech-lead"
+decision = "allow"
+priority = 990
+description = "Allow tier2-tech-lead."
+
+[[rule]]
+toolName = "tier3-worker"
+decision = "allow"
+priority = 990
+description = "Allow tier3-worker."
+
+[[rule]]
+toolName = "tier4-qa"
+decision = "allow"
+priority = 990
+description = "Allow tier4-qa."
+
+[[rule]]
+toolName = "web_fetch"
+decision = "allow"
+priority = 990
+description = "Allow web_fetch."
+
+[[rule]]
+toolName = "write_file"
+decision = "allow"
+priority = 990
+description = "Allow write_file."

.gemini/settings.json

@@ -0,0 +1,34 @@
+{
+  "workspace_folders": [
+    "C:/projects/manual_slop",
+    "C:/projects/gencpp",
+    "C:/projects/VEFontCache-Odin"
+  ],
+  "experimental": {
+    "enableAgents": true
+  },
+  "tools": {
+    "whitelist": [
+      "*"
+    ],
+    "discoveryCommand": "powershell.exe -NoProfile -Command \"Get-Content .gemini/tools.json -Raw\"",
+    "callCommand": "scripts\\tool_call.exe"
+  },
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "manual-slop-bridge",
+            "type": "command",
+            "command": "python C:/projects/manual_slop/scripts/cli_tool_bridge.py"
+          }
+        ]
+      }
+    ]
+  },
+  "hooksConfig": {
+    "enabled": true
+  }
+}

.gemini/skills/mma-orchestrator

@@ -0,0 +1 @@
+C:/projects/manual_slop/mma-orchestrator

.gemini/skills/mma-tier1-orchestrator/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: mma-tier1-orchestrator
+description: Focused on product alignment, high-level planning, and track initialization.
+---
+
+# MMA Tier 1: Orchestrator
+
+You are the Tier 1 Orchestrator. Your role is to oversee the product direction and manage project/track initialization within the Conductor framework.
+
+## Primary Context Documents
+Read at session start: `conductor/product.md`, `conductor/product-guidelines.md`
+
+## Architecture Fallback
+When planning tracks that touch core systems, consult:
+- `docs/guide_architecture.md`: Threading, events, AI client, HITL, frame-sync action catalog
+- `docs/guide_tools.md`: MCP Bridge, Hook API endpoints, ApiHookClient methods
+- `docs/guide_mma.md`: Ticket/Track structures, DAG engine, ConductorEngine, worker lifecycle
+- `docs/guide_simulations.md`: live_gui fixture, Puppeteer pattern, mock provider
+
+## Responsibilities
+- Maintain alignment with the product guidelines and definition.
+- Define track boundaries and initialize new tracks (`/conductor:newTrack`).
+- Set up the project environment (`/conductor:setup`).
+- Delegate track execution to the Tier 2 Tech Lead.
+
+## Surgical Spec Protocol (MANDATORY)
+When creating or refining tracks, you MUST:
+1. **Audit** the codebase with `get_code_outline`, `py_get_definition`, `grep_search` before writing any spec. Document what exists with file:line refs.
+2. **Spec gaps, not features** — frame requirements relative to what already exists.
+3. **Write worker-ready tasks** — each specifies WHERE (file:line), WHAT (change), HOW (API call), SAFETY (thread constraints).
+4. **For fix tracks** — list root cause candidates with code-level reasoning.
+5. **Reference architecture docs** — link to relevant `docs/guide_*.md` sections.
+6. **Map dependencies** — state execution order and blockers between tracks.
+
+See `activate_skill mma-orchestrator` for the full protocol and examples.
+
+## Limitations
+- Do not execute tracks or implement features.
+- Do not write code or perform low-level bug fixing.
+- Keep context strictly focused on product definitions and high-level strategy.

.gemini/skills/mma-tier2-tech-lead/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: mma-tier2-tech-lead
+description: Focused on track execution, architectural design, and implementation oversight.
+---
+
+# MMA Tier 2: Tech Lead
+
+You are the Tier 2 Tech Lead. Your role is to manage the implementation of tracks (`/conductor:implement`), ensure architectural integrity, and oversee the work of Tier 3 and 4 sub-agents.
+
+## Architecture Fallback
+When implementing tracks, consult these docs for threading, data flow, and module interactions:
+- `docs/guide_architecture.md`: Thread domains, `_process_pending_gui_tasks` action catalog, AI client architecture, HITL blocking flow
+- `docs/guide_tools.md`: MCP tools, Hook API endpoints, session logging
+- `docs/guide_mma.md`: Ticket/Track structures, DAG engine, worker lifecycle
+- `docs/guide_simulations.md`: Testing patterns, mock provider
+
+## Responsibilities
+- Manage the execution of implementation tracks.
+- Ensure alignment with `tech-stack.md` and project architecture.
+- Break down tasks into specific technical steps for Tier 3 Workers.
+- Maintain persistent context throughout a track's implementation phase (No Context Amnesia).
+- Review implementations and coordinate bug fixes via Tier 4 QA.
+- **CRITICAL: ATOMIC PER-TASK COMMITS**: You MUST commit your progress on a per-task basis. Immediately after a task is verified successfully, you must stage the changes, commit them, attach the git note summary, and update `plan.md` before moving to the next task. Do NOT batch multiple tasks into a single commit.
+- **Meta-Level Sanity Check**: After completing a track (or upon explicit request), perform a codebase sanity check. Run `uv run ruff check .` and `uv run mypy --explicit-package-bases .` to ensure Tier 3 Workers haven't degraded static analysis constraints. Identify broken simulation tests and append them to a tech debt track or fix them immediately.
+
+## Surgical Delegation Protocol
+When delegating to Tier 3 workers, construct prompts that specify:
+- **WHERE**: Exact file and line range to modify
+- **WHAT**: The specific change (add function, modify dict, extend table)
+- **HOW**: Which API calls, data structures, or patterns to use
+- **SAFETY**: Thread-safety constraints (e.g., "push via `_pending_gui_tasks` with lock")
+
+Example prompt: `"In gui_2.py, modify _render_mma_dashboard (lines 2685-2699). Extend the token usage table from 3 to 5 columns by adding 'Model' and 'Est. Cost'. Use imgui.table_setup_column(). Import cost_tracker. Use 1-space indentation."`
+
+## Limitations
+- Do not perform heavy implementation work directly; delegate to Tier 3.
+- Delegate implementation tasks to Tier 3 Workers using `uv run python scripts/mma_exec.py --role tier3-worker "[PROMPT]"`.
+- For error analysis of large logs, use `uv run python scripts/mma_exec.py --role tier4-qa "[PROMPT]"`.
+- Minimize full file reads for large modules; rely on "Skeleton Views" and git diffs.

.gemini/skills/mma-tier3-worker/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: mma-tier3-worker
+description: Focused on TDD implementation, surgical code changes, and following specific specs.
+---
+
+# MMA Tier 3: Worker
+
+You are the Tier 3 Worker. Your role is to implement specific, scoped technical requirements, follow Test-Driven Development (TDD), and make surgical code modifications. You operate in a stateless manner (Context Amnesia).
+
+## Responsibilities
+- Implement code strictly according to the provided prompt and specifications.
+- Write failing tests first, then implement the code to pass them.
+- Ensure all changes are minimal, functional, and conform to the requested standards.
+- Utilize provided tool access (read_file, write_file, etc.) to perform implementation and verification.
+
+## Limitations
+- Do not make architectural decisions.
+- Do not modify unrelated files beyond the immediate task scope.
+- Always operate statelessly; assume each task starts with a clean context.
+- Rely on "Skeleton Views" provided by Tier 2/Orchestrator for understanding dependencies.

.gemini/skills/mma-tier4-qa/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: mma-tier4-qa
+description: Focused on test analysis, error summarization, and bug reproduction.
+---
+
+# MMA Tier 4: QA Agent
+
+You are the Tier 4 QA Agent. Your role is to analyze error logs, summarize tracebacks, and help diagnose issues efficiently. You operate in a stateless manner (Context Amnesia).
+
+## Responsibilities
+- Compress large stack traces or log files into concise, actionable summaries.
+- Identify the root cause of test failures or runtime errors.
+- Provide a brief, technical description of the required fix.
+- Utilize provided diagnostic and exploration tools to verify failures.
+
+## Limitations
+- Do not implement the fix directly.
+- Ensure your output is extremely brief and focused.
+- Always operate statelessly; assume each analysis starts with a clean context.

.gemini/tools/fetch_url.json

@@ -0,0 +1,17 @@
+{
+  "name": "fetch_url",
+  "description": "Fetch the full text content of a URL (stripped of HTML tags).",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "The full URL to fetch."
+      }
+    },
+    "required": [
+      "url"
+    ]
+  },
+  "command": "python scripts/tool_call.py fetch_url"
+}

.gemini/tools/get_file_summary.json

@@ -0,0 +1,17 @@
+{
+  "name": "get_file_summary",
+  "description": "Get a compact heuristic summary of a file without reading its full content. For Python: imports, classes, methods, functions, constants. For TOML: table keys. For Markdown: headings. Others: line count + preview. Use this before read_file to decide if you need the full content.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Absolute or relative path to the file to summarise."
+      }
+    },
+    "required": [
+      "path"
+    ]
+  },
+  "command": "python scripts/tool_call.py get_file_summary"
+}

.gemini/tools/get_git_diff.json

@@ -0,0 +1,25 @@
+{
+  "name": "get_git_diff",
+  "description": "Returns the git diff for a file or directory. Use this to review changes efficiently without reading entire files.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Path to the file or directory."
+      },
+      "base_rev": {
+        "type": "string",
+        "description": "Base revision (e.g. 'HEAD', 'HEAD~1', or a commit hash). Defaults to 'HEAD'."
+      },
+      "head_rev": {
+        "type": "string",
+        "description": "Head revision (optional)."
+      }
+    },
+    "required": [
+      "path"
+    ]
+  },
+  "command": "python scripts/tool_call.py get_git_diff"
+}

.gemini/tools/py_get_code_outline.json

@@ -0,0 +1,17 @@
+{
+  "name": "py_get_code_outline",
+  "description": "Get a hierarchical outline of a code file. This returns classes, functions, and methods with their line ranges and brief docstrings. Use this to quickly map out a file's structure before reading specific sections.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Path to the code file (currently supports .py)."
+      }
+    },
+    "required": [
+      "path"
+    ]
+  },
+  "command": "python scripts/tool_call.py py_get_code_outline"
+}

.gemini/tools/py_get_skeleton.json

@@ -0,0 +1,17 @@
+{
+  "name": "py_get_skeleton",
+  "description": "Get a skeleton view of a Python file. This returns all classes and function signatures with their docstrings, but replaces function bodies with '...'. Use this to understand module interfaces without reading the full implementation.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Path to the .py file."
+      }
+    },
+    "required": [
+      "path"
+    ]
+  },
+  "command": "python scripts/tool_call.py py_get_skeleton"
+}

.gemini/tools/run_powershell.json

@@ -0,0 +1,17 @@
+{
+  "name": "run_powershell",
+  "description": "Run a PowerShell script within the project base_dir. Use this to create, edit, rename, or delete files and directories. stdout and stderr are returned to you as the result.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "script": {
+        "type": "string",
+        "description": "The PowerShell script to execute."
+      }
+    },
+    "required": [
+      "script"
+    ]
+  },
+  "command": "python scripts/tool_call.py run_powershell"
+}

.gemini/tools/search_files.json

@@ -0,0 +1,22 @@
+{
+  "name": "search_files",
+  "description": "Search for files matching a glob pattern within an allowed directory. Supports recursive patterns like '**/*.py'. Use this to find files by extension or name pattern.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Absolute path to the directory to search within."
+      },
+      "pattern": {
+        "type": "string",
+        "description": "Glob pattern, e.g. '*.py', '**/*.toml', 'src/**/*.rs'."
+      }
+    },
+    "required": [
+      "path",
+      "pattern"
+    ]
+  },
+  "command": "python scripts/tool_call.py search_files"
+}

.gemini/tools/web_search.json

@@ -0,0 +1,17 @@
+{
+  "name": "web_search",
+  "description": "Search the web using DuckDuckGo. Returns the top 5 search results with titles, URLs, and snippets.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "The search query."
+      }
+    },
+    "required": [
+      "query"
+    ]
+  },
+  "command": "python scripts/tool_call.py web_search"
+}

.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "manual-slop": {
+      "type": "stdio",
+      "command": "C:\\Users\\Ed\\scoop\\apps\\uv\\current\\uv.exe",
+      "args": [
+        "run",
+        "python",
+        "C:\\projects\\manual_slop\\scripts\\mcp_server.py"
+      ],
+      "env": {}
+    }
+  }
+}

ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# ARCHITECTURE.md
+
+## Tech Stack
+- **Framework**: [Primary framework/language]
+- **Database**: [Database system]
+- **Frontend**: [Frontend technology]
+- **Backend**: [Backend technology]
+- **Infrastructure**: [Hosting/deployment]
+- **Build Tools**: [Build system]
+
+## Directory Structure
+```
+project/
+├── src/              # Source code
+├── tests/            # Test files
+├── docs/             # Documentation
+├── config/           # Configuration files
+└── scripts/          # Build/deployment scripts
+```
+
+## Key Architectural Decisions
+
+### [Decision 1]
+**Context**: [Why this decision was needed]
+**Decision**: [What was decided]
+**Rationale**: [Why this approach was chosen]
+**Consequences**: [Trade-offs and implications]
+
+## Component Architecture
+
+### [ComponentName] Structure <!-- #component-anchor -->
+```typescript
+// Major classes with exact line numbers
+class MainClass { /* lines 100-500 */ }    // <!-- #main-class -->
+class Helper { /* lines 501-600 */ }       // <!-- #helper-class -->
+```
+
+## System Flow Diagram
+```
+[User] -> [Frontend] -> [API] -> [Database]
+           |            |
+           v            v
+       [Cache]     [External Service]
+```
+
+## Common Patterns
+
+### [Pattern Name]
+**When to use**: [Circumstances]
+**Implementation**: [How to implement]
+**Example**: [Code example with line numbers]
+
+## Keywords <!-- #keywords -->
+- architecture
+- system design
+- tech stack
+- components
+- patterns

BUILD.md

@@ -0,0 +1,103 @@
+# BUILD.md
+
+## Prerequisites
+- [Runtime requirements]
+- [Development tools needed]
+- [Environment setup]
+
+## Build Commands
+
+### Development
+```bash
+# Start development server
+npm run dev
+
+# Run in watch mode
+npm run watch
+```
+
+### Production
+```bash
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+### Testing
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test file
+npm test -- filename
+```
+
+### Linting & Formatting
+```bash
+# Lint code
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+
+# Format code
+npm run format
+```
+
+## CI/CD Pipeline
+
+### GitHub Actions
+```yaml
+# .github/workflows/main.yml
+name: CI/CD
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+```
+
+## Deployment
+
+### Staging
+1. [Deployment steps]
+2. [Verification steps]
+
+### Production
+1. [Pre-deployment checklist]
+2. [Deployment steps]
+3. [Post-deployment verification]
+
+## Rollback Procedures
+1. [Emergency rollback steps]
+2. [Database rollback if needed]
+3. [Verification steps]
+
+## Troubleshooting
+
+### Common Issues
+**Issue**: [Problem description]
+**Solution**: [How to fix]
+
+### Build Failures
+- [Common build errors and solutions]
+
+## Keywords <!-- #keywords -->
+- build
+- deployment
+- ci/cd
+- testing
+- production

CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+<!-- Generated by Claude Conductor v2.0.0 -->
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Critical Context (Read First)
+- **Tech Stack**: Python 3.11+, Dear PyGui / ImGui, FastAPI, Uvicorn
+- **Main File**: `gui_2.py` (primary GUI), `ai_client.py` (multi-provider LLM abstraction)
+- **Core Mechanic**: GUI orchestrator for LLM-driven coding with 4-tier MMA architecture
+- **Key Integration**: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless), MCP tools
+- **Platform Support**: Windows (PowerShell) — single developer, local use
+- **DO NOT**: Read full files >50 lines without using `py_get_skeleton` or `get_file_summary` first. Do NOT perform heavy implementation directly — delegate to Tier 3 Workers.
+
+## Environment
+- Shell: PowerShell (pwsh) on Windows
+- Do NOT use bash-specific syntax (use PowerShell equivalents)
+- Use `uv run` for all Python execution
+- Path separators: forward slashes work in PowerShell
+- **Shell execution in Claude Code**: The `Bash` tool runs in a mingw sandbox on Windows and produces unreliable/empty output. Use `run_powershell` MCP tool for ALL shell commands (git, tests, scans). Bash is last-resort only when MCP server is not running.
+
+## Session Startup Checklist
+**IMPORTANT**: At the start of each session:
+1. **Check TASKS.md** — look for IN_PROGRESS or BLOCKED tracks
+2. **Review recent JOURNAL.md entries** — scan last 2-3 entries for context
+3. **If resuming work**: run `/conductor-setup` to load full context
+4. **If starting fresh**: run `/conductor-status` for overview
+
+## Quick Reference
+**GUI Entry**: `gui_2.py` — Primary ImGui interface
+**AI Client**: `ai_client.py` — Multi-provider abstraction (Gemini, Anthropic, DeepSeek)
+**MCP Client**: `mcp_client.py:773-831` — Tool dispatch (26 tools)
+**Project Manager**: `project_manager.py` — Context & file management
+**MMA Engine**: `multi_agent_conductor.py:15-100` — ConductorEngine orchestration
+**Tech Lead**: `conductor_tech_lead.py` — Tier 2 ticket generation
+**DAG Engine**: `dag_engine.py` — Task dependency resolution
+**Session Logger**: `session_logger.py` — Audit trails (JSON-L + markdown)
+**Shell Runner**: `shell_runner.py` — PowerShell execution (60s timeout)
+**Models**: `models.py:6-84` — Ticket and Track data structures
+**File Cache**: `file_cache.py` — ASTParser with tree-sitter skeletons
+**Summarizer**: `summarize.py` — Heuristic file summaries
+**Outliner**: `outline_tool.py` — Code outline with line ranges
+
+## Conductor System
+The project uses a spec-driven track system in `conductor/`:
+- **Tracks**: `conductor/tracks/{name}_{YYYYMMDD}/` — spec.md, plan.md, metadata.json
+- **Workflow**: `conductor/workflow.md` — full task lifecycle and TDD protocol
+- **Tech Stack**: `conductor/tech-stack.md` — technology constraints
+- **Product**: `conductor/product.md` — product vision and guidelines
+
+### Conductor Commands (Claude Code slash commands)
+- `/conductor-setup` — bootstrap session with conductor context
+- `/conductor-status` — show all track status
+- `/conductor-new-track` — create a new track (Tier 1)
+- `/conductor-implement` — execute a track (Tier 2 — delegates to Tier 3/4)
+- `/conductor-verify` — phase completion verification and checkpointing
+
+### MMA Tier Commands
+- `/mma-tier1-orchestrator` — product alignment, planning
+- `/mma-tier2-tech-lead` — track execution, architectural oversight
+- `/mma-tier3-worker` — stateless TDD implementation
+- `/mma-tier4-qa` — stateless error analysis
+
+### Delegation (Tier 2 spawns Tier 3/4)
+```powershell
+uv run python scripts\claude_mma_exec.py --role tier3-worker "Task prompt here"
+uv run python scripts\claude_mma_exec.py --role tier4-qa "Error analysis prompt"
+```
+
+## Current State
+- [x] Multi-provider AI client (Gemini, Anthropic, DeepSeek)
+- [x] Dear PyGui / ImGui GUI with multi-panel interface
+- [x] MMA 4-tier orchestration engine
+- [x] Custom MCP tools (26 tools via mcp_client.py)
+- [x] Session logging and audit trails
+- [x] Gemini CLI headless adapter
+- [x] Claude Code conductor integration
+- [~] AI-Optimized Python Style Refactor (Phase 3 — type hints for UI modules)
+- [~] Robust Live Simulation Verification (Phase 2 — Epic/Track verification)
+- [ ] Documentation Refresh and Context Cleanup
+
+## Development Workflow
+1. Run `/conductor-setup` to load session context
+2. Pick active track from `TASKS.md` or `/conductor-status`
+3. Run `/conductor-implement` to resume track execution
+4. Follow TDD: Red (failing tests) → Green (pass) → Refactor
+5. Delegate implementation to Tier 3 Workers, errors to Tier 4 QA
+6. On phase completion: run `/conductor-verify` for checkpoint
+
+## Anti-Patterns (Avoid These)
+- **Don't read full large files** — use `py_get_skeleton`, `get_file_summary`, `py_get_code_outline` first (Research-First Protocol)
+- **Don't implement directly as Tier 2** — delegate to Tier 3 Workers via `claude_mma_exec.py`
+- **Don't skip TDD** — write failing tests before implementation
+- **Don't modify tech stack silently** — update `conductor/tech-stack.md` BEFORE implementing
+- **Don't skip phase verification** — run `/conductor-verify` when all tasks in a phase are `[x]`
+- **Don't mix track work** — stay focused on one track at a time
+
+## MCP Tools (available via manual-slop MCP server)
+When the MCP server is running, these tools are available natively:
+`py_get_skeleton`, `py_get_code_outline`, `py_get_definition`, `py_update_definition`,
+`py_get_signature`, `py_set_signature`, `py_get_class_summary`, `py_find_usages`,
+`py_get_imports`, `py_check_syntax`, `py_get_hierarchy`, `py_get_docstring`,
+`get_file_summary`, `get_file_slice`, `set_file_slice`, `get_git_diff`, `get_tree`,
+`search_files`, `read_file`, `list_directory`, `web_search`, `fetch_url`,
+`run_powershell`, `get_ui_performance`, `py_get_var_declaration`, `py_set_var_declaration`
+
+## Journal Update Requirements
+Update JOURNAL.md after:
+- Completing any significant feature or fix
+- Encountering and resolving errors
+- End of each work session
+- Making architectural decisions
+Format: What/Why/How/Issues/Result structure
+
+## Task Management Integration
+- **TASKS.md**: Quick-read pointer to active conductor tracks
+- **conductor/tracks/*/plan.md**: Detailed task state (source of truth)
+- **JOURNAL.md**: Completed work history with `|TASK:ID|` tags
+- **ERRORS.md**: P0/P1 error tracking

CONDUCTOR.md

@@ -0,0 +1,511 @@
+# CONDUCTOR.md
+<!-- Generated by Claude Conductor v2.0.0 -->
+
+> _Read me first. Every other doc is linked below._
+
+## Critical Context (Read First)
+- **Tech Stack**: [List core technologies]
+- **Main File**: [Primary code file and line count]
+- **Core Mechanic**: [One-line description]
+- **Key Integration**: [Important external services]
+- **Platform Support**: [Deployment targets]
+- **DO NOT**: [Critical things to avoid]
+
+## Table of Contents
+1. [Architecture](ARCHITECTURE.md) - Tech stack, folder structure, infrastructure
+2. [Design Tokens](DESIGN.md) - Colors, typography, visual system
+3. [UI/UX Patterns](UIUX.md) - Components, interactions, accessibility
+4. [Runtime Config](CONFIG.md) - Environment variables, feature flags
+5. [Data Model](DATA_MODEL.md) - Database schema, entities, relationships
+6. [API Contracts](API.md) - Endpoints, request/response formats, auth
+7. [Build & Release](BUILD.md) - Build process, deployment, CI/CD
+8. [Testing Guide](TEST.md) - Test strategies, E2E scenarios, coverage
+9. [Operational Playbooks](PLAYBOOKS/DEPLOY.md) - Deployment, rollback, monitoring
+10. [Contributing](CONTRIBUTING.md) - Code style, PR process, conventions
+11. [Error Ledger](ERRORS.md) - Critical P0/P1 error tracking
+12. [Task Management](TASKS.md) - Active tasks, phase tracking, context preservation
+
+## Quick Reference
+**Main Constants**: `[file:lines]` - Description  
+**Core Class**: `[file:lines]` - Description  
+**Key Function**: `[file:lines]` - Description  
+[Include 10-15 most accessed code locations]
+
+## Current State
+- [x] Feature complete
+- [ ] Feature in progress
+- [ ] Feature planned
+[Track active work]
+
+## Development Workflow
+[5-6 steps for common workflow]
+
+## Task Templates
+### 1. [Common Task Name]
+1. Step with file:line reference
+2. Step with specific action
+3. Test step
+4. Documentation update
+
+[Include 3-5 templates]
+
+## Anti-Patterns (Avoid These)
+❌ **Don't [action]** - [Reason]  
+[List 5-6 critical mistakes]
+
+## Version History
+- **v1.0.0** - Initial release
+- **v1.1.0** - Feature added (see JOURNAL.md YYYY-MM-DD)  
+[Link major versions to journal entries]
+
+## Continuous Engineering Journal <!-- do not remove -->
+
+Claude, keep an ever-growing changelog in [`JOURNAL.md`](JOURNAL.md).
+
+### What to Journal
+- **Major changes**: New features, significant refactors, API changes
+- **Bug fixes**: What broke, why, and how it was fixed
+- **Frustration points**: Problems that took multiple attempts to solve
+- **Design decisions**: Why we chose one approach over another
+- **Performance improvements**: Before/after metrics
+- **User feedback**: Notable issues or requests
+- **Learning moments**: New techniques or patterns discovered
+
+### Journal Format
+\```
+## YYYY-MM-DD HH:MM
+
+### [Short Title]
+- **What**: Brief description of the change
+- **Why**: Reason for the change
+- **How**: Technical approach taken
+- **Issues**: Any problems encountered
+- **Result**: Outcome and any metrics
+
+### [Short Title] |ERROR:ERR-YYYY-MM-DD-001|
+- **What**: Critical P0/P1 error description
+- **Why**: Root cause analysis
+- **How**: Fix implementation
+- **Issues**: Debugging challenges
+- **Result**: Resolution and prevention measures
+
+### [Task Title] |TASK:TASK-YYYY-MM-DD-001|
+- **What**: Task implementation summary
+- **Why**: Part of [Phase Name] phase
+- **How**: Technical approach and key decisions
+- **Issues**: Blockers encountered and resolved
+- **Result**: Task completed, findings documented in ARCHITECTURE.md
+\```
+
+### Compaction Rule
+When `JOURNAL.md` exceeds **500 lines**:
+1. Claude summarizes the oldest half into `JOURNAL_ARCHIVE/<year>-<month>.md`
+2. Remaining entries stay in `JOURNAL.md` so the file never grows unbounded
+
+> ⚠️ Claude must NEVER delete raw history—only move & summarize.
+
+### 2. ARCHITECTURE.md
+**Purpose**: System design, tech stack decisions, and code structure with line numbers.
+
+**Required Elements**:
+- Technology stack listing
+- Directory structure diagram
+- Key architectural decisions with rationale
+- Component architecture with exact line numbers
+- System flow diagram (ASCII art)
+- Common patterns section
+- Keywords for search optimization
+
+**Line Number Format**:
+\```
+#### ComponentName Structure <!-- #component-anchor -->
+\```typescript
+// Major classes with exact line numbers
+class MainClass { /* lines 100-500 */ }    // <!-- #main-class -->
+class Helper { /* lines 501-600 */ }       // <!-- #helper-class -->
+\```
+\```
+
+### 3. DESIGN.md
+**Purpose**: Visual design system, styling, and theming documentation.
+
+**Required Sections**:
+- Typography system
+- Color palette (with hex values)
+- Visual effects specifications
+- Character/entity design
+- UI/UX component styling
+- Animation system
+- Mobile design considerations
+- Accessibility guidelines
+- Keywords section
+
+### 4. DATA_MODEL.md
+**Purpose**: Database schema, application models, and data structures.
+
+**Required Elements**:
+- Database schema (SQL)
+- Application data models (TypeScript/language interfaces)
+- Validation rules
+- Common queries
+- Data migration history
+- Keywords for entities
+
+### 5. API.md
+**Purpose**: Complete API documentation with examples.
+
+**Structure for Each Endpoint**:
+\```
+### Endpoint Name
+
+\```http
+METHOD /api/endpoint
+\```
+
+#### Request
+\```json
+{
+  "field": "type"
+}
+\```
+
+#### Response
+\```json
+{
+  "field": "value"
+}
+\```
+
+#### Details
+- **Rate limit**: X requests per Y seconds
+- **Auth**: Required/Optional
+- **Notes**: Special considerations
+\```
+
+### 6. CONFIG.md
+**Purpose**: Runtime configuration, environment variables, and settings.
+
+**Required Sections**:
+- Environment variables (required and optional)
+- Application configuration constants
+- Feature flags
+- Performance tuning settings
+- Security configuration
+- Common patterns for configuration changes
+
+### 7. BUILD.md
+**Purpose**: Build process, deployment, and CI/CD documentation.
+
+**Include**:
+- Prerequisites
+- Build commands
+- CI/CD pipeline configuration
+- Deployment steps
+- Rollback procedures
+- Troubleshooting guide
+
+### 8. TEST.md
+**Purpose**: Testing strategies, patterns, and examples.
+
+**Sections**:
+- Test stack and tools
+- Running tests commands
+- Test structure
+- Coverage goals
+- Common test patterns
+- Debugging tests
+
+### 9. UIUX.md
+**Purpose**: Interaction patterns, user flows, and behavior specifications.
+
+**Cover**:
+- Input methods
+- State transitions
+- Component behaviors
+- User flows
+- Accessibility patterns
+- Performance considerations
+
+### 10. CONTRIBUTING.md
+**Purpose**: Guidelines for contributors.
+
+**Include**:
+- Code of conduct
+- Development setup
+- Code style guide
+- Commit message format
+- PR process
+- Common patterns
+
+### 11. PLAYBOOKS/DEPLOY.md
+**Purpose**: Step-by-step operational procedures.
+
+**Format**:
+- Pre-deployment checklist
+- Deployment steps (multiple options)
+- Post-deployment verification
+- Rollback procedures
+- Troubleshooting
+
+### 12. ERRORS.md (Critical Error Ledger)
+**Purpose**: Track and resolve P0/P1 critical errors with full traceability.
+
+**Required Structure**:
+\```
+# Critical Error Ledger <!-- auto-maintained -->
+
+## Schema
+| ID | First seen | Status | Severity | Affected area | Link to fix |
+|----|------------|--------|----------|---------------|-------------|
+
+## Active Errors
+[New errors added here, newest first]
+
+## Resolved Errors
+[Moved here when fixed, with links to fixes]
+\```
+
+**Error ID Format**: `ERR-YYYY-MM-DD-001` (increment for multiple per day)
+
+**Severity Definitions**:
+- **P0**: Complete outage, data loss, security breach
+- **P1**: Major functionality broken, significant performance degradation
+- **P2**: Minor functionality (not tracked in ERRORS.md)
+- **P3**: Cosmetic issues (not tracked in ERRORS.md)
+
+**Claude's Error Logging Process**:
+1. When P0/P1 error occurs, immediately add to Active Errors
+2. Create corresponding JOURNAL.md entry with details
+3. When resolved:
+   - Move to Resolved Errors section
+   - Update status to "resolved"
+   - Add commit hash and PR link
+   - Add `|ERROR:<ID>|` tag to JOURNAL.md entry
+   - Link back to JOURNAL entry from ERRORS.md
+
+### 13. TASKS.md (Active Task Management)
+**Purpose**: Track ongoing work with phase awareness and context preservation between sessions.
+
+**IMPORTANT**: TASKS.md complements Claude's built-in todo system - it does NOT replace it:
+- Claude's todos: For immediate task tracking within a session
+- TASKS.md: For preserving context and state between sessions
+
+**Required Structure**:
+```
+# Task Management
+
+## Active Phase
+**Phase**: [High-level project phase name]
+**Started**: YYYY-MM-DD
+**Target**: YYYY-MM-DD
+**Progress**: X/Y tasks completed
+
+## Current Task
+**Task ID**: TASK-YYYY-MM-DD-NNN
+**Title**: [Descriptive task name]
+**Status**: PLANNING | IN_PROGRESS | BLOCKED | TESTING | COMPLETE
+**Started**: YYYY-MM-DD HH:MM
+**Dependencies**: [List task IDs this depends on]
+
+### Task Context
+<!-- Critical information needed to resume this task -->
+- **Previous Work**: [Link to related tasks/PRs]
+- **Key Files**: [Primary files being modified with line ranges]
+- **Environment**: [Specific config/versions if relevant]
+- **Next Steps**: [Immediate actions when resuming]
+
+### Findings & Decisions
+- **FINDING-001**: [Discovery that affects approach]
+- **DECISION-001**: [Technical choice made] → Link to ARCHITECTURE.md
+- **BLOCKER-001**: [Issue preventing progress] → Link to resolution
+
+### Task Chain
+1. ✅ [Completed prerequisite task] (TASK-YYYY-MM-DD-001)
+2. 🔄 [Current task] (CURRENT)
+3. ⏳ [Next planned task]
+4. ⏳ [Future task in phase]
+```
+
+**Task Management Rules**:
+1. **One Active Task**: Only one task should be IN_PROGRESS at a time
+2. **Context Capture**: Before switching tasks, capture all context needed to resume
+3. **Findings Documentation**: Record unexpected discoveries that impact the approach
+4. **Decision Linking**: Link architectural decisions to ARCHITECTURE.md
+5. **Completion Trigger**: When task completes:
+   - Generate JOURNAL.md entry with task summary
+   - Archive task details to TASKS_ARCHIVE/YYYY-MM/TASK-ID.md
+   - Load next task from chain or prompt for new phase
+
+**Task States**:
+- **PLANNING**: Defining approach and breaking down work
+- **IN_PROGRESS**: Actively working on implementation
+- **BLOCKED**: Waiting on external dependency or decision
+- **TESTING**: Implementation complete, validating functionality
+- **COMPLETE**: Task finished and documented
+
+**Integration with Journal**:
+- Each completed task auto-generates a journal entry
+- Journal references task ID for full context
+- Critical findings promoted to relevant documentation
+
+## Documentation Optimization Rules
+
+### 1. Line Number Anchors
+- Add exact line numbers for every class, function, and major code section
+- Format: `**Class Name (Lines 100-200)**`
+- Add HTML anchors: `<!-- #class-name -->`
+- Update when code structure changes significantly
+
+### 2. Quick Reference Card
+- Place in CLAUDE.md after Table of Contents
+- Include 10-15 most common code locations
+- Format: `**Feature**: `file:lines` - Description`
+
+### 3. Current State Tracking
+- Use checkbox format in CLAUDE.md
+- `- [x] Completed feature`
+- `- [ ] In-progress feature`
+- Update after each work session
+
+### 4. Task Templates
+- Provide 3-5 step-by-step workflows
+- Include specific line numbers
+- Reference files that need updating
+- Add test/verification steps
+
+### 5. Keywords Sections
+- Add to each major .md file
+- List alternative search terms
+- Format: `## Keywords <!-- #keywords -->`
+- Include synonyms and related terms
+
+### 6. Anti-Patterns
+- Use ❌ emoji for clarity
+- Explain why each is problematic
+- Include 5-6 critical mistakes
+- Place prominently in CLAUDE.md
+
+### 7. System Flow Diagrams
+- Use ASCII art for simplicity
+- Show data/control flow
+- Keep visual and readable
+- Place in ARCHITECTURE.md
+
+### 8. Common Patterns
+- Add to relevant docs (CONFIG.md, ARCHITECTURE.md)
+- Show exact code changes needed
+- Include before/after examples
+- Reference specific functions
+
+### 9. Version History
+- Link to JOURNAL.md entries
+- Format: `v1.0.0 - Feature (see JOURNAL.md YYYY-MM-DD)`
+- Track major changes only
+
+### 10. Cross-Linking
+- Link between related sections
+- Use relative paths: `[Link](./FILE.md#section)`
+- Ensure bidirectional linking where appropriate
+
+## Journal System Setup
+
+### JOURNAL.md Structure
+\```
+# Engineering Journal
+
+## YYYY-MM-DD HH:MM
+
+### [Descriptive Title]
+- **What**: Brief description of the change
+- **Why**: Reason for the change
+- **How**: Technical approach taken
+- **Issues**: Any problems encountered
+- **Result**: Outcome and any metrics
+
+---
+
+[Entries continue chronologically]
+\```
+
+### Journal Best Practices
+1. **Entry Timing**: Add entry immediately after significant work
+2. **Detail Level**: Include enough detail to understand the change months later
+3. **Problem Documentation**: Especially document multi-attempt solutions
+4. **Learning Moments**: Capture new techniques discovered
+5. **Metrics**: Include performance improvements, time saved, etc.
+
+### Archive Process
+When JOURNAL.md exceeds 500 lines:
+1. Create `JOURNAL_ARCHIVE/` directory
+2. Move oldest 250 lines to `JOURNAL_ARCHIVE/YYYY-MM.md`
+3. Add summary header to archive file
+4. Keep recent entries in main JOURNAL.md
+
+## Implementation Steps
+
+### Phase 1: Initial Setup (30-60 minutes)
+1. **Create CLAUDE.md** with all required sections
+2. **Fill Critical Context** with 6 essential facts
+3. **Create Table of Contents** with placeholder links
+4. **Add Quick Reference** with top 10-15 code locations
+5. **Set up Journal section** with formatting rules
+
+### Phase 2: Core Documentation (2-4 hours)
+1. **Create each .md file** from the list above
+2. **Add Keywords section** to each file
+3. **Cross-link between files** where relevant
+4. **Add line numbers** to code references
+5. **Create PLAYBOOKS/ directory** with DEPLOY.md
+6. **Create ERRORS.md** with schema table
+
+### Phase 3: Optimization (1-2 hours)
+1. **Add Task Templates** to CLAUDE.md
+2. **Create ASCII system flow** in ARCHITECTURE.md
+3. **Add Common Patterns** sections
+4. **Document Anti-Patterns**
+5. **Set up Version History**
+
+### Phase 4: First Journal Entry
+Create initial JOURNAL.md entry documenting the setup:
+\```
+## YYYY-MM-DD HH:MM
+
+### Documentation Framework Implementation
+- **What**: Implemented CLAUDE.md modular documentation system
+- **Why**: Improve AI navigation and code maintainability
+- **How**: Split monolithic docs into focused modules with cross-linking
+- **Issues**: None - clean implementation
+- **Result**: [Number] documentation files created with full cross-referencing
+\```
+
+## Maintenance Guidelines
+
+### Daily
+- Update JOURNAL.md with significant changes
+- Mark completed items in Current State
+- Update line numbers if major refactoring
+
+### Weekly
+- Review and update Quick Reference section
+- Check for broken cross-links
+- Update Task Templates if workflows change
+
+### Monthly
+- Review Keywords sections for completeness
+- Update Version History
+- Check if JOURNAL.md needs archiving
+
+### Per Release
+- Update Version History in CLAUDE.md
+- Create comprehensive JOURNAL.md entry
+- Review all documentation for accuracy
+- Update Current State checklist
+
+## Benefits of This System
+
+1. **AI Efficiency**: Claude can quickly navigate to exact code locations
+2. **Modularity**: Easy to update specific documentation without affecting others
+3. **Discoverability**: New developers/AI can quickly understand the project
+4. **History Tracking**: Complete record of changes and decisions
+5. **Task Automation**: Templates reduce repetitive instructions
+6. **Error Prevention**: Anti-patterns prevent common mistakes

Dockerfile

@@ -0,0 +1,34 @@
+# Use python:3.11-slim as a base
+FROM python:3.11-slim
+
+# Set environment variables
+# UV_SYSTEM_PYTHON=1 allows uv to install into the system site-packages
+ENV PYTHONDONTWRITEBYTECODE=1 
+    PYTHONUNBUFFERED=1 
+    UV_SYSTEM_PYTHON=1
+
+# Install system dependencies and uv
+RUN apt-get update && apt-get install -y --no-install-recommends 
+    curl 
+    ca-certificates 
+    && rm -rf /var/lib/apt/lists/* 
+    && curl -LsSf https://astral.sh/uv/install.sh | sh 
+    && mv /root/.local/bin/uv /usr/local/bin/uv
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy dependency files first to leverage Docker layer caching
+COPY pyproject.toml requirements.txt* ./
+
+# Install dependencies via uv
+RUN if [ -f requirements.txt ]; then uv pip install --no-cache -r requirements.txt; fi
+
+# Copy the rest of the application code
+COPY . .
+
+# Expose port 8000 for the headless API/service
+EXPOSE 8000
+
+# Set the entrypoint to run the app in headless mode
+ENTRYPOINT ["python", "gui_2.py", "--headless"]

JOURNAL.md

@@ -0,0 +1,53 @@
+# Engineering Journal
+
+## 2026-02-28 14:43
+
+### Documentation Framework Implementation
+- **What**: Implemented Claude Conductor modular documentation system
+- **Why**: Improve AI navigation and code maintainability
+- **How**: Used `npx claude-conductor` to initialize framework
+- **Issues**: None - clean implementation
+- **Result**: Documentation framework successfully initialized
+
+---
+
+---
+
+## 2026-03-02
+
+### Track: context_token_viz_20260301 — Completed |TASK:context_token_viz_20260301|
+- **What**: Token budget visualization panel (all 3 phases)
+- **Why**: Zero visibility into context window usage; `get_history_bleed_stats` existed but had no UI
+- **How**: Extended `get_history_bleed_stats` with `_add_bleed_derived` helper (adds 8 derived fields); added `_render_token_budget_panel` with color-coded progress bar, breakdown table, trim warning, Gemini/Anthropic cache status; 3 auto-refresh triggers (`_token_stats_dirty` flag); `/api/gui/token_stats` endpoint; `--timeout` flag on `claude_mma_exec.py`
+- **Issues**: `set_file_slice` dropped `def _render_message_panel` line — caught by outline check, fixed with 1-line insert. Tier 3 delegation via `run_powershell` hard-capped at 60s — implemented changes directly per user approval; added `--timeout` flag for future use.
+- **Result**: 17 passing tests, all phases verified by user. Token panel visible in AI Settings under "Token Budget". Commits: 5bfb20f → d577457.
+
+### Next: mma_agent_focus_ux (planned, not yet tracked)
+- **What**: Per-agent filtering for MMA observability panels (comms, tool calls, discussion, token budget)
+- **Why**: All panels are global/session-scoped; in MMA mode with 4 tiers, data from all agents mixes. No way to isolate what a specific tier is doing.
+- **Gap**: `_comms_log` and `_tool_log` have no tier/agent tag. `mma_streams` stream_id is the only per-agent key that exists.
+- **See**: TASKS.md for full audit and implementation intent.
+
+---
+
+## 2026-03-02 (Session 2)
+
+### Tracks Initialized: feature_bleed_cleanup + mma_agent_focus_ux |TASK:feature_bleed_cleanup_20260302| |TASK:mma_agent_focus_ux_20260302|
+- **What**: Audited codebase for feature bleed; initialized 2 new conductor tracks
+- **Why**: Entropy from Tier 2 track implementations — redundant code, dead methods, layout regressions, no tier context in observability
+- **Bleed findings** (gui_2.py): Dead duplicate `_render_comms_history_panel` (3041-3073, stale `type` key, wrong method ref); dead `begin_main_menu_bar()` block (1680-1705, Quit has never worked); 4 duplicate `__init__` assignments; double "Token Budget" label with no collapsing header
+- **Agent focus findings** (ai_client.py + conductors): No `current_tier` var; Tier 3 swaps callback but never stamps tier; Tier 2 doesn't swap at all; `_tool_log` is untagged tuple list
+- **Result**: 2 tracks committed (4f11d1e, c1a86e2). Bleed cleanup is active; agent focus depends on it.
+
+- **More Tracks**: Initialized 'tech_debt_and_test_cleanup_20260302' and 'conductor_workflow_improvements_20260302' to harden TDD discipline, resolve test tech debt (false-positives, dupes), and mandate AST-based codebase auditing.
+- **Final Track**: Initialized 'architecture_boundary_hardening_20260302' to fix the GUI HITL bypass allowing direct AST mutations, patch token bloat in `mma_exec.py`, and implement cascading blockers in `dag_engine.py`.
+- **Testing Consolidation**: Initialized 'testing_consolidation_20260302' track to standardize simulation testing workflows around the pytest `live_gui` fixture and eliminate redundant `subprocess.Popen` wrappers.
+- **Dependency Order**: Added an explicit 'Track Dependency Order' execution guide to `TASKS.md` to ensure safe progression through the accumulated tech debt.
+- **Documentation**: Added guide_meta_boundary.md to explicitly clarify the difference between the Application's strict-HITL environment and the autonomous Meta-Tooling environment, helping future Tiers avoid feature bleed.
+- **Heuristics & Backlog**: Added Data-Oriented Design and Immediate Mode architectural heuristics (inspired by Muratori/Acton) to product-guidelines.md. Logged future decoupling and robust parsing tracks to a 'Future Backlog' in TASKS.md.
+---
+
+
+
+
+

MMA_Support/Architecture_Recommendation.md

@@ -0,0 +1,45 @@
+# MMA Hierarchical Delegation: Recommended Architecture
+
+## 1. Overview
+The Multi-Model Architecture (MMA) utilizes a 4-Tier hierarchy to ensure token efficiency and structural integrity. The primary agent (Conductor) acts as the Tier 2 Tech Lead, delegating specific, stateless tasks to Tier 3 (Workers) and Tier 4 (Utility) agents.
+
+## 2. Agent Roles & Responsibilities
+
+### Tier 2: The Conductor (Tech Lead)
+- **Role:** Orchestrator of the project lifecycle via the Conductor framework.
+- **Context:** High-reasoning, long-term memory of project goals and specifications.
+- **Key Tool:** `mma-orchestrator` skill (Strategy).
+- **Delegation Logic:** Identifies tasks that would bloat the primary context (large code blocks, massive error traces) and spawns sub-agents.
+
+### Tier 3: The Worker (Contributor)
+- **Role:** Stateless code generator.
+- **Context:** Isolated. Sees only the target file and the specific ticket.
+- **Protocol:** Receives a "Worker" system prompt. Outputs clean code or diffs.
+- **Invocation:** `.\scripts\run_subagent.ps1 -Role Worker -Prompt "..."`
+
+### Tier 4: The Utility (QA/Compressor)
+- **Role:** Stateless translator and summarizer.
+- **Context:** Minimal. Sees only the error trace or snippet.
+- **Protocol:** Receives a "QA" system prompt. Outputs compressed findings (max 50 tokens).
+- **Invocation:** `.\scripts\run_subagent.ps1 -Role QA -Prompt "..."`
+
+## 3. Invocation Protocol
+
+### Step 1: Detection
+Tier 2 detects a delegation trigger:
+- Coding task > 50 lines.
+- Error trace > 100 lines.
+
+### Step 2: Spawning
+Tier 2 calls the delegation script:
+```powershell
+.\scripts\run_subagent.ps1 -Role <Worker|QA> -Prompt "Specific instructions..."
+```
+
+### Step 3: Integration
+Tier 2 receives the sub-agent's response.
+- **If Worker:** Tier 2 applies the code changes (using `replace` or `write_file`) and verifies.
+- **If QA:** Tier 2 uses the compressed error to inform the next fix attempt or passes it to a Worker.
+
+## 4. System Prompt Management
+The `run_subagent.ps1` script should be updated to maintain a library of role-specific system prompts, ensuring that Tier 3/4 agents remain focused and tool-free (to prevent nested complexity).

MMA_Support/Final_Analysis_Report.md

@@ -0,0 +1,30 @@
+# MMA Tiered Architecture: Final Analysis Report
+
+## 1. Executive Summary
+The implementation and verification of the 4-Tier Hierarchical Multi-Model Architecture (MMA) within the Conductor framework have been successfully completed. The architecture provides a robust "Token Firewall" that prevents the primary context from being bloated by repetitive coding tasks and massive error traces.
+
+## 2. Architectural Findings
+
+### Centralized Strategy vs. Role-Based Sub-Agents
+- **Decision:** A Hybrid Approach was implemented.
+- **Rationale:** The Tier 2 Orchestrator (Conductor) maintains the high-level strategy via a centralized skill, while Tier 3 (Worker) and Tier 4 (QA) agents are governed by surgical, role-specific system prompts. This ensures that sub-agents remain focused and stateless without the overhead of complex, nested tool-usage logic.
+
+### Delegation Efficacy
+- **Tier 3 (Worker):** Successfully isolated code generation from the main conversation. The worker generates clean code/diffs that are then integrated by the Orchestrator.
+- **Tier 4 (QA):** Demonstrated superior token efficiency by compressing multi-hundred-line stack traces into ~20-word actionable fixes.
+- **Traceability:** The `-ShowContext` flag in `scripts/run_subagent.ps1` provides immediate visibility into the "Connective Tissue" of the hierarchy, allowing human supervisors to monitor the hand-offs.
+
+## 3. Recommended Protocol (Final)
+
+1. **Identification:** Tier 2 identifies a "Bloat Trigger" (Coding > 50 lines, Errors > 100 lines).
+2. **Delegation:** Tier 2 spawns a sub-agent via `.\scripts
+un_subagent.ps1 -Role [Worker|QA] -Prompt "..."`.
+3. **Integration:** Tier 2 receives the stateless response and applies it to the project state.
+4. **Checkpointing:** Tier 2 performs Phase-level checkpoints to "Wipe" trial-and-error memory and solidify the new state.
+
+## 4. Verification Results
+- **Automated Tests:** 100% Pass (4/4 tests in `tests/conductor/test_infrastructure.py`).
+- **Isolation:** Confirmed via `test_subagent_isolation_live`.
+- **Live Trace:** Manually verified and approved by the user (Tier 2 -> 3 -> 4 flow).
+
+## 5. Conclusion

MMA_Support/mma_tiered_orchestrator_skill.md

@@ -0,0 +1,66 @@
+# Skill: MMA Tiered Orchestrator
+
+## Description
+This skill enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) directly within the Gemini CLI using Token Firewalling and sub-agent task delegation. It teaches the CLI how to act as a Tier 1/2 Orchestrator, dispatching stateless tasks to cheaper models using shell commands, thereby preventing massive error traces or heavy coding contexts from polluting the primary prompt context.
+
+<instructions>
+# MMA Token Firewall & Tiered Delegation Protocol
+
+You are operating as a Tier 1 Product Manager or Tier 2 Tech Lead within the MMA Framework. Your context window is extremely valuable and must be protected from token bloat (such as raw, repetitive code edits, trial-and-error histories, or massive stack traces).
+
+To accomplish this, you MUST delegate token-heavy or stateless tasks to "Tier 3 Contributors" or "Tier 4 QA Agents" by spawning secondary Gemini CLI instances via `run_shell_command`.
+
+**CRITICAL Prerequisite:**
+To avoid hanging the CLI and ensure proper environment authentication, you MUST NOT call the `gemini` command directly. Instead, you MUST use the wrapper script:
+`.\scripts\run_subagent.ps1 -Prompt "..."`
+
+## 1. The Tier 3 Worker (Heads-Down Coding)
+When you need to perform a significant code modification (e.g., refactoring a 500-line script, writing a massive class, or implementing a predefined spec):
+1. **DO NOT** attempt to write or use `replace`/`write_file` yourself. Your history will bloat.
+2. **DO** construct a single, highly specific prompt.
+3. **DO** spawn a sub-agent using `run_shell_command` pointing to the target file.
+   *Command:* `.\scripts\run_subagent.ps1 -Prompt "Modify [FILE_PATH] to implement [SPECIFIC_INSTRUCTION]. Only write the code, no pleasantries."`
+4. If you need the sub-agent to automatically apply changes instead of just returning the text, use `gemini run` or pipe the output appropriately. However, the best method is to let the sub-agent modify the code and return "Done."
+
+## 2. The Tier 4 QA Agent (Error Translation)
+If you run a local test (e.g., `npm test`, `pytest`, `go run`) via `run_shell_command` and it fails with a massive traceback (e.g., 200+ lines of `stderr`):
+1. **DO NOT** analyze the raw `stderr` in your own context window.
+2. **DO** immediately spawn a stateless Tier 4 agent to compress the error.
+3. *Command:* `.\scripts\run_subagent.ps1 -Prompt "Summarize this stack trace into a 20-word fix: [PASTE_SNIPPET_OF_STDERR_HERE]"`
+4. Use the 20-word fix returned by the Tier 4 agent to inform your next architectural decision or pass it to the Tier 3 worker.
+
+## 3. Context Amnesia (Phase Checkpoints)
+When you complete a major Phase or Track within the `conductor` workflow:
+1. Stage your changes and commit them.
+2. Draft a comprehensive summary of the state changes in a Git Note attached to the commit.
+3. Treat the checkpoint as a "Memory Wipe." Actively disregard previous conversational turns and trial-and-error histories. Rely exclusively on the newly generated Git Note and the physical state of the files on disk for your next Phase.
+</instructions>
+
+<examples>
+### Example 1: Spawning a Tier 4 QA Agent
+**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output.
+**Agent (You):** 
+```json
+{
+  "command": ".\\scripts\\run_subagent.ps1 -Prompt \"Summarize this stack trace into a 20-word fix: [snip first 30 lines...]\"",
+  "description": "Spawning Tier 4 QA to compress error trace statelessly."
+}
+```
+
+### Example 2: Spawning a Tier 3 Worker
+**User:** Please implement the `ASTParser` class in `file_cache.py` as defined in Track 1.
+**Agent (You):**
+```json
+{
+  "command": ".\\scripts\\run_subagent.ps1 -Prompt \"Read file_cache.py and implement the ASTParser class using tree-sitter. Ensure you preserve docstrings but strip function bodies. Output the updated code or edit the file directly.\"",
+  "description": "Delegating implementation to a Tier 3 Worker."
+}
+```
+</examples>
+
+<triggers>
+- When asked to write large amounts of boilerplate or repetitive code.
+- When encountering a large error trace from a shell execution.
+- When explicitly instructed to act as a "Tech Lead" or "Orchestrator".
+- When managing complex, multi-file Track implementations.
+</triggers>

MMA_UX_SPEC.md

@@ -0,0 +1,36 @@
+# MMA Observability & UX Specification
+
+## 1. Goal
+Implement the visible surface area of the 4-Tier Hierarchical Multi-Model Architecture within `gui_2.py`. This ensures the user can monitor, control, and debug the multi-agent execution flow.
+
+## 2. Core Components
+
+### 2.1 MMA Dashboard Panel
+- **Visibility:** A new dockable panel named "MMA Dashboard".
+- **Track Status:** Display the current active `Track` ID and overall progress (e.g., "3/10 Tickets Complete").
+- **Ticket DAG Visualization:** A list or simple graph representing the `Ticket` queue.
+    - Each ticket shows: `ID`, `Target`, `Status` (Pending, Running, Paused, Complete, Blocked).
+    - Visual indicators for dependencies (e.g., indented or linked).
+
+### 2.2 The Execution Clutch (HITL)
+- **Step Mode Toggle:** A global or per-track checkbox to enable "Step Mode".
+- **Pause Points:**
+    - **Pre-Execution:** When a Tier 3 worker generates a tool call (e.g., `write_file`), the engine pauses.
+    - **UI Interaction:** The GUI displays the proposed script/change and provides:
+        - `[Approve]`: Proceed with execution.
+        - `[Edit Payload]`: Open the Memory Mutator.
+        - `[Abort]`: Mark the ticket as Blocked/Cancelled.
+- **Visual Feedback:** Tactile/Arcade-style blinking or color changes when the engine is "Paused for HITL".
+
+### 2.3 Memory Mutator (The "Debug" Superpower)
+- **Functionality:** A modal or dedicated text area that allows the user to edit the raw JSON conversation history of a paused worker.
+- **Use Case:** Fixing AI hallucinations or providing specific guidance mid-turn without restarting the context window.
+- **Integration:** After editing, the "Approve" button sends the *modified* history back to the engine.
+
+### 2.4 Tiered Metrics & Logs
+- **Observability:** Show which model (Tier 1, 2, 3, or 4) is currently active.
+- **Sub-Agent Logs:** Provide quick links to open the timestamped log files generated by `mma_exec.py`.
+
+## 3. Technical Integration
+- **Event Bus:** Use the existing `AsyncEventQueue` to push `StateUpdateEvents` from the `ConductorEngine` to the GUI.
+- **Non-Blocking:** Ensure the UI remains responsive (FPS > 60) even when multiple tickets are processing or the engine is waiting for user input.

MainContext.md

@@ -1,283 +0,0 @@
-# Manual Slop
-
-## Summary
-
-Is a local GUI tool for manually curating and sending context to AI APIs. It aggregates files, screenshots, and discussion history into a structured markdown file and sends it to a chosen AI provider with a user-written message. The AI can also execute PowerShell scripts within the project directory, with user confirmation required before each execution.
-
-**Stack:**
-- `dearpygui` - GUI with docking/floating/resizable panels
-- `google-genai` - Gemini API
-- `anthropic` - Anthropic API
-- `tomli-w` - TOML writing
-- `uv` - package/env management
-
-**Files:**
-- `gui_legacy.py` - main GUI, `App` class, all panels, all callbacks, confirmation dialog, layout persistence, rich comms rendering; `[+ Maximize]` buttons in `ConfirmDialog` and `win_script_output` now pass text directly as `user_data` / read from `self._last_script` / `self._last_output` instance vars instead of `dpg.get_value(tag)` — fixes glitch when word-wrap is ON or dialog is dismissed before viewer opens
-- `ai_client.py` - unified provider wrapper, model listing, session management, send, tool/function-call loop, comms log, provider error classification, token estimation, and aggressive history truncation
-- `aggregate.py` - reads config, collects files/screenshots/discussion, builds `file_items` with `mtime` for cache optimization, writes numbered `.md` files to `output_dir` using `build_markdown_from_items` to avoid double I/O; `run()` returns `(markdown_str, path, file_items)` tuple; `summary_only=False` by default (full file contents sent, not heuristic summaries)
-- `shell_runner.py` - subprocess wrapper that runs PowerShell scripts sandboxed to `base_dir`, returns stdout/stderr/exit code as a string
-- `session_logger.py` - opens timestamped log files at session start; writes comms entries as JSON-L and tool calls as markdown; saves each AI-generated script as a `.ps1` file
-- `project_manager.py` - per-project .toml load/save, entry serialisation (entry_to_str/str_to_entry with @timestamp support), default_project/default_discussion factories, migrate_from_legacy_config, flat_config for aggregate.run(), git helpers (get_git_commit, get_git_log)
-- `theme.py` - palette definitions, font loading, scale, load_from_config/save_to_config
-- `gemini.py` - legacy standalone Gemini wrapper (not used by the main GUI; superseded by `ai_client.py`)
-- `file_cache.py` - stub; Anthropic Files API path removed; kept so stale imports don't break
-- `mcp_client.py` - MCP-style tools (read_file, list_directory, search_files, get_file_summary, web_search, fetch_url); allowlist enforced against project file_items + base_dirs for file tools; web tools are unrestricted; dispatched by ai_client tool-use loop for both Anthropic and Gemini
-- `summarize.py` - local heuristic summariser (no AI); .py via AST, .toml via regex, .md headings, generic preview; used by mcp_client.get_file_summary and aggregate.build_summary_section
-- `config.toml` - global-only settings: [ai] provider+model+system_prompt, [theme] palette+font+scale, [projects] paths array + active path
-- `manual_slop.toml` - per-project file: [project] name+git_dir+system_prompt+main_context, [output] namespace+output_dir, [files] base_dir+paths, [screenshots] base_dir+paths, [discussion] roles+active+[discussion.discussions.<name>] git_commit+last_updated+history
-- `credentials.toml` - gemini api_key, anthropic api_key
-- `dpg_layout.ini` - Dear PyGui window layout file (auto-saved on exit, auto-loaded on startup); gitignore this per-user
-
-**GUI Panels:**
-- **Projects** - active project name display (green), git directory input + Browse button, scrollable list of loaded project paths (click name to switch, x to remove), Add Project / New Project / Save All buttons
-- **Config** - namespace, output dir, save (these are project-level fields from the active .toml)
-- **Files** - base_dir, scrollable path list with remove, add file(s), add wildcard
-- **Screenshots** - base_dir, scrollable path list with remove, add screenshot(s)
-- **Discussion History** - discussion selector (collapsible header): listbox of named discussions, git commit + last_updated display, Update Commit button, Create/Rename/Delete buttons with name input; structured entry editor: each entry has collapse toggle (-/+), role combo, timestamp display, multiline content field; per-entry Ins/Del buttons when collapsed; global toolbar: + Entry, -All, +All, Clear All, Save; collapsible **Roles** sub-section; -> History buttons on Message and Response panels append current message/response as new entry with timestamp
-- **Provider** - provider combo (gemini/anthropic), model listbox populated from API, fetch models button
-- **Message** - multiline input, Gen+Send button, MD Only button, Reset session button, -> History button
-- **Response** - readonly multiline displaying last AI response, -> History button
-- **Tool Calls** - scrollable log of every PowerShell tool call the AI made; Clear button
-- **System Prompts** - global (all projects) and project-specific multiline text areas for injecting custom system instructions. Combined with the built-in tool prompt.
-- **Comms History** - rich structured live log of every API interaction; status line at top; colour legend; Clear button
-
-**Layout persistence:**
-- `dpg.configure_app(..., init_file="dpg_layout.ini")` loads the ini at startup if it exists; DPG silently ignores a missing file
-- `dpg.save_init_file("dpg_layout.ini")` is called immediately before `dpg.destroy_context()` on clean exit
-- The ini records window positions, sizes, and dock node assignments in DPG's native format
-- First run (no ini) uses the hardcoded `pos=` defaults in `_build_ui()`; after that the ini takes over
-- Delete `dpg_layout.ini` to reset to defaults
-
-**Project management:**
-- `config.toml` is global-only: `[ai]`, `[theme]`, `[projects]` (paths list + active path). No project data lives here.
-- Each project has its own `.toml` file (e.g. `manual_slop.toml`). Multiple project tomls can be registered by path.
-- `App.__init__` loads global config, then loads the active project `.toml` via `project_manager.load_project()`. Falls back to `migrate_from_legacy_config()` if no valid project file exists, creating a new `.toml` automatically.
-- `_flush_to_project()` pulls widget values into `self.project` (the per-project dict) and serialises disc_entries into the active discussion's history list
-- `_flush_to_config()` writes global settings ([ai], [theme], [projects]) into `self.config`
-- `_save_active_project()` writes `self.project` to the active `.toml` path via `project_manager.save_project()`
-- `_do_generate()` calls both flush methods, saves both files, then uses `project_manager.flat_config()` to produce the dict that `aggregate.run()` expects — so `aggregate.py` needs zero changes
-- Switching projects: saves current project, loads new one, refreshes all GUI state, resets AI session
-- New project: file dialog for save path, creates default project structure, saves it, switches to it
-
-**Discussion management (per-project):**
-- Each project `.toml` stores one or more named discussions under `[discussion.discussions.<name>]`
-- Each discussion has: `git_commit` (str), `last_updated` (ISO timestamp), `history` (list of serialised entry strings)
-- `active` key in `[discussion]` tracks which discussion is currently selected
-- Creating a discussion: adds a new empty discussion dict via `default_discussion()`, switches to it
-- Renaming: moves the dict to a new key, updates `active` if it was the current one
-- Deleting: removes the dict; cannot delete the last discussion; switches to first remaining if active was deleted
-- Switching: flushes current entries to project, loads new discussion's history, rebuilds disc list
-- Update Commit button: runs `git rev-parse HEAD` in the project's `git_dir` and stores result + timestamp in the active discussion
-- Timestamps: each disc entry carries a `ts` field (ISO datetime); shown next to the role combo; new entries from `-> History` or `+ Entry` get `now_ts()`
-
-**Entry serialisation (project_manager):**
-- `entry_to_str(entry)` → `"@<ts>\n<role>:\n<content>"` (or `"<role>:\n<content>"` if no ts)
-- `str_to_entry(raw, roles)` → parses optional `@<ts>` prefix, then role line, then content; returns `{role, content, collapsed, ts}`
-- Round-trips correctly through TOML string arrays; handles legacy entries without timestamps
-
-**AI Tool Use (PowerShell):**
-- Both Gemini and Anthropic are configured with a `run_powershell` tool/function declaration
-- When the AI wants to edit or create files it emits a tool call with a `script` string
-- `ai_client` runs a loop (max `MAX_TOOL_ROUNDS = 10`) feeding tool results back until the AI stops calling tools
-- Before any script runs, `gui_legacy.py` shows a modal `ConfirmDialog` on the main thread; the background send thread blocks on a `threading.Event` until the user clicks Approve or Reject
-- The dialog displays `base_dir`, shows the script in an editable text box (allowing last-second tweaks), and has Approve & Run / Reject buttons
-- On approval the (possibly edited) script is passed to `shell_runner.run_powershell()` which prepends `Set-Location -LiteralPath '<base_dir>'` and runs it via `powershell -NoProfile -NonInteractive -Command`
-- stdout, stderr, and exit code are returned to the AI as the tool result
-- Rejections return `"USER REJECTED: command was not executed"` to the AI
-- All tool calls (script + result/rejection) are appended to `_tool_log` and displayed in the Tool Calls panel
-
-**Dynamic file context refresh (ai_client.py):**
-- After the last tool call in each round, project files from `file_items` are checked via `_reread_file_items()`. It uses `mtime` to only re-read modified files, returning only the `changed` files to build a minimal `[FILES UPDATED]` block.
-- For Anthropic: the refreshed file contents are injected as a `text` block appended to the `tool_results` user message, prefixed with `[FILES UPDATED]` and an instruction not to re-read them.
-- For Gemini: refreshed file contents are appended to the last function response's `output` string as a `[SYSTEM: FILES UPDATED]` block. On the next tool round, stale `[FILES UPDATED]` blocks are stripped from history and old tool outputs are truncated to `_history_trunc_limit` characters to control token growth.
-- `_build_file_context_text(file_items)` formats the refreshed files as markdown code blocks (same format as the original context)
-- The `tool_result_send` comms log entry filters out the injected text block (only logs actual `tool_result` entries) to keep the comms panel clean
-- `file_items` flows from `aggregate.build_file_items()` → `gui.py` `self.last_file_items` → `ai_client.send(file_items=...)` → `_send_anthropic(file_items=...)` / `_send_gemini(file_items=...)`
-- System prompt updated to tell the AI: "the user's context files are automatically refreshed after every tool call, so you do NOT need to re-read files that are already provided in the <context> block"
-
-**Anthropic bug fixes applied (session history):**
-- Bug 1: SDK ContentBlock objects now converted to plain dicts via `_content_block_to_dict()` before storing in `_anthropic_history`; prevents re-serialisation failures on subsequent tool-use rounds
-- Bug 2: `_repair_anthropic_history` simplified to dict-only path since history always contains dicts
-- Bug 3: Gemini part.function_call access now guarded with `hasattr` check
-- Bug 4: Anthropic `b.type == "tool_use"` changed to `getattr(b, "type", None) == "tool_use"` for safe access during response processing
-
-**Comms Log (ai_client.py):**
-- `_comms_log: list[dict]` accumulates every API interaction during a session
-- `_append_comms(direction, kind, payload)` called at each boundary: OUT/request before sending, IN/response after each model reply, OUT/tool_call before executing, IN/tool_result after executing, OUT/tool_result_send when returning results to the model
-- Entry fields: `ts` (HH:MM:SS), `direction` (OUT/IN), `kind`, `provider`, `model`, `payload` (dict)
-- Anthropic responses also include `usage` (input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens) and `stop_reason` in payload
-- `get_comms_log()` returns a snapshot; `clear_comms_log()` empties it
-- `comms_log_callback` (injected by gui_legacy.py) is called from the background thread with each new entry; gui queues entries in `_pending_comms` (lock-protected) and flushes them to the DPG panel each render frame
-- `COMMS_CLAMP_CHARS = 300` in gui_legacy.py governs the display cutoff for heavy text fields
-
-**Comms History panel — rich structured rendering (gui_legacy.py):**
-
-Rather than showing raw JSON, each comms entry is rendered using a kind-specific renderer function. Unknown kinds fall back to a generic key/value layout.
-
-Colour maps:
-- Direction: OUT = blue-ish `(100,200,255)`, IN = green-ish `(140,255,160)`
-- Kind: request=gold, response=light-green, tool_call=orange, tool_result=light-blue, tool_result_send=lavender
-- Labels: grey `(180,180,180)`; values: near-white `(220,220,220)`; dict keys/indices: `(140,200,255)`; numbers/token counts: `(180,255,180)`; sub-headers: `(220,200,120)`
-
-Helper functions:
-- `_add_text_field(parent, label, value)` — labelled text; strings longer than `COMMS_CLAMP_CHARS` render as an 80px readonly scrollable `input_text`; shorter strings render as `add_text`
-- `_add_kv_row(parent, key, val)` — single horizontal key: value row
-- `_render_usage(parent, usage)` — renders Anthropic token usage dict in a fixed display order (input → cache_read → cache_creation → output)
-- `_render_tool_calls_list(parent, tool_calls)` — iterates tool call list, showing name, id, and all args via `_add_text_field`
-
-Kind-specific renderers (in `_KIND_RENDERERS` dict, dispatched by `_render_comms_entry`):
-- `_render_payload_request` — shows `message` field via `_add_text_field`
-- `_render_payload_response` — shows round, stop_reason (orange), text, tool_calls list, usage block
-- `_render_payload_tool_call` — shows name, optional id, script via `_add_text_field`
-- `_render_payload_tool_result` — shows name, optional id, output via `_add_text_field`
-- `_render_payload_tool_result_send` — iterates results list, shows tool_use_id and content per result
-- `_render_payload_generic` — fallback for unknown kinds; renders all keys, using `_add_text_field` for keys in `_HEAVY_KEYS`, `_add_kv_row` for others; dicts/lists are JSON-serialised
-
-Entry layout: index + timestamp + direction + kind + provider/model header row, then payload rendered by the appropriate function, then a separator line.
-
-**Session Logger (session_logger.py):**
-- `open_session()` called once at GUI startup; creates `logs/` and `scripts/generated/` directories; opens `logs/comms_<ts>.log` and `logs/toolcalls_<ts>.log` (line-buffered)
-- `log_comms(entry)` appends each comms entry as a JSON-L line to the comms log; called from `App._on_comms_entry` (background thread); thread-safe via GIL + line buffering
-- `log_tool_call(script, result, script_path)` writes the script to `scripts/generated/<ts>_<seq:04d>.ps1` and appends a markdown record to the toolcalls log without the script body (just the file path + result); uses a `threading.Lock` for the sequence counter
-- `close_session()` flushes and closes both file handles; called just before `dpg.destroy_context()`
-
-**Anthropic prompt caching & history management:**
-- System prompt + context are combined into one string, chunked into <=120k char blocks, and sent as the `system=` parameter array. Only the LAST chunk gets `cache_control: ephemeral`, so the entire system prefix is cached as one unit.
-- Last tool in `_ANTHROPIC_TOOLS` (`run_powershell`) has `cache_control: ephemeral`; this means the tools prefix is cached together with the system prefix after the first request.
-- The user message is sent as a plain `[{"type": "text", "text": user_message}]` block with NO cache_control. The context lives in `system=`, not in the first user message.
-- `_add_history_cache_breakpoint` places `cache_control:ephemeral` on the last content block of the second-to-last user message, using the 4th cache breakpoint to cache the conversation history prefix.
-- `_trim_anthropic_history` uses token estimation (`_CHARS_PER_TOKEN = 3.5`) to keep the prompt under `_ANTHROPIC_MAX_PROMPT_TOKENS = 180_000`. It strips stale file refreshes from old turns, and drops oldest turn pairs if still over budget.
-- The tools list is built once per session via `_get_anthropic_tools()` and reused across all API calls within the tool loop, avoiding redundant Python-side reconstruction.
-- `_strip_cache_controls()` removes stale `cache_control` markers from all history entries before each API call, ensuring only the stable system/tools prefix consumes cache breakpoint slots.
-- Cache stats (creation tokens, read tokens) are surfaced in the comms log usage dict and displayed in the Comms History panel
-
-**Data flow:**
-1. GUI edits are held in `App` state (`self.files`, `self.screenshots`, `self.disc_entries`, `self.project`) and dpg widget values
-2. `_flush_to_project()` pulls all widget values into `self.project` dict (per-project data)
-3. `_flush_to_config()` pulls global settings into `self.config` dict
-4. `_do_generate()` calls both flush methods, saves both files, calls `project_manager.flat_config(self.project, disc_name)` to produce a dict for `aggregate.run()`, which writes the md and returns `(markdown_str, path, file_items)`
-5. `cb_generate_send()` calls `_do_generate()` then threads a call to `ai_client.send(md, message, base_dir)`
-6. `ai_client.send()` prepends the md as a `<context>` block to the user message and sends via the active provider chat session
-7. If the AI responds with tool calls, the loop handles them (with GUI confirmation) before returning the final text response
-8. Sessions are stateful within a run (chat history maintained), `Reset` clears them, the tool log, and the comms log
-
-**Config persistence:**
-- `config.toml` — global only: `[ai]` provider+model, `[theme]` palette+font+scale, `[projects]` paths array + active path
-- `<project>.toml` — per-project: output, files, screenshots, discussion (roles, active discussion name, all named discussions with their history+metadata)
-- On every send and save, both files are written
-- On clean exit, `run()` calls `_flush_to_project()`, `_save_active_project()`, `_flush_to_config()`, `save_config()` before destroying context
-
-**Threading model:**
-- DPG render loop runs on the main thread
-- AI sends and model fetches run on daemon background threads
-- `_pending_dialog` (guarded by a `threading.Lock`) is set by the background thread and consumed by the render loop each frame, calling `dialog.show()` on the main thread
-- `dialog.wait()` blocks the background thread on a `threading.Event` until the user acts
-- `_pending_comms` (guarded by a separate `threading.Lock`) is populated by `_on_comms_entry` (background thread) and drained by `_flush_pending_comms()` each render frame (main thread)
-
-**Provider error handling:**
-- `ProviderError(kind, provider, original)` wraps upstream API exceptions with a classified `kind`: quota, rate_limit, auth, balance, network, unknown
-- `_classify_anthropic_error` and `_classify_gemini_error` inspect exception types and status codes/message bodies to assign the kind
-- `ui_message()` returns a human-readable label for display in the Response panel
-
-**MCP file tools (mcp_client.py + ai_client.py):**
-- Four read-only tools exposed to the AI as native function/tool declarations: `read_file`, `list_directory`, `search_files`, `get_file_summary`
-- Access control: `mcp_client.configure(file_items, extra_base_dirs)` is called before each send; builds an allowlist of resolved absolute paths from the project's `file_items` plus the `base_dir`; any path that is not explicitly in the list or not under one of the allowed directories returns `ACCESS DENIED`
-- `mcp_client.dispatch(tool_name, tool_input)` is the single dispatch entry point used by both Anthropic and Gemini tool-use loops; `TOOL_NAMES` set now includes all six tool names
-- Anthropic: MCP tools appear before `run_powershell` in the tools list (no `cache_control` on them; only `run_powershell` carries `cache_control: ephemeral`)
-- Gemini: MCP tools are included in the `FunctionDeclaration` list alongside `run_powershell`
-- `get_file_summary` uses `summarize.summarise_file()` — same heuristic used for the initial `<context>` block, so the AI gets the same compact structural view it already knows
-- `list_directory` sorts dirs before files; shows name, type, and size
-- `search_files` uses `Path.glob()` with the caller-supplied pattern (supports `**/*.py` style)
-- `read_file` returns raw UTF-8 text; errors (not found, access denied, decode error) are returned as error strings rather than exceptions, so the AI sees them as tool results
-- `web_search(query)` queries DuckDuckGo HTML endpoint and returns the top 5 results (title, URL, snippet) as a formatted string; uses a custom `_DDGParser` (HTMLParser subclass)
-- `fetch_url(url)` fetches a URL, strips HTML tags/scripts via `_TextExtractor` (HTMLParser subclass), collapses whitespace, and truncates to 40k chars to prevent context blowup; handles DuckDuckGo redirect links automatically
-- `summarize.py` heuristics: `.py` → AST imports + ALL_CAPS constants + classes+methods + top-level functions; `.toml` → table headers + top-level keys; `.md` → h1–h3 headings with indentation; all others → line count + first 8 lines preview
-- Comms log: MCP tool calls log `OUT/tool_call` with `{"name": ..., "args": {...}}` and `IN/tool_result` with `{"name": ..., "output": ...}`; rendered in the Comms History panel via `_render_payload_tool_call` (shows each arg key/value) and `_render_payload_tool_result` (shows output)
-
-**Known extension points:**
-- Add more providers by adding a section to `credentials.toml`, a `_list_*` and `_send_*` function in `ai_client.py`, and the provider name to the `PROVIDERS` list in `gui_legacy.py`
-- Discussion history excerpts could be individually toggleable for inclusion in the generated md
-- `MAX_TOOL_ROUNDS` in `ai_client.py` caps agentic loops at 10 rounds; adjustable
-- `COMMS_CLAMP_CHARS` in gui_legacy.py controls the character threshold for clamping heavy payload fields in the Comms History panel
-- Additional project metadata (description, tags, created date) could be added to `[project]` in the per-project toml
-
-### Gemini Context Management
-- Gemini uses explicit caching via `client.caches.create()` to store the `system_instruction` + tools as an immutable cached prefix with a 1-hour TTL. The cache is created once per chat session.
-- Proactively rebuilds cache at 90% of `_GEMINI_CACHE_TTL = 3600` to avoid stale-reference errors.
-- When context changes (detected via `md_content` hash), the old cache is deleted, a new cache is created, and chat history is migrated to a fresh chat session pointing at the new cache.
-- Trims history by dropping oldest pairs if input tokens exceed `_GEMINI_MAX_INPUT_TOKENS = 900_000`.
-- If cache creation fails (e.g., content is under the minimum token threshold — 1024 for Flash, 4096 for Pro), the system falls back to inline `system_instruction` in the chat config. Implicit caching may still provide cost savings in this case.
-- The `<context>` block lives inside `system_instruction`, NOT in user messages, preventing history bloat across turns.
-- On cleanup/exit, active caches are deleted via `ai_client.cleanup()` to prevent orphaned billing.
-
-### Latest Changes
-- Removed `Config` panel from the GUI to streamline per-project configuration.
-- `output_dir` was moved into the Projects panel.
-- `auto_add_history` was moved to the Discussion History panel.
-- `namespace` is no longer a configurable field; `aggregate.py` automatically uses the active project's `name` property.
-
-### UI / Visual Updates
-- The success blink notification on the response text box is now dimmer and more transparent to be less visually jarring.
-- Added a new floating **Last Script Output** popup window. This window automatically displays and blinks blue whenever the AI executes a PowerShell tool, showing both the executed script and its result in real-time.
-
-
-## Recent Changes (Text Viewer Maximization)
-- **Global Text Viewer (gui_legacy.py)**: Added a dedicated, large popup window (win_text_viewer) to allow reading and scrolling through large, dense text blocks without feeling cramped.
-- **Comms History**: Every multi-line text field in the comms log now has a [+] button next to its label that opens the text in the Global Text Viewer.
-- **Tool Log History**: Added [+ Script] and [+ Output] buttons next to each logged tool call to easily maximize and read the full executed scripts and raw tool outputs.
-- **Last Script Output Popup**: Expanded the default size of the popup (now 800x600) and gave the input script panel more vertical space to prevent it from feeling 'scrunched'. Added [+ Maximize] buttons for both the script and the output sections to inspect them in full detail.
-- **Confirm Dialog**: The script confirmation modal now has a [+ Maximize] button so you can read large generated scripts in full-screen before approving them.
-
-## UI Enhancements (2026-02-21)
-
-### Global Word-Wrap
-
-A new **Word-Wrap** checkbox has been added to the **Projects** panel. This setting is saved per-project in its .toml file.
-
-- When **enabled** (default), long text in read-only panels (like the main Response window, Tool Call outputs, and Comms History) will wrap to fit the panel width.
-- When **disabled**, text will not wrap, and a horizontal scrollbar will appear for oversized content.
-
-This allows you to choose the best viewing mode for either prose or wide code blocks.
-
-### Maximizable Discussion Entries
-
-Each entry in the **Discussion History** now features a [+ Max] button. Clicking this button opens the full text of that entry in the large **Text Viewer** popup, making it easy to read or copy large blocks of text from the conversation history without being constrained by the small input box.
-\n\n## Multi-Viewport & Docking\nThe application now supports Dear PyGui Viewport Docking. Windows can be dragged outside the main application area or docked together. A global 'Windows' menu in the viewport menu bar allows you to reopen any closed panels.
-
-## Extensive Documentation (2026-02-22)
-
-Documentation has been completely rewritten matching the strict, structural format of `VEFontCache-Odin`. 
-- `docs/guide_architecture.md`: Details the Python implementation algorithms, queue management for UI rendering, the specific AST heuristics used for context aggregation, and the distinct algorithms for trimming Anthropic history vs Gemini state caching.
-- `docs/Readme.md`: The core interface manual.
-- `docs/guide_tools.md`: Security architecture for `_is_allowed` paths and definitions of the read-only vs destructive tool pipeline.
-
-
-
-
-## Updates (2026-02-22 — ai_client.py & aggregate.py)
-
-### mcp_client.py — Web Tools Added
-- `web_search(query)` and `fetch_url(url)` added as two new MCP tools alongside the existing four file tools.
-- `TOOL_NAMES` set updated to include all six tool names for dispatch routing.
-- `MCP_TOOL_SPECS` list extended with full JSON schema definitions for both web tools.
-- Both tools are declared in `_build_anthropic_tools()` and `_gemini_tool_declaration()` so they are available to both providers.
-- Web tools bypass the `_is_allowed` path check (no filesystem access); file tools retain the allowlist enforcement.
-
-### aggregate.py — run() double-I/O elimination
-- `run()` now calls `build_file_items()` once, then passes the result to `build_markdown_from_items()` instead of calling `build_files_section()` separately. This avoids reading every file twice per send.
-- `build_markdown_from_items()` accepts a `summary_only` flag (default `False`); when `False` it inlines full file content; when `True` it delegates to `summarize.build_summary_markdown()` for compact structural summaries.
-- `run()` returns a 3-tuple `(markdown_str, output_path, file_items)` — the `file_items` list is passed through to `gui_legacy.py` as `self.last_file_items` for dynamic context refresh after tool calls.
-
-
-## Updates (2026-02-22 — gui_legacy.py [+ Maximize] bug fix)
-
-### Problem
-Three `[+ Maximize]` buttons were reading their text content via `dpg.get_value(tag)` at click time:
-1. `ConfirmDialog.show()` — passed `f"{self._tag}_script"` as `user_data` and called `dpg.get_value(u)` in the lambda. If the dialog was dismissed before the viewer opened, the item no longer existed and the call would fail silently or crash.
-2. `win_script_output` Script `[+ Maximize]` — used `user_data="last_script_text"` and `dpg.get_value(u)`. When word-wrap is ON, `last_script_text` is hidden (`show=False`); in some DPG versions `dpg.get_value` on a hidden `input_text` returns `""`.
-3. `win_script_output` Output `[+ Maximize]` — same issue with `"last_script_output"`.
-
-### Fix
-- `ConfirmDialog.show()`: changed `user_data` to `self._script` (the actual text string captured at button-creation time) and the callback to `lambda s, a, u: _show_text_viewer("Confirm Script", u)`. The text is now baked in at dialog construction, not read from a potentially-deleted widget.
-- `App._append_tool_log()`: added `self._last_script = script` and `self._last_output = result` assignments so the latest values are always available as instance state.
-- `win_script_output` buttons: both `[+ Maximize]` buttons now use `lambda s, a, u: _show_text_viewer("...", self._last_script/output)` directly, bypassing DPG widget state entirely.

Readme.md

@@ -1,45 +1,132 @@
-# Manual Slop
+# Sloppy
 
-Vibe coding.. but more manual
+![img](./gallery/splash.png)
 
-![img](./gallery/python_2026-02-21_23-37-29.png)
+A GUI orchestrator for local LLM-driven coding sessions. Manual Slop bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe asynchronous pipeline, ensuring every AI-generated payload passes through a human-auditable gate before execution.
 
-This tool is designed to work as an auxiliary assistant that natively interacts with your codebase via PowerShell and MCP-like file tools, supporting both Anthropic and Gemini APIs.
+**Tech Stack**: Python 3.11+, Dear PyGui / ImGui, FastAPI, Uvicorn
+**Providers**: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless)
+**Platform**: Windows (PowerShell) — single developer, local use
 
-Features:
+![img](./gallery/python_2026-03-01_23-45-34.png)
 
-* Multi-provider support (Anthropic & Gemini).
+---
-* Multi-project workspace management via TOML configuration.
+
-* Rich discussion history with branching and timestamps.
+## Architecture at a Glance
-* Real-time file context aggregation and summarization.
+
-* Integrated tool execution:
+Four thread domains operate concurrently: the ImGui main loop, an asyncio worker for AI calls, a `HookServer` (HTTP on `:8999`) for external automation, and transient threads for model fetching. Background threads never write GUI state directly — they serialize task dicts into lock-guarded lists that the main thread drains once per frame ([details](./docs/guide_architecture.md#the-task-pipeline-producer-consumer-synchronization)).
-  * PowerShell scripting for file modifications.
+
-  * MCP-like filesystem tools (read, list, search, summarize).
+The **Execution Clutch** suspends the AI execution thread on a `threading.Condition` when a destructive action (PowerShell script, sub-agent spawn) is requested. The GUI renders a modal where the user can read, edit, or reject the payload. On approval, the condition is signaled and execution resumes ([details](./docs/guide_architecture.md#the-execution-clutch-human-in-the-loop)).
-  * Web search and URL fetching.
+
-* Extensive UI features:
+The **MMA (Multi-Model Agent)** system decomposes epics into tracks, tracks into DAG-ordered tickets, and executes each ticket with a stateless Tier 3 worker that starts from `ai_client.reset_session()` — no conversational bleed between tickets ([details](./docs/guide_mma.md)).
-  * Word-wrap toggles.
+
-  * Popup text viewers for large script/output inspection.
+---
-  * Color theming and UI scaling.
 
 ## Documentation
 
-* [docs/Readme.md](docs/Readme.md) for the interface and usage guide
+| Guide | Scope |
-* [docs/guide_tools.md](docs/guide_tools.md) for information on the AI tooling capabilities
+|---|---|
-* [docs/guide_architecture.md](docs/guide_architecture.md) for an in-depth breakdown of the codebase architecture
+| [Architecture](./docs/guide_architecture.md) | Threading model, event system, AI client multi-provider architecture, HITL mechanism, comms logging |
+| [Tools & IPC](./docs/guide_tools.md) | MCP Bridge security model, all 26 native tools, Hook API endpoints, ApiHookClient reference, shell runner |
+| [MMA Orchestration](./docs/guide_mma.md) | 4-tier hierarchy, Ticket/Track data structures, DAG engine, ConductorEngine execution loop, worker lifecycle |
+| [Simulations](./docs/guide_simulations.md) | `live_gui` fixture, Puppeteer pattern, mock provider, visual verification patterns, ASTParser / summarizer |
 
-## Instructions
+---
 
-1. Make a credentials.toml in the immediate directory of your clone:
+## Module Map
+
+| File | Lines | Role |
+|---|---|---|
+| `gui_2.py` | ~3080 | Primary ImGui interface — App class, frame-sync, HITL dialogs |
+| `ai_client.py` | ~1800 | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI) |
+| `mcp_client.py` | ~870 | 26 MCP tools with filesystem sandboxing and tool dispatch |
+| `api_hooks.py` | ~330 | HookServer — REST API for external automation on `:8999` |
+| `api_hook_client.py` | ~245 | Python client for the Hook API (used by tests and external tooling) |
+| `multi_agent_conductor.py` | ~250 | ConductorEngine — Tier 2 orchestration loop with DAG execution |
+| `conductor_tech_lead.py` | ~100 | Tier 2 ticket generation from track briefs |
+| `dag_engine.py` | ~100 | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) |
+| `models.py` | ~100 | Ticket, Track, WorkerContext dataclasses |
+| `events.py` | ~89 | EventEmitter, AsyncEventQueue, UserRequestEvent |
+| `project_manager.py` | ~300 | TOML config persistence, discussion management, track state |
+| `session_logger.py` | ~200 | JSON-L + markdown audit trails (comms, tools, CLI, hooks) |
+| `shell_runner.py` | ~100 | PowerShell execution with timeout, env config, QA callback |
+| `file_cache.py` | ~150 | ASTParser (tree-sitter) — skeleton and curated views |
+| `summarize.py` | ~120 | Heuristic file summaries (imports, classes, functions) |
+| `outline_tool.py` | ~80 | Hierarchical code outline via stdlib `ast` |
+
+---
+
+## Setup
+
+### Prerequisites
+
+- Python 3.11+
+- [`uv`](https://github.com/astral-sh/uv) for package management
+
+### Installation
+
+```powershell
+git clone <repo>
+cd manual_slop
+uv sync
+```
+
+### Credentials
+
+Configure in `credentials.toml`:
 
 ```toml
 [gemini]
-api_key = "****"
+api_key = "YOUR_KEY"
+
 [anthropic]
-api_key = "****"
+api_key = "YOUR_KEY"
+
+[deepseek]
+api_key = "YOUR_KEY"
 ```
 
-2. Have fun. This is experiemntal slop.
+### Running
 
-```ps1
+```powershell
-uv run .\gui_2.py
+uv run gui_2.py                        # Normal mode
+uv run gui_2.py --enable-test-hooks    # With Hook API on :8999
+```
+
+### Running Tests
+
+```powershell
+uv run pytest tests/ -v
+```
+
+---
+
+## Project Configuration
+
+Projects are stored as `<name>.toml` files. The discussion history is split into a sibling `<name>_history.toml` to keep the main config lean.
+
+```toml
+[project]
+name = "my_project"
+git_dir = "./my_repo"
+system_prompt = ""
+
+[files]
+base_dir = "./my_repo"
+paths = ["src/**/*.py", "README.md"]
+
+[screenshots]
+base_dir = "./my_repo"
+paths = []
+
+[output]
+output_dir = "./md_gen"
+
+[gemini_cli]
+binary_path = "gemini"
+
+[agent.tools]
+run_powershell = true
+read_file = true
+# ... 26 tool flags
 ```

TASKS.md

@@ -0,0 +1,111 @@
+# TASKS.md
+<!-- Quick-read pointer to active and planned conductor tracks -->
+<!-- Source of truth for task state is conductor/tracks/*/plan.md -->
+
+## Active Tracks
+- `feature_bleed_cleanup_20260302` — Dead code & conflicting design state cleanup (Phase 1-3)
+
+## Completed This Session
+- `context_token_viz_20260301` — Token budget panel (color bar, breakdown table, trim warning, cache status, auto-refresh). All phases verified. Commit: d577457.
+
+## Planned: Next Track
+
+### `mma_agent_focus_ux_20260302` (initialized — run after bleed cleanup)
+**Priority:** High
+**Depends on:** `feature_bleed_cleanup_20260302` Phase 1 (dead comms panel removed)
+**Track dir:** `conductor/tracks/mma_agent_focus_ux_20260302/`
+
+**Audit-confirmed gaps:**
+- `ai_client._append_comms` emits entries with no `source_tier` key
+- `ai_client` has no `current_tier` module variable — no way for tiers to self-identify
+- `_tool_log` is `list[tuple[str,str,float]]` — no tier field, tuple must migrate to dict
+- `run_worker_lifecycle` replaces `comms_log_callback` but never stamps `source_tier`
+- `generate_tickets` (Tier 2) does NOT replace callback at all
+- No Focus Agent selector widget in Operations Hub
+
+**Scope:** Phase 1 (tier tagging) → Phase 2 (tool log dict migration) → Phase 3 (Focus Agent UI + filter). Per-tier token stats deferred to sub-track.
+
+### `tech_debt_and_test_cleanup_20260302` (initialized)
+**Priority:** High
+**Depends on:** `feature_bleed_cleanup_20260302`
+**Track dir:** `conductor/tracks/tech_debt_and_test_cleanup_20260302/`
+
+**Audit-confirmed gaps:**
+- 13 test files duplicate `app_instance` fixture instead of using `conftest.py`.
+- Duplicate test files (`test_ast_parser_curated.py`).
+- Multiple simulation tests silently pass with no assertions.
+- `gui_2.py` initializes 9 state variables in `__init__` that are never read.
+- `gui_2.py` has over 15 uncalled HTTP/background methods.
+
+**Scope:** Phase 1 (Fixture deduplication) → Phase 2 (False-positive test fixing) → Phase 3 (Dead code excision in `gui_2.py`).
+
+### `conductor_workflow_improvements_20260302` (initialized)
+**Priority:** High
+**Depends on:** None
+**Track dir:** `conductor/tracks/conductor_workflow_improvements_20260302/`
+
+**Audit-confirmed gaps:**
+- Tier 2 skill lacks enforcement of AST pre-implementation scans to prevent duplicate state variables.
+- Tier 2 skill lacks explicit rejection of non-TDD execution.
+- Tier 3 skill does not strictly forbid implementing code without failing tests.
+- `workflow.md` lacks explicit warnings against zero-assertion tests and redundant `__init__` state.
+
+**Scope:** Phase 1 (Update MMA Skill prompts) → Phase 2 (Update `workflow.md`).
+
+### `architecture_boundary_hardening_20260302` (initialized)
+**Priority:** High
+**Depends on:** None
+**Track dir:** `conductor/tracks/architecture_boundary_hardening_20260302/`
+
+**Audit-confirmed gaps:**
+- `ai_client.py` loops execute `set_file_slice` and `py_update_definition` instantly without checking `pre_tool_callback`, bypassing GUI approval.
+- New `mcp_client.py` tools are not exposed in the GUI or `manual_slop.toml` config for user control.
+- `mma_exec.py` bypasses skeletonization for `mcp_client`, causing token bloat.
+- `dag_engine.py` does not cascade `blocked` states, causing orchestrator infinite loops.
+
+**Scope:** Phase 1 (Meta-tooling token fix) → Phase 2 (Complete MCP Tool Integration & Seal GUI HITL bypass) → Phase 3 (Fix DAG Engine cascading blocks).
+
+### `testing_consolidation_20260302` (initialized)
+**Priority:** Medium
+**Depends on:** `tech_debt_and_test_cleanup_20260302`
+**Track dir:** `conductor/tracks/testing_consolidation_20260302/`
+
+**Audit-confirmed gaps:**
+- `visual_mma_verification.py` manually runs `subprocess.Popen` instead of using the robust `live_gui` fixture.
+- Duplicate architectural logic between tests and `simulation/` directories causing fragmentation.
+
+**Scope:** Phase 1 (Migrate manual launchers to fixtures) → Phase 2 (Consolidate simulation scripts).
+
+---
+
+## Track Dependency Order (Execution Guide)
+To ensure smooth execution, execute the tracks in the following order:
+1. `feature_bleed_cleanup_20260302` (Base cleanup of GUI structure)
+2. `mma_agent_focus_ux_20260302` (Depends on feature bleed cleanup Phase 1)
+3. `architecture_boundary_hardening_20260302` (Fixes critical HITL & Token leaks; independent but foundational)
+4. `tech_debt_and_test_cleanup_20260302` (Re-establishes testing foundation; run after feature tracks)
+5. `testing_consolidation_20260302` (Refactors testing methodology; depends on tech debt cleanup)
+6. `conductor_workflow_improvements_20260302` (Meta-level updates to skills/workflow docs; can be run anytime)
+
+---
+
+## Future Backlog (Post-Cleanup)
+*To be evaluated in a future Tier 1 session after the immediate tech debt queue is cleared.*
+
+### `gui_decoupling_controller`
+**Context:** `gui_2.py` is over 3,500 lines and operates as a Monolithic God Object. It violates the "Data-Oriented & Immediate Mode" heuristics by owning complex business logic, orchestrator hooks (`_bg_create_track`), and markdown file building instead of acting as a pure view.
+**Goal:** Create a headless `orchestrator_pm.py` or `app_controller.py` that handles the core lifecycle, allowing `gui_2.py` to be a lagless, immediate-mode projection of the state.
+
+### `robust_json_parsing_tech_lead`
+**Context:** In `conductor_tech_lead.py`, the `generate_tickets` function relies on a generic `try...except` block to parse the LLM's JSON ticket array. If the model hallucinates or outputs invalid JSON, it silently returns an empty array `[]`, causing the GUI to fail the track creation process without giving the model a chance to self-correct.
+**Goal:** Implement a programmatic retry loop that catches `JSONDecodeError` and feeds the error back to the Tier 2 model for self-correction before failing the UI operation.
+
+### `strict_static_analysis_and_typing`
+**Context:** Running `uv run ruff check .` and `uv run mypy --explicit-package-bases .` revealed massive technical debt in type safety (512+ Mypy errors across 64 files, 200+ remaining Ruff violations). The `gui_2.py` and `api_hook_client.py` files specifically have severe "Any" bleeding and incorrect unions.
+**Goal:** Resolve all static analysis errors. Enforce strict `mypy` compliance, remove implicit `Optional` types, and fix ambiguous variables (`l`). Integrate `ruff` and `mypy` into a CI pre-commit hook so Tier 3 workers are forced to write type-safe code going forward.
+
+### `test_suite_performance_and_flakiness`
+**Context:** Running `uv run pytest` takes over 5.0 minutes to execute and frequently hangs on integration tests (e.g. `test_spawn_interception.py`). Several simulation tests (`test_sim_ai_settings.py`, `test_extended_sims.py`) are also currently failing or timing out. 
+**Goal:** Audit the test suite for `time.sleep()` abuse. Replace hardcoded sleeps with `threading.Event()` hooks or robust polling. Isolate slow integration tests with `@pytest.mark.slow` and ensure the core unit test suite runs in under 10 seconds to maintain high-velocity TDD.
+
+

aggregate.py

@@ -1,4 +1,5 @@
 # aggregate.py
+from __future__ import annotations
 """
 Note(Gemini):
 This module orchestrates the construction of the final Markdown context string. 
@@ -15,92 +16,94 @@ import tomllib
 import re
 import glob
 from pathlib import Path, PureWindowsPath
+from typing import Any
 import summarize
 import project_manager
+from file_cache import ASTParser
 
 def find_next_increment(output_dir: Path, namespace: str) -> int:
-    pattern = re.compile(rf"^{re.escape(namespace)}_(\d+)\.md$")
+ pattern = re.compile(rf"^{re.escape(namespace)}_(\d+)\.md$")
-    max_num = 0
+ max_num = 0
-    for f in output_dir.iterdir():
+ for f in output_dir.iterdir():
-        if f.is_file():
+  if f.is_file():
-            match = pattern.match(f.name)
+   match = pattern.match(f.name)
-            if match:
+   if match:
-                max_num = max(max_num, int(match.group(1)))
+    max_num = max(max_num, int(match.group(1)))
-    return max_num + 1
+ return max_num + 1
 
 def is_absolute_with_drive(entry: str) -> bool:
-    try:
+ try:
-        p = PureWindowsPath(entry)
+  p = PureWindowsPath(entry)
-        return p.drive != ""
+  return p.drive != ""
-    except Exception:
+ except Exception:
-        return False
+  return False
 
 def resolve_paths(base_dir: Path, entry: str) -> list[Path]:
-    has_drive = is_absolute_with_drive(entry)
+ has_drive = is_absolute_with_drive(entry)
-    is_wildcard = "*" in entry
+ is_wildcard = "*" in entry
-    
+ matches = []
-    matches = []
+ if is_wildcard:
-    if is_wildcard:
+  root = Path(entry) if has_drive else base_dir / entry
-        root = Path(entry) if has_drive else base_dir / entry
+  matches = [Path(p) for p in glob.glob(str(root), recursive=True) if Path(p).is_file()]
-        matches = [Path(p) for p in glob.glob(str(root), recursive=True) if Path(p).is_file()]
+ else:
-    else:
+  p = Path(entry) if has_drive else (base_dir / entry).resolve()
-        p = Path(entry) if has_drive else (base_dir / entry).resolve()
+  matches = [p]
-        matches = [p]
+  # Blacklist filter
-        
+ filtered = []
-    # Blacklist filter
+ for p in matches:
-    filtered = []
+  name = p.name.lower()
-    for p in matches:
+  if name == "history.toml" or name.endswith("_history.toml"):
-        name = p.name.lower()
+   continue
-        if name == "history.toml" or name.endswith("_history.toml"):
+  filtered.append(p)
-            continue
+ return sorted(filtered)
-        filtered.append(p)
-        
-    return sorted(filtered)
 
 def build_discussion_section(history: list[str]) -> str:
-    sections = []
+ sections = []
-    for i, paste in enumerate(history, start=1):
+ for i, paste in enumerate(history, start=1):
-        sections.append(f"### Discussion Excerpt {i}\n\n{paste.strip()}")
+  sections.append(f"### Discussion Excerpt {i}\n\n{paste.strip()}")
-    return "\n\n---\n\n".join(sections)
+ return "\n\n---\n\n".join(sections)
 
-def build_files_section(base_dir: Path, files: list[str]) -> str:
+def build_files_section(base_dir: Path, files: list[str | dict[str, Any]]) -> str:
-    sections = []
+ sections = []
-    for entry in files:
+ for entry_raw in files:
-        paths = resolve_paths(base_dir, entry)
+  if isinstance(entry_raw, dict):
-        if not paths:
+   entry = entry_raw.get("path")
-            sections.append(f"### `{entry}`\n\n```text\nERROR: no files matched: {entry}\n```")
+  else:
-            continue
+   entry = entry_raw
-        for path in paths:
+  paths = resolve_paths(base_dir, entry)
-            suffix = path.suffix.lstrip(".")
+  if not paths:
-            lang = suffix if suffix else "text"
+   sections.append(f"### `{entry}`\n\n```text\nERROR: no files matched: {entry}\n```")
-            try:
+   continue
-                content = path.read_text(encoding="utf-8")
+  for path in paths:
-            except FileNotFoundError:
+   suffix = path.suffix.lstrip(".")
-                content = f"ERROR: file not found: {path}"
+   lang = suffix if suffix else "text"
-            except Exception as e:
+   try:
-                content = f"ERROR: {e}"
+    content = path.read_text(encoding="utf-8")
-            original = entry if "*" not in entry else str(path)
+   except FileNotFoundError:
-            sections.append(f"### `{original}`\n\n```{lang}\n{content}\n```")
+    content = f"ERROR: file not found: {path}"
-    return "\n\n---\n\n".join(sections)
+   except Exception as e:
+    content = f"ERROR: {e}"
+   original = entry if "*" not in entry else str(path)
+   sections.append(f"### `{original}`\n\n```{lang}\n{content}\n```")
+ return "\n\n---\n\n".join(sections)
 
 def build_screenshots_section(base_dir: Path, screenshots: list[str]) -> str:
-    sections = []
+ sections = []
-    for entry in screenshots:
+ for entry in screenshots:
-        paths = resolve_paths(base_dir, entry)
+  paths = resolve_paths(base_dir, entry)
-        if not paths:
+  if not paths:
-            sections.append(f"### `{entry}`\n\n_ERROR: no files matched: {entry}_")
+   sections.append(f"### `{entry}`\n\n_ERROR: no files matched: {entry}_")
-            continue
+   continue
-        for path in paths:
+  for path in paths:
-            original = entry if "*" not in entry else str(path)
+   original = entry if "*" not in entry else str(path)
-            if not path.exists():
+   if not path.exists():
-                sections.append(f"### `{original}`\n\n_ERROR: file not found: {path}_")
+    sections.append(f"### `{original}`\n\n_ERROR: file not found: {path}_")
-                continue
+    continue
-            sections.append(f"### `{original}`\n\n![{path.name}]({path.as_posix()})")
+   sections.append(f"### `{original}`\n\n![{path.name}]({path.as_posix()})")
-    return "\n\n---\n\n".join(sections)
+ return "\n\n---\n\n".join(sections)
 
-
+def build_file_items(base_dir: Path, files: list[str | dict[str, Any]]) -> list[dict[str, Any]]:
-def build_file_items(base_dir: Path, files: list[str]) -> list[dict]:
+ """
-    """
     Return a list of dicts describing each file, for use by ai_client when it
     wants to upload individual files rather than inline everything as markdown.
 
@@ -110,142 +113,215 @@ def build_file_items(base_dir: Path, files: list[str]) -> list[dict]:
         content  : str   (file text, or error string)
         error    : bool
         mtime    : float (last modification time, for skip-if-unchanged optimization)
+        tier     : int | None (optional tier for context management)
     """
-    items = []
+ items = []
-    for entry in files:
+ for entry_raw in files:
-        paths = resolve_paths(base_dir, entry)
+  if isinstance(entry_raw, dict):
-        if not paths:
+   entry = entry_raw.get("path")
-            items.append({"path": None, "entry": entry, "content": f"ERROR: no files matched: {entry}", "error": True, "mtime": 0.0})
+   tier = entry_raw.get("tier")
-            continue
+  else:
-        for path in paths:
+   entry = entry_raw
-            try:
+   tier = None
-                content = path.read_text(encoding="utf-8")
+  paths = resolve_paths(base_dir, entry)
-                mtime = path.stat().st_mtime
+  if not paths:
-                error = False
+   items.append({"path": None, "entry": entry, "content": f"ERROR: no files matched: {entry}", "error": True, "mtime": 0.0, "tier": tier})
-            except FileNotFoundError:
+   continue
-                content = f"ERROR: file not found: {path}"
+  for path in paths:
-                mtime = 0.0
+   try:
-                error = True
+    content = path.read_text(encoding="utf-8")
-            except Exception as e:
+    mtime = path.stat().st_mtime
-                content = f"ERROR: {e}"
+    error = False
-                mtime = 0.0
+   except FileNotFoundError:
-                error = True
+    content = f"ERROR: file not found: {path}"
-            items.append({"path": path, "entry": entry, "content": content, "error": error, "mtime": mtime})
+    mtime = 0.0
-    return items
+    error = True
+   except Exception as e:
+    content = f"ERROR: {e}"
+    mtime = 0.0
+    error = True
+   items.append({"path": path, "entry": entry, "content": content, "error": error, "mtime": mtime, "tier": tier})
+ return items
 
-def build_summary_section(base_dir: Path, files: list[str]) -> str:
+def build_summary_section(base_dir: Path, files: list[str | dict[str, Any]]) -> str:
-    """
+ """
     Build a compact summary section using summarize.py — one short block per file.
     Used as the initial <context> block instead of full file contents.
     """
-    items = build_file_items(base_dir, files)
+ items = build_file_items(base_dir, files)
-    return summarize.build_summary_markdown(items)
+ return summarize.build_summary_markdown(items)
 
-def _build_files_section_from_items(file_items: list[dict]) -> str:
+def _build_files_section_from_items(file_items: list[dict[str, Any]]) -> str:
-    """Build the files markdown section from pre-read file items (avoids double I/O)."""
+ """Build the files markdown section from pre-read file items (avoids double I/O)."""
-    sections = []
+ sections = []
-    for item in file_items:
+ for item in file_items:
-        path = item.get("path")
+  path = item.get("path")
-        entry = item.get("entry", "unknown")
+  entry = item.get("entry", "unknown")
-        content = item.get("content", "")
+  content = item.get("content", "")
-        if path is None:
+  if path is None:
-            sections.append(f"### `{entry}`\n\n```text\n{content}\n```")
+   sections.append(f"### `{entry}`\n\n```text\n{content}\n```")
-            continue
+   continue
-        suffix = path.suffix.lstrip(".") if hasattr(path, "suffix") else "text"
+  suffix = path.suffix.lstrip(".") if hasattr(path, "suffix") else "text"
-        lang = suffix if suffix else "text"
+  lang = suffix if suffix else "text"
-        original = entry if "*" not in entry else str(path)
+  original = entry if "*" not in entry else str(path)
-        sections.append(f"### `{original}`\n\n```{lang}\n{content}\n```")
+  sections.append(f"### `{original}`\n\n```{lang}\n{content}\n```")
-    return "\n\n---\n\n".join(sections)
+ return "\n\n---\n\n".join(sections)
 
+def build_markdown_from_items(file_items: list[dict[str, Any]], screenshot_base_dir: Path, screenshots: list[str], history: list[str], summary_only: bool = False) -> str:
+ """Build markdown from pre-read file items instead of re-reading from disk."""
+ parts = []
+ # STATIC PREFIX: Files and Screenshots must go first to maximize Cache Hits
+ if file_items:
+  if summary_only:
+   parts.append("## Files (Summary)\n\n" + summarize.build_summary_markdown(file_items))
+  else:
+   parts.append("## Files\n\n" + _build_files_section_from_items(file_items))
+ if screenshots:
+  parts.append("## Screenshots\n\n" + build_screenshots_section(screenshot_base_dir, screenshots))
+  # DYNAMIC SUFFIX: History changes every turn, must go last
+ if history:
+  parts.append("## Discussion History\n\n" + build_discussion_section(history))
+ return "\n\n---\n\n".join(parts)
 
-def build_markdown_from_items(file_items: list[dict], screenshot_base_dir: Path, screenshots: list[str], history: list[str], summary_only: bool = False) -> str:
+def build_markdown_no_history(file_items: list[dict[str, Any]], screenshot_base_dir: Path, screenshots: list[str], summary_only: bool = False) -> str:
-    """Build markdown from pre-read file items instead of re-reading from disk."""
+ """Build markdown with only files + screenshots (no history). Used for stable caching."""
-    parts = []
+ return build_markdown_from_items(file_items, screenshot_base_dir, screenshots, history=[], summary_only=summary_only)
-    # STATIC PREFIX: Files and Screenshots must go first to maximize Cache Hits
-    if file_items:
-        if summary_only:
-            parts.append("## Files (Summary)\n\n" + summarize.build_summary_markdown(file_items))
-        else:
-            parts.append("## Files\n\n" + _build_files_section_from_items(file_items))
-    if screenshots:
-        parts.append("## Screenshots\n\n" + build_screenshots_section(screenshot_base_dir, screenshots))
-    # DYNAMIC SUFFIX: History changes every turn, must go last
-    if history:
-        parts.append("## Discussion History\n\n" + build_discussion_section(history))
-    return "\n\n---\n\n".join(parts)
-
-
-def build_markdown_no_history(file_items: list[dict], screenshot_base_dir: Path, screenshots: list[str], summary_only: bool = False) -> str:
-    """Build markdown with only files + screenshots (no history). Used for stable caching."""
-    return build_markdown_from_items(file_items, screenshot_base_dir, screenshots, history=[], summary_only=summary_only)
-
 
 def build_discussion_text(history: list[str]) -> str:
-    """Build just the discussion history section text. Returns empty string if no history."""
+ """Build just the discussion history section text. Returns empty string if no history."""
-    if not history:
+ if not history:
-        return ""
+  return ""
-    return "## Discussion History\n\n" + build_discussion_section(history)
+ return "## Discussion History\n\n" + build_discussion_section(history)
 
+def build_tier1_context(file_items: list[dict[str, Any]], screenshot_base_dir: Path, screenshots: list[str], history: list[str]) -> str:
+ """
+    Tier 1 Context: Strategic/Orchestration.
+    Full content for core conductor files and files with tier=1, summaries for others.
+    """
+ core_files = {"product.md", "tech-stack.md", "workflow.md", "tracks.md"}
+ parts = []
+ # Files section
+ if file_items:
+  sections = []
+  for item in file_items:
+   path = item.get("path")
+   name = path.name if path else ""
+   if name in core_files or item.get("tier") == 1:
+   # Include in full
+    sections.append("### `" + (item.get("entry") or str(path)) + "`\n\n" + 
+     f"```{path.suffix.lstrip('.') if path.suffix else 'text'}\n{item.get('content', '')}\n```")
+   else:
+   # Summarize
+    sections.append("### `" + (item.get("entry") or str(path)) + "`\n\n" + 
+     summarize.summarise_file(path, item.get("content", "")))
+  parts.append("## Files (Tier 1 - Mixed)\n\n" + "\n\n---\n\n".join(sections))
+ if screenshots:
+  parts.append("## Screenshots\n\n" + build_screenshots_section(screenshot_base_dir, screenshots))
+ if history:
+  parts.append("## Discussion History\n\n" + build_discussion_section(history))
+ return "\n\n---\n\n".join(parts)
 
-def build_markdown(base_dir: Path, files: list[str], screenshot_base_dir: Path, screenshots: list[str], history: list[str], summary_only: bool = False) -> str:
+def build_tier2_context(file_items: list[dict[str, Any]], screenshot_base_dir: Path, screenshots: list[str], history: list[str]) -> str:
-    parts = []
+ """
-    # STATIC PREFIX: Files and Screenshots must go first to maximize Cache Hits
+    Tier 2 Context: Architectural/Tech Lead.
-    if files:
+    Full content for all files (standard behavior).
-        if summary_only:
+    """
-            parts.append("## Files (Summary)\n\n" + build_summary_section(base_dir, files))
+ return build_markdown_from_items(file_items, screenshot_base_dir, screenshots, history, summary_only=False)
-        else:
-            parts.append("## Files\n\n" + build_files_section(base_dir, files))
-    if screenshots:
-        parts.append("## Screenshots\n\n" + build_screenshots_section(screenshot_base_dir, screenshots))
-    # DYNAMIC SUFFIX: History changes every turn, must go last
-    if history:
-        parts.append("## Discussion History\n\n" + build_discussion_section(history))
-    return "\n\n---\n\n".join(parts)
 
-def run(config: dict) -> tuple[str, Path, list[dict]]:
+def build_tier3_context(file_items: list[dict[str, Any]], screenshot_base_dir: Path, screenshots: list[str], history: list[str], focus_files: list[str]) -> str:
-    namespace = config.get("project", {}).get("name")
+ """
-    if not namespace:
+    Tier 3 Context: Execution/Worker.
-        namespace = config.get("output", {}).get("namespace", "project")
+    Full content for focus_files and files with tier=3, summaries/skeletons for others.
-    output_dir = Path(config["output"]["output_dir"])
+    """
-    base_dir = Path(config["files"]["base_dir"])
+ parts = []
-    files = config["files"].get("paths", [])
+ if file_items:
-    screenshot_base_dir = Path(config.get("screenshots", {}).get("base_dir", "."))
+  sections = []
-    screenshots = config.get("screenshots", {}).get("paths", [])
+  for item in file_items:
-    history = config.get("discussion", {}).get("history", [])
+   path = item.get("path")
+   entry = item.get("entry", "")
+   path_str = str(path) if path else ""
+   # Check if this file is in focus_files (by name or path)
+   is_focus = False
+   for focus in focus_files:
+    if focus == entry or (path and focus == path.name) or focus in path_str:
+     is_focus = True
+     break
+   if is_focus or item.get("tier") == 3:
+    sections.append("### `" + (entry or path_str) + "`\n\n" + 
+     f"```{path.suffix.lstrip('.') if path and path.suffix else 'text'}\n{item.get('content', '')}\n```")
+   else:
+    content = item.get("content", "")
+    if path and path.suffix == ".py" and not item.get("error"):
+     try:
+      parser = ASTParser("python")
+      skeleton = parser.get_skeleton(content)
+      sections.append(f"### `{entry or path_str}` (AST Skeleton)\n\n```python\n{skeleton}\n```")
+     except Exception as e:
+     # Fallback to summary if AST parsing fails
+      sections.append(f"### `{entry or path_str}`\n\n" + summarize.summarise_file(path, content))
+    else:
+     sections.append(f"### `{entry or path_str}`\n\n" + summarize.summarise_file(path, content))
+  parts.append("## Files (Tier 3 - Focused)\n\n" + "\n\n---\n\n".join(sections))
+ if screenshots:
+  parts.append("## Screenshots\n\n" + build_screenshots_section(screenshot_base_dir, screenshots))
+ if history:
+  parts.append("## Discussion History\n\n" + build_discussion_section(history))
+ return "\n\n---\n\n".join(parts)
 
-    output_dir.mkdir(parents=True, exist_ok=True)
+def build_markdown(base_dir: Path, files: list[str | dict[str, Any]], screenshot_base_dir: Path, screenshots: list[str], history: list[str], summary_only: bool = False) -> str:
-    increment = find_next_increment(output_dir, namespace)
+ parts = []
-    output_file = output_dir / f"{namespace}_{increment:03d}.md"
+ # STATIC PREFIX: Files and Screenshots must go first to maximize Cache Hits
-    # Build file items once, then construct markdown from them (avoids double I/O)
+ if files:
-    file_items = build_file_items(base_dir, files)
+  if summary_only:
-    summary_only = config.get("project", {}).get("summary_only", False)
+   parts.append("## Files (Summary)\n\n" + build_summary_section(base_dir, files))
-    markdown = build_markdown_from_items(file_items, screenshot_base_dir, screenshots, history,
+  else:
-                                         summary_only=summary_only)
+   parts.append("## Files\n\n" + build_files_section(base_dir, files))
-    output_file.write_text(markdown, encoding="utf-8")
+ if screenshots:
-    return markdown, output_file, file_items
+  parts.append("## Screenshots\n\n" + build_screenshots_section(screenshot_base_dir, screenshots))
+  # DYNAMIC SUFFIX: History changes every turn, must go last
+ if history:
+  parts.append("## Discussion History\n\n" + build_discussion_section(history))
+ return "\n\n---\n\n".join(parts)
 
-def main():
+def run(config: dict[str, Any]) -> tuple[str, Path, list[dict[str, Any]]]:
-    # Load global config to find active project
+ namespace = config.get("project", {}).get("name")
-    config_path = Path("config.toml")
+ if not namespace:
-    if not config_path.exists():
+  namespace = config.get("output", {}).get("namespace", "project")
-        print("config.toml not found.")
+ output_dir = Path(config["output"]["output_dir"])
-        return
+ base_dir = Path(config["files"]["base_dir"])
-        
+ files = config["files"].get("paths", [])
-    with open(config_path, "rb") as f:
+ screenshot_base_dir = Path(config.get("screenshots", {}).get("base_dir", "."))
-        global_cfg = tomllib.load(f)
+ screenshots = config.get("screenshots", {}).get("paths", [])
-        
+ history = config.get("discussion", {}).get("history", [])
-    active_path = global_cfg.get("projects", {}).get("active")
+ output_dir.mkdir(parents=True, exist_ok=True)
-    if not active_path:
+ increment = find_next_increment(output_dir, namespace)
-        print("No active project found in config.toml.")
+ output_file = output_dir / f"{namespace}_{increment:03d}.md"
-        return
+ # Build file items once, then construct markdown from them (avoids double I/O)
-        
+ file_items = build_file_items(base_dir, files)
-    # Use project_manager to load project (handles history segregation)
+ summary_only = config.get("project", {}).get("summary_only", False)
-    proj = project_manager.load_project(active_path)
+ markdown = build_markdown_from_items(file_items, screenshot_base_dir, screenshots, history,
-    # Use flat_config to make it compatible with aggregate.run()
+  summary_only=summary_only)
-    config = project_manager.flat_config(proj)
+ output_file.write_text(markdown, encoding="utf-8")
-    
+ return markdown, output_file, file_items
-    markdown, output_file, _ = run(config)
+
-    print(f"Written: {output_file}")
+def main() -> None:
+# Load global config to find active project
+ config_path = Path("config.toml")
+ if not config_path.exists():
+  print("config.toml not found.")
+  return
+ with open(config_path, "rb") as f:
+  global_cfg = tomllib.load(f)
+ active_path = global_cfg.get("projects", {}).get("active")
+ if not active_path:
+  print("No active project found in config.toml.")
+  return
+  # Use project_manager to load project (handles history segregation)
+ proj = project_manager.load_project(active_path)
+ # Use flat_config to make it compatible with aggregate.run()
+ config = project_manager.flat_config(proj)
+ markdown, output_file, _ = run(config)
+ print(f"Written: {output_file}")
 
 if __name__ == "__main__":
-    main()
+ main()

api_hook_client.py

@@ -1,139 +1,245 @@
+from __future__ import annotations
 import requests
 import json
 import time
+from typing import Any
 
 class ApiHookClient:
-    def __init__(self, base_url="http://127.0.0.1:8999", max_retries=5, retry_delay=2):
+ def __init__(self, base_url: str = "http://127.0.0.1:8999", max_retries: int = 5, retry_delay: float = 0.2) -> None:
-        self.base_url = base_url
+  self.base_url = base_url
-        self.max_retries = max_retries
+  self.max_retries = max_retries
-        self.retry_delay = retry_delay
+  self.retry_delay = retry_delay
 
-    def wait_for_server(self, timeout=10):
+ def wait_for_server(self, timeout: float = 3) -> bool:
-        """
+  """
         Polls the /status endpoint until the server is ready or timeout is reached.
         """
-        start_time = time.time()
+  start_time = time.time()
-        while time.time() - start_time < timeout:
+  while time.time() - start_time < timeout:
-            try:
+   try:
-                if self.get_status().get('status') == 'ok':
+    if self.get_status().get('status') == 'ok':
-                    return True
+     return True
-            except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
+   except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
-                time.sleep(0.5)
+    time.sleep(0.1)
-        return False
+  return False
 
-    def _make_request(self, method, endpoint, data=None):
+ def _make_request(self, method: str, endpoint: str, data: dict | None = None, timeout: float | None = None) -> dict | None:
-        url = f"{self.base_url}{endpoint}"
+  url = f"{self.base_url}{endpoint}"
-        headers = {'Content-Type': 'application/json'}
+  headers = {'Content-Type': 'application/json'}
-        
+  last_exception = None
-        last_exception = None
+  # Increase default request timeout for local server
-        for attempt in range(self.max_retries + 1):
+  req_timeout = timeout if timeout is not None else 10.0
-            try:
+  for attempt in range(self.max_retries + 1):
-                if method == 'GET':
+   try:
-                    response = requests.get(url, timeout=5)
+    if method == 'GET':
-                elif method == 'POST':
+     response = requests.get(url, timeout=req_timeout)
-                    response = requests.post(url, json=data, headers=headers, timeout=5)
+    elif method == 'POST':
-                else:
+     response = requests.post(url, json=data, headers=headers, timeout=req_timeout)
-                    raise ValueError(f"Unsupported HTTP method: {method}")
+    else:
-                
+     raise ValueError(f"Unsupported HTTP method: {method}")
-                response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
+    response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
-                return response.json()
+    return response.json()
-            except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
+   except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
-                last_exception = e
+    last_exception = e
-                if attempt < self.max_retries:
+    if attempt < self.max_retries:
-                    time.sleep(self.retry_delay)
+     time.sleep(self.retry_delay)
-                    continue
+     continue
-                else:
+    else:
-                    if isinstance(e, requests.exceptions.Timeout):
+     if isinstance(e, requests.exceptions.Timeout):
-                        raise requests.exceptions.Timeout(f"Request to {endpoint} timed out after {self.max_retries} retries.") from e
+      raise requests.exceptions.Timeout(f"Request to {endpoint} timed out after {self.max_retries} retries.") from e
-                    else:
+     else:
-                        raise requests.exceptions.ConnectionError(f"Could not connect to API hook server at {self.base_url} after {self.max_retries} retries.") from e
+      raise requests.exceptions.ConnectionError(f"Could not connect to API hook server at {self.base_url} after {self.max_retries} retries.") from e
-            except requests.exceptions.HTTPError as e:
+   except requests.exceptions.HTTPError as e:
-                raise requests.exceptions.HTTPError(f"HTTP error {e.response.status_code} for {endpoint}: {e.response.text}") from e
+    raise requests.exceptions.HTTPError(f"HTTP error {e.response.status_code} for {endpoint}: {e.response.text}") from e
-            except json.JSONDecodeError as e:
+   except json.JSONDecodeError as e:
-                raise ValueError(f"Failed to decode JSON from response for {endpoint}: {response.text}") from e
+    raise ValueError(f"Failed to decode JSON from response for {endpoint}: {response.text}") from e
-        
+  if last_exception:
-        if last_exception:
+   raise last_exception
-            raise last_exception
 
-    def get_status(self):
+ def get_status(self) -> dict:
-        """Checks the health of the hook server."""
+  """Checks the health of the hook server."""
-        url = f"{self.base_url}/status"
+  url = f"{self.base_url}/status"
-        try:
+  try:
-            response = requests.get(url, timeout=1)
+   response = requests.get(url, timeout=5.0)
-            response.raise_for_status()
+   response.raise_for_status()
-            return response.json()
+   return response.json()
-        except Exception:
+  except Exception:
-            raise requests.exceptions.ConnectionError(f"Could not reach /status at {self.base_url}")
+   raise requests.exceptions.ConnectionError(f"Could not reach /status at {self.base_url}")
 
-    def get_project(self):
+ def get_project(self) -> dict | None:
-        return self._make_request('GET', '/api/project')
+  return self._make_request('GET', '/api/project')
 
-    def post_project(self, project_data):
+ def post_project(self, project_data: dict) -> dict | None:
-        return self._make_request('POST', '/api/project', data={'project': project_data})
+  return self._make_request('POST', '/api/project', data={'project': project_data})
 
-    def get_session(self):
+ def get_session(self) -> dict | None:
-        return self._make_request('GET', '/api/session')
+  res = self._make_request('GET', '/api/session')
+  return res
 
-    def get_performance(self):
+ def get_mma_status(self) -> dict | None:
-        """Retrieves UI performance metrics."""
+  """Retrieves current MMA status (track, tickets, tier, etc.)"""
-        return self._make_request('GET', '/api/performance')
+  return self._make_request('GET', '/api/gui/mma_status')
 
-    def post_session(self, session_entries):
+ def push_event(self, event_type: str, payload: dict) -> dict | None:
-        return self._make_request('POST', '/api/session', data={'session': {'entries': session_entries}})
+  """Pushes an event to the GUI's AsyncEventQueue via the /api/gui endpoint."""
+  return self.post_gui({
+    "action": event_type,
+    "payload": payload
+   })
 
-    def post_gui(self, gui_data):
+ def get_performance(self) -> dict | None:
-        return self._make_request('POST', '/api/gui', data=gui_data)
+  """Retrieves UI performance metrics."""
+  return self._make_request('GET', '/api/performance')
 
-    def select_tab(self, tab_bar, tab):
+ def post_session(self, session_entries: list) -> dict | None:
-        """Tells the GUI to switch to a specific tab in a tab bar."""
+  return self._make_request('POST', '/api/session', data={'session': {'entries': session_entries}})
-        return self.post_gui({
-            "action": "select_tab",
-            "tab_bar": tab_bar,
-            "tab": tab
-        })
 
-    def select_list_item(self, listbox, item_value):
+ def post_gui(self, gui_data: dict) -> dict | None:
-        """Tells the GUI to select an item in a listbox by its value."""
+  return self._make_request('POST', '/api/gui', data=gui_data)
-        return self.post_gui({
-            "action": "select_list_item",
-            "listbox": listbox,
-            "item_value": item_value
-        })
 
-    def set_value(self, item, value):
+ def select_tab(self, tab_bar: str, tab: str) -> dict | None:
-        """Sets the value of a GUI item."""
+  """Tells the GUI to switch to a specific tab in a tab bar."""
-        return self.post_gui({
+  return self.post_gui({
-            "action": "set_value",
+    "action": "select_tab",
-            "item": item,
+    "tab_bar": tab_bar,
-            "value": value
+    "tab": tab
-        })
+   })
 
-    def click(self, item, *args, **kwargs):
+ def select_list_item(self, listbox: str, item_value: str) -> dict | None:
-        """Simulates a click on a GUI button or item."""
+  """Tells the GUI to select an item in a listbox by its value."""
-        user_data = kwargs.pop('user_data', None)
+  return self.post_gui({
-        return self.post_gui({
+    "action": "select_list_item",
-            "action": "click",
+    "listbox": listbox,
-            "item": item,
+    "item_value": item_value
-            "args": args,
+   })
-            "kwargs": kwargs,
-            "user_data": user_data
-        })
 
-    def get_indicator_state(self, tag):
+ def set_value(self, item: str, value: Any) -> dict | None:
-        """Checks if an indicator is shown using the diagnostics endpoint."""
+  """Sets the value of a GUI item."""
-        # Mapping tag to the keys used in diagnostics endpoint
+  return self.post_gui({
-        mapping = {
+    "action": "set_value",
-            "thinking_indicator": "thinking",
+    "item": item,
-            "operations_live_indicator": "live",
+    "value": value
-            "prior_session_indicator": "prior"
+   })
-        }
-        key = mapping.get(tag, tag)
-        try:
-            diag = self._make_request('GET', '/api/gui/diagnostics')
-            return {"tag": tag, "shown": diag.get(key, False)}
-        except Exception as e:
-            return {"tag": tag, "shown": False, "error": str(e)}
 
-    def reset_session(self):
+ def get_value(self, item: str) -> Any:
-        """Simulates clicking the 'Reset Session' button in the GUI."""
+  """Gets the value of a GUI item via its mapped field."""
-        return self.click("btn_reset")
+  try:
+  # First try direct field querying via POST
+   res = self._make_request('POST', '/api/gui/value', data={"field": item})
+   if res and "value" in res:
+    v = res.get("value")
+    if v is not None:
+     return v
+  except Exception:
+   pass
+  try:
+  # Try GET fallback
+   res = self._make_request('GET', f'/api/gui/value/{item}')
+   if res and "value" in res:
+    v = res.get("value")
+    if v is not None:
+     return v
+  except Exception:
+   pass
+  try:
+  # Fallback for thinking/live/prior which are in diagnostics
+   diag = self._make_request('GET', '/api/gui/diagnostics')
+   if item in diag:
+    return diag[item]
+    # Map common indicator tags to diagnostics keys
+   mapping = {
+    "thinking_indicator": "thinking",
+    "operations_live_indicator": "live",
+    "prior_session_indicator": "prior"
+   }
+   key = mapping.get(item)
+   if key and key in diag:
+    return diag[key]
+  except Exception:
+   pass
+  return None
+
+ def get_text_value(self, item_tag: str) -> str | None:
+  """Wraps get_value and returns its string representation, or None."""
+  val = self.get_value(item_tag)
+  return str(val) if val is not None else None
+
+ def get_node_status(self, node_tag: str) -> Any:
+  """Wraps get_value for a DAG node or queries the diagnostic endpoint for its status."""
+  val = self.get_value(node_tag)
+  if val is not None:
+   return val
+  try:
+   diag = self._make_request('GET', '/api/gui/diagnostics')
+   if 'nodes' in diag and node_tag in diag['nodes']:
+    return diag['nodes'][node_tag]
+   if node_tag in diag:
+    return diag[node_tag]
+  except Exception:
+   pass
+  return None
+
+ def click(self, item: str, *args: Any, **kwargs: Any) -> dict | None:
+  """Simulates a click on a GUI button or item."""
+  user_data = kwargs.pop('user_data', None)
+  return self.post_gui({
+    "action": "click",
+    "item": item,
+    "args": args,
+    "kwargs": kwargs,
+    "user_data": user_data
+   })
+
+ def get_indicator_state(self, tag: str) -> dict:
+  """Checks if an indicator is shown using the diagnostics endpoint."""
+  # Mapping tag to the keys used in diagnostics endpoint
+  mapping = {
+   "thinking_indicator": "thinking",
+   "operations_live_indicator": "live",
+   "prior_session_indicator": "prior"
+  }
+  key = mapping.get(tag, tag)
+  try:
+   diag = self._make_request('GET', '/api/gui/diagnostics')
+   return {"tag": tag, "shown": diag.get(key, False)}
+  except Exception as e:
+   return {"tag": tag, "shown": False, "error": str(e)}
+
+ def get_events(self) -> list:
+  """Fetches and clears the event queue from the server."""
+  try:
+   return self._make_request('GET', '/api/events').get("events", [])
+  except Exception:
+   return []
+
+ def wait_for_event(self, event_type: str, timeout: float = 5) -> dict | None:
+  """Polls for a specific event type."""
+  start = time.time()
+  while time.time() - start < timeout:
+   events = self.get_events()
+   for ev in events:
+    if ev.get("type") == event_type:
+     return ev
+   time.sleep(0.1) # Fast poll
+  return None
+
+ def wait_for_value(self, item: str, expected: Any, timeout: float = 5) -> bool:
+  """Polls until get_value(item) == expected."""
+  start = time.time()
+  while time.time() - start < timeout:
+   if self.get_value(item) == expected:
+    return True
+   time.sleep(0.1) # Fast poll
+  return False
+
+ def reset_session(self) -> dict | None:
+  """Simulates clicking the 'Reset Session' button in the GUI."""
+  return self.click("btn_reset")
+
+ def request_confirmation(self, tool_name: str, args: dict) -> Any:
+  """Asks the user for confirmation via the GUI (blocking call)."""
+  # Using a long timeout as this waits for human input (60 seconds)
+  res = self._make_request('POST', '/api/ask',
+   data={'type': 'tool_approval', 'tool': tool_name, 'args': args},
+   timeout=60.0)
+  return res.get('response')

api_hooks.py

@@ -1,152 +1,310 @@
+from __future__ import annotations
 import json
 import threading
-from http.server import HTTPServer, BaseHTTPRequestHandler
+import uuid
+from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
+from typing import Any
 import logging
 import session_logger
 
-class HookServerInstance(HTTPServer):
+class HookServerInstance(ThreadingHTTPServer):
-    """Custom HTTPServer that carries a reference to the main App instance."""
+ """Custom HTTPServer that carries a reference to the main App instance."""
-    def __init__(self, server_address, RequestHandlerClass, app):
+ def __init__(self, server_address: tuple[str, int], RequestHandlerClass: type, app: Any) -> None:
-        super().__init__(server_address, RequestHandlerClass)
+  super().__init__(server_address, RequestHandlerClass)
-        self.app = app
+  self.app = app
 
 class HookHandler(BaseHTTPRequestHandler):
-    """Handles incoming HTTP requests for the API hooks."""
+ """Handles incoming HTTP requests for the API hooks."""
-    def do_GET(self):
+ def do_GET(self) -> None:
-        app = self.server.app
+  app = self.server.app
-        session_logger.log_api_hook("GET", self.path, "")
+  session_logger.log_api_hook("GET", self.path, "")
-        if self.path == '/status':
+  if self.path == '/status':
-            self.send_response(200)
+   self.send_response(200)
-            self.send_header('Content-Type', 'application/json')
+   self.send_header('Content-Type', 'application/json')
-            self.end_headers()
+   self.end_headers()
-            self.wfile.write(json.dumps({'status': 'ok'}).encode('utf-8'))
+   self.wfile.write(json.dumps({'status': 'ok'}).encode('utf-8'))
-        elif self.path == '/api/project':
+  elif self.path == '/api/project':
-            import project_manager
+   import project_manager
-            self.send_response(200)
+   self.send_response(200)
-            self.send_header('Content-Type', 'application/json')
+   self.send_header('Content-Type', 'application/json')
-            self.end_headers()
+   self.end_headers()
-            flat = project_manager.flat_config(app.project)
+   flat = project_manager.flat_config(app.project)
-            self.wfile.write(json.dumps({'project': flat}).encode('utf-8'))
+   self.wfile.write(json.dumps({'project': flat}).encode('utf-8'))
-        elif self.path == '/api/session':
+  elif self.path == '/api/session':
-            self.send_response(200)
+   self.send_response(200)
-            self.send_header('Content-Type', 'application/json')
+   self.send_header('Content-Type', 'application/json')
-            self.end_headers()
+   self.end_headers()
-            self.wfile.write(
+   with app._disc_entries_lock:
-                json.dumps({'session': {'entries': app.disc_entries}}).
+    entries_snapshot = list(app.disc_entries)
-                encode('utf-8'))
+   self.wfile.write(
-        elif self.path == '/api/performance':
+    json.dumps({'session': {'entries': entries_snapshot}}).
-            self.send_response(200)
+    encode('utf-8'))
-            self.send_header('Content-Type', 'application/json')
+  elif self.path == '/api/performance':
-            self.end_headers()
+   self.send_response(200)
-            metrics = {}
+   self.send_header('Content-Type', 'application/json')
-            if hasattr(app, 'perf_monitor'):
+   self.end_headers()
-                metrics = app.perf_monitor.get_metrics()
+   metrics = {}
-            self.wfile.write(json.dumps({'performance': metrics}).encode('utf-8'))
+   if hasattr(app, 'perf_monitor'):
-        elif self.path == '/api/gui/diagnostics':
+    metrics = app.perf_monitor.get_metrics()
-            # Safe way to query multiple states at once via the main thread queue
+   self.wfile.write(json.dumps({'performance': metrics}).encode('utf-8'))
-            event = threading.Event()
+  elif self.path == '/api/events':
-            result = {}
+  # Long-poll or return current event queue
-            
+   self.send_response(200)
-            def check_all():
+   self.send_header('Content-Type', 'application/json')
-                try:
+   self.end_headers()
-                    # Generic state check based on App attributes (works for both DPG and ImGui versions)
+   events = []
-                    status = getattr(app, "ai_status", "idle")
+   if hasattr(app, '_api_event_queue'):
-                    result["thinking"] = status in ["sending...", "running powershell..."]
+    with app._api_event_queue_lock:
-                    result["live"] = status in ["running powershell...", "fetching url...", "searching web...", "powershell done, awaiting AI..."]
+     events = list(app._api_event_queue)
-                    result["prior"] = getattr(app, "is_viewing_prior_session", False)
+     app._api_event_queue.clear()
-                finally:
+   self.wfile.write(json.dumps({'events': events}).encode('utf-8'))
-                    event.set()
+  elif self.path == '/api/gui/value':
+  # POST with {"field": "field_tag"} to get value
+   content_length = int(self.headers.get('Content-Length', 0))
+   body = self.rfile.read(content_length)
+   data = json.loads(body.decode('utf-8'))
+   field_tag = data.get("field")
+   event = threading.Event()
+   result = {"value": None}
 
-            with app._pending_gui_tasks_lock:
+   def get_val():
-                app._pending_gui_tasks.append({
+    try:
-                    "action": "custom_callback",
+     if field_tag in app._settable_fields:
-                    "callback": check_all
+      attr = app._settable_fields[field_tag]
-                })
+      val = getattr(app, attr, None)
-            
+      result["value"] = val
-            if event.wait(timeout=2):
+    finally:
-                self.send_response(200)
+     event.set()
-                self.send_header('Content-Type', 'application/json')
+   with app._pending_gui_tasks_lock:
-                self.end_headers()
+    app._pending_gui_tasks.append({
-                self.wfile.write(json.dumps(result).encode('utf-8'))
+      "action": "custom_callback",
-            else:
+      "callback": get_val
-                self.send_response(504)
+     })
-                self.end_headers()
+   if event.wait(timeout=60):
-                self.wfile.write(json.dumps({'error': 'timeout'}).encode('utf-8'))
+    self.send_response(200)
-        else:
+    self.send_header('Content-Type', 'application/json')
-            self.send_response(404)
+    self.end_headers()
-            self.end_headers()
+    self.wfile.write(json.dumps(result).encode('utf-8'))
+   else:
+    self.send_response(504)
+    self.end_headers()
+  elif self.path.startswith('/api/gui/value/'):
+  # Generic endpoint to get the value of any settable field
+   field_tag = self.path.split('/')[-1]
+   event = threading.Event()
+   result = {"value": None}
 
-    def do_POST(self):
+   def get_val():
-        app = self.server.app
+    try:
-        content_length = int(self.headers.get('Content-Length', 0))
+     if field_tag in app._settable_fields:
-        body = self.rfile.read(content_length)
+      attr = app._settable_fields[field_tag]
-        body_str = body.decode('utf-8') if body else ""
+      result["value"] = getattr(app, attr, None)
-        session_logger.log_api_hook("POST", self.path, body_str)
+    finally:
-        
+     event.set()
-        try:
+   with app._pending_gui_tasks_lock:
-            data = json.loads(body_str) if body_str else {}
+    app._pending_gui_tasks.append({
-            if self.path == '/api/project':
+      "action": "custom_callback",
-                app.project = data.get('project', app.project)
+      "callback": get_val
-                self.send_response(200)
+     })
-                self.send_header('Content-Type', 'application/json')
+   if event.wait(timeout=60):
-                self.end_headers()
+    self.send_response(200)
-                self.wfile.write(
+    self.send_header('Content-Type', 'application/json')
-                    json.dumps({'status': 'updated'}).encode('utf-8'))
+    self.end_headers()
-            elif self.path == '/api/session':
+    self.wfile.write(json.dumps(result).encode('utf-8'))
-                app.disc_entries = data.get('session', {}).get(
+   else:
-                    'entries', app.disc_entries)
+    self.send_response(504)
-                self.send_response(200)
+    self.end_headers()
-                self.send_header('Content-Type', 'application/json')
+  elif self.path == '/api/gui/mma_status':
-                self.end_headers()
+   event = threading.Event()
-                self.wfile.write(
+   result = {}
-                    json.dumps({'status': 'updated'}).encode('utf-8'))
-            elif self.path == '/api/gui':
-                with app._pending_gui_tasks_lock:
-                    app._pending_gui_tasks.append(data)
-                    
-                self.send_response(200)
-                self.send_header('Content-Type', 'application/json')
-                self.end_headers()
-                self.wfile.write(
-                    json.dumps({'status': 'queued'}).encode('utf-8'))
-            else:
-                self.send_response(404)
-                self.end_headers()
-        except Exception as e:
-            self.send_response(500)
-            self.send_header('Content-Type', 'application/json')
-            self.end_headers()
-            self.wfile.write(json.dumps({'error': str(e)}).encode('utf-8'))
 
-    def log_message(self, format, *args):
+   def get_mma():
-        logging.info("Hook API: " + format % args)
+    try:
+     result["mma_status"] = getattr(app, "mma_status", "idle")
+     result["ai_status"] = getattr(app, "ai_status", "idle")
+     result["active_tier"] = getattr(app, "active_tier", None)
+     at = getattr(app, "active_track", None)
+     result["active_track"] = at.id if hasattr(at, "id") else at
+     result["active_tickets"] = getattr(app, "active_tickets", [])
+     result["mma_step_mode"] = getattr(app, "mma_step_mode", False)
+     result["pending_tool_approval"] = getattr(app, "_pending_ask_dialog", False)
+     result["pending_script_approval"] = getattr(app, "_pending_dialog", None) is not None
+     result["pending_mma_step_approval"] = getattr(app, "_pending_mma_approval", None) is not None
+     result["pending_mma_spawn_approval"] = getattr(app, "_pending_mma_spawn", None) is not None
+     result["pending_approval"] = result["pending_mma_step_approval"] or result["pending_tool_approval"]
+     result["pending_spawn"] = result["pending_mma_spawn_approval"]
+     result["tracks"] = getattr(app, "tracks", [])
+     result["proposed_tracks"] = getattr(app, "proposed_tracks", [])
+     result["mma_streams"] = getattr(app, "mma_streams", {})
+     result["mma_tier_usage"] = getattr(app, "mma_tier_usage", {})
+    finally:
+     event.set()
+   with app._pending_gui_tasks_lock:
+    app._pending_gui_tasks.append({
+      "action": "custom_callback",
+      "callback": get_mma
+     })
+   if event.wait(timeout=60):
+    self.send_response(200)
+    self.send_header('Content-Type', 'application/json')
+    self.end_headers()
+    self.wfile.write(json.dumps(result).encode('utf-8'))
+   else:
+    self.send_response(504)
+    self.end_headers()
+  elif self.path == '/api/gui/diagnostics':
+   event = threading.Event()
+   result = {}
+
+   def check_all():
+    try:
+     status = getattr(app, "ai_status", "idle")
+     result["thinking"] = status in ["sending...", "running powershell..."]
+     result["live"] = status in ["running powershell...", "fetching url...", "searching web...", "powershell done, awaiting AI..."]
+     result["prior"] = getattr(app, "is_viewing_prior_session", False)
+    finally:
+     event.set()
+   with app._pending_gui_tasks_lock:
+    app._pending_gui_tasks.append({
+      "action": "custom_callback",
+      "callback": check_all
+     })
+   if event.wait(timeout=60):
+    self.send_response(200)
+    self.send_header('Content-Type', 'application/json')
+    self.end_headers()
+    self.wfile.write(json.dumps(result).encode('utf-8'))
+   else:
+    self.send_response(504)
+    self.end_headers()
+    self.wfile.write(json.dumps({'error': 'timeout'}).encode('utf-8'))
+  else:
+   self.send_response(404)
+   self.end_headers()
+
+ def do_POST(self) -> None:
+  app = self.server.app
+  content_length = int(self.headers.get('Content-Length', 0))
+  body = self.rfile.read(content_length)
+  body_str = body.decode('utf-8') if body else ""
+  session_logger.log_api_hook("POST", self.path, body_str)
+  try:
+   data = json.loads(body_str) if body_str else {}
+   if self.path == '/api/project':
+    app.project = data.get('project', app.project)
+    self.send_response(200)
+    self.send_header('Content-Type', 'application/json')
+    self.end_headers()
+    self.wfile.write(json.dumps({'status': 'updated'}).encode('utf-8'))
+   elif self.path.startswith('/api/confirm/'):
+    action_id = self.path.split('/')[-1]
+    approved = data.get('approved', False)
+    if hasattr(app, 'resolve_pending_action'):
+     success = app.resolve_pending_action(action_id, approved)
+     if success:
+      self.send_response(200)
+      self.send_header('Content-Type', 'application/json')
+      self.end_headers()
+      self.wfile.write(json.dumps({'status': 'ok'}).encode('utf-8'))
+     else:
+      self.send_response(404)
+      self.end_headers()
+    else:
+     self.send_response(500)
+     self.end_headers()
+   elif self.path == '/api/session':
+    with app._disc_entries_lock:
+     app.disc_entries = data.get('session', {}).get('entries', app.disc_entries)
+    self.send_response(200)
+    self.send_header('Content-Type', 'application/json')
+    self.end_headers()
+    self.wfile.write(json.dumps({'status': 'updated'}).encode('utf-8'))
+   elif self.path == '/api/gui':
+    with app._pending_gui_tasks_lock:
+     app._pending_gui_tasks.append(data)
+    self.send_response(200)
+    self.send_header('Content-Type', 'application/json')
+    self.end_headers()
+    self.wfile.write(json.dumps({'status': 'queued'}).encode('utf-8'))
+   elif self.path == '/api/ask':
+    request_id = str(uuid.uuid4())
+    event = threading.Event()
+    if not hasattr(app, '_pending_asks'): app._pending_asks = {}
+    if not hasattr(app, '_ask_responses'): app._ask_responses = {}
+    app._pending_asks[request_id] = event
+    with app._api_event_queue_lock:
+     app._api_event_queue.append({"type": "ask_received", "request_id": request_id, "data": data})
+    with app._pending_gui_tasks_lock:
+     app._pending_gui_tasks.append({"type": "ask", "request_id": request_id, "data": data})
+    if event.wait(timeout=60.0):
+     response_data = app._ask_responses.get(request_id)
+     if request_id in app._ask_responses: del app._ask_responses[request_id]
+     self.send_response(200)
+     self.send_header('Content-Type', 'application/json')
+     self.end_headers()
+     self.wfile.write(json.dumps({'status': 'ok', 'response': response_data}).encode('utf-8'))
+    else:
+     if request_id in app._pending_asks: del app._pending_asks[request_id]
+     self.send_response(504)
+     self.end_headers()
+     self.wfile.write(json.dumps({'error': 'timeout'}).encode('utf-8'))
+   elif self.path == '/api/ask/respond':
+    request_id = data.get('request_id')
+    response_data = data.get('response')
+    if request_id and hasattr(app, '_pending_asks') and request_id in app._pending_asks:
+     app._ask_responses[request_id] = response_data
+     event = app._pending_asks[request_id]
+     event.set()
+     del app._pending_asks[request_id]
+     with app._pending_gui_tasks_lock:
+      app._pending_gui_tasks.append({"action": "clear_ask", "request_id": request_id})
+     self.send_response(200)
+     self.send_header('Content-Type', 'application/json')
+     self.end_headers()
+     self.wfile.write(json.dumps({'status': 'ok'}).encode('utf-8'))
+    else:
+     self.send_response(404)
+     self.end_headers()
+   else:
+    self.send_response(404)
+    self.end_headers()
+  except Exception as e:
+   self.send_response(500)
+   self.send_header('Content-Type', 'application/json')
+   self.end_headers()
+   self.wfile.write(json.dumps({'error': str(e)}).encode('utf-8'))
+
+def log_message(self, format: str, *args: Any) -> None:
+ logging.info("Hook API: " + format % args)
 
 class HookServer:
-    def __init__(self, app, port=8999):
+ def __init__(self, app: Any, port: int = 8999) -> None:
-        self.app = app
+  self.app = app
-        self.port = port
+  self.port = port
-        self.server = None
+  self.server = None
-        self.thread = None
+  self.thread = None
 
-    def start(self):
+ def start(self) -> None:
-        if not getattr(self.app, 'test_hooks_enabled', False):
+  if self.thread and self.thread.is_alive():
-            return
+   return
-            
+  is_gemini_cli = getattr(self.app, 'current_provider', '') == 'gemini_cli'
-        # Ensure the app has the task queue and lock initialized
+  if not getattr(self.app, 'test_hooks_enabled', False) and not is_gemini_cli:
-        if not hasattr(self.app, '_pending_gui_tasks'):
+   return
-            self.app._pending_gui_tasks = []
+  if not hasattr(self.app, '_pending_gui_tasks'): self.app._pending_gui_tasks = []
-        if not hasattr(self.app, '_pending_gui_tasks_lock'):
+  if not hasattr(self.app, '_pending_gui_tasks_lock'): self.app._pending_gui_tasks_lock = threading.Lock()
-            self.app._pending_gui_tasks_lock = threading.Lock()
+  if not hasattr(self.app, '_pending_asks'): self.app._pending_asks = {}
-            
+  if not hasattr(self.app, '_ask_responses'): self.app._ask_responses = {}
-        self.server = HookServerInstance(('127.0.0.1', self.port), HookHandler, self.app)
+  if not hasattr(self.app, '_api_event_queue'): self.app._api_event_queue = []
-        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+  if not hasattr(self.app, '_api_event_queue_lock'): self.app._api_event_queue_lock = threading.Lock()
-        self.thread.start()
+  self.server = HookServerInstance(('127.0.0.1', self.port), HookHandler, self.app)
-        logging.info(f"Hook server started on port {self.port}")
+  self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+  self.thread.start()
+  logging.info(f"Hook server started on port {self.port}")
 
-    def stop(self):
+ def stop(self) -> None:
-        if self.server:
+  if self.server:
-            self.server.shutdown()
+   self.server.shutdown()
-            self.server.server_close()
+   self.server.server_close()
-            if self.thread:
+   if self.thread:
-                self.thread.join()
+    self.thread.join()
-            logging.info("Hook server stopped")
+   logging.info("Hook server stopped")

cleanup_ai_client.py

@@ -0,0 +1,583 @@
+
+import os
+
+path = 'ai_client.py'
+with open(path, 'r', encoding='utf-8') as f:
+ lines = f.readlines()
+
+# Very basic cleanup: remove lines after the first 'def get_history_bleed_stats' 
+# or other markers of duplication if they exist.
+# Actually, I'll just rewrite the relevant functions and clean up the end of the file.
+
+new_lines = []
+skip = False
+for line in lines:
+ if 'def _send_gemini(' in line and 'stream_callback' in line:
+  # This is my partially applied change, I'll keep it but fix it.
+  pass
+ if 'def send(' in line and 'import json' in lines[lines.index(line)-1]:
+  # This looks like the duplicated send at the end
+  skip = True
+ if not skip:
+  new_lines.append(line)
+ if skip and 'return {' in line and 'percentage' in line:
+  # End of duplicated get_history_bleed_stats
+  # skip = False # actually just keep skipping till the end
+  pass
+
+# It's better to just surgically fix the file content in memory.
+content = "".join(new_lines)
+
+# I'll use a more robust approach: I'll define the final versions of the functions I want to change.
+
+_SEND_GEMINI_NEW = '''def _send_gemini(md_content: str, user_message: str, base_dir: str,
+ file_items: list[dict[str, Any]] | None = None,
+ discussion_history: str = "",
+ pre_tool_callback: Optional[Callable[[str], bool]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ enable_tools: bool = True,
+ stream_callback: Optional[Callable[[str], None]] = None) -> str:
+ global _gemini_chat, _gemini_cache, _gemini_cache_md_hash, _gemini_cache_created_at
+ try:
+  _ensure_gemini_client(); mcp_client.configure(file_items or [], [base_dir])
+  # Only stable content (files + screenshots) goes in the cached system instruction.
+  # Discussion history is sent as conversation messages so the cache isn't invalidated every turn.
+  sys_instr = f"{_get_combined_system_prompt()}
+
+<context>
+{md_content}
+</context>"
+  td = _gemini_tool_declaration() if enable_tools else None
+  tools_decl = [td] if td else None
+  # DYNAMIC CONTEXT: Check if files/context changed mid-session
+  current_md_hash = hashlib.md5(md_content.encode()).hexdigest()
+  old_history = None
+  if _gemini_chat and _gemini_cache_md_hash != current_md_hash:
+   old_history = list(_get_gemini_history_list(_gemini_chat)) if _get_gemini_history_list(_gemini_chat) else []
+   if _gemini_cache:
+    try: _gemini_client.caches.delete(name=_gemini_cache.name)
+    except Exception as e: _append_comms("OUT", "request", {"message": f"[CACHE DELETE WARN] {e}"})
+   _gemini_chat = None
+   _gemini_cache = None
+   _gemini_cache_created_at = None
+   _append_comms("OUT", "request", {"message": "[CONTEXT CHANGED] Rebuilding cache and chat session..."})
+  if _gemini_chat and _gemini_cache and _gemini_cache_created_at:
+   elapsed = time.time() - _gemini_cache_created_at
+   if elapsed > _GEMINI_CACHE_TTL * 0.9:
+    old_history = list(_get_gemini_history_list(_gemini_chat)) if _get_gemini_history_list(_get_gemini_history_list(_gemini_chat)) else []
+    try: _gemini_client.caches.delete(name=_gemini_cache.name)
+    except Exception as e: _append_comms("OUT", "request", {"message": f"[CACHE DELETE WARN] {e}"})
+    _gemini_chat = None
+    _gemini_cache = None
+    _gemini_cache_created_at = None
+    _append_comms("OUT", "request", {"message": f"[CACHE TTL] Rebuilding cache (expired after {int(elapsed)}s)..."})
+  if not _gemini_chat:
+   chat_config = types.GenerateContentConfig(
+    system_instruction=sys_instr,
+    tools=tools_decl,
+    temperature=_temperature,
+    max_output_tokens=_max_tokens,
+    safety_settings=[types.SafetySetting(category="HARM_CATEGORY_DANGEROUS_CONTENT", threshold="BLOCK_ONLY_HIGH")]
+   )
+   should_cache = False
+   try:
+    count_resp = _gemini_client.models.count_tokens(model=_model, contents=[sys_instr])
+    if count_resp.total_tokens >= 2048:
+     should_cache = True
+    else:
+     _append_comms("OUT", "request", {"message": f"[CACHING SKIPPED] Context too small ({count_resp.total_tokens} tokens < 2048)"})
+   except Exception as e:
+    _append_comms("OUT", "request", {"message": f"[COUNT FAILED] {e}"})
+   if should_cache:
+    try:
+     _gemini_cache = _gemini_client.caches.create(
+      model=_model,
+      config=types.CreateCachedContentConfig(
+       system_instruction=sys_instr,
+       tools=tools_decl,
+       ttl=f"{_GEMINI_CACHE_TTL}s",
+      )
+     )
+     _gemini_cache_created_at = time.time()
+     chat_config = types.GenerateContentConfig(
+      cached_content=_gemini_cache.name,
+      temperature=_temperature,
+      max_output_tokens=_max_tokens,
+      safety_settings=[types.SafetySetting(category="HARM_CATEGORY_DANGEROUS_CONTENT", threshold="BLOCK_ONLY_HIGH")]
+     )
+     _append_comms("OUT", "request", {"message": f"[CACHE CREATED] {_gemini_cache.name}"})
+    except Exception as e:
+     _gemini_cache = None
+     _gemini_cache_created_at = None
+     _append_comms("OUT", "request", {"message": f"[CACHE FAILED] {type(e).__name__}: {e} \u2014 falling back to inline system_instruction"})
+   kwargs = {"model": _model, "config": chat_config}
+   if old_history:
+    kwargs["history"] = old_history
+   _gemini_chat = _gemini_client.chats.create(**kwargs)
+   _gemini_cache_md_hash = current_md_hash
+   if discussion_history and not old_history:
+    _gemini_chat.send_message(f"[DISCUSSION HISTORY]
+
+{discussion_history}")
+    _append_comms("OUT", "request", {"message": f"[HISTORY INJECTED] {len(discussion_history)} chars"})
+  _append_comms("OUT", "request", {"message": f"[ctx {len(md_content)} + msg {len(user_message)}]"})
+  payload: str | list[types.Part] = user_message
+  all_text: list[str] = []
+  _cumulative_tool_bytes = 0
+  if _gemini_chat and _get_gemini_history_list(_gemini_chat):
+   for msg in _get_gemini_history_list(_gemini_chat):
+    if msg.role == "user" and hasattr(msg, "parts"):
+     for p in msg.parts:
+      if hasattr(p, "function_response") and p.function_response and hasattr(p.function_response, "response"):
+       r = p.function_response.response
+       if isinstance(r, dict) and "output" in r:
+        val = r["output"]
+        if isinstance(val, str):
+         if "[SYSTEM: FILES UPDATED]" in val:
+          val = val.split("[SYSTEM: FILES UPDATED]")[0].strip()
+         if _history_trunc_limit > 0 and len(val) > _history_trunc_limit:
+          val = val[:_history_trunc_limit] + "
+
+... [TRUNCATED BY SYSTEM TO SAVE TOKENS.]"
+         r["output"] = val
+  for r_idx in range(MAX_TOOL_ROUNDS + 2):
+   events.emit("request_start", payload={"provider": "gemini", "model": _model, "round": r_idx})
+   if stream_callback:
+    resp = _gemini_chat.send_message_stream(payload)
+    txt_chunks = []
+    for chunk in resp:
+     c_txt = chunk.text
+     if c_txt:
+      txt_chunks.append(c_txt)
+      stream_callback(c_txt)
+    txt = "".join(txt_chunks)
+    calls = [p.function_call for c in resp.candidates if getattr(c, "content", None) for p in c.content.parts if hasattr(p, "function_call") and p.function_call]
+    usage = {"input_tokens": getattr(resp.usage_metadata, "prompt_token_count", 0), "output_tokens": getattr(resp.usage_metadata, "candidates_token_count", 0)}
+    cached_tokens = getattr(resp.usage_metadata, "cached_content_token_count", None)
+    if cached_tokens: usage["cache_read_input_tokens"] = cached_tokens
+   else:
+    resp = _gemini_chat.send_message(payload)
+    txt = "
+".join(p.text for c in resp.candidates if getattr(c, "content", None) for p in c.content.parts if hasattr(p, "text") and p.text)
+    calls = [p.function_call for c in resp.candidates if getattr(c, "content", None) for p in c.content.parts if hasattr(p, "function_call") and p.function_call]
+    usage = {"input_tokens": getattr(resp.usage_metadata, "prompt_token_count", 0), "output_tokens": getattr(resp.usage_metadata, "candidates_token_count", 0)}
+    cached_tokens = getattr(resp.usage_metadata, "cached_content_token_count", None)
+    if cached_tokens: usage["cache_read_input_tokens"] = cached_tokens
+   if txt: all_text.append(txt)
+   events.emit("response_received", payload={"provider": "gemini", "model": _model, "usage": usage, "round": r_idx})
+   reason = resp.candidates[0].finish_reason.name if resp.candidates and hasattr(resp.candidates[0], "finish_reason") else "STOP"
+   _append_comms("IN", "response", {"round": r_idx, "stop_reason": reason, "text": txt, "tool_calls": [{"name": c.name, "args": dict(c.args)} for c in calls], "usage": usage})
+   total_in = usage.get("input_tokens", 0)
+   if total_in > _GEMINI_MAX_INPUT_TOKENS * 0.4 and _gemini_chat and _get_gemini_history_list(_gemini_chat):
+    hist = _get_gemini_history_list(_gemini_chat)
+    dropped = 0
+    while len(hist) > 4 and total_in > _GEMINI_MAX_INPUT_TOKENS * 0.3:
+     saved = 0
+     for _ in range(2):
+      if not hist: break
+      for p in hist[0].parts:
+       if hasattr(p, "text") and p.text: saved += int(len(p.text) / _CHARS_PER_TOKEN)
+       elif hasattr(p, "function_response") and p.function_response:
+        r = getattr(p.function_response, "response", {})
+        if isinstance(r, dict): saved += int(len(str(r.get("output", ""))) / _CHARS_PER_TOKEN)
+      hist.pop(0)
+      dropped += 1
+     total_in -= max(saved, 200)
+    if dropped > 0: _append_comms("OUT", "request", {"message": f"[GEMINI HISTORY TRIMMED: dropped {dropped} old entries]"})
+   if not calls or r_idx > MAX_TOOL_ROUNDS: break
+   f_resps: list[types.Part] = []
+   log: list[dict[str, Any]] = []
+   for i, fc in enumerate(calls):
+    name, args = fc.name, dict(fc.args)
+    if pre_tool_callback:
+     payload_str = json.dumps({"tool": name, "args": args})
+     if not pre_tool_callback(payload_str):
+      out = "USER REJECTED: tool execution cancelled"
+      f_resps.append(types.Part.from_function_response(name=name, response={"output": out}))
+      log.append({"tool_use_id": name, "content": out})
+      continue
+    events.emit("tool_execution", payload={"status": "started", "tool": name, "args": args, "round": r_idx})
+    if name in mcp_client.TOOL_NAMES:
+     _append_comms("OUT", "tool_call", {"name": name, "args": args})
+     out = mcp_client.dispatch(name, args)
+    elif name == TOOL_NAME:
+     scr = args.get("script", "")
+     _append_comms("OUT", "tool_call", {"name": TOOL_NAME, "script": scr})
+     out = _run_script(scr, base_dir, qa_callback)
+    else: out = f"ERROR: unknown tool '{name}'"
+    if i == len(calls) - 1:
+     if file_items:
+      file_items, changed = _reread_file_items(file_items)
+      ctx = _build_file_diff_text(changed)
+      if ctx: out += f"
+
+[SYSTEM: FILES UPDATED]
+
+{ctx}"
+     if r_idx == MAX_TOOL_ROUNDS: out += "
+
+[SYSTEM: MAX ROUNDS. PROVIDE FINAL ANSWER.]"
+    out = _truncate_tool_output(out)
+    _cumulative_tool_bytes += len(out)
+    f_resps.append(types.Part.from_function_response(name=name, response={"output": out}))
+    log.append({"tool_use_id": name, "content": out})
+    events.emit("tool_execution", payload={"status": "completed", "tool": name, "result": out, "round": r_idx})
+   if _cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    f_resps.append(types.Part.from_text(f"SYSTEM WARNING: Cumulative tool output exceeded {_MAX_TOOL_OUTPUT_BYTES // 1000}KB budget."))
+    _append_comms("OUT", "request", {"message": f"[TOOL OUTPUT BUDGET EXCEEDED: {_cumulative_tool_bytes} bytes]"})
+   _append_comms("OUT", "tool_result_send", {"results": log})
+   payload = f_resps
+  return "
+
+".join(all_text) if all_text else "(No text returned)"
+ except Exception as e: raise _classify_gemini_error(e) from e
+'''
+
+_SEND_ANTHROPIC_NEW = '''def _send_anthropic(md_content: str, user_message: str, base_dir: str, file_items: list[dict[str, Any]] | None = None, discussion_history: str = "", pre_tool_callback: Optional[Callable[[str], bool]] = None, qa_callback: Optional[Callable[[str], str]] = None, stream_callback: Optional[Callable[[str], None]] = None) -> str:
+ try:
+  _ensure_anthropic_client()
+  mcp_client.configure(file_items or [], [base_dir])
+  stable_prompt = _get_combined_system_prompt()
+  stable_blocks = [{"type": "text", "text": stable_prompt, "cache_control": {"type": "ephemeral"}}]
+  context_text = f"
+
+<context>
+{md_content}
+</context>"
+  context_blocks = _build_chunked_context_blocks(context_text)
+  system_blocks = stable_blocks + context_blocks
+  if discussion_history and not _anthropic_history:
+   user_content: list[dict[str, Any]] = [{"type": "text", "text": f"[DISCUSSION HISTORY]
+
+{discussion_history}
+
+---
+
+{user_message}"}]
+  else:
+   user_content = [{"type": "text", "text": user_message}]
+  for msg in _anthropic_history:
+   if msg.get("role") == "user" and isinstance(msg.get("content"), list):
+    modified = False
+    for block in msg["content"]:
+     if isinstance(block, dict) and block.get("type") == "tool_result":
+      t_content = block.get("content", "")
+      if _history_trunc_limit > 0 and isinstance(t_content, str) and len(t_content) > _history_trunc_limit:
+       block["content"] = t_content[:_history_trunc_limit] + "
+
+... [TRUNCATED BY SYSTEM]"
+       modified = True
+    if modified: _invalidate_token_estimate(msg)
+  _strip_cache_controls(_anthropic_history)
+  _repair_anthropic_history(_anthropic_history)
+  _anthropic_history.append({"role": "user", "content": user_content})
+  _add_history_cache_breakpoint(_anthropic_history)
+  all_text_parts: list[str] = []
+  _cumulative_tool_bytes = 0
+  def _strip_private_keys(history: list[dict[str, Any]]) -> list[dict[str, Any]]:
+   return [{k: v for k, v in m.items() if not k.startswith("_")} for m in history]
+  for round_idx in range(MAX_TOOL_ROUNDS + 2):
+   dropped = _trim_anthropic_history(system_blocks, _anthropic_history)
+   if dropped > 0:
+    est_tokens = _estimate_prompt_tokens(system_blocks, _anthropic_history)
+    _append_comms("OUT", "request", {"message": f"[HISTORY TRIMMED: dropped {dropped} old messages]"})
+   events.emit("request_start", payload={"provider": "anthropic", "model": _model, "round": round_idx})
+   if stream_callback:
+    with _anthropic_client.messages.stream(
+     model=_model,
+     max_tokens=_max_tokens,
+     temperature=_temperature,
+     system=system_blocks,
+     tools=_get_anthropic_tools(),
+     messages=_strip_private_keys(_anthropic_history),
+    ) as stream:
+     for event in stream:
+      if event.type == "content_block_delta" and event.delta.type == "text_delta":
+       stream_callback(event.delta.text)
+     response = stream.get_final_message()
+   else:
+    response = _anthropic_client.messages.create(
+     model=_model,
+     max_tokens=_max_tokens,
+     temperature=_temperature,
+     system=system_blocks,
+     tools=_get_anthropic_tools(),
+     messages=_strip_private_keys(_anthropic_history),
+    )
+   serialised_content = [_content_block_to_dict(b) for b in response.content]
+   _anthropic_history.append({"role": "assistant", "content": serialised_content})
+   text_blocks = [b.text for b in response.content if hasattr(b, "text") and b.text]
+   if text_blocks: all_text_parts.append("
+".join(text_blocks))
+   tool_use_blocks = [{"id": b.id, "name": b.name, "input": b.input} for b in response.content if getattr(b, "type", None) == "tool_use"]
+   usage_dict: dict[str, Any] = {}
+   if response.usage:
+    usage_dict["input_tokens"] = response.usage.input_tokens
+    usage_dict["output_tokens"] = response.usage.output_tokens
+    for k in ["cache_creation_input_tokens", "cache_read_input_tokens"]:
+     val = getattr(response.usage, k, None)
+     if val is not None: usage_dict[k] = val
+   events.emit("response_received", payload={"provider": "anthropic", "model": _model, "usage": usage_dict, "round": round_idx})
+   _append_comms("IN", "response", {"round": round_idx, "stop_reason": response.stop_reason, "text": "
+".join(text_blocks), "tool_calls": tool_use_blocks, "usage": usage_dict})
+   if response.stop_reason != "tool_use" or not tool_use_blocks: break
+   if round_idx > MAX_TOOL_ROUNDS: break
+   tool_results: list[dict[str, Any]] = []
+   for block in response.content:
+    if getattr(block, "type", None) != "tool_use": continue
+    b_name, b_id, b_input = block.name, block.id, block.input
+    if pre_tool_callback:
+     if not pre_tool_callback(json.dumps({"tool": b_name, "args": b_input})):
+      tool_results.append({"type": "tool_result", "tool_use_id": b_id, "content": "USER REJECTED: tool execution cancelled"})
+      continue
+    events.emit("tool_execution", payload={"status": "started", "tool": b_name, "args": b_input, "round": round_idx})
+    if b_name in mcp_client.TOOL_NAMES:
+     _append_comms("OUT", "tool_call", {"name": b_name, "id": b_id, "args": b_input})
+     output = mcp_client.dispatch(b_name, b_input)
+    elif b_name == TOOL_NAME:
+     scr = b_input.get("script", "")
+     _append_comms("OUT", "tool_call", {"name": TOOL_NAME, "id": b_id, "script": scr})
+     output = _run_script(scr, base_dir, qa_callback)
+    else: output = f"ERROR: unknown tool '{b_name}'"
+    truncated = _truncate_tool_output(output)
+    _cumulative_tool_bytes += len(truncated)
+    tool_results.append({"type": "tool_result", "tool_use_id": b_id, "content": truncated})
+    _append_comms("IN", "tool_result", {"name": b_name, "id": b_id, "output": output})
+    events.emit("tool_execution", payload={"status": "completed", "tool": b_name, "result": output, "round": round_idx})
+   if _cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    tool_results.append({"type": "text", "text": "SYSTEM WARNING: Cumulative tool output exceeded budget."})
+   if file_items:
+    file_items, changed = _reread_file_items(file_items)
+    refreshed_ctx = _build_file_diff_text(changed)
+    if refreshed_ctx: tool_results.append({"type": "text", "text": f"[FILES UPDATED]
+
+{refreshed_ctx}"})
+   if round_idx == MAX_TOOL_ROUNDS: tool_results.append({"type": "text", "text": "SYSTEM WARNING: MAX TOOL ROUNDS REACHED."})
+   _anthropic_history.append({"role": "user", "content": tool_results})
+   _append_comms("OUT", "tool_result_send", {"results": [{"tool_use_id": r["tool_use_id"], "content": r["content"]} for r in tool_results if r.get("type") == "tool_result"]})
+  return "
+
+".join(all_text_parts) if all_text_parts else "(No text returned)"
+ except Exception as exc: raise _classify_anthropic_error(exc) from exc
+'''
+
+_SEND_DEEPSEEK_NEW = '''def _send_deepseek(md_content: str, user_message: str, base_dir: str,
+ file_items: list[dict[str, Any]] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str], bool]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None) -> str:
+ try:
+  mcp_client.configure(file_items or [], [base_dir])
+  creds = _load_credentials()
+  api_key = creds.get("deepseek", {}).get("api_key")
+  if not api_key: raise ValueError("DeepSeek API key not found")
+  api_url = "https://api.deepseek.com/chat/completions"
+  headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+  current_api_messages: list[dict[str, Any]] = []
+  with _deepseek_history_lock:
+   for msg in _deepseek_history: current_api_messages.append(msg)
+  initial_user_message_content = user_message
+  if discussion_history: initial_user_message_content = f"[DISCUSSION HISTORY]
+
+{discussion_history}
+
+---
+
+{user_message}"
+  current_api_messages.append({"role": "user", "content": initial_user_message_content})
+  request_payload: dict[str, Any] = {"model": _model, "messages": current_api_messages, "temperature": _temperature, "max_tokens": _max_tokens, "stream": stream}
+  sys_msg = {"role": "system", "content": f"{_get_combined_system_prompt()}
+
+<context>
+{md_content}
+</context>"}
+  request_payload["messages"].insert(0, sys_msg)
+  all_text_parts: list[str] = []
+  _cumulative_tool_bytes = 0
+  round_idx = 0
+  while round_idx <= MAX_TOOL_ROUNDS + 1:
+   events.emit("request_start", payload={"provider": "deepseek", "model": _model, "round": round_idx, "streaming": stream})
+   try:
+    response = requests.post(api_url, headers=headers, json=request_payload, timeout=60, stream=stream)
+    response.raise_for_status()
+   except requests.exceptions.RequestException as e: raise _classify_deepseek_error(e) from e
+   if stream:
+    aggregated_content, aggregated_tool_calls, aggregated_reasoning = "", [], ""
+    current_usage, final_finish_reason = {}, "stop"
+    for line in response.iter_lines():
+     if not line: continue
+     decoded = line.decode('utf-8')
+     if decoded.startswith('data: '):
+      chunk_str = decoded[len('data: '):]
+      if chunk_str.strip() == '[DONE]': continue
+      try:
+       chunk = json.loads(chunk_str)
+       delta = chunk.get("choices", [{}])[0].get("delta", {})
+       if delta.get("content"):
+        aggregated_content += delta["content"]
+        if stream_callback: stream_callback(delta["content"])
+       if delta.get("reasoning_content"): aggregated_reasoning += delta["reasoning_content"]
+       if delta.get("tool_calls"):
+        for tc_delta in delta["tool_calls"]:
+         idx = tc_delta.get("index", 0)
+         while len(aggregated_tool_calls) <= idx: aggregated_tool_calls.append({"id": "", "type": "function", "function": {"name": "", "arguments": ""}})
+         target = aggregated_tool_calls[idx]
+         if tc_delta.get("id"): target["id"] = tc_delta["id"]
+         if tc_delta.get("function", {}).get("name"): target["function"]["name"] += tc_delta["function"]["name"]
+         if tc_delta.get("function", {}).get("arguments"): target["function"]["arguments"] += tc_delta["function"]["arguments"]
+       if chunk.get("choices", [{}])[0].get("finish_reason"): final_finish_reason = chunk["choices"][0]["finish_reason"]
+       if chunk.get("usage"): current_usage = chunk["usage"]
+      except json.JSONDecodeError: continue
+    assistant_text, tool_calls_raw, reasoning_content, finish_reason, usage = aggregated_content, aggregated_tool_calls, aggregated_reasoning, final_finish_reason, current_usage
+   else:
+    response_data = response.json()
+    choices = response_data.get("choices", [])
+    if not choices: break
+    choice = choices[0]
+    message = choice.get("message", {})
+    assistant_text, tool_calls_raw, reasoning_content, finish_reason, usage = message.get("content", ""), message.get("tool_calls", []), message.get("reasoning_content", ""), choice.get("finish_reason", "stop"), response_data.get("usage", {})
+   full_assistant_text = (f"<thinking>
+{reasoning_content}
+</thinking>
+" if reasoning_content else "") + assistant_text
+   with _deepseek_history_lock:
+    msg_to_store = {"role": "assistant", "content": assistant_text}
+    if reasoning_content: msg_to_store["reasoning_content"] = reasoning_content
+    if tool_calls_raw: msg_to_store["tool_calls"] = tool_calls_raw
+    _deepseek_history.append(msg_to_store)
+   if full_assistant_text: all_text_parts.append(full_assistant_text)
+   _append_comms("IN", "response", {"round": round_idx, "stop_reason": finish_reason, "text": full_assistant_text, "tool_calls": tool_calls_raw, "usage": usage, "streaming": stream})
+   if finish_reason != "tool_calls" and not tool_calls_raw: break
+   if round_idx > MAX_TOOL_ROUNDS: break
+   tool_results_for_history: list[dict[str, Any]] = []
+   for i, tc_raw in enumerate(tool_calls_raw):
+    tool_info = tc_raw.get("function", {})
+    tool_name, tool_args_str, tool_id = tool_info.get("name"), tool_info.get("arguments", "{}"), tc_raw.get("id")
+    try: tool_args = json.loads(tool_args_str)
+    except: tool_args = {}
+    if pre_tool_callback:
+     if not pre_tool_callback(json.dumps({"tool": tool_name, "args": tool_args})):
+      tool_output = "USER REJECTED: tool execution cancelled"
+      tool_results_for_history.append({"role": "tool", "tool_call_id": tool_id, "content": tool_output})
+      continue
+    events.emit("tool_execution", payload={"status": "started", "tool": tool_name, "args": tool_args, "round": round_idx})
+    if tool_name in mcp_client.TOOL_NAMES:
+     _append_comms("OUT", "tool_call", {"name": tool_name, "id": tool_id, "args": tool_args})
+     tool_output = mcp_client.dispatch(tool_name, tool_args)
+    elif tool_name == TOOL_NAME:
+     script = tool_args.get("script", "")
+     _append_comms("OUT", "tool_call", {"name": TOOL_NAME, "id": tool_id, "script": script})
+     tool_output = _run_script(script, base_dir, qa_callback)
+    else: tool_output = f"ERROR: unknown tool '{tool_name}'"
+    if i == len(tool_calls_raw) - 1:
+     if file_items:
+      file_items, changed = _reread_file_items(file_items)
+      ctx = _build_file_diff_text(changed)
+      if ctx: tool_output += f"
+
+[SYSTEM: FILES UPDATED]
+
+{ctx}"
+     if round_idx == MAX_TOOL_ROUNDS: tool_output += "
+
+[SYSTEM: MAX ROUNDS. PROVIDE FINAL ANSWER.]"
+    tool_output = _truncate_tool_output(tool_output)
+    _cumulative_tool_bytes += len(tool_output)
+    tool_results_for_history.append({"role": "tool", "tool_call_id": tool_id, "content": tool_output})
+    _append_comms("IN", "tool_result", {"name": tool_name, "id": tool_id, "output": tool_output})
+    events.emit("tool_execution", payload={"status": "completed", "tool": tool_name, "result": tool_output, "round": round_idx})
+   if _cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    tool_results_for_history.append({"role": "user", "content": "SYSTEM WARNING: Cumulative tool output exceeded budget."})
+   with _deepseek_history_lock:
+    for tr in tool_results_for_history: _deepseek_history.append(tr)
+   next_messages: list[dict[str, Any]] = []
+   with _deepseek_history_lock:
+    for msg in _deepseek_history: next_messages.append(msg)
+   next_messages.insert(0, sys_msg)
+   request_payload["messages"] = next_messages
+   round_idx += 1
+  return "
+
+".join(all_text_parts) if all_text_parts else "(No text returned)"
+ except Exception as e: raise _classify_deepseek_error(e) from e
+'''
+
+_SEND_NEW = '''def send(
+ md_content: str,
+ user_message: str,
+ base_dir: str = ".",
+ file_items: list[dict[str, Any]] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str], bool]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ enable_tools: bool = True,
+ stream_callback: Optional[Callable[[str], None]] = None,
+) -> str:
+ """
+    Sends a prompt with the full markdown context to the current AI provider.
+    Returns the final text response.
+    """
+ with _send_lock:
+  if _provider == "gemini":
+   return _send_gemini(
+    md_content, user_message, base_dir, file_items, discussion_history,
+    pre_tool_callback, qa_callback, enable_tools, stream_callback
+   )
+  elif _provider == "gemini_cli":
+   return _send_gemini_cli(
+    md_content, user_message, base_dir, file_items, discussion_history,
+    pre_tool_callback, qa_callback
+   )
+  elif _provider == "anthropic":
+   return _send_anthropic(
+    md_content, user_message, base_dir, file_items, discussion_history,
+    pre_tool_callback, qa_callback, stream_callback=stream_callback
+   )
+  elif _provider == "deepseek":
+   return _send_deepseek(
+    md_content, user_message, base_dir, file_items, discussion_history,
+    stream, pre_tool_callback, qa_callback, stream_callback
+   )
+  else:
+   raise ValueError(f"Unknown provider: {_provider}")
+'''
+
+# Use regex or simple string replacement to replace the old functions with new ones.
+import re
+
+def replace_func(content, func_name, new_body):
+ # This is tricky because functions can be complex.
+ # I'll just use a marker based approach for this specific file.
+ start_marker = f'def {func_name}('
+ # Find the next 'def ' or end of file
+ start_idx = content.find(start_marker)
+ if start_idx == -1: return content
+ 
+ # Find the end of the function (rough estimation based on next def at column 0)
+ next_def = re.search(r'
+
+def ', content[start_idx+1:])
+ if next_def:
+  end_idx = start_idx + 1 + next_def.start()
+ else:
+  end_idx = len(content)
+ 
+ return content[:start_idx] + new_body + content[end_idx:]
+
+# Final content construction
+content = replace_func(content, '_send_gemini', _SEND_GEMINI_NEW)
+content = replace_func(content, '_send_anthropic', _SEND_ANTHROPIC_NEW)
+content = replace_func(content, '_send_deepseek', _SEND_DEEPSEEK_NEW)
+content = replace_func(content, 'send', _SEND_NEW)
+
+# Remove the duplicated parts at the end if any
+marker = 'import json
+from typing import Any, Callable, Optional, List'
+if marker in content:
+ content = content[:content.find(marker)]
+
+with open(path, 'w', encoding='utf-8') as f:
+ f.write(content)

conductor/archive/comprehensive_gui_ux_20260228/index.md

@@ -0,0 +1,5 @@
+# Track comprehensive_gui_ux_20260228 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/comprehensive_gui_ux_20260228/metadata.json

@@ -0,0 +1,10 @@
+{
+    "description":  "Enhance existing MMA orchestration GUI: tier stream panels, DAG editing, cost tracking, conductor lifecycle forms, track-scoped discussions, approval indicators, visual polish.",
+    "track_id":  "comprehensive_gui_ux_20260228",
+    "type":  "feature",
+    "created_at":  "2026-03-01T08:42:57Z",
+    "status":  "completed",
+    "updated_at":  "2026-03-01T20:15:00Z",
+    "refined_by":  "claude-opus-4-6 (1M context)",
+    "refined_from_commit":  "08e003a"
+}

conductor/archive/comprehensive_gui_ux_20260228/plan.md

@@ -0,0 +1,58 @@
+# Implementation Plan: Comprehensive Conductor & MMA GUI UX
+
+Architecture reference: [docs/guide_architecture.md](../../docs/guide_architecture.md), [docs/guide_mma.md](../../docs/guide_mma.md)
+
+## Phase 1: Tier Stream Panels & Approval Indicators
+Focus: Make all 4 tier output streams visible and indicate pending approvals.
+
+- [x] Task 1.1: Replace the single Tier 1 strategy text box in `_render_mma_dashboard` (gui_2.py:2700-2701) with four collapsible sections — one per tier. Each section uses `imgui.collapsing_header(f"Tier {N}: {label}")` wrapping a `begin_child` scrollable region (200px height). Tier 1 = "Strategy", Tier 2 = "Tech Lead", Tier 3 = "Workers", Tier 4 = "QA". Tier 3 should aggregate all `mma_streams` keys containing "Tier 3" with ticket ID sub-headers. Each section auto-scrolls to bottom when new content arrives (track previous scroll position, scroll only if user was at bottom).
+- [x] Task 1.2: Add approval state indicators to the MMA dashboard. After the "Status:" line in `_render_mma_dashboard` (gui_2.py:2672-2676), check `self._pending_mma_spawn`, `self._pending_mma_approval`, and `self._pending_ask_dialog`. When any is active, render a colored blinking badge: `imgui.text_colored(ImVec4(1,0.3,0.3,1), "APPROVAL PENDING")` using `sin(time.time()*5)` for alpha pulse. Also add a `imgui.same_line()` button "Go to Approval" that scrolls/focuses the relevant dialog.
+- [x] Task 1.3: Write unit tests verifying: (a) `mma_streams` with keys "Tier 1", "Tier 2 (Tech Lead)", "Tier 3: T-001", "Tier 4 (QA)" are all rendered (check by mocking `imgui.collapsing_header` calls); (b) approval indicators appear when `_pending_mma_spawn is not None`.
+- [x] Task 1.4: Conductor - User Manual Verification 'Phase 1: Tier Stream Panels & Approval Indicators' (Protocol in workflow.md)
+
+## Phase 2: Cost Tracking & Enhanced Token Table
+Focus: Add cost estimation to the existing token usage display.
+
+- [x] Task 2.1: Create a new module `cost_tracker.py` with a `MODEL_PRICING` dict mapping model name patterns to `{"input_per_mtok": float, "output_per_mtok": float}`. Include entries for: `gemini-2.5-flash-lite` ($0.075/$0.30), `gemini-2.5-flash` ($0.15/$0.60), `gemini-3-flash-preview` ($0.15/$0.60), `gemini-3.1-pro-preview` ($3.50/$10.50), `claude-*-sonnet` ($3/$15), `claude-*-opus` ($15/$75), `deepseek-v3` ($0.27/$1.10). Function: `estimate_cost(model: str, input_tokens: int, output_tokens: int) -> float` that does pattern matching on model name and returns dollar cost.
+- [x] Task 2.2: Extend the token usage table in `_render_mma_dashboard` (gui_2.py:2685-2699) from 3 columns to 5: add "Est. Cost" and "Model". Populate using `cost_tracker.estimate_cost()` with the model name from `self.mma_tier_usage` (need to extend `tier_usage` dict in `ConductorEngine._push_state` to include model name per tier, or use a default mapping: Tier 1 → `gemini-3.1-pro-preview`, Tier 2 → `gemini-3-flash-preview`, Tier 3 → `gemini-2.5-flash-lite`, Tier 4 → `gemini-2.5-flash-lite`). Show total cost row at bottom.
+- [x] Task 2.3: Write tests for `cost_tracker.estimate_cost()` covering all model patterns and edge cases (unknown model returns 0).
+- [x] Task 2.4: Conductor - User Manual Verification 'Phase 2: Cost Tracking & Enhanced Token Table' (Protocol in workflow.md)
+
+## Phase 3: Track Proposal Editing & Conductor Lifecycle Forms
+Focus: Make track proposals editable and add conductor setup/newTrack GUI forms.
+
+- [x] Task 3.1: Enhance `_render_track_proposal_modal` (gui_2.py:2146-2173) to make track titles and goals editable. Replace `imgui.text_colored` for title with `imgui.input_text(f"##track_title_{idx}", track['title'])`. Replace `imgui.text_wrapped` for goal with `imgui.input_text_multiline(f"##track_goal_{idx}", track['goal'], ImVec2(-1, 60))`. Add a "Remove" button per track (`imgui.button(f"Remove##{idx}")`) that pops from `self.proposed_tracks`. Edited values must be written back to `self.proposed_tracks[idx]`.
+- [x] Task 3.2: Add a "Conductor Setup" collapsible section at the top of the MMA dashboard (before the Track Browser). Contains a "Run Setup" button. On click, reads `conductor/workflow.md`, `conductor/tech-stack.md`, `conductor/product.md` using `Path.read_text()`, computes a readiness summary (files found, line counts, track count via `project_manager.get_all_tracks()`), and displays it in a read-only text region. This is informational only — no backend changes.
+- [x] Task 3.3: Add a "New Track" form below the Track Browser. Fields: track name (input_text), description (input_text_multiline), type dropdown (feature/chore/fix via `imgui.combo`). "Create" button calls a new helper `_cb_create_track(name, desc, type)` that: creates `conductor/tracks/{name}_{date}/` directory, writes a minimal `spec.md` from the description, writes an empty `plan.md` template, writes `metadata.json` with the track ID/type/status="new", then refreshes `self.tracks` via `project_manager.get_all_tracks()`.
+- [x] Task 3.4: Write tests for track creation helper: verify directory structure, file contents, and metadata.json format. Test proposal modal editing by verifying `proposed_tracks` list is mutated correctly.
+- [x] Task 3.5: Conductor - User Manual Verification 'Phase 3: Track Proposal Editing & Conductor Lifecycle Forms' (Protocol in workflow.md)
+
+## Phase 4: DAG Editing & Track-Scoped Discussion
+Focus: Allow GUI-based ticket manipulation and track-specific discussion history.
+
+- [x] Task 4.1: Add an "Add Ticket" button below the Task DAG section in `_render_mma_dashboard`. On click, show an inline form: ticket ID (input_text, default auto-increment like "T-NNN"), description (input_text_multiline), target_file (input_text), depends_on (multi-select or comma-separated input of existing ticket IDs). "Create" button appends a new `Ticket` dict to `self.active_tickets` with `status="todo"` and triggers `_push_mma_state_update()` to synchronize the ConductorEngine. Cancel hides the form. Store the form visibility in `self._show_add_ticket_form: bool`.
+- [x] Task 4.2: Add a "Delete" button to each DAG node in `_render_ticket_dag_node` (gui_2.py:2770-2773, after the Skip button). On click, show a confirmation popup. On confirm, remove the ticket from `self.active_tickets`, remove it from all other tickets' `depends_on` lists, and push state update. Only allow deletion of `todo` or `blocked` tickets (not `in_progress` or `completed`).
+- [x] Task 4.3: Add track-scoped discussion support. In `_render_discussion_panel` (gui_2.py:2295-2483), add a toggle checkbox "Track Discussion" (visible only when `self.active_track` is set). When toggled ON: load history via `project_manager.load_track_history(self.active_track.id, base_dir)` into `self.disc_entries`, set a flag `self._track_discussion_active = True`. When toggled OFF or track changes: restore project discussion. On save/flush, if `_track_discussion_active`, write to track history file instead of project history.
+- [x] Task 4.4: Write tests for: (a) adding a ticket updates `active_tickets` and has correct default fields; (b) deleting a ticket removes it from all `depends_on` references; (c) track discussion toggle switches `disc_entries` source.
+- [x] Task 4.5: Conductor - User Manual Verification 'Phase 4: DAG Editing & Track-Scoped Discussion' (Protocol in workflow.md)
+
+## Phase 5: Visual Polish & Integration Testing
+Focus: Dense, responsive dashboard with arcade aesthetics and end-to-end verification.
+
+- [x] Task 5.1: Add color-coded styling to the Track Browser table. Status column uses colored text: "new" = gray, "active" = yellow, "done" = green, "blocked" = red. Progress bar uses `imgui.push_style_color` to tint: <33% red, 33-66% yellow, >66% green.
+- [x] Task 5.2: Improve the DAG tree nodes with status-colored left borders. Use `imgui.get_cursor_screen_pos()` and `imgui.get_window_draw_list().add_rect_filled()` to draw a 4px colored strip to the left of each tree node matching its status color.
+- [x] Task 5.3: Add a "Dashboard Summary" header line at the top of `_render_mma_dashboard` showing: `Track: {name} | Tickets: {done}/{total} | Cost: ${total_cost:.4f} | Status: {mma_status}` in a single dense line with colored segments.
+- [x] Task 5.4: Write an end-to-end integration test (extending `tests/visual_sim_mma_v2.py` or creating `tests/visual_sim_gui_ux.py`) that verifies via `ApiHookClient`: (a) track creation form produces correct directory structure; (b) tier streams are populated during MMA execution; (c) approval indicators appear when expected; (d) cost tracking shows non-zero values after execution.
+- [x] Task 5.5: Verify all new UI elements maintain >30 FPS via `get_ui_performance` during a full MMA simulation run.
+- [x] Task 5.6: Conductor - User Manual Verification 'Phase 5: Visual Polish & Integration Testing' (Protocol in workflow.md)
+
+## Phase 6: Live Worker Streaming & Engine Enhancements
+Focus: Make MMA execution observable in real-time and configurable from the GUI. Currently workers are black boxes until completion.
+
+- [x] Task 6.1: Wire `ai_client.comms_log_callback` to per-ticket streams during `run_worker_lifecycle` (multi_agent_conductor.py:207-300). Before calling `ai_client.send()`, set `ai_client.comms_log_callback` to a closure that pushes intermediate text chunks to the GUI via `_queue_put(event_queue, loop, "response", {"text": chunk, "stream_id": f"Tier 3 (Worker): {ticket.id}", "status": "streaming..."})`. After `send()` returns, restore the original callback. This gives real-time output streaming to the Tier 3 stream panels from Phase 1.
+- [x] Task 6.2: Add per-tier model configuration to the MMA dashboard. Below the token usage table in `_render_mma_dashboard`, add a collapsible "Tier Model Config" section with 4 rows (Tier 1-4). Each row: tier label + `imgui.combo` dropdown populated from `ai_client.list_models()` (cached). Store selections in `self.mma_tier_models: dict[str, str]` with defaults from `mma_exec.get_model_for_role()`. On change, write to `self.project["mma"]["tier_models"]` for persistence.
+- [x] Task 6.3: Wire per-tier model config into the execution pipeline. In `ConductorEngine.run` (multi_agent_conductor.py:105-135), when creating `WorkerContext`, read the model name from the GUI's `mma_tier_models` dict (passed via the event queue or stored on the engine). Pass it through to `run_worker_lifecycle` which should use it in `ai_client.set_provider`/`ai_client.set_model_params` before calling `send()`. Also update `mma_exec.py:get_model_for_role` to accept an override parameter.
+- [x] Task 6.4: Add parallel DAG execution. In `ConductorEngine.run` (multi_agent_conductor.py:100-135), replace the sequential `for ticket in ready_tasks` loop with `asyncio.gather(*[loop.run_in_executor(None, run_worker_lifecycle, ...) for ticket in ready_tasks])`. Each worker already gets its own `ai_client.reset_session()` so they're isolated. Guard with `ai_client._send_lock` awareness — if the lock serializes all sends, parallel execution won't help. In that case, create per-worker provider instances or use separate session IDs. Mark this task as exploratory — if `_send_lock` blocks parallelism, document the constraint and defer.
+- [x] Task 6.5: Add automatic retry with model escalation. In `ConductorEngine.run`, after `run_worker_lifecycle` returns, check if `ticket.status == "blocked"`. If so, and `retry_count < max_retries` (default 2), increment retry count, escalate the model (e.g., flash-lite → flash → pro), and re-execute. Store `retry_count` as a field on the ticket dict. After max retries, leave as blocked.
+- [x] Task 6.6: Write tests for: (a) streaming callback pushes intermediate content to event queue; (b) per-tier model config persists to project TOML; (c) retry escalation increments model tier.
+- [x] Task 6.7: Conductor - User Manual Verification 'Phase 6: Live Worker Streaming & Engine Enhancements' (Protocol in workflow.md)

conductor/archive/comprehensive_gui_ux_20260228/spec.md

@@ -0,0 +1,112 @@
+# Track Specification: Comprehensive Conductor & MMA GUI UX
+
+## Overview
+
+This track enhances the existing MMA orchestration GUI from its current functional-but-minimal state to a production-quality control surface. The existing implementation already has a working Track Browser, DAG tree visualizer, epic planning flow, approval dialogs, and token usage table. This track focuses on the **gaps**: dedicated tier stream panels, DAG editing, track-scoped discussions, conductor lifecycle GUI forms, cost tracking, and visual polish.
+
+## Current State Audit (as of 08e003a)
+
+### Already Implemented (DO NOT re-implement)
+- **Track Browser table** (`_render_mma_dashboard`, lines 2633-2660): Title, status, progress bar, Load button per track.
+- **Epic Planning** (`_render_projects_panel`, lines 1968-1983 + `_cb_plan_epic`): Input field + "Plan Epic (Tier 1)" button, background thread orchestration.
+- **Track Proposal Modal** (`_render_track_proposal_modal`, lines 2146-2173): Shows proposed tracks, Start/Accept/Cancel.
+- **Step Mode toggle**: Checkbox for "Step Mode (HITL)" with `self.mma_step_mode`.
+- **Active Track Info**: Description + ticket progress bar.
+- **Token Usage Table**: Per-tier input/output display in a 3-column ImGui table.
+- **Tier 1 Strategy Stream**: `mma_streams.get("Tier 1")` rendered as read-only multiline (150px).
+- **Task DAG Tree** (`_render_ticket_dag_node`, lines 2726-2785): Recursive tree with color-coded status (gray/yellow/green/red/orange), tooltips showing ID/target/description/dependencies/worker-stream, Retry/Skip buttons.
+- **Spawn Interceptor** (`MMASpawnApprovalDialog`): Editable prompt, context_md, abort capability.
+- **MMA Step Approval** (`MMAApprovalDialog`): Editable payload, approve/reject.
+- **Script Confirmation** (`ConfirmDialog`): Editable script, approve/reject.
+- **Comms History Panel** (`_render_comms_history_panel`, lines 2859-2984).
+- **Tool Calls Panel** (`_render_tool_calls_panel`, lines 2787-2857).
+- **Performance Monitor**: FPS, Frame Time, CPU, Input Lag via `perf_monitor`.
+
+### Gaps to Fill (This Track's Scope)
+
+1. **Tier Stream Panels**: Only Tier 1 gets a dedicated text box. Tier 2/3/4 streams exist in `mma_streams` dict but have no dedicated UI. Tier 3 output is tooltip-only on DAG nodes. No Tier 2 (Tech Lead) or Tier 4 (QA) visibility at all.
+2. **DAG Editing**: Can Retry/Skip tickets but cannot reorder, insert, or delete tasks from the GUI.
+3. **Conductor Lifecycle Forms**: `/conductor:setup` and `/conductor:newTrack` have no GUI equivalents — they're CLI-only. Users must use slash commands or the epic planning flow.
+4. **Track-Scoped Discussion**: Discussions are global. When a track is active, the discussion panel should optionally isolate to that track's context. `project_manager.load_track_history()` exists but isn't wired to the GUI.
+5. **Cost Estimation**: Token counts are displayed but not converted to estimated cost per tier or per track.
+6. **Approval State Indicators**: The dashboard doesn't visually indicate when a spawn/step/tool approval is pending. `pending_mma_spawn_approval`, `pending_mma_step_approval`, `pending_tool_approval` are tracked but not rendered.
+7. **Track Proposal Editing**: The modal shows proposed tracks read-only. No ability to edit track titles, goals, or remove unwanted tracks before accepting.
+8. **Stream Scrollability**: Tier 1 stream is a 150px non-scrolling text box. Needs proper scrollable, resizable panels for all tier streams.
+
+## Goals
+
+1. **Tier Stream Visibility**: Dedicated, scrollable panels for all 4 tier output streams (Tier 1 Strategy, Tier 2 Tech Lead, Tier 3 Worker, Tier 4 QA) with auto-scroll and copy support.
+2. **DAG Manipulation**: Add/remove tickets from the active track's DAG via the GUI, with dependency validation.
+3. **Conductor GUI Forms**: Setup and track creation forms that invoke the same logic as the CLI slash commands.
+4. **Track-Scoped Discussions**: Switch the discussion panel to track-specific history when a track is active.
+5. **Cost Tracking**: Per-tier and per-track cost estimation based on model pricing.
+6. **Approval Indicators**: Clear visual cues (blinking, color changes) when any approval gate is pending.
+7. **Track Proposal Editing**: Allow editing/removing proposed tracks before acceptance.
+8. **Polish & Density**: Make the dashboard information-dense and responsive to the MMA engine's state.
+
+## Functional Requirements
+
+### Tier Stream Panels
+- Four collapsible/expandable text regions in the MMA dashboard, one per tier.
+- Auto-scroll to bottom on new content. Toggle for manual scroll lock.
+- Each stream populated from `self.mma_streams` keyed by tier prefix.
+- Tier 3 streams: aggregate all `"Tier 3: T-xxx"` keyed entries, render with ticket ID headers.
+
+### DAG Editing
+- "Add Ticket" button: opens an inline form (ID, description, target_file, depends_on dropdown).
+- "Remove Ticket" button on each DAG node (with confirmation).
+- Changes must update `self.active_tickets`, rebuild the ConductorEngine's `TrackDAG`, and push state via `_push_state`.
+
+### Conductor Lifecycle Forms
+- "Setup Conductor" button that reads `conductor/workflow.md`, `conductor/tech-stack.md`, `conductor/product.md` and displays a readiness summary.
+- "New Track" form: name, description, type dropdown. Creates the track directory structure under `conductor/tracks/`.
+
+### Track-Scoped Discussion
+- When `self.active_track` is set, add a toggle "Track Discussion" that switches to `project_manager.load_track_history(track_id)`.
+- Saving flushes to the track's history file instead of the project's.
+
+### Cost Tracking
+- Model pricing table (configurable or hardcoded initial version).
+- Compute `cost = (input_tokens / 1M) * input_price + (output_tokens / 1M) * output_price` per tier.
+- Display as additional column in the existing token usage table.
+
+### Approval Indicators
+- When `_pending_mma_spawn` is not None: flash the "MMA Dashboard" tab header or show a blinking indicator.
+- When `_pending_mma_approval` is not None: similar.
+- When `_pending_ask_dialog` is True: similar.
+- Use `imgui.push_style_color` to tint the relevant UI region.
+
+### Track Proposal Editing
+- Make track titles and goals editable in the proposal modal.
+- Add a "Remove" button per proposed track.
+- Edited data flows back to `self.proposed_tracks` before acceptance.
+
+## Non-Functional Requirements
+- **Thread Safety**: All new data mutations from background threads must go through `_pending_gui_tasks`. No direct GUI state writes from non-main threads.
+- **No New Dependencies**: Use only existing Dear PyGui / imgui-bundle APIs.
+- **Performance**: New panels must not degrade FPS below 30 under normal operation. Verify via `get_ui_performance`.
+
+## Architecture Reference
+- Threading model and `_process_pending_gui_tasks` action catalog: [docs/guide_architecture.md](../../docs/guide_architecture.md)
+- MMA data structures (Ticket, Track, WorkerContext): [docs/guide_mma.md](../../docs/guide_mma.md)
+- Hook API for testing: [docs/guide_tools.md](../../docs/guide_tools.md)
+- Simulation patterns: [docs/guide_simulations.md](../../docs/guide_simulations.md)
+
+## Functional Requirements (Engine Enhancements)
+
+### Live Worker Streaming
+- During `run_worker_lifecycle`, set `ai_client.comms_log_callback` to push intermediate text chunks to the per-ticket stream via the event queue. Currently workers are black boxes until completion — both Claude Code and Gemini CLI stream in real-time. The callback should push `{"text": chunk, "stream_id": "Tier 3 (Worker): {ticket.id}", "status": "streaming..."}` events.
+
+### Per-Tier Model Configuration
+- `mma_exec.py:get_model_for_role` is hardcoded. Add a GUI section with `imgui.combo` dropdowns for each tier's model. Persist to `project["mma"]["tier_models"]`. Wire into `ConductorEngine` and `run_worker_lifecycle`.
+
+### Parallel DAG Execution
+- `ConductorEngine.run()` executes ready tickets sequentially. DAG-independent tickets should run in parallel via `asyncio.gather`. Constraint: `ai_client._send_lock` serializes all API calls — parallel workers may need separate provider instances or the lock needs to be per-session rather than global. Mark as exploratory.
+
+### Automatic Retry with Model Escalation
+- `mma_exec.py` has `--failure-count` for escalation but `ConductorEngine` doesn't use it. When a worker produces BLOCKED, auto-retry with a more capable model (up to 2 retries).
+
+## Out of Scope
+- Remote management via web browser.
+- Visual diagram generation (Dear PyGui node editor for DAG — future track).
+- Docking/floating multi-viewport layout (requires imgui docking branch investigation — future track).

conductor/archive/consolidate_cruft_and_log_taxonomy_20260228/index.md

@@ -0,0 +1,5 @@
+# Track consolidate_cruft_and_log_taxonomy_20260228 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/consolidate_cruft_and_log_taxonomy_20260228/metadata.json

@@ -0,0 +1,8 @@
+{
+    "description":  "Consolidate temp/test file cruft into a specific directory we can add to gitignore that shouldn\u0027t be tracked. Migrate existing session logs into a ./logs/sessions category. Make sure future logs get dumped into there.",
+    "track_id":  "consolidate_cruft_and_log_taxonomy_20260228",
+    "type":  "chore",
+    "created_at":  "2026-03-01T08:49:02Z",
+    "status":  "new",
+    "updated_at":  "2026-03-01T08:49:02Z"
+}

conductor/archive/consolidate_cruft_and_log_taxonomy_20260228/plan.md

@@ -0,0 +1,24 @@
+# Implementation Plan: Consolidate Temp/Test Cruft & Log Taxonomy
+
+## Phase 1: Directory Structure & Gitignore [checkpoint: 590293e]
+- [x] Task: Create `tests/artifacts/`, `logs/sessions/`, `logs/agents/`, and `logs/errors/`. (fab109e)
+- [x] Task: Update `.gitignore` to exclude `tests/artifacts/` and all `logs/` sub-folders. (fab109e)
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Directory Structure & Gitignore' (Protocol in workflow.md) (fab109e)
+
+## Phase 2: App Logic Redirection [checkpoint: 6326546]
+- [x] Task: Update `session_logger.py` to use `logs/sessions/`, `logs/agents/`, and `logs/errors/` for its outputs. (6326546)
+- [x] Task: Modify `project_manager.py` to store temporary project TOMLs in `tests/artifacts/`. (6326546)
+- [x] Task: Update `shell_runner.py` or `scripts/mma_exec.py` to use `tests/artifacts/` for its temporary scripts and outputs. (6326546)
+- [x] Task: Add foundational support (e.g., in `metadata.json` for sessions) to store "annotated names" for logs. (6326546)
+- [x] Task: Conductor - User Manual Verification 'Phase 2: App Logic Redirection' (Protocol in workflow.md) (6326546)
+
+## Phase 3: Migration Script [checkpoint: 61d513a]
+- [x] Task: Create `scripts/migrate_cruft.ps1` to identify and move existing files (e.g., `temp_*.toml`, `*.log`) from the root to their new locations. (61d513a)
+- [x] Task: Test the migration script on a few dummy files. (61d513a)
+- [x] Task: Execute the migration script and verify the project root is clean. (61d513a)
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Migration Script' (Protocol in workflow.md) (61d513a)
+
+## Phase 4: Regression Testing & Final Verification [checkpoint: 6326546]
+- [x] Task: Run a full session through the GUI and verify that all logs and temp files are created in the new sub-directories. (6326546)
+- [x] Task: Verify that `tests/artifacts/` is correctly ignored by git. (6326546)
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Regression Testing & Final Verification' (Protocol in workflow.md) (6326546)

conductor/archive/consolidate_cruft_and_log_taxonomy_20260228/spec.md

@@ -0,0 +1,32 @@
+# Track Specification: Consolidate Temp/Test Cruft & Log Taxonomy
+
+## Overview
+This track focuses on cleaning up the project root by consolidating temporary and test-related files into a dedicated directory and establishing a structured taxonomy for session logs. This will improve project organization and make manual file exploration easier before a dedicated GUI log viewer is implemented.
+
+## Goals
+1.  **Establish Artifacts Directory:** Create `tests/artifacts/` as the primary location for temporary test data and non-persistent cruft.
+2.  **Gitignore Updates:** Update `.gitignore` to ensure this new directory and its contents are not tracked.
+3.  **Log Taxonomy Setup:** Organize `./logs/` into clear sub-categories: `sessions/`, `agents/`, and `errors/`.
+4.  **Migration Script:** Provide a PowerShell script to move existing files and logs into the new structure.
+5.  **Future-Proofing:** Update the application logic (e.g., `session_logger.py`, `project_manager.py`) to ensure all future logs and temp files are created in the correct sub-directories.
+6.  **Annotated Names Capability:** Add foundational support for attaching human-readable "annotated names" to log sessions for easier GUI lookup later.
+
+## Functional Requirements
+-   **Structure:** Create `tests/artifacts/`, `logs/sessions/`, `logs/agents/`, and `logs/errors/`.
+-   **Configuration:** Update the app's default paths for temporary files (e.g., `temp_project.toml`) to use `tests/artifacts/`.
+-   **Logging Logic:** Modify `SessionLogger` to use the new taxonomy based on the type of log (e.g., `agents/` for sub-agent runs).
+-   **Migration Tool:** A script (`scripts/migrate_cruft.ps1`) that identifies and moves existing root-level `temp_*.toml`, `*.log`, and other cruft.
+
+## Non-Functional Requirements
+-   **Non-Destructive:** The migration script should use `Move-Item -Force` but ideally verify file presence before moving.
+-   **Cleanliness:** No new temporary files should appear in the project root after this track is implemented.
+
+## Acceptance Criteria
+-   `tests/artifacts/` exists and contains redirected temp files.
+-   `.gitignore` excludes `tests/artifacts/` and all `logs/` sub-folders.
+-   Existing logs are successfully moved into `logs/sessions/`, `logs/agents/`, or `logs/errors/`.
+-   A new session correctly places its logs into the categorized sub-folders.
+
+## Out of Scope
+-   The full GUI implementation of the log viewer (this is just the filesystem foundation).
+-   Consolidation of `.git` or `.venv` directories.

conductor/archive/deepseek_support_20260225/index.md

@@ -0,0 +1,5 @@
+# Track deepseek_support_20260225 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/deepseek_support_20260225/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "deepseek_support_20260225",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-02-25T00:00:00Z",
+  "updated_at": "2026-02-25T00:00:00Z",
+  "description": "Add support for the deepseek api as a provider."
+}

conductor/archive/deepseek_support_20260225/plan.md

@@ -0,0 +1,27 @@
+# Implementation Plan: DeepSeek API Provider Support
+
+## Phase 1: Infrastructure & Common Logic [checkpoint: 0ec3720]
+- [x] Task: Initialize MMA Environment `activate_skill mma-orchestrator` 1b3ff23
+- [x] Task: Update `credentials.toml` schema and configuration logic in `project_manager.py` to support `deepseek` 1b3ff23
+- [x] Task: Define the `DeepSeekProvider` interface in `ai_client.py` and align with existing provider patterns 1b3ff23
+- [x] Task: Conductor - User Manual Verification 'Infrastructure & Common Logic' (Protocol in workflow.md) 1b3ff23
+
+## Phase 2: DeepSeek API Client Implementation
+- [x] Task: Write failing tests for `DeepSeekProvider` model selection and basic completion
+- [x] Task: Implement `DeepSeekProvider` using the dedicated SDK
+- [x] Task: Write failing tests for streaming and tool calling parity in `DeepSeekProvider`
+- [x] Task: Implement streaming and tool calling logic for DeepSeek models
+- [x] Task: Conductor - User Manual Verification 'DeepSeek API Client Implementation' (Protocol in workflow.md)
+
+## Phase 3: Reasoning Traces & Advanced Capabilities
+- [x] Task: Write failing tests for reasoning trace capture in `DeepSeekProvider` (DeepSeek-R1)
+- [x] Task: Implement reasoning trace processing and integration with discussion history
+- [x] Task: Write failing tests for token estimation and cost tracking for DeepSeek models
+- [x] Task: Implement token usage tracking according to DeepSeek pricing
+- [x] Task: Conductor - User Manual Verification 'Reasoning Traces & Advanced Capabilities' (Protocol in workflow.md)
+
+## Phase 4: GUI Integration & Final Verification
+- [x] Task: Update `gui_2.py` and `theme_2.py` (if necessary) to include DeepSeek in the provider selection UI
+- [x] Task: Implement automated regression tests for the full DeepSeek lifecycle (prompt, streaming, tool call, reasoning)
+- [x] Task: Verify overall performance and UI responsiveness with the new provider
+- [x] Task: Conductor - User Manual Verification 'GUI Integration & Final Verification' (Protocol in workflow.md)

conductor/archive/deepseek_support_20260225/spec.md

@@ -0,0 +1,31 @@
+# Specification: DeepSeek API Provider Support
+
+## Overview
+Implement a new AI provider module to support the DeepSeek API within the Manual Slop application. This integration will leverage a dedicated SDK to provide access to high-performance models (DeepSeek-V3 and DeepSeek-R1) with support for streaming, tool calling, and detailed reasoning traces.
+
+## Functional Requirements
+- **Dedicated SDK Integration:** Utilize a DeepSeek-specific Python client for API interactions.
+- **Model Support:** Initial support for `deepseek-v3` (general performance) and `deepseek-r1` (reasoning).
+- **Core Features:**
+    - **Streaming:** Support real-time response generation for a better user experience.
+    - **Tool Calling:** Integrate with Manual Slop's existing tool/function execution framework.
+    - **Reasoning Traces:** Capture and display reasoning paths if provided by the model (e.g., DeepSeek-R1).
+- **Configuration Management:**
+    - Add `[deepseek]` section to `credentials.toml` for `api_key`.
+    - Update `config.toml` to allow selecting DeepSeek as the active provider.
+
+## Non-Functional Requirements
+- **Parity:** Maintain consistency with existing Gemini and Anthropic provider implementations in `ai_client.py`.
+- **Error Handling:** Robust handling of API rate limits and connection issues specific to DeepSeek.
+- **Observability:** Track token usage and costs according to DeepSeek's pricing model.
+
+## Acceptance Criteria
+- [ ] User can select "DeepSeek" as a provider in the GUI.
+- [ ] Successful completion of prompts using both DeepSeek-V3 and DeepSeek-R1 models.
+- [ ] Tool calling works correctly for standard operations (e.g., `read_file`).
+- [ ] Reasoning traces from R1 are captured and visible in the discussion history.
+- [ ] Streaming responses function correctly without blocking the GUI.
+
+## Out of Scope
+- Support for OpenAI-compatible proxies for DeepSeek in this initial track.
+- Automated fine-tuning or custom model endpoints.

conductor/archive/documentation_refresh_20260224/plan.md

@@ -0,0 +1,38 @@
+# Implementation Plan: Deep Architectural Documentation Refresh
+
+## Phase 1: Context Cleanup & Research
+- [x] Task: Audit references to `MainContext.md` across the project.
+- [x] Task: Delete `MainContext.md` and update any identified references.
+- [x] Task: Execute `py_get_skeleton` and `py_get_code_outline` for `events.py`, `api_hooks.py`, `api_hook_client.py`, and `gui_2.py` to create a technical map for the guides.
+- [x] Task: Analyze the `live_gui` fixture in `tests/conftest.py` and the simulation loop in `tests/visual_sim_mma_v2.py`.
+
+## Phase 2: Core Architecture Deep Dive
+Update `docs/guide_architecture.md` with expert-level detail.
+- [x] Task: Document the Dual-Threaded App Lifetime: Main GUI loop vs. Daemon execution threads.
+- [x] Task: Detail the `AsyncEventQueue` and `EventEmitter` roles in the decoupling strategy.
+- [x] Task: Explain the `_pending_gui_tasks` synchronization mechanism for bridging the Hook Server and GUI.
+- [x] Task: Document the "Linear Execution Clutch" and its deterministic state machine.
+- [x] Task: Verify the architectural descriptions against the actual implementation.
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Core Architecture Deep Dive' (Protocol in workflow.md)
+
+## Phase 3: Hook System & Tooling Technical Reference
+Update `docs/guide_tools.md` to include low-level API details.
+- [x] Task: Create a comprehensive API reference for all `HookServer` endpoints.
+- [x] Task: Document the `ApiHookClient` implementation, including retries and polling strategies.
+- [x] Task: Update the MCP toolset guide with current native tool implementations.
+- [x] Task: Document the `ask/respond` IPC flow for "Human-in-the-Loop" confirmations.
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Hook System & Tooling Technical Reference' (Protocol in workflow.md)
+
+## Phase 4: Verification & Simulation Framework
+Create the new `docs/guide_simulations.md` guide.
+- [x] Task: Detail the Live GUI testing infrastructure: `--enable-test-hooks` and the `live_gui` fixture.
+- [x] Task: Breakdown the Simulation Lifecycle: Startup, Polling, Interaction, and Assertion.
+- [x] Task: Document the mock provider strategy using `tests/mock_gemini_cli.py`.
+- [x] Task: Provide examples of visual verification tests (e.g., MMA lifecycle).
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Verification & Simulation Framework' (Protocol in workflow.md)
+
+## Phase 5: README & Roadmap Update
+- [x] Task: Update `Readme.md` with current setup (`uv`, `credentials.toml`) and vision.
+- [x] Task: Perform a project-wide link validation of all Markdown files.
+- [x] Task: Verify the high-density information style across all documentation.
+- [x] Task: Conductor - User Manual Verification 'Phase 5: README & Roadmap Update' (Protocol in workflow.md)

conductor/archive/documentation_refresh_20260224/spec.md

@@ -0,0 +1,45 @@
+# Track Specification: Deep Architectural Documentation Refresh
+
+## Overview
+This track implements a high-density, expert-level documentation suite for the Manual Slop project. The documentation style is strictly modeled after the **pedagogical and narrative standards** of `gencpp` and `VEFontCache-Odin`. It moves beyond simple "User Guides" to provide a **"USA Graphics Company"** architectural reference: high information density, tactical technical transparency, and a narrative intent that guides a developer from high-level philosophy to low-level implementation.
+
+## Pedagogical Goals
+1.  **Narrative Intent:** Documentation must transition the reader through a logical learning journey: **Philosophy/Mental Model -> Architectural Boundaries -> Implementation Logic -> Verification/Simulation.**
+2.  **High Information Density:** Eliminate conversational filler and "fluff." Every sentence must provide architectural signal (state transitions, data flows, constraints).
+3.  **Technical Transparency:** Document the "How" and "Why" behind design decisions (e.g., *Why* the dual-threaded `Asyncio` loop? *How* does the "Execution Clutch" bridge the thread gap?).
+4.  **Architectural Mapping:** Use precise symbol names (`AsyncEventQueue`, `_pending_gui_tasks`, `HookServer`) to map the documentation directly to the source code.
+5.  **Multi-Layered Depth:** Each major component (Architecture, Tools, Simulations) must have its own dedicated, expert-level guide. No consolidation into single, shallow files.
+
+## Functional Requirements (Documentation Areas)
+
+### 1. Core Architecture (`docs/guide_architecture.md`)
+-   **System Philosophy:** The "Decoupled State Machine" mental model.
+-   **Application Lifetime:** The multi-threaded boot sequence and the "Dual-Flush" persistence model.
+-   **The Task Pipeline:** Detailed producer-consumer synchronization between the GUI (Main) and AI (Daemon) threads.
+-   **The Execution Clutch (HITL):** Detailed state machine for human-in-the-loop interception and payload mutation.
+
+### 2. Tooling & IPC Reference (`docs/guide_tools.md`)
+-   **MCP Bridge:** Low-level security constraints and filesystem sandboxing.
+-   **Hook API:** A full technical reference for the REST/IPC interface (endpoints, payloads, diagnostics).
+-   **IPC Flow:** The `ask/respond` sequence for synchronous human-in-the-loop requests.
+
+### 3. Verification & Simulation Framework (`docs/guide_simulations.md`)
+-   **Infrastructure:** The `--enable-test-hooks` flag and the `live_gui` pytest fixture.
+-   **Lifecycle:** The "Puppeteer" pattern for driving the GUI via automated clients.
+-   **Mocking Strategy:** Script-based AI provider mocking via `mock_gemini_cli.py`.
+-   **Visual Assertion:** Examples of verifying the rendered state (DAG, Terminal streams) rather than just API returns.
+
+### 4. Product Vision & Roadmap (`Readme.md`)
+-   **Technological Identity:** High-density experimental tool for local AI orchestration.
+-   **Pedagogical Landing:** Direct links to the deep-dive guides to establish the project's expert-level tone immediately.
+
+## Acceptance Criteria for Expert Review (Claude Opus)
+-   [ ] **Zero Filler:** No introductory "In this section..." or "Now we will..." conversational markers.
+-   [ ] **Structural Parity:** Documentation follows the `gencpp` pattern (Philosophy -> Code Paths -> Interface).
+-   [ ] **Expert-Level Detail:** Includes data structures, locking mechanisms, and thread-safety constraints.
+-   [ ] **Narrative Cohesion:** The documents feel like a single, expert-authored manual for a complex graphics or systems engine.
+-   [ ] **Tactile Interaction:** Explains the "Linear Execution Clutch" as a physical shift in the application's processing gears.
+
+## Out of Scope
+-   Documenting legacy `gui_legacy.py` code beyond its role as a fallback.
+-   Visual diagram generation (focusing on high-signal text-based architectural mapping).

conductor/archive/gemini_cli_headless_20260224/index.md

@@ -0,0 +1,5 @@
+# Track gemini_cli_headless_20260224 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/gemini_cli_headless_20260224/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "gemini_cli_headless_20260224",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-02-24T23:45:00Z",
+  "updated_at": "2026-02-24T23:45:00Z",
+  "description": "Support gemini cli headless as an alternative to the raw client_api route. So that they user may use their gemini subscription and gemini cli features within manual slop for a more discliplined and visually enriched UX."
+}

conductor/archive/gemini_cli_headless_20260224/plan.md

@@ -0,0 +1,26 @@
+# Implementation Plan: Gemini CLI Headless Integration
+
+## Phase 1: IPC Infrastructure Extension [checkpoint: c0bccce]
+- [x] Task: Extend `api_hooks.py` to support synchronous "Ask" requests. This involves adding a way for a client to POST a request and wait for a user response from the GUI. (1792107)
+- [x] Task: Update `api_hook_client.py` with a `request_confirmation(tool_name, args)` method that blocks until the GUI responds. (93f640d)
+- [x] Task: Create a standalone test script `tests/test_sync_hooks.py` to verify that the CLI-to-GUI communication works as expected. (1792107)
+- [x] Task: Conductor - User Manual Verification 'Phase 1: IPC Infrastructure Extension' (Protocol in workflow.md) (c0bccce)
+
+## Phase 2: Gemini CLI Adapter & Tool Bridge
+- [x] Task: Implement `scripts/cli_tool_bridge.py`. This script will be called by the Gemini CLI `BeforeTool` hook and use `ApiHookClient` to talk to the GUI. (211000c)
+- [x] Task: Implement the `GeminiCliAdapter` in `ai_client.py` (or a new `gemini_cli_adapter.py`). It must handle the `subprocess` lifecycle and parse the `stream-json` output. (b762a80)
+- [x] Task: Integrate `GeminiCliAdapter` into the main `ai_client.send()` logic. (b762a80)
+- [x] Task: Write unit tests for the JSON parsing and subprocess management in `GeminiCliAdapter`. (b762a80)
+- [~] Task: Conductor - User Manual Verification 'Phase 2: Gemini CLI Adapter & Tool Bridge' (Protocol in workflow.md)
+
+## Phase 3: GUI Integration & Provider Support
+- [x] Task: Update `gui_2.py` to add "Gemini CLI" to the provider dropdown. (3ce4fa0)
+- [x] Task: Implement UI elements for "Gemini CLI Session Management" (Login button, session ID display). (3ce4fa0)
+- [x] Task: Update the `manual_slop.toml` logic to persist Gemini CLI specific settings (e.g., path to CLI, approval mode). (3ce4fa0)
+- [~] Task: Conductor - User Manual Verification 'Phase 3: GUI Integration & Provider Support' (Protocol in workflow.md)
+
+## Phase 4: Integration Testing & UX Polish
+- [x] Task: Create a comprehensive integration test `tests/test_gemini_cli_integration.py` that uses the `live_gui` fixture to simulate a full session. (d187a6c)
+- [x] Task: Verify tool confirmation flow: CLI Tool -> Bridge -> GUI Modal -> User Approval -> CLI Execution. (d187a6c)
+- [x] Task: Polish the display of CLI telemetry (tokens/latency) in the GUI diagnostics panel. (1e5b43e)
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Integration Testing & UX Polish' (Protocol in workflow.md) (1e5b43e)

conductor/archive/gemini_cli_headless_20260224/spec.md

@@ -0,0 +1,45 @@
+# Specification: Gemini CLI Headless Integration
+
+## Overview
+This track integrates the `gemini` CLI as a headless backend provider for Manual Slop. This allows users to leverage their Gemini subscription and the CLI's advanced features (e.g., specialized sub-agents like `codebase_investigator`, structured JSON streaming, and robust session management) directly within the Manual Slop GUI.
+
+## Goals
+- Add "Gemini CLI" as a selectable AI provider in Manual Slop.
+- Support both persistent interactive sessions and one-off task-specific delegation (e.g., running `gemini investigate`).
+- Implement a secure "BeforeTool" hook to ensure all CLI-initiated tool calls are intercepted and confirmed via the Manual Slop GUI.
+- Capture and display the CLI's visually enriched output (via JSONL stream) within the existing discussion history.
+
+## Functional Requirements
+
+### 1. Gemini CLI Provider Adapter
+- **Implementation**: Create a `GeminiCliAdapter` class (or extend `ai_client.py`) that wraps the `gemini` CLI subprocess.
+- **Communication**: Use `--output-format stream-json` to receive real-time updates (text chunks, tool calls, status).
+- **Session Management**: Support session persistence by tracking the session ID and passing it to subsequent CLI calls.
+- **Authentication**: 
+    - Provide a "Login to Gemini CLI" action in the GUI that triggers `gemini login`.
+    - Support passing an API key via environment variables if configured in `manual_slop.toml`.
+
+### 2. GUI Intercepted Tool Execution
+- **Mechanism**: Use the Gemini CLI's `BeforeTool` hook.
+- **Hook Helper**: A small Python script `scripts/cli_tool_bridge.py` will be registered as the `BeforeTool` hook.
+- **IPC**: This bridge script will communicate with Manual Slop's `HookServer` (extending it to support synchronous "ask" requests).
+- **Confirmation**: When a tool is requested, the bridge blocks until the user confirms/denies the action in the GUI, returning the decision as JSON to the CLI.
+
+### 3. Visual & Telemetry Integration
+- **Rich Output**: Parse the `stream-json` events to display markdown content and tool status in the GUI.
+- **Telemetry**: Extract and display token usage and latency metrics provided by the CLI's `result` event.
+
+## Non-Functional Requirements
+- **Performance**: The subprocess bridge should introduce minimal latency (<100ms overhead for communication).
+- **Reliability**: Gracefully handle CLI crashes or timeouts by reporting errors in the GUI and allowing session resets.
+
+## Acceptance Criteria
+- [ ] User can select "Gemini CLI" in the Provider dropdown.
+- [ ] User can successfully send messages and receive streamed responses from the CLI.
+- [ ] Any tool call (PowerShell/MCP) initiated by the CLI triggers the standard Manual Slop confirmation modal.
+- [ ] Tools only execute after user approval; rejection correctly notifies the CLI agent.
+- [ ] Session history is maintained correctly across multiple turns when using the CLI provider.
+
+## Out of Scope
+- Full terminal emulation (ANSI color support) within the GUI; the focus is on structured text and data.
+- Migrating existing raw `client_api` sessions to CLI sessions.

conductor/archive/gemini_cli_parity_20260225/index.md

@@ -0,0 +1,5 @@
+# Track gemini_cli_parity_20260225 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/gemini_cli_parity_20260225/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "gemini_cli_parity_20260225",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-02-25T00:00:00Z",
+  "updated_at": "2026-02-25T00:00:00Z",
+  "description": "Make sure gemini cli behavior and feature set have full parity with regular direct gemini api usage in ai_client.py and elsewhere"
+}

conductor/archive/gemini_cli_parity_20260225/plan.md

@@ -0,0 +1,32 @@
+# Implementation Plan: Gemini CLI Parity
+
+## Phase 1: Infrastructure & Common Logic
+- [x] Task: Initialize MMA Environment `activate_skill mma-orchestrator`
+- [x] Task: Audit `gemini_cli_adapter.py` and `ai_client.py` for parity gaps (Findings: missing count_tokens, safety settings, and robust system prompt handling in CLI adapter)
+- [x] Task: Implement common logging utilities for CLI bridge observability
+- [x] Task: Conductor - User Manual Verification 'Infrastructure & Common Logic' (Protocol in workflow.md)
+
+## Phase 2: Token Counting & Safety Settings
+- [x] Task: Write failing tests for token estimation in `GeminiCLIAdapter`
+- [x] Task: Implement token counting parity in `GeminiCLIAdapter`
+- [x] Task: Write failing tests for safety setting application in `GeminiCLIAdapter`
+- [x] Task: Implement safety filter application in `GeminiCLIAdapter`
+- [x] Task: Conductor - User Manual Verification 'Token Counting & Safety Settings' (Protocol in workflow.md)
+
+## Phase 3: Tool Calling Parity & System Instructions
+- [x] Task: Write failing tests for system instruction usage in `GeminiCLIAdapter`
+- [x] Task: Implement system instruction propagation in `GeminiCLIAdapter`
+- [x] Task: Write failing tests for tool call/response mapping in `cli_tool_bridge.py`
+- [x] Task: Synchronize tool call handling between bridge and `ai_client.py`
+- [x] Task: Conductor - User Manual Verification 'Tool Calling Parity & System Instructions' (Protocol in workflow.md)
+
+## Phase 4: Final Verification & Performance Diagnostics
+- [x] Task: Implement automated parity regression tests comparing CLI vs Direct API outputs
+- [x] Task: Verify bridge latency and error handling robustness
+- [x] Task: Conductor - User Manual Verification 'Final Verification & Performance Diagnostics' (Protocol in workflow.md)
+
+## Phase 5: Edge Case Resilience & GUI Integration Tests
+- [x] Task: Implement tests for context bleed prevention (filtering non-assistant messages)
+- [x] Task: Implement tests for parameter name resilience (dir_path/file_path aliases)
+- [x] Task: Implement tests for tool call loop termination and payload persistence
+- [x] Task: Conductor - User Manual Verification 'Edge Case Resilience' (Protocol in workflow.md)

conductor/archive/gemini_cli_parity_20260225/spec.md

@@ -0,0 +1,27 @@
+# Specification: Gemini CLI Parity
+
+## Overview
+Achieve full functional and behavioral parity between the Gemini CLI integration (`gemini_cli_adapter.py`, `cli_tool_bridge.py`) and the direct Gemini API implementation (`ai_client.py`). This ensures that users leveraging the Gemini CLI as a headless backend provider experience the same level of capability, reliability, and observability as direct API users.
+
+## Functional Requirements
+- **Token Estimation Parity:** Implement accurate token counting for both input and output in the Gemini CLI adapter to match the precision of the direct API.
+- **Safety Settings Parity:** Enable full configuration and enforcement of Gemini safety filters when using the CLI provider.
+- **Tool Calling Parity:** Synchronize tool definition mapping, call handling, and response processing between the CLI bridge and the direct SDK.
+- **System Instructions Parity:** Ensure system prompts and instructions are consistently passed and handled across both providers.
+- **Bridge Robustness:** Enhance the `cli_tool_bridge.py` and adapter to improve latency, error handling (retries), and detailed subprocess observability.
+
+## Non-Functional Requirements
+- **Observability:** Detailed logging of CLI subprocess interactions for debugging.
+- **Performance:** Minimize the overhead introduced by the bridge mechanism.
+- **Maintainability:** Ensure that future changes to `ai_client.py` can be easily mirrored in the CLI adapter.
+
+## Acceptance Criteria
+- [ ] Token counts for identical prompts match within a 5% margin between CLI and Direct API.
+- [ ] Safety settings configured in the GUI are correctly applied to CLI sessions.
+- [ ] Tool calls from the CLI are successfully executed and returned via the bridge without loss of context.
+- [ ] System instructions are correctly utilized by the model when using the CLI.
+- [ ] Automated tests verify that responses and tool execution flows are identical for both providers.
+
+## Out of Scope
+- Performance optimizations for the `gemini` CLI binary itself.
+- Support for non-Gemini CLI providers in this track.

conductor/archive/gui_sim_extension_20260224/plan.md

@@ -0,0 +1,39 @@
+# Implementation Plan: Extended GUI Simulation Testing
+
+## Phase 1: Setup and Architecture [checkpoint: b255d4b]
+- [x] Task: Review the existing baseline simulation test to identify reusable components or fixtures without modifying the original. a0b1c2d
+- [x] Task: Design the modular structure for the new simulation scripts within the `simulation/` directory. e1f2g3h
+- [x] Task: Create a base test configuration or fixture that initializes the GUI with the `--enable-test-hooks` flag and the `ApiHookClient` for API testing. i4j5k6l
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Setup and Architecture' (Protocol in workflow.md) m7n8o9p
+
+## Phase 2: Context and Chat Simulation [checkpoint: a77d0e7]
+- [x] Task: Create the test script `sim_context.py` focused on the Context and Discussion panels. q1r2s3t
+- [x] Task: Simulate file aggregation interactions and context limit verification. u4v5w6x
+- [x] Task: Implement history generation and test chat submission via API hooks. y7z8a9b
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Context and Chat Simulation' (Protocol in workflow.md) c1d2e3f
+
+## Phase 3: AI Settings and Tools Simulation [checkpoint: 760eec2]
+- [x] Task: Create the test script `sim_ai_settings.py` for AI model configuration changes (Gemini/Anthropic). g1h2i3j
+- [x] Task: Create the test script `sim_tools.py` focusing on file exploration, search, and MCP-like tool triggers. k4l5m6n
+- [x] Task: Validate proper panel rendering and data updates via API hooks for both AI settings and tool results. o7p8q9r
+- [x] Task: Conductor - User Manual Verification 'Phase 3: AI Settings and Tools Simulation' (Protocol in workflow.md) s1t2u3v
+
+## Phase 4: Execution and Modals Simulation [checkpoint: e8959bf]
+- [x] Task: Create the test script `sim_execution.py`. w3x4y5z
+- [x] Task: Simulate the AI generating a PowerShell script that triggers the explicit confirmation modal. a1b2c3d
+- [x] Task: Assert the modal appears correctly and accepts input/approval from the simulated user. e4f5g6h
+- [x] Task: Validate the executed output via API hooks. i7j8k9l
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Execution and Modals Simulation' (Protocol in workflow.md) m0n1o2p
+
+## Phase 5: Reactive Interaction and Final Polish [checkpoint: final]
+- [x] Task: Implement reactive `/api/events` endpoint for real-time GUI feedback. x1y2z3a
+- [x] Task: Add auto-scroll and fading blink effects to Tool and Comms history panels. b4c5d6e
+- [x] Task: Restrict simulation testing to `gui_2.py` and ensure full integration pass. f7g8h9i
+- [x] Task: Conductor - User Manual Verification 'Phase 5: Reactive Interaction and Final Polish' (Protocol in workflow.md) j0k1l2m
+
+## Phase 6: Multi-Turn & Stability Polish [checkpoint: pass]
+- [x] Task: Implement looping reactive simulation for multi-turn tool approvals. a1b2c3d
+- [x] Task: Fix Gemini 400 error by adding token threshold for context caching. e4f5g6h
+- [x] Task: Ensure `btn_reset` clears all relevant UI fields including `ai_input`. i7j8k9l
+- [x] Task: Run full test suite (70+ tests) and ensure 100% pass rate. m0n1o2p
+- [x] Task: Conductor - User Manual Verification 'Phase 6: Multi-Turn & Stability Polish' (Protocol in workflow.md) q1r2s3t

conductor/archive/logging_refactor_20260226/index.md

@@ -0,0 +1,5 @@
+# Track logging_refactor_20260226 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/logging_refactor_20260226/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "logging_refactor_20260226",
+  "type": "chore",
+  "status": "new",
+  "created_at": "2026-02-26T08:45:00Z",
+  "updated_at": "2026-02-26T08:45:00Z",
+  "description": "Review logging used throughout the project. The log directory has several categories of logs and they are getting quite large in number. We need sub-directories and we need a way to prune logs that aren't valuable to keep."
+}

conductor/archive/logging_refactor_20260226/plan.md

@@ -0,0 +1,39 @@
+# Implementation Plan: Logging Reorganization and Automated Pruning
+
+## Phase 1: Session Organization & Registry Foundation
+- [x] Task: Initialize MMA Environment (Protocol: `activate_skill mma-orchestrator`) [9a66b76]
+- [x] Task: Implement `LogRegistry` to manage `log_registry.toml` [10fbfd0]
+    - [x] Define TOML schema for session metadata.
+    - [x] Create methods to register sessions and update whitelist status.
+- [x] Task: Implement Session-Based Directory Creation [3f4dc1a]
+    - [x] Create utility to generate Session IDs: `YYYYMMDD_HHMMSS[_Label]`.
+    - [x] Update logging initialization to create and use session sub-directories.
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Foundation' (Protocol in workflow.md) [3f4dc1a]
+
+## Phase 2: Pruning Logic & Heuristics
+- [x] Task: Implement `LogPruner` Core Logic [bd2a79c]
+    - [x] Implement time-based filtering (older than 24h).
+    - [x] Implement size-based heuristic for "insignificance" (~2 KB).
+- [x] Task: Implement Auto-Whitelisting Heuristics [4e9c47f]
+    - [x] Implement content scanning for `ERROR`, `WARNING`, `EXCEPTION`.
+    - [x] Implement complexity detection (message count > 10).
+- [x] Task: Integrate Pruning into App Startup [8b75883]
+    - [x] Hook the pruner into `gui_2.py` startup sequence.
+    - [x] Ensure pruning runs asynchronously to prevent startup lag.
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Pruning' (Protocol in workflow.md) [8b75883]
+
+## Phase 3: GUI Integration & Manual Control
+- [x] Task: Add "Log Management" UI Panel [7d52123]
+    - [x] Display a list of recent sessions from the registry.
+    - [x] Add "Star/Unstar" toggle for manual whitelisting.
+- [x] Task: Display Session Metrics in UI [7d52123]
+    - [x] Show size, message count, and status (Whitelisted/Pending Prune).
+- [x] Task: Conductor - User Manual Verification 'Phase 3: GUI' (Protocol in workflow.md) [7d52123]
+
+## Phase 4: Final Verification & Cleanup
+- [x] Task: Comprehensive Integration Testing [23c0f0a]
+    - [x] Verify that empty old logs are deleted.
+    - [x] Verify that complex/error-filled old logs are preserved.
+- [x] Task: Final Refactoring and Documentation [04a991e]
+    - [x] Ensure all new classes and methods follow project style.
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Final' (Protocol in workflow.md) [04a991e]

conductor/archive/logging_refactor_20260226/spec.md

@@ -0,0 +1,42 @@
+# Specification: Logging Reorganization and Automated Pruning
+
+## Overview
+Currently, `gui_2.py` and the test suites generate a large number of log files in a flat `logs/` directory. These logs accumulate quickly, especially during incremental development and testing. This track aims to organize logs into session-based sub-directories and implement a heuristic-based pruning system to keep the log directory clean while preserving valuable sessions.
+
+## Functional Requirements
+1. **Session-Based Organization:**
+   - Logs must be stored in sub-directories within `logs/`.
+   - Sub-directory naming convention: `YYYYMMDD_HHMMSS[_Label]` (e.g., `20260226_143005_feature_x`).
+   - The "Label" should be included if a project or track is active at session start.
+2. **Central Registry:**
+   - A `logs/log_registry.toml` file will track session metadata, including:
+     - Session ID / Path
+     - Start Time
+     - Whitelist Status (Manual/Auto)
+     - Metrics (message count, errors detected, total size).
+3. **Automated Pruning Heuristic:**
+   - Pruning triggers on application startup (`gui_2.py`).
+   - **Target:** Logs older than 24 hours.
+   - **Exemption:** Whitelisted logs are never auto-pruned.
+   - **Insignificance Criteria:** Non-whitelisted logs under a specific size threshold (heuristic: ~2 KB) or with zero significant interactions will be purged.
+4. **Whitelisting System:**
+   - **Auto-Whitelisting:** Sessions are marked as "rich" if they meet any of these:
+     - Complexity: > 10 messages/interactions.
+     - Diagnostics: Contains `ERROR`, `WARNING`, `EXCEPTION`.
+     - Major Events: User created a new project or initialized a track.
+   - **Manual Whitelisting:** The user can "star" a session via the GUI (persisted in the registry).
+
+## Non-Functional Requirements
+- **Performance:** Pruning and registry updates must be asynchronous or extremely fast to avoid delaying app startup.
+- **Safety:** Ensure the pruning logic is conservative to prevent accidental data loss of important debug information.
+
+## Acceptance Criteria
+- [ ] New logs are created in session-specific folders.
+- [ ] The `log_registry.toml` correctly identifies and tracks sessions.
+- [ ] On startup, non-whitelisted logs older than 1 day are successfully pruned.
+- [ ] Whitelisted logs (due to complexity or errors) remain untouched.
+- [ ] (Bonus) The GUI displays a basic list of sessions with their "starred" status.
+
+## Out of Scope
+- Migrating the entire backlog of existing flat logs (focus is on new sessions).
+- Implementing a full-blown log viewer (basic metadata view only).

conductor/archive/manual_slop_headless_20260225/index.md

@@ -0,0 +1,5 @@
+# Track manual_slop_headless_20260225 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/manual_slop_headless_20260225/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "manual_slop_headless_20260225",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-02-25T12:00:00Z",
+  "updated_at": "2026-02-25T12:00:00Z",
+  "description": "Support headless manual_slop for making an unraid gui docker frontend and a unraid server backend down the line."
+}

conductor/archive/manual_slop_headless_20260225/plan.md

@@ -0,0 +1,52 @@
+# Implementation Plan: Manual Slop Headless Backend
+
+## Phase 1: Project Setup & Headless Scaffold [checkpoint: d5f056c]
+- [x] Task: Update dependencies (02fc847)
+    - [x] Add `fastapi` and `uvicorn` to `pyproject.toml` (and sync `requirements.txt` via `uv`).
+- [x] Task: Implement headless startup
+    - [x] Modify `gui_2.py` (or create `headless.py`) to parse a `--headless` CLI flag.
+    - [x] Update config parsing in `config.toml` to support headless configuration sections.
+    - [x] Bypass Dear PyGui initialization if headless mode is active.
+- [x] Task: Create foundational API application
+    - [x] Set up the core FastAPI application instance.
+    - [x] Implement `/health` and `/status` endpoints for Docker lifecycle checks.
+- [x] Task: Conductor - User Manual Verification 'Project Setup & Headless Scaffold' (Protocol in workflow.md) d5f056c
+
+## Phase 2: Core API Routes & Authentication [checkpoint: 4e0bcd5]
+- [x] Task: Implement API Key Security
+    - [x] Create a dependency/middleware in FastAPI to validate `X-API-KEY`.
+    - [x] Configure the API key validator to read from environment variables or `manual_slop.toml` (supporting Unraid template secrets).
+    - [x] Add tests for authorized and unauthorized API access.
+- [x] Task: Implement AI Generation Endpoint
+    - [x] Create a `/api/v1/generate` POST endpoint.
+    - [x] Map request payloads to `ai_client.py` unified wrappers.
+    - [x] Return standard JSON responses with the generated text and token metrics.
+- [x] Task: Conductor - User Manual Verification 'Core API Routes & Authentication' (Protocol in workflow.md) 4e0bcd5
+
+## Phase 3: Remote Tool Confirmation Mechanism [checkpoint: a6e184e]
+- [x] Task: Refactor Execution Engine for Async Wait
+    - [x] Modify `shell_runner.py` and tool-call loops to support a non-blocking "Pending Confirmation" state instead of launching a GUI modal.
+- [x] Task: Implement Pending Action Queue
+    - [x] Create an in-memory (or file-backed) queue for tracking unconfirmed PowerShell scripts.
+- [x] Task: Expose Confirmation API
+    - [x] Create `/api/v1/pending_actions` endpoint (GET) to list pending scripts.
+    - [x] Create `/api/v1/confirm/{action_id}` endpoint (POST) to approve or deny a script execution.
+    - [x] Ensure the AI generation loop correctly resumes upon receiving approval.
+- [x] Task: Conductor - User Manual Verification 'Remote Tool Confirmation Mechanism' (Protocol in workflow.md) a6e184e
+
+## Phase 4: Session & Context Management via API [checkpoint: 7f3a1e2]
+- [x] Task: Expose Session History
+    - [x] Create endpoints to list, retrieve, and delete session logs from the `project_history.toml`.
+- [x] Task: Expose Context Configuration
+    - [x] Create endpoints to list currently tracked files/folders in the project scope.
+- [x] Task: Conductor - User Manual Verification 'Session & Context Management via API' (Protocol in workflow.md) 7f3a1e2
+
+## Phase 5: Dockerization [checkpoint: 5176b8d]
+- [x] Task: Create Dockerfile
+    - [x] Write a `Dockerfile` using `python:3.11-slim` as a base.
+    - [x] Configure `uv` inside the container for fast dependency installation.
+    - [x] Expose the API port (e.g., 8000) and set the container entrypoint.
+- [x] Task: Conductor - User Manual Verification 'Dockerization' (Protocol in workflow.md) 5176b8d
+
+## Phase: Review Fixes
+- [x] Task: Apply review suggestions (docstrings and security fix) 9b50bfa

conductor/archive/manual_slop_headless_20260225/spec.md

@@ -0,0 +1,48 @@
+# Specification: Manual Slop Headless Backend
+
+## Overview
+Transform Manual Slop into a decoupled, container-friendly backend service. This track enables the core AI orchestration and tool execution logic to run without a GUI, exposing its capabilities via a secured REST API optimized for an Unraid Docker environment.
+
+## Goals
+- Decouple the GUI logic (`Dear PyGui`, `ImGui`) from the core AI and Tool logic.
+- Implement a lightweight REST API server (FastAPI) to handle AI interactions.
+- Ensure full compatibility with Unraid Docker networking and configuration patterns.
+- Maintain the "Human-in-the-Loop" safety model through a remote confirmation mechanism.
+
+## Functional Requirements
+
+### 1. Headless Mode Lifecycle
+- **Startup**: Provide a `--headless` flag or `[headless]` section in `manual_slop.toml` to skip GUI initialization.
+- **Dependencies**: Ensure the app can start in environments without an X11/Wayland display or GPU.
+- **Service Mode**: Support running as a persistent background daemon/service.
+
+### 2. REST API (FastAPI)
+- **Status/Health**: `/status` and `/health` endpoints for Docker/Unraid monitoring.
+- **AI Interface**: `/generate` and `/stream` endpoints to interact with configured AI providers.
+- **Tool Management**: Endpoints to list and execute tools (PowerShell/MCP).
+- **Session Support**: Manage conversation history and project context via API.
+
+### 3. Security & Authentication
+- **API Key**: Require a `X-API-KEY` header for all sensitive endpoints.
+- **Unraid Integration**: API keys should be configurable via Environment Variables (standard for Unraid templates).
+
+### 4. Remote Confirmation Mechanism
+- **Challenge/Response**: When a tool requires execution, the API should return a "Pending Confirmation" state.
+- **Webhook/Poll**: Support a mechanism (e.g., a `/confirm/{id}` endpoint) for the future frontend to approve/deny actions.
+
+## Non-Functional Requirements
+- **Performance**: Headless mode should use significantly less memory/CPU than the GUI version.
+- **Logging**: Use standard Python `logging` for Docker-compatible stdout/stderr output.
+- **Portability**: Must run reliably inside a standard `python:3.11-slim` or similar Docker image.
+
+## Acceptance Criteria
+- [ ] Manual Slop starts successfully with `--headless` and no display environment.
+- [ ] API is accessible via a configurable port (e.g., 8000).
+- [ ] All API requests are rejected without a valid API Key.
+- [ ] AI generation works via REST endpoints, returning structured JSON or a stream.
+- [ ] Tool execution is successfully blocked until a separate "Confirm" API call is made.
+
+## Out of Scope
+- Building the actual Unraid GUI frontend (React/Vue/etc.).
+- Multi-user authentication (OIDC/OAuth2).
+- Native Unraid `.plg` plugin development (focusing on Docker).

conductor/archive/mma_core_engine_20260224/index.md

@@ -0,0 +1,9 @@
+# MMA Core Engine Implementation
+
+This track implements the 5 Core Epics defined during the MMA Architecture Evaluation.
+
+### Navigation
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Original Architecture Proposal / Meta-Track](../mma_implementation_20260224/index.md)
+- [MMA Support Directory (Source of Truth)](../../../MMA_Support/)

conductor/archive/mma_core_engine_20260224/metadata.json

@@ -0,0 +1,6 @@
+{
+  "id": "mma_core_engine_20260224",
+  "title": "MMA Core Engine Implementation",
+  "status": "planning",
+  "created_at": "2026-02-24T00:00:00.000000"
+}

conductor/archive/mma_core_engine_20260224/plan.md

@@ -0,0 +1,85 @@
+# Implementation Plan: MMA Core Engine Implementation
+
+## Phase 1: Track 1 - The Memory Foundations (AST Parser) [checkpoint: ac31e41]
+- [x] Task: Dependency Setup (8fb75cc)
+    - [x] Add `tree-sitter` and `tree-sitter-python` to `pyproject.toml` / `requirements.txt` (8fb75cc)
+- [x] Task: Core Parser Class (7a609ca)
+    - [x] Create `ASTParser` in `file_cache.py` (7a609ca)
+- [x] Task: Skeleton View Extraction (7a609ca)
+    - [x] Write query to extract `function_definition` and `class_definition` (7a609ca)
+    - [x] Replace bodies with `pass`, keep type hints and signatures (7a609ca)
+- [x] Task: Curated View Extraction (7a609ca)
+    - [x] Keep class structures, module docstrings (7a609ca)
+    - [x] Preserve `@core_logic` or `# [HOT]` function bodies, hide others (7a609ca)
+
+## Phase 2: Track 2 - State Machine & Data Structures [checkpoint: a518a30]
+- [x] Task: The Dataclasses (f9b5a50)
+    - [x] Create `models.py` defining `Ticket` and `Track` (f9b5a50)
+- [x] Task: Worker Context Definition (ee71929)
+    - [x] Define `WorkerContext` holding `Ticket` ID, model config, and ephemeral messages (ee71929)
+- [x] Task: State Mutator Methods (e925b21)
+    - [x] Implement `ticket.mark_blocked()`, `ticket.mark_complete()`, `track.get_executable_tickets()` (e925b21)
+
+## Phase 3: Track 3 - The Linear Orchestrator & Execution Clutch [checkpoint: e6c8d73]
+- [x] Task: The Engine Core (7a30168)
+    - [x] Create `multi_agent_conductor.py` containing `ConductorEngine` and `run_worker_lifecycle` (7a30168)
+- [x] Task: Context Injection (9d6d174)
+    - [x] Format context strings using `file_cache.py` target AST views (9d6d174)
+- [x] Task: The HITL Execution Clutch (1afd9c8)
+    - [x] Before executing `write_file`/`shell_runner.py` tools in step-mode, prompt user for confirmation (1afd9c8)
+    - [x] Provide functionality to mutate the history JSON before resuming execution (1afd9c8)
+
+## Phase 4: Track 4 - Tier 4 QA Interception [checkpoint: 61d17ad]
+- [x] Task: The Interceptor Loop (bc654c2)
+    - [x] Catch `subprocess.run()` execution errors inside `shell_runner.py` (bc654c2)
+- [x] Task: Tier 4 Instantiation (8e4e326)
+    - [x] Make a secondary API call to `default_cheap` model passing `stderr` and snippet (8e4e326)
+- [x] Task: Payload Formatting (fb3da4d)
+    - [x] Inject the 20-word fix summary into the Tier 3 worker history (fb3da4d)
+
+## Phase 5: Track 5 - UI Decoupling & Tier 1/2 Routing (The Final Boss) [checkpoint: 3982fda]
+- [x] Task: The Event Bus (695cb4a)
+    - [x] Implement an `asyncio.Queue` linking GUI actions to the backend engine (695cb4a)
+- [x] Task: Tier 1 & 2 System Prompts (a28d71b)
+    - [x] Create structured system prompts for Epic routing and Ticket creation (a28d71b)
+- [x] Task: The Dispatcher Loop (1dacd36)
+    - [x] Read Tier 2 JSON flat-lists, construct Tickets, execute Stub resolution paths (1dacd36)
+- [x] Task: UI Component Update (68861c0)
+    - [x] Refactor `gui_2.py` to push `UserRequestEvent` instead of blocking on API generation (68861c0)
+
+## Phase 6: Live & Headless Verification
+- [x] Task: Headless Engine Verification
+    - [x] Run a comprehensive headless test scenario (e.g., using a mock or dedicated test script).
+    - [x] Verify Ticket execution, "Context Amnesia" (statelessness), and Tier 4 error interception.
+- [x] Task: Live GUI Integration Verification
+    - [x] Launch `gui_2.py` and verify Event Bus responsiveness.
+    - [x] Confirm UI updates and async event handling during multi-model generation.
+- [x] Task: Comprehensive Regression Suite
+    - [x] Run all tests in `tests/` related to MMA, Conductor, and Async Events.
+    - [x] Verify that no regressions were introduced in existing functionality.
+
+## Phase 7: MMA Observability & UX
+- [x] Task: MMA Dashboard Implementation
+    - [x] Create a new dockable panel in `gui_2.py` for "MMA Dashboard".
+    - [x] Display active `Track` and `Ticket` queue status.
+- [x] Task: Execution Clutch UI
+    - [x] Implement Step Mode toggle and Pause Points logic in the GUI.
+    - [x] Add `[Approve]`, `[Edit Payload]`, and `[Abort]` buttons for tool execution.
+- [x] Task: Memory Mutator Modal
+    - [x] Create a modal for editing raw JSON conversation history of paused workers.
+- [x] Task: Tiered Metrics & Log Links
+    - [x] Add visual indicators for the active model Tier.
+    - [x] Provide clickable links to sub-agent logs.
+
+## Phase 8: Visual Verification & Interaction Tests
+- [x] Task: Visual Verification Script
+    - [x] Create `tests/visual_mma_verification.py` to drive the GUI into various MMA states.
+    - [x] Verify MMA Dashboard visibility and progress bar.
+    - [x] Verify Ticket Queue rendering with correct status colors.
+- [x] Task: HITL Interaction Verification
+    - [x] Drive a simulated HITL pause through the verification script.
+    - [x] Manually verify the "MMA Step Approval" modal appearance.
+    - [x] Manually verify "Edit Payload" (Memory Mutator) functionality.
+- [~] Task: Final Polish & Fixes
+    - [ ] Fix any visual glitches or layout issues discovered during manual testing.
+    - [ ] Fix any visual glitches or layout issues discovered during manual testing.

conductor/archive/mma_core_engine_20260224/spec.md

@@ -0,0 +1,39 @@
+# Specification: MMA Core Engine Implementation
+
+## 1. Overview
+This track consolidates the implementation of the 4-Tier Hierarchical Multi-Model Architecture into the `manual_slop` codebase. The architecture transitions the current monolithic single-agent loop into a compartmentalized, token-efficient, and fully debuggable state machine.
+
+## 2. Functional Requirements
+
+### Phase 1: The Memory Foundations (AST Parser)
+- Integrate `tree-sitter` and `tree-sitter-python` into `pyproject.toml` / `requirements.txt`.
+- Implement `ASTParser` in `file_cache.py` to extract strict memory views (Skeleton View, Curated View).
+- Strip function bodies from dependencies while preserving `@core_logic` or `# [HOT]` logic for the target modules.
+
+### Phase 2: State Machine & Data Structures
+- Create `models.py` incorporating strict Pydantic/Dataclass schemas for `Ticket`, `Track`, and `WorkerContext`.
+- Enforce rigid state mutators governing dependencies between tickets (e.g., locking execution until a stub generation ticket completes).
+
+### Phase 3: The Linear Orchestrator & Execution Clutch
+- Build `multi_agent_conductor.py` and a `ConductorEngine` dispatcher loop.
+- Embed the "Execution Clutch" allowing developers to pause, review, and manually rewrite payloads (JSON history mutation) before applying changes to the local filesystem.
+
+### Phase 4: Tier 4 QA Interception
+- Augment `shell_runner.py` with try/except wrappers capturing process errors (`stderr`).
+- Rather than feeding raw stack traces to an expensive model, instantly forward them to a stateless `default_cheap` sub-agent for a 20-word summarization that is subsequently injected into the primary worker's context.
+
+### Phase 5: UI Decoupling & Tier 1/2 Routing (The Final Boss)
+- Disconnect `gui_2.py` from direct LLM inference requests.
+- Bind the GUI to a synchronous or `asyncio.Queue` Event Bus managed by the Orchestrator, allowing dynamic tracking of parallel worker executions without thread-locking the interface.
+
+## 3. Acceptance Criteria
+- [ ] A 1000-line script can be successfully parsed into a 100-line AST Skeleton.
+- [ ] Tickets properly block and resolve depending on stub-generation dependencies.
+- [ ] Shell errors are compressed into >50-token hints using the cheap utility model.
+- [ ] The GUI remains responsive during multi-model generation phases.
+
+## 4. Meta-Track Reference & Source of Truth
+For the original rationale, API formatting recommendations (e.g., Godot ECS schemas vs Nested JSON), and strict token firewall workflows, refer back to the architectural planning meta-track: `conductor/tracks/mma_implementation_20260224/`.
+
+**Fallback Source of Truth:**
+As a fallback, any track or sub-task should absolve its source of truth by referencing the `./MMA_Support/` directory. This directory contains the original design documents and raw discussions from which the entire `mma_implementation` track and 4-Tier Architecture were initially generated.

conductor/archive/mma_dashboard_visualization_overhaul/index.md

@@ -0,0 +1,7 @@
+# MMA Dashboard Visualization Overhaul
+
+Overhauls the GUI dashboard to display a visual DAG, live streams, and track browsers.
+
+### Navigation
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)

conductor/archive/mma_dashboard_visualization_overhaul/metadata.json

@@ -0,0 +1,6 @@
+{
+  "id": "mma_dashboard_visualization_overhaul",
+  "title": "MMA Dashboard Visualization Overhaul",
+  "status": "planned",
+  "created_at": "2026-02-27T19:20:00.000000"
+}

conductor/archive/mma_dashboard_visualization_overhaul/plan.md

@@ -0,0 +1,16 @@
+# Implementation Plan: MMA Dashboard Visualization Overhaul
+
+## Phase 1: Track Browser Panel [checkpoint: 2b1cfbb]
+- [x] Task: Implement a list view in the MMA Dashboard that reads from the `tracks` directory. 2b1cfbb
+- [x] Task: Add functionality to select an active track and load its state into the UI. 2b1cfbb
+- [x] Task: Display progress bars based on task completion within the active track. 2b1cfbb
+
+## Phase 2: DAG Visualizer Component [checkpoint: 7252d75]
+- [x] Task: Design the layout for the Task DAG using DearPyGui Node Editor or collapsible Tree Nodes. 7252d75
+- [x] Task: Write the data-binding logic to map the backend Python DAG (from Track 1) to the UI visualizer. 7252d75
+- [x] Task: Add visual indicators (colors/icons) for Task statuses (Ready, Blocked, Done). 7252d75
+
+## Phase 3: Live Output Streams [checkpoint: 25b72fb]
+- [x] Task: Refactor the AI response handling to support multiple concurrent UI text streams. 25b72fb
+- [x] Task: Bind the output of Tier 1 (Planning) to a designated "Strategy" text box. 25b72fb
+- [x] Task: Bind the output of Tier 2 and spawned Tier 3/4 workers to the active Task's detail view in the DAG. 25b72fb

conductor/archive/mma_dashboard_visualization_overhaul/spec.md

@@ -0,0 +1,34 @@
+# Track Specification: MMA Dashboard Visualization Overhaul
+
+## Overview
+Make the invisible backend operations visible and interactive. The current GUI is too barebones to effectively manage a multi-agent system. This track overhauls the MMA Dashboard to provide real-time insights into tracks, task dependencies, and agent streams.
+
+## Goals
+1.  **Track Browser:** Create a dedicated panel to view all tracks, their statuses, and overall progress metrics.
+2.  **DAG Visualizer:** Implement a visual representation (hierarchical list or node graph) of the current Track's tasks, clearly indicating status and blockers.
+3.  **Live Output Streams:** Ensure the GUI text boxes stream the output of Tier 1 (Planning), Tier 2 (Directing), and Tiers 3/4 (Executing) in real-time, tied precisely to their respective tasks.
+
+## Constraints
+-   Must be built natively using DearPyGui capabilities (e.g., node editor or nested tree nodes).
+-   Must be performant and not block the main rendering loop when updating live text streams.
+
+## Context & Origins
+This track was born from the "Human Verification" phase of the initial MMA Orchestrator prototype (`mma_orchestrator_integration_20260226`). We realized that while the backend API plumbing for the hierarchical MMA tiers (Tiers 1-4) was technically functional, the product lacked the necessary state management, UX visualization, and human-in-the-loop security gates to be usable. 
+
+**Key Takeaways from the Prototype Phase:**
+- The Tier 2 (Tech Lead) needs its own track-scoped discussion history, rather than polluting the global project history.
+- Tasks within a track require a DAG (Directed Acyclic Graph) engine to manage complex dependencies and blocking states.
+- The GUI must visualize this DAG and stream the output of individual workers directly to their associated tasks.
+- We must enforce tiered context subsetting so that Tier 3/4 workers don't receive the massive global context blob, and we need a pre-spawn approval modal so the user can intercept, review, and modify worker prompts/contexts before they execute.
+
+**Instructions for the Implementing Agent:**
+As you execute this track, ensure you maintain alignment with the other Phase 2 tracks. If you learn something that impacts the dependent tracks, please append a similar "Context Summary" to their `spec.md` files before concluding your run.
+
+## Execution Order & Dependencies
+This is a multi-track phase. To ensure architectural integrity, these tracks **MUST** be executed in the following strict order:
+1. **MMA Data Architecture & DAG Engine:** (Builds the state and execution foundation)
+2. **Tiered Context Scoping & HITL Approval:** (Builds the security and context subsetting on top of the state)
+3. **[CURRENT] MMA Dashboard Visualization Overhaul:** (Builds the UI to visualize the state and subsets)
+4. **Robust Live Simulation Verification:** (Builds the tests to verify the UI and state)
+
+**Prerequisites for this track:** `Tiered Context Scoping & HITL Approval` MUST be completed (`[x]`) before starting this track.

conductor/archive/mma_data_architecture_dag_engine/index.md

@@ -0,0 +1,7 @@
+# MMA Data Architecture & DAG Engine
+
+Restructures manual_slop state and execution into a per-track DAG model.
+
+### Navigation
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)

conductor/archive/mma_data_architecture_dag_engine/metadata.json

@@ -0,0 +1,6 @@
+{
+  "id": "mma_data_architecture_dag_engine",
+  "title": "MMA Data Architecture & DAG Engine",
+  "status": "planned",
+  "created_at": "2026-02-27T19:20:00.000000"
+}