Round of Polishing

CLAUDE-PATTERNS.md

@@ -252,3 +252,28 @@ const isRemote = !!session.sshRemoteId;
 // CORRECT
 const isRemote = !!session.sshRemoteId || !!session.sessionSshRemoteConfig?.enabled;
 ```
+
+## 11. UI Bug Debugging Checklist
+
+When debugging visual issues (tooltips clipped, elements not visible, scroll behavior):
+
+1. **CSS First:** Check parent container properties before code logic:
+   - `overflow: hidden` on ancestors (clipping issues)
+   - `z-index` stacking context conflicts
+   - `position` mismatches (fixed/absolute/relative)
+
+2. **Scroll Issues:** Use `scrollIntoView({ block: 'nearest' })` not centering
+
+3. **Portal Escape:** For overlays/tooltips that get clipped, use `createPortal(el, document.body)` to escape stacking context
+
+4. **Fixed Positioning:** Elements with `position: fixed` inside transformed parents won't position relative to viewport—check ancestor transforms
+
+**Common fixes:**
+```typescript
+// Tooltip/overlay escaping parent overflow
+import { createPortal } from 'react-dom';
+{isOpen && createPortal(<Overlay />, document.body)}
+
+// Scroll element into view without centering
+element.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+```

CLAUDE.md

@@ -64,6 +64,12 @@ Use these terms consistently in code, comments, and documentation:
 
 ---
 
+## Code Style
+
+This codebase uses **tabs for indentation**, not spaces. Always match existing file indentation when editing.
+
+---
+
 ## Project Overview
 
 Maestro is an Electron desktop app for managing multiple AI coding assistants simultaneously with a keyboard-first interface.
@@ -260,6 +266,20 @@ See [[CLAUDE-PATTERNS.md]] for detailed SSH patterns.
 
 ## Debugging
 
+### Root Cause Verification (Before Implementing Fixes)
+
+Initial hypotheses are often wrong. Before implementing any fix:
+
+1. **IPC issues:** Verify handler is registered in `src/main/index.ts` before modifying caller code
+2. **UI rendering bugs:** Check CSS properties (overflow, z-index, position) on element AND parent containers before changing component logic
+3. **State not updating:** Trace the data flow from source to consumer; check if the setter is being called vs if re-render is suppressed
+4. **Feature not working:** Verify the code path is actually being executed (add temporary `console.log`, check output, then remove)
+
+**Historical patterns that wasted time:**
+- Tab naming bug: Modal coordination was "fixed" when the actual issue was an unregistered IPC handler
+- Tooltip clipping: Attempted `overflow: visible` on element when parent container had `overflow: hidden`
+- Session validation: Fixed renderer calls when handler wasn't wired in main process
+
 ### Focus Not Working
 1. Add `tabIndex={0}` or `tabIndex={-1}`
 2. Add `outline-none` class

README.md

@@ -12,6 +12,8 @@ Collaborate with AI to create detailed specification documents, then let Auto Ru
 
 Run multiple agents in parallel with a Linear/Superhuman-level responsive interface. Currently supporting **Claude Code**, **OpenAI Codex**, **OpenCode**, and **Factory Droid** with plans for additional agentic coding tools (Gemini CLI, Qwen3 Coder) based on user demand.
 
+> **How It Works:** Maestro is a pass-through to your AI provider. Whatever MCP tools, skills, permissions, or authentication you have configured in Claude Code, Codex, or OpenCode works identically in Maestro. The only difference is we're not running interactively—each task gets a prompt and returns a response, whether it's a new session or resuming a prior one.
+
 <div align="center">
   <a href="https://youtu.be/fmwwTOg7cyA?si=dJ89K54tGflKa5G4">
     <img src="https://github.com/user-attachments/assets/deaf601d-1898-4ede-bf5a-42e46874ebb3"

docs/about/overview.md

@@ -49,3 +49,4 @@ This approach mirrors methodologies like [Spec-Kit](https://github.com/github/sp
 | **History** | Timestamped log of all actions (user commands, AI responses, Auto Run completions) with session links. |
 | **Remote Control** | Web interface for mobile access. Local network or remote via Cloudflare tunnel. |
 | **CLI** | Headless command-line tool for scripting, automation, and CI/CD integration. |
+| **Provider Pass-Through** | Maestro delegates all AI work to your installed provider (Claude Code, Codex, OpenCode). Your MCP tools, custom skills, permissions, and authentication all carry over—Maestro runs them in batch mode (prompt in, response out) rather than interactive mode. |

docs/getting-started.md

@@ -14,6 +14,10 @@ Follow the [Installation](./installation) instructions for your platform, then l
 
 Maestro supports **Claude Code**, **Codex** (OpenAI), and **OpenCode** as providers. Make sure at least one is installed and authenticated.
 
+<Note>
+Maestro is a pass-through to your provider. Your MCP tools, custom skills, permissions, and authentication all work in Maestro exactly as they do when running the provider directly. The only difference is batch mode execution—Maestro sends a prompt and receives a response rather than running an interactive session.
+</Note>
+
 **Option A: Quick Setup**
 Create your first agent manually using the **+** button in the sidebar.
 

docs/installation.md

@@ -23,6 +23,10 @@ Download the latest release for your platform from the [Releases](https://github
   - [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Qwen3 Coder](https://github.com/QwenLM/Qwen-Agent) — Planned support
 - Git (optional, for git-aware features)
 
+<Note>
+Maestro is a pass-through to your provider. Your MCP tools, custom skills, permissions, and authentication all work in Maestro exactly as they do when running the provider directly—Maestro just orchestrates the conversation flow in batch mode.
+</Note>
+
 ## WSL2 Users (Windows Subsystem for Linux)
 
 <Warning>

docs/troubleshooting.md

@@ -4,6 +4,18 @@ description: System logs, process monitor, debug packages, and how to get help w
 icon: life-ring
 ---
 
+## Frequently Asked Questions
+
+**Do my MCP tools, skills, and permissions work in Maestro?**
+
+Yes. Maestro is a pass-through—it calls your provider (Claude Code, Codex, OpenCode) in batch mode rather than interactive mode. Whatever works when you run the provider directly will work in Maestro. Your MCP servers, custom skills, authentication, and tool permissions all carry over automatically.
+
+**What's the difference between running the provider directly vs. through Maestro?**
+
+The only difference is execution mode. When you run Claude Code directly, it's interactive—you send a message, watch it work, and respond in real-time. Maestro runs in batch mode: it sends a prompt, the provider processes it fully, and returns the response. This enables unattended automation via Auto Run and parallel agent management. Everything else—your tools, permissions, context—remains identical.
+
+---
+
 ## System Logs
 
 Maestro maintains detailed system logs that help diagnose issues. Access them via:

src/__tests__/integration/symphony.integration.test.ts

@@ -222,10 +222,17 @@ describe('Symphony Integration Tests', () => {
       },
     } as unknown as BrowserWindow;
 
+    // Setup mock sessions store (returns empty by default - no sessions)
+    const mockSessionsStore = {
+      get: vi.fn().mockReturnValue([]),
+      set: vi.fn(),
+    };
+
     // Setup dependencies
     mockDeps = {
       app: mockApp,
       getMainWindow: () => mockMainWindow,
+      sessionsStore: mockSessionsStore as any,
     };
 
     // Default fetch mock (successful responses)

src/__tests__/main/ipc/handlers/symphony.test.ts

@@ -64,6 +64,7 @@ describe('Symphony IPC handlers', () => {
 	let mockApp: App;
 	let mockMainWindow: BrowserWindow;
 	let mockDeps: SymphonyHandlerDependencies;
+	let mockSessionsStore: { get: ReturnType<typeof vi.fn>; set: ReturnType<typeof vi.fn> };
 
 	beforeEach(() => {
 		vi.clearAllMocks();
@@ -88,10 +89,17 @@ describe('Symphony IPC handlers', () => {
 			},
 		} as unknown as BrowserWindow;
 
+		// Setup mock sessions store (exposed for individual tests to modify)
+		mockSessionsStore = {
+			get: vi.fn().mockReturnValue([]),
+			set: vi.fn(),
+		};
+
 		// Setup dependencies
 		mockDeps = {
 			app: mockApp,
 			getMainWindow: () => mockMainWindow,
+			sessionsStore: mockSessionsStore as any,
 		};
 
 		// Default mock for fs operations
@@ -1209,7 +1217,7 @@ describe('Symphony IPC handlers', () => {
 			expect(result.state.stats.repositoriesContributed).toEqual([]);
 		});
 
-		it('should return persisted state from disk', async () => {
+		it('should return persisted state from disk (with valid sessions)', async () => {
 			const persistedState = {
 				active: [
 					{
@@ -1267,17 +1275,49 @@ describe('Symphony IPC handlers', () => {
 				},
 			};
 			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(persistedState));
+			// Mock the session to exist so the active contribution is included
+			mockSessionsStore.get.mockReturnValue([{ id: 'session-123', name: 'Test Session' }]);
 
 			const handler = handlers.get('symphony:getState');
 			const result = await handler!({} as any);
 
-			expect(result.state).toEqual(persistedState);
 			expect(result.state.active).toHaveLength(1);
 			expect(result.state.active[0].id).toBe('contrib_123');
 			expect(result.state.history).toHaveLength(1);
 			expect(result.state.stats.totalContributions).toBe(1);
 		});
 
+		it('should filter out active contributions with missing sessions', async () => {
+			const persistedState = {
+				active: [
+					{
+						id: 'contrib_with_session',
+						repoSlug: 'owner/repo',
+						sessionId: 'session-exists',
+						status: 'running',
+					},
+					{
+						id: 'contrib_orphaned',
+						repoSlug: 'owner/repo2',
+						sessionId: 'session-gone',
+						status: 'running',
+					},
+				],
+				history: [],
+				stats: { totalContributions: 0 },
+			};
+			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(persistedState));
+			// Only one session exists
+			mockSessionsStore.get.mockReturnValue([{ id: 'session-exists', name: 'Existing' }]);
+
+			const handler = handlers.get('symphony:getState');
+			const result = await handler!({} as any);
+
+			// Only the contribution with an existing session should be returned
+			expect(result.state.active).toHaveLength(1);
+			expect(result.state.active[0].id).toBe('contrib_with_session');
+		});
+
 		it('should handle file read errors gracefully', async () => {
 			vi.mocked(fs.readFile).mockRejectedValue(new Error('Permission denied'));
 
@@ -1302,26 +1342,33 @@ describe('Symphony IPC handlers', () => {
 			expect(result.contributions).toEqual([]);
 		});
 
-		it('should return all active contributions from state', async () => {
+		it('should return active contributions that have matching sessions', async () => {
 			const stateWithActive = {
 				active: [
 					{
 						id: 'contrib_1',
 						repoSlug: 'owner/repo1',
 						issueNumber: 1,
 						status: 'running',
+						sessionId: 'session_1',
 					},
 					{
 						id: 'contrib_2',
 						repoSlug: 'owner/repo2',
 						issueNumber: 2,
 						status: 'paused',
+						sessionId: 'session_2',
 					},
 				],
 				history: [],
 				stats: {},
 			};
 			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(stateWithActive));
+			// Mock sessions store to return matching sessions
+			mockSessionsStore.get.mockReturnValue([
+				{ id: 'session_1', name: 'Session 1' },
+				{ id: 'session_2', name: 'Session 2' },
+			]);
 
 			const handler = handlers.get('symphony:getActive');
 			const result = await handler!({} as any);
@@ -1330,6 +1377,39 @@ describe('Symphony IPC handlers', () => {
 			expect(result.contributions[0].id).toBe('contrib_1');
 			expect(result.contributions[1].id).toBe('contrib_2');
 		});
+
+		it('should filter out contributions whose sessions no longer exist', async () => {
+			const stateWithActive = {
+				active: [
+					{
+						id: 'contrib_1',
+						repoSlug: 'owner/repo1',
+						issueNumber: 1,
+						status: 'running',
+						sessionId: 'session_exists',
+					},
+					{
+						id: 'contrib_2',
+						repoSlug: 'owner/repo2',
+						issueNumber: 2,
+						status: 'paused',
+						sessionId: 'session_gone',
+					},
+				],
+				history: [],
+				stats: {},
+			};
+			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(stateWithActive));
+			// Only return session_exists, session_gone is missing
+			mockSessionsStore.get.mockReturnValue([{ id: 'session_exists', name: 'Existing Session' }]);
+
+			const handler = handlers.get('symphony:getActive');
+			const result = await handler!({} as any);
+
+			// Only contrib_1 should be returned since contrib_2's session is gone
+			expect(result.contributions).toHaveLength(1);
+			expect(result.contributions[0].id).toBe('contrib_1');
+		});
 	});
 
 	describe('symphony:getCompleted', () => {

src/__tests__/renderer/components/AutoRun.test.tsx

@@ -876,7 +876,7 @@ describe('AutoRun', () => {
 
 			// Use getAllByText since the refresh button exists in both document selector and empty state
 			expect(screen.getAllByText('Refresh').length).toBeGreaterThanOrEqual(1);
-			expect(screen.getByText('Select Folder')).toBeInTheDocument();
+			expect(screen.getByText('Change Folder')).toBeInTheDocument();
 		});
 
 		it('calls onRefresh when clicking Refresh in empty state', async () => {
@@ -897,8 +897,8 @@ describe('AutoRun', () => {
 			const props = createDefaultProps({ documentList: [], selectedFile: null });
 			renderWithProvider(<AutoRun {...props} />);
 
-			// Get the Select Folder button in the empty state
-			fireEvent.click(screen.getByText('Select Folder'));
+			// Get the Change Folder button in the empty state
+			fireEvent.click(screen.getByText('Change Folder'));
 
 			await waitFor(() => {
 				expect(props.onOpenSetup).toHaveBeenCalled();

src/main/index.ts

@@ -608,6 +608,7 @@ function setupIpcHandlers() {
 	registerSymphonyHandlers({
 		app,
 		getMainWindow: () => mainWindow,
+		sessionsStore,
 	});
 
 	// Register tab naming handlers for automatic tab naming

src/main/ipc/handlers/index.ts

@@ -259,6 +259,7 @@ export function registerAllHandlers(deps: HandlerDependencies): void {
 	registerSymphonyHandlers({
 		app: deps.app,
 		getMainWindow: deps.getMainWindow,
+		sessionsStore: deps.sessionsStore,
 	});
 	// Register agent error handlers (error state management)
 	registerAgentErrorHandlers();