feat: Virtuosos — multi-account multiplexing and capacity-aware routing

[openasocket]

Summary

Virtuosos is a multi-account multiplexing and capacity-aware routing system for Maestro. This PR implements the full stack — from account registry and usage tracking through provider switching, health monitoring, and detailed analytics.

Core Features

• Multi-Provider Account Management: Register and manage accounts across all supported providers — Claude Code, OpenAI Codex, Gemini CLI, OpenCode, and Factory Droid. Accounts are grouped by provider in the Accounts tab with section headers and count badges.
• Provider Auto-Discovery: "Discover Existing" scans for installed provider config directories across all providers:
  • Claude Code: `~/.claude-*` prefix directories
  • OpenAI Codex: `~/.codex` (auth via `auth.json`)
  • Gemini CLI: `~/.gemini` (auth via `oauth_creds.json`, identity from `google_accounts.json`)
  • OpenCode: `~/.opencode`
• Account Multiplexing: Capacity-aware routing distributes work across accounts based on real-time usage and throttle detection
• Provider Switching (Merge-Back): One-click "Switch Provider" action migrates an agent to a different provider while preserving full conversation context and provenance chain. Archived agents show visual treatment (reduced opacity, hollow status, migration label)
• Unarchive with Conflict Detection: Right-click context menu option to restore archived agents. Detects conflicts when another active agent shares the same name and provider — prompts user to archive or delete the conflicting agent first
• Provider Health Dashboard: Live error monitoring with health cards, error rate tracking, and automated failover configuration
• Provider Detail View: Click into any provider for deep analytics:
  • Summary stats (total queries, avg duration, reliability %, error rate)
  • Comparison benchmarks against fleet averages
  • 5 visualization charts (daily trend, hourly activity, duration distribution, error timeline, response time heatmap)
  • Clickable session list with migration timeline
  • Inline error breakdown bar
• Usage Analytics: Per-token-type breakdown, sparklines, trend indicators, P90 predictions, and time-range selectors (24h/7d/30d/monthly)
• Automated Failover: ProviderErrorTracker monitors error patterns and can automatically switch agents to healthy providers when thresholds are exceeded

Technical Highlights

• `MultiplexableAgent` type extended to `'claude-code' | 'codex' | 'opencode' | 'factory-droid' | 'gemini-cli'`
• Multi-provider discovery via `ProviderDiscoveryConfig` pattern — each provider has its own dir pattern, auth files, and identity extractor
• Server-side SQL aggregation for per-agent hourly data (`byAgentByHour`), matching the proven `byAgentByDay` pattern
• Encore Feature gating — entire Virtuosos feature set gated behind `encoreFeatures.virtuosos` toggle
• SSH-aware spawning — all agent spawn paths support SSH remote execution
• Stats DB v4 migration — account usage tracking integrated into existing stats infrastructure

Recent Fixes

• Multi-provider discovery: `discoverExistingAccounts()` rewritten from Claude-only (`~/.claude-*`) to multi-provider scanner detecting Codex, Gemini CLI, OpenCode installs
• Provider-grouped accounts UI: Accounts tab groups accounts by provider type with section headers instead of a flat list
• Create account with provider selector: New account creation form includes provider dropdown
• Unarchive conflict detection: Requires both `name` AND `toolType` match — prevents unrelated agents from blocking unarchive
• Modal accessibility: Fixed archive button contrast (white on teal → `accentForeground` on accent)
• Hourly chart data: Server-side SQL aggregation replaces broken client-side computation
• Duplicate reliability display: Removed redundant gauge chart, added compact inline error breakdown

Test Plan

• Account CRUD (create, edit, delete, list)
• Multi-provider discovery finds Claude, Codex, and Gemini CLI installs
• Accounts grouped by provider in the Accounts tab
• Provider selector in Create New Virtuoso form
• Capacity-aware account selection routes to least-used account
• Provider switch creates new session with transferred context
• Source session archived with visual treatment after switch
• Unarchive detects conflicts by name + provider type
• Unarchive modal offers archive/delete options for conflicting agent
• Provider Health Dashboard shows live error rates
• Provider Detail View charts render with real data
• Hourly activity chart populated via server-side aggregation
• Feature gated behind Encore Features toggle
• TypeScript compiles cleanly, all tests pass (485 files, 20235 tests)

Closes #408

🤖 Generated with Claude Code

[coderabbitai]

🧹 Nitpick comments (1)

src/shared/account-types.ts (1)

132-132: Move import statement to the top of the file.

The import of ToolType is placed after export statements. Standard convention is to place all imports at the top of the file for readability and consistency.

Proposed fix

Move line 132 to the top of the file:

 /**
  * Account multiplexing types for managing multiple Claude Code accounts.
  * Supports usage monitoring, limit tracking, and automatic account switching.
  */
+
+import type { ToolType } from './types';

 /** Unique identifier for an account (generated UUID) */
 export type AccountId = string;

And remove from line 132:

 export const DEFAULT_TOKEN_WINDOW_MS = 5 * 60 * 60 * 1000;

-import type { ToolType } from './types';
-
 /**
  * Configuration for automated provider failover (Virtuosos vertical swapping).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/shared/account-types.ts` at line 132, Move the import of ToolType so all
imports are grouped at the top of the file: locate the existing import statement
"import type { ToolType }" (currently after export statements) and cut it to
place alongside the other imports at the top of src/shared/account-types.ts,
ensuring no duplicate imports remain and preserving the "type" import modifier
and any ESLint/max-import-order rules.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/shared/account-types.ts`:
- Line 132: Move the import of ToolType so all imports are grouped at the top of
the file: locate the existing import statement "import type { ToolType }"
(currently after export statements) and cut it to place alongside the other
imports at the top of src/shared/account-types.ts, ensuring no duplicate imports
remain and preserving the "type" import modifier and any ESLint/max-import-order
rules.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/renderer/hooks/agent/useProviderSwitch.ts`:
- Around line 195-205: The try/catch around
window.maestro.agents.get(targetProvider) in useProviderSwitch.ts currently
swallows all errors; update the catch to distinguish expected "agent not
available" logic from unexpected IPC/infrastructure failures by reporting
unexpected errors to Sentry (or the app's error-tracking) and rethrowing (or
returning a failed state) so they don't silently continue; keep the existing
availability check using agentStatus and getAgentDisplayName(targetProvider) but
if agentCheckError looks like an infrastructure/IPC error, call the app's error
reporter (e.g., captureException) with agentCheckError and then throw the error
to fail fast.
- Around line 39-50: The ProviderSwitchRequest type includes archiveSource but
the switchProvider implementation in useProviderSwitch never uses it; either
remove archiveSource from the ProviderSwitchRequest interface or implement
archiving logic inside switchProvider (or the useProviderSwitch hook) that, when
archiveSource is true, calls the existing session-archiving routine (e.g.,
invoke the archiveSession/archiveCurrentTab function or dispatch the archive
action used elsewhere) after switching providers; update any callers or tests
accordingly to reflect the chosen approach and keep ProviderSwitchRequest and
switchProvider signatures consistent.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

rg -n 'archiveSource' src/renderer/hooks/agent/useProviderSwitch.ts

Repository: RunMaestro/Maestro

Length of output: 119

---

🏁 Script executed:

sed -n '90,110p' src/renderer/hooks/agent/useProviderSwitch.ts

Repository: RunMaestro/Maestro

Length of output: 772

---

🏁 Script executed:

sed -n '140,200p' src/renderer/hooks/agent/useProviderSwitch.ts

Repository: RunMaestro/Maestro

Length of output: 1751

---

🏁 Script executed:

rg -n 'archive' src/renderer/hooks/agent/useProviderSwitch.ts

Repository: RunMaestro/Maestro

Length of output: 236

---

Unused parameter: archiveSource is defined but never used.

The archiveSource field is defined in ProviderSwitchRequest but is not destructured or used anywhere in the switchProvider function implementation. Either implement the archive logic within this hook, or remove the field if archiving is handled by the caller.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderer/hooks/agent/useProviderSwitch.ts` around lines 39 - 50, The
ProviderSwitchRequest type includes archiveSource but the switchProvider
implementation in useProviderSwitch never uses it; either remove archiveSource
from the ProviderSwitchRequest interface or implement archiving logic inside
switchProvider (or the useProviderSwitch hook) that, when archiveSource is true,
calls the existing session-archiving routine (e.g., invoke the
archiveSession/archiveCurrentTab function or dispatch the archive action used
elsewhere) after switching providers; update any callers or tests accordingly to
reflect the chosen approach and keep ProviderSwitchRequest and switchProvider
signatures consistent.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Swallowed exception may mask infrastructure failures.

The catch block logs a warning but continues execution. If window.maestro.agents.get() fails due to IPC issues or other infrastructure problems, the operation will proceed and fail later with a less informative error.

Consider either letting the error propagate (fail fast) or explicitly handling expected failure cases while reporting unexpected ones to Sentry.

🛡️ Suggested fix to report unexpected errors

 try {
 	const agentStatus = await window.maestro.agents.get(targetProvider);
 	if (!agentStatus?.available) {
 		throw new Error(
 			`${getAgentDisplayName(targetProvider)} is not available. Please install and configure it first.`
 		);
 	}
 } catch (agentCheckError) {
-	// If we can't check, log warning but continue
-	console.warn('Could not verify agent availability:', agentCheckError);
+	// Only continue if it's a timeout or network error; otherwise fail fast
+	if (agentCheckError instanceof Error && agentCheckError.message.includes('timeout')) {
+		console.warn('Agent availability check timed out, continuing:', agentCheckError);
+	} else {
+		throw agentCheckError;
+	}
 }

As per coding guidelines: "Do NOT silently swallow exceptions with try-catch-console.error blocks. Let unhandled exceptions bubble up to Sentry for error tracking."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	try {
	const agentStatus = await window.maestro.agents.get(targetProvider);
	if (!agentStatus?.available) {
	throw new Error(
	`${getAgentDisplayName(targetProvider)} is not available. Please install and configure it first.`
	);
	}
	} catch (agentCheckError) {
	// If we can't check, log warning but continue
	console.warn('Could not verify agent availability:', agentCheckError);
	}
	try {
	const agentStatus = await window.maestro.agents.get(targetProvider);
	if (!agentStatus?.available) {
	throw new Error(
	`${getAgentDisplayName(targetProvider)} is not available. Please install and configure it first.`
	);
	}
	} catch (agentCheckError) {
	// Only continue if it's a timeout or network error; otherwise fail fast
	if (agentCheckError instanceof Error && agentCheckError.message.includes('timeout')) {
	console.warn('Agent availability check timed out, continuing:', agentCheckError);
	} else {
	throw agentCheckError;
	}
	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderer/hooks/agent/useProviderSwitch.ts` around lines 195 - 205, The
try/catch around window.maestro.agents.get(targetProvider) in
useProviderSwitch.ts currently swallows all errors; update the catch to
distinguish expected "agent not available" logic from unexpected
IPC/infrastructure failures by reporting unexpected errors to Sentry (or the
app's error-tracking) and rethrowing (or returning a failed state) so they don't
silently continue; keep the existing availability check using agentStatus and
getAgentDisplayName(targetProvider) but if agentCheckError looks like an
infrastructure/IPC error, call the app's error reporter (e.g., captureException)
with agentCheckError and then throw the error to fail fast.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/renderer/components/SwitchProviderModal.tsx`:
- Around line 239-240: The div with the onKeyDown handler (the element using
handleKeyDown) cannot receive keyboard events because it lacks focusability; add
tabIndex={0} to that div and add the "outline-none" class to preserve visual
styling (remove the eslint disable comment afterwards) so keyboard navigation
works and handleKeyDown will fire as intended.
- Around line 108-110: In SwitchProviderModal's catch block (the one that
currently does console.error('Failed to detect agents for provider switch:',
err)), replace the silent console logging with a call to our Sentry reporting
utility (e.g., reportError or captureException) and pass the caught error along
with contextual metadata (provider IDs, selected provider, user action such as
"switch provider", and any relevant state from detectAgentsForProvider or
detectAgents call) so errors are recorded in Sentry with context for debugging;
keep console.error only if you want local logs but ensure the Sentry call is the
primary error reporting mechanism.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Silent exception swallowing violates error handling guidelines.

The catch block logs to console.error but doesn't report to Sentry. Per coding guidelines, use Sentry utilities for error reporting with context rather than silently swallowing exceptions.

🛡️ Proposed fix to report error to Sentry

+import { captureException } from '../utils/sentry';

 			} catch (err) {
-				console.error('Failed to detect agents for provider switch:', err);
+				captureException(err, {
+					tags: { component: 'SwitchProviderModal' },
+					extra: { sourceToolType: sourceSession.toolType },
+				});
 			}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderer/components/SwitchProviderModal.tsx` around lines 108 - 110, In
SwitchProviderModal's catch block (the one that currently does
console.error('Failed to detect agents for provider switch:', err)), replace the
silent console logging with a call to our Sentry reporting utility (e.g.,
reportError or captureException) and pass the caught error along with contextual
metadata (provider IDs, selected provider, user action such as "switch
provider", and any relevant state from detectAgentsForProvider or detectAgents
call) so errors are recorded in Sentry with context for debugging; keep
console.error only if you want local logs but ensure the Sentry call is the
primary error reporting mechanism.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Missing tabIndex prevents keyboard navigation from working.

The <div> with onKeyDown handler lacks tabIndex={0}, so it cannot receive focus and keyboard events won't fire. The eslint-disable comment acknowledges this accessibility gap. Per coding guidelines, add tabIndex={0} and outline-none class to ensure focus works correctly.

⌨️ Proposed fix to enable keyboard focus

-			{/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
-			<div className="flex flex-col gap-4" onKeyDown={handleKeyDown}>
+			<div
+				className="flex flex-col gap-4 outline-none"
+				onKeyDown={handleKeyDown}
+				tabIndex={0}
+				ref={(el) => el?.focus()}
+			>

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	{/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
	<div className="flex flex-col gap-4" onKeyDown={handleKeyDown}>
	<div
	className="flex flex-col gap-4 outline-none"
	onKeyDown={handleKeyDown}
	tabIndex={0}
	ref={(el) => el?.focus()}
	>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderer/components/SwitchProviderModal.tsx` around lines 239 - 240, The
div with the onKeyDown handler (the element using handleKeyDown) cannot receive
keyboard events because it lacks focusability; add tabIndex={0} to that div and
add the "outline-none" class to preserve visual styling (remove the eslint
disable comment afterwards) so keyboard navigation works and handleKeyDown will
fire as intended.

[openasocket]

Multi-Provider Account Support (commits acc91b5, 29e087f)

What changed

1. Multi-provider account discovery (account-setup.ts)

The discoverExistingAccounts() function was Claude-only — it scanned for ~/.claude-* directories and nothing else. This meant Codex, Gemini CLI, and other provider installs were invisible to Virtuosos.

Rewrote it using a ProviderDiscoveryConfig pattern where each provider declares:

• Dir pattern: prefix-based (~/.claude-*) or single-dir (~/.codex, ~/.gemini)
• Auth files: ordered list of files to check for authentication status
• Identity extractor: provider-specific function to pull email/account identity from auth files

Currently discovers:

Provider	Directory	Auth detection
Claude Code	~/.claude-*	.claude.json, .credentials.json
OpenAI Codex	~/.codex	auth.json, config.toml
Gemini CLI	~/.gemini	oauth_creds.json, google_accounts.json
OpenCode	~/.opencode	config.json, auth.json

2. Provider-grouped accounts UI (AccountsPanel.tsx)

Previously rendered a flat list of accounts. Now groups them by provider type with section headers (e.g., "Claude Code — 2 accounts", "OpenAI Codex — 1 account"). Uses a local PROVIDER_DISPLAY_NAMES map that covers all MultiplexableAgent types including gemini-cli (which isn't in ToolType yet).

3. Provider selector in account creation

"Create New Virtuoso" form now includes a provider dropdown so you can register accounts for any supported provider, not just Claude Code.

4. Type system updates

• MultiplexableAgent extended: 'claude-code' | 'codex' | 'opencode' | 'factory-droid' | 'gemini-cli'
• agentType plumbed through IPC, preload, and global.d.ts for accounts:add and accounts:discover-existing

5. Unarchive conflict fix (App.tsx)

Was matching on toolType only — any agent on the same provider would trigger a false conflict (e.g., an unrelated monitoring widget blocking unarchive of a different Claude agent). Now requires both name AND toolType match.

6. Modal accessibility (UnarchiveConflictModal.tsx)

Archive button had white text on teal accent background — poor contrast. Changed to theme.colors.accentForeground for proper readability.

Reasoning

The whole point of Virtuosos is multi-provider orchestration. Having account management locked to Claude Code only undermined the provider switching, failover, and health monitoring features. With this change, a user with 2 Claude accounts, 1 Codex account, and 1 Gemini CLI install sees all of them in one place, grouped by provider, discoverable with a single click.

[openasocket]

Review Fixes Applied

All CodeRabbit review items addressed (2 critical, 1 major, 2 minor) plus conflict resolution verified across 18 files. Branch is fully rebased on main with no conflicts.

Critical Fixes

• ThrottleEvent field mismatch (AccountUsageDashboard.tsx, VirtuosoUsageView.tsx) — Frontend ThrottleEvent interface expected totalTokens and recoveryAction, but backend (account-usage.ts) sends tokensAtThrottle and never sends recoveryAction. This caused undefined values in the throttle table and broken conditional rendering. Aligned both frontend interfaces with the backend definition: renamed totalTokens → tokensAtThrottle, added missing id and sessionId fields, removed phantom recoveryAction field. Removed the "Recovery" column from the dashboard table and the recoveryAction conditional block from VirtuosoUsageView.

• SwitchProviderModal keyboard navigation broken (SwitchProviderModal.tsx) — The <div> with onKeyDown handler lacked tabIndex, so keyboard events never fired — arrow key navigation and Enter/Escape were completely non-functional. Added tabIndex={0}, outline-none class, and ref={(el) => el?.focus()} auto-focus. Removed the now-unnecessary eslint-disable for jsx-a11y/no-static-element-interactions. Follows the same pattern as AutoRunLightbox.tsx.

Major Fix

• Silent error swallowing in account flows (App.tsx, AccountSelector.tsx, SwitchProviderModal.tsx, MergeSessionModal.tsx) — 15 instances of console.error and empty .catch(() => {}) across 4 files were hiding failures from Sentry. Replaced all with Sentry.captureException(error, { extra: { operation, ...context } }). Covers: account reconciliation, switch respawn, auto-switch, account assignment, provider clearing, unarchive kill, account list fetch, agent detection, and merge execution. Decision: used operation string in every Sentry payload to make it easy to filter and triage in the Sentry dashboard.

Minor Fixes

• Unused archiveSource parameter (useProviderSwitch.ts, ProviderSwitchRequest interface) — Defined in the interface but never consumed by the hook. Archiving is handled entirely by App.tsx after the hook returns. Removed from the interface, the switchProvider() call, and JSDoc. Left archiveSource in SwitchProviderModal's onConfirmSwitch callback type and handleConfirmProviderSwitch where it is actually consumed.

• Agent availability check failure handling (useProviderSwitch.ts) — Separated the IPC call (window.maestro.agents.get) from the availability check into distinct try/catch blocks. Infrastructure failures (IPC throws) now report to Sentry with provider/agent context and re-throw a user-facing error, rather than being silently swallowed by the catch-all. The !agentStatus?.available path now correctly propagates to the outer catch.

• accountId fallback in SessionList tooltip (SessionList.tsx) — Tooltip only showed accountName, displaying nothing when the name was missing but an ID existed. Changed to session.accountName || session.accountId, matching the fallback pattern already used in the context menu.

Conflict Resolution (18 files)

Branch rebased cleanly onto main with no conflict markers. Verified integration of both sides across all 18 originally-conflicting files:

File	Verification
package-lock.json	Regenerated via npm install (removed 33 stale packages)
src/main/index.ts	All 31 IPC handler registrations present, no duplicates
src/main/preload/index.ts	All preload bridges merged (accounts, providers, wakatime, tabNaming, directorNotes)
src/main/ipc/handlers/index.ts	All handler exports present with AccountRegistry pass-through
src/main/group-chat/group-chat-storage.ts	Both sides' fields present, accountId correctly optional
src/main/stats/schema.ts + migrations.ts	Migration versions sequential (v1-v4), no collisions
src/renderer/App.tsx	Account management hooks/effects interleaved with extracted hooks
InputArea.tsx, SessionList.tsx, TabBar.tsx, MainPanel.tsx, QuickActionsModal.tsx	Both sides' UI features integrated
useMainKeyboardHandler.ts	All 55 shortcuts verified, no key collisions
useMainPanelProps.ts + session/index.ts	Hook exports merged correctly
TabBar.test.tsx	All 156 tests pass, no assertion changes needed

Verification

• ✅ 485 test files pass, 20,235 tests pass (0 failures)
• ✅ All 3 TypeScript configs clean (zero type errors)
• ⬜ Manual testing pending: multi-account switching, provider health dashboard, throttle event display