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

[openasocket]

Virtuosos

Virtuosos is Maestro's multi-account multiplexing system. It allows users to register multiple AI provider accounts (e.g., several Claude API keys or Pro subscriptions) and have Maestro intelligently distribute agent sessions across them.

Intent

Power users and teams frequently hit rate limits or usage caps on a single account, especially during intensive coding sessions with many concurrent agents. Virtuosos solves this by treating multiple accounts as a pooled resource — Maestro automatically selects the account with the most remaining capacity when spawning or restarting agents, and can seamlessly switch accounts mid-session when throttling is detected.

Value Proposition

• Uninterrupted workflows: Automatic failover when an account hits rate limits — agents switch to a healthy account and resume without user intervention
• Capacity-aware routing: New agent spawns are directed to the account with the most headroom, maximizing throughput across all registered accounts
• Usage visibility: Per-account usage dashboards with token breakdowns, sparkline trends, P90 predictions, and time-range toggles (24h/7d/30d/monthly) give users real-time insight into consumption patterns
• CLI integration: Batch playbook runs can distribute work across accounts for higher parallelism
• Graceful degradation: When all accounts are exhausted, Maestro surfaces recovery options and pauses Auto Run rather than failing silently

What's Included (32 commits, 148 files, ~14k lines)

Core Infrastructure

• Account registry store with CRUD operations and persistence
• Account directory setup service with login orchestration
• Environment variable injection per account at spawn time
• IPC handlers and preload bridge (window.maestro.accounts.*)
• Stats database v4 migration for per-account usage tracking

Multiplexing Engine

• Capacity-aware selectNextAccount() using historical usage data
• Throttle detection from agent error streams triggering automatic account switches
• Account switch execution with process restart and session resume
• Session/assignment persistence for restart recovery
• Auth recovery service and polling for expired credentials
• All-accounts-exhausted handling with recovery IPC

UI Surfaces

• VirtuososModal: Dedicated modal with tabbed Configuration/Usage views
• AccountSelector: Inline account picker for agent creation and manual switching
• AccountSwitchModal: Confirmation dialog for manual account changes
• AccountUsageDashboard: Per-account usage charts with sparklines, trend indicators, and P90 predictions
• AccountTrendChart: Time-range toggle sparklines (24h/7d/30d/monthly)
• AccountRateMetrics: Rate-of-consumption metrics display
• Inline usage badges on SessionItem and ProcessMonitor
• Account display in SymphonyModal and session merge/transfer flows

CLI & Batch

• maestro accounts CLI command for headless account management
• Batch processor integration for distributing playbook runs across accounts

Testing

• Comprehensive test suites for AccountRegistry, AccountRecoveryPoller, AccountSetup, AccountSwitcher, AccountThrottleHandler, AccountEnvInjector, and UI components

Test Plan

• Register multiple accounts via VirtuososModal and verify persistence across app restart
• Spawn agents and confirm capacity-aware account selection routes to the least-used account
• Trigger rate limiting on one account and verify automatic failover to another
• Verify usage dashboard displays accurate per-account token breakdowns and trend charts
• Run npm run test — all new and existing tests pass
• Run npm run lint — no type errors
• Test CLI maestro accounts subcommands
• Verify batch playbook runs distribute across accounts

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Full "Virtuosos" multi-account support: manage, discover, create, and configure Claude accounts with per-account limits, rotation and capacity-aware selection.
  • UI: account selector, Account Switch modal, Virtuosos modal, Accounts panel, usage dashboards, charts, history, and session/account badges.
  • CLI: list accounts and options to select/rotate accounts for playbooks.
  • Automatic throttling handling, auth-recovery flow, provider-switch workflow, and richer per-query telemetry (tokens & cost).

• Bug Fixes

  • Unified "Re-authenticate" label for auth-recovery actions.

[pedramamini]

@CodeRabbit review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds full account-multiplexing: account store/registry, setup/repair tooling, StatsDB migration v4 and account usage tracking, throttle handling, auth-recovery and switching services, CLI support and spawn env injection, renderer UI (management, selector, dashboards), IPC/preload APIs, process/listener integration, and many tests.

Changes

Cohort / File(s)	Summary
Account core modules src/main/accounts/... (account-registry.ts, account-setup.ts, account-auth-recovery.ts, account-switcher.ts, account-throttle-handler.ts, account-recovery-poller.ts, account-env-injector.ts, account-utils.ts)	New account management services: registry, setup/repair, auth-recovery, switcher, throttle handling, recovery poller, env injector, and window-bound helper. Public APIs added (classes, functions, interfaces) — review registry selection logic, persistence, and public method signatures.
Stats DB, migrations & usage src/main/stats/... (migrations.ts, schema.ts, account-usage.ts, stats-db.ts, query-events.ts, row-mappers.ts)	Migration v4: extend query_events with account/token/cost fields; add account_usage_windows & account_throttle_events tables; provide upsert/query helpers and StatsDB delegators. Review SQL, migration ordering, version bump, and delegating methods.
Process integration & listeners src/main/process-listeners/..., src/main/process-manager/... (account-usage-listener.ts, error-listener.ts, stats-listener.ts, types.ts, ExitHandler.ts)	Wire account usage aggregation, throttle/error delegation (auth_expired/rate_limited) to account handlers, and propagate usage token fields on exit/stats. Types extended for optional account deps; check listener lifecycle and dependency wiring.
Stores & initialization src/main/stores/... (account-store-types.ts, instances.ts, getters.ts, index.ts)	New accountStore added, defaults introduced, getter getAccountStore() exported and re-exported; initialization updated. Review defaults and store migration implications.
IPC / preload / main wiring src/main/ipc/handlers/..., src/main/preload/..., src/main/index.ts	New account IPC handlers and preload API (window.maestro.accounts), main startup wires AccountRegistry, handlers, poller, switcher, auth recovery; process handlers extended to inject CLAUDE_CONFIG_DIR and record prompts. Verify handler registration, permission/error paths, and preload typings.
CLI src/cli/services/account-reader.ts, src/cli/commands/accounts.ts, src/cli/services/agent-spawner.ts, src/cli/commands/run-playbook.ts, src/cli/index.ts, src/cli/services/batch-processor.ts	Add CLI account reader, accounts list command; forward configDir to agent spawns (CLAUDE_CONFIG_DIR); add --account and --account-rotation options and per-task account resolution/rotation. Check option parsing, spawn env injection, and batch-processor rotation cache.
Group-chat & grooming src/main/group-chat/..., src/main/utils/context-groomer.ts	Propagate accountRegistry and injectAccountEnv into group-chat spawn flows; GroupChat gains optional accountId; context groomer accepts accountId. Review SSH/remote spawn paths for env injection safety.
Shared types & constants src/shared/..., src/main/constants.ts, src/renderer/global.d.ts	New account-types module, DEFAULT_TOKEN_WINDOW_MS, bump STATS_DB_VERSION → 4, expand QueryEvent with token/cost fields, add REGEX_SESSION_SUFFIX. Inspect public type changes and downstream consumers.
Renderer components & UI src/renderer/components/... (AccountSelector, AccountSwitchModal, AccountsPanel, VirtuososModal, VirtuosoUsageView, AccountUsageHistory, plus many files)`	New accounts UI surface: selector, switch modal, full management panel, Virtuosos modal, usage dashboard and charts, session/account badges, and wiring for switching/recovery. Large UI additions — review accessibility, keyboard navigation, and event wiring to IPC.
Renderer hooks & stores src/renderer/hooks/..., src/renderer/stores/... (useAccountUsage.ts, provider-switch, agentStore, modalStore, input processing)`	New useAccountUsage hook (predictions/rates), useProviderSwitch, inject accountId into spawn args, agentStore now triggers auth-recovery via IPC, modalStore adds virtuosos state. Review hook algorithms (predictions), subscriptions, and prop typings.
Usage dashboards & charts src/renderer/components/UsageDashboard/...	New AccountUsageDashboard, AccountTrendChart, AccountRateMetrics, and tab integration (Virtuosos). Large visual components — review performance, data fetching cadence, and memoization.
Preload, tests & mocks src/main/preload/accounts.ts, src/__tests__/**, src/__tests__/setup.ts	Preload exposes comprehensive accounts API; tests added/updated across CLI, main, and renderer (many suites). setup.ts expands mockMaestro.accounts. Review test mocks for realism and ensure no accidental export/API regressions.
Misc & UX various (exit-listener.ts, StdoutHandler.ts, AutoRun.tsx, SettingsModal.tsx, modalPriorities.ts, renderer types)`	Standardize session-suffix regex, remove debug logs, add AutoRun recovery UI, Virtuosos feature flag, new modal priorities, extend renderer session types (accountId/accountName and migration provenance). Verify feature-flag gating and modal priority interactions.

Sequence Diagram(s)

sequenceDiagram
    participant Renderer as Renderer (Client)
    participant PM as ProcessManager
    participant AUS as AccountUsageListener
    participant Reg as AccountRegistry
    participant DB as StatsDB
    participant Notif as SafeSend

    Renderer->>PM: emit usage event (sessionId, tokens)
    PM->>AUS: forward usage event
    AUS->>Reg: getAssignment(sessionId) / try base session
    Reg-->>AUS: accountId
    AUS->>DB: upsertAccountUsageWindow(accountId, windowStart, windowEnd, tokens)
    DB-->>AUS: ack
    AUS->>DB: getAccountUsageInWindow(accountId, windowStart, windowEnd)
    DB-->>AUS: usage metrics
    AUS->>AUS: compute usagePercent & predictions
    AUS->>Notif: emit account:usage-update with metrics
    Notif-->>Renderer: usage update

Loading

sequenceDiagram
    participant Renderer as Client
    participant Auth as AccountAuthRecovery
    participant PM as ProcessManager
    participant Login as ClaudeLoginProcess
    participant Reg as AccountRegistry
    participant Notif as SafeSend

    Renderer->>Auth: recoverAuth(sessionId, accountId)
    Auth->>Reg: setStatus(accountId, 'expired')
    Auth->>PM: kill agent (sessionId)
    PM-->>Auth: killed
    Auth->>Notif: emit account:auth-recovery-started
    Auth->>Login: spawnClaudeLogin(configDir) [CLAUDE_CONFIG_DIR set]
    Login-->>Auth: exit code / timeout
    alt success
        Auth->>Reg: setStatus(accountId, 'active')
        Auth->>Notif: emit account:auth-recovery-completed
        Auth->>Notif: emit account:switch-respawn (lastPrompt)
    else failure
        Auth->>Auth: fallback syncCredentialsFromBase(configDir)
        Auth->>Notif: emit account:auth-recovery-failed
    end

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Feature: Add “Switch Provider” (safe migrate) for existing agent sessions #408 — Implements provider-switch/workflow and session migration/provenance which overlaps the provider-switch and migration-related changes in this PR.

Possibly related PRs

• Enhance the usage of Global Environment Vars #405 — Touches spawn environment handling and env merging; closely related to CLAUDE_CONFIG_DIR injection and spawn plumbing introduced here.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: Virtuosos — multi-account multiplexing and capacity-aware routing' clearly summarizes the main change—introducing a multi-account system with capacity-aware routing, which is the primary focus of this large changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Note

Due to the large number of review comments, Critical severity comments were prioritized as inline comments.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (6)

src/renderer/components/MergeSessionModal.tsx (1)

458-465: ⚠️ Potential issue | 🟠 Major

Exception silently swallowed — report to Sentry or surface to user.

The catch block logs the error but doesn't report it to Sentry or provide user feedback. Per coding guidelines, unexpected errors should bubble up for error tracking.

Proposed fix: Report to Sentry and optionally surface error state

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

 	const handleMerge = useCallback(async () => {
 		const target = viewMode === 'paste' ? pastedIdMatch : selectedTarget;
 		if (!target) return;

 		setIsMerging(true);
 		try {
 			await onMerge(target.sessionId, target.tabId, options);
 			onClose();
 		} catch (error) {
-			console.error('Merge failed:', error);
+			captureException(error, { extra: { targetSessionId: target.sessionId, targetTabId: target.tabId } });
+			// Consider adding error state to show user feedback
 		} finally {
 			setIsMerging(false);
 		}
 	}, [viewMode, pastedIdMatch, selectedTarget, options, onMerge, onClose]);

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."

🤖 Prompt for AI Agents

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

In `@src/renderer/components/MergeSessionModal.tsx` around lines 458 - 465, The
catch block in MergeSessionModal (around the onMerge call) currently only
console.error's the exception; update it to report the error to Sentry (e.g.,
call Sentry.captureException(error) after importing your Sentry client),
optionally set a local error state or trigger a user-facing notification/toast
to surface the failure to the user, and then rethrow the error so it bubbles to
the global handler; keep the final setIsMerging(false) in finally. Reference:
onMerge, setIsMerging, and the MergeSessionModal component.

src/renderer/components/UsageDashboard/ChartSkeletons.tsx (1)

343-384: ⚠️ Potential issue | 🟡 Minor

Add a skeleton for the new “accounts” view to avoid a blank loading state.

viewMode now allows 'accounts', but DashboardSkeleton doesn’t render anything for it, so the loading UI is empty. Consider mapping it to an existing skeleton or creating a dedicated one.

🧩 Minimal fallback (treat accounts like overview until a dedicated skeleton exists)

-			{viewMode === 'overview' && (
+			{(viewMode === 'overview' || viewMode === 'accounts') && (

🤖 Prompt for AI Agents

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

In `@src/renderer/components/UsageDashboard/ChartSkeletons.tsx` around lines 343 -
384, DashboardSkeleton currently accepts viewMode including 'accounts' but
doesn't render anything for it; update the component (DashboardSkeleton) to
handle viewMode === 'accounts' by mapping it to an existing skeleton (e.g.,
render the same children as 'overview': SummaryCardsSkeleton with
summaryCardsCols, the chart grid with AgentComparisonChartSkeleton and
SourceDistributionChartSkeleton, ActivityHeatmapSkeleton, and
DurationTrendsChartSkeleton) so the accounts loading state shows the same
fallback UI until a dedicated AccountsSkeleton is created; ensure you reuse the
existing props (theme, chartGridCols, summaryCardsCols) and the same structure
used in the 'overview' branch.

src/main/group-chat/group-chat-agent.ts (1)

193-233: ⚠️ Potential issue | 🟠 Major

Account environment injection is lost after SSH wrapping.

The CLAUDE_CONFIG_DIR injected at lines 196-204 is stored in spawnEnvVars, but the SSH wrapping block at lines 209-233 passes the original configResolution.effectiveCustomEnvVars ?? effectiveEnvVars (line 217) to wrapSpawnWithSsh, then overwrites spawnEnvVars with sshWrapped.customEnvVars (line 229). This discards the injected account config for SSH-spawned participants.

🔧 Proposed fix: Pass the updated spawnEnvVars to SSH wrapping

 	// Inject CLAUDE_CONFIG_DIR for account multiplexing
 	if (accountRegistry) {
 		const envToInject: Record<string, string> = spawnEnvVars ? { ...spawnEnvVars } : {};
 		const assignedId = injectAccountEnv(
 			sessionId,
 			agentId,
 			envToInject,
 			accountRegistry,
 			accountId,
 		);
 		if (assignedId) {
 			spawnEnvVars = envToInject;
 		}
 	}
 
 	// Apply SSH wrapping if SSH is configured and store is available
 	if (sshStore && sessionOverrides?.sshRemoteConfig) {
 		console.log(`[GroupChat:Debug] Applying SSH wrapping for participant...`);
 		const sshWrapped = await wrapSpawnWithSsh(
 			{
 				command,
 				args: configResolution.args,
 				cwd,
 				prompt,
-				customEnvVars: configResolution.effectiveCustomEnvVars ?? effectiveEnvVars,
+				customEnvVars: spawnEnvVars,
 				promptArgs: agentConfig?.promptArgs,
 				noPromptSeparator: agentConfig?.noPromptSeparator,
 				agentBinaryName: agentConfig?.binaryName,
 			},
 			sessionOverrides.sshRemoteConfig,
 			sshStore
 		);

🤖 Prompt for AI Agents

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

In `@src/main/group-chat/group-chat-agent.ts` around lines 193 - 233, The account
env injected by injectAccountEnv into spawnEnvVars is being dropped because
wrapSpawnWithSsh is called with configResolution.effectiveCustomEnvVars ??
effectiveEnvVars instead of the possibly-updated spawnEnvVars; update the
wrapSpawnWithSsh call to pass spawnEnvVars (the variable possibly mutated by
injectAccountEnv) and after the call ensure you merge/retain existing keys when
applying sshWrapped.customEnvVars (i.e., merge sshWrapped.customEnvVars into
spawnEnvVars rather than wholesale replace) so CLAUDE_CONFIG_DIR and other
injected values persist; key symbols: injectAccountEnv, spawnEnvVars,
wrapSpawnWithSsh, configResolution.effectiveCustomEnvVars, effectiveEnvVars,
sshWrapped.customEnvVars.

src/main/group-chat/group-chat-router.ts (1)

523-562: ⚠️ Potential issue | 🟠 Major

SSH spawns drop the injected account env.
At Line 541 and Line 947 the SSH wrapper receives pre‑injection env vars, so CLAUDE_CONFIG_DIR doesn’t reach the remote process. Pass the post‑injection env variables to preserve account assignment.

🔧 Suggested fix

 					const sshWrapped = await wrapSpawnWithSsh(
 						{
 							command,
 							args: finalArgs,
 							cwd: os.homedir(),
 							prompt: fullPrompt,
-							customEnvVars:
-								configResolution.effectiveCustomEnvVars ??
-								getCustomEnvVarsCallback?.(chat.moderatorAgentId),
+							customEnvVars: spawnEnvVars,
 							promptArgs: agent.promptArgs,
 							noPromptSeparator: agent.noPromptSeparator,
 							agentBinaryName: agent.binaryName,
 						},
@@
 					const sshWrapped = await wrapSpawnWithSsh(
 						{
 							command: spawnCommand,
 							args: spawnArgs,
 							cwd,
 							prompt: participantPrompt,
-							customEnvVars:
-								configResolution.effectiveCustomEnvVars ??
-								getCustomEnvVarsCallback?.(participant.agentId),
+							customEnvVars: finalSpawnEnvVars,
 							promptArgs: agent.promptArgs,
 							noPromptSeparator: agent.noPromptSeparator,
 							agentBinaryName: agent.binaryName,
 						},

Also applies to: 927-968

🤖 Prompt for AI Agents

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

In `@src/main/group-chat/group-chat-router.ts` around lines 523 - 562, The SSH
wrapper is being called with pre-injection env vars so CLAUDE_CONFIG_DIR
injected by injectAccountEnv is lost; after calling injectAccountEnv (see
injectAccountEnv and spawnEnvVars usage) pass the updated spawnEnvVars into
wrapSpawnWithSsh (instead of the original custom env source) and ensure
sshWrapped.customEnvVars is set back to spawnEnvVars so the remote process
receives the post-injection environment; update both places where
wrapSpawnWithSsh is invoked (the moderator and the other agent flow) to use the
post-injection spawnEnvVars variable.

src/main/ipc/handlers/process.ts (1)

295-458: ⚠️ Potential issue | 🟠 Major

Propagate injected account env into SSH command build.
Line 443 passes effectiveCustomEnvVars, which omits the injected CLAUDE_CONFIG_DIR. Remote sessions will run under the wrong account. Use customEnvVarsToPass instead.

🔧 Suggested fix

 						const sshCommand = await buildSshCommandWithStdin(sshResult.config, {
 							command: remoteCommand,
 							args: sshArgs,
 							cwd: config.cwd,
-							env: effectiveCustomEnvVars,
+							env: customEnvVarsToPass,
 							// prompt is not passed as CLI arg - it goes via stdinInput
 							stdinInput,

🤖 Prompt for AI Agents

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

In `@src/main/ipc/handlers/process.ts` around lines 295 - 458, The SSH command is
built with effectiveCustomEnvVars which doesn't include the injected
CLAUDE_CONFIG_DIR (so remote sessions use the wrong account); change the env
passed into buildSshCommandWithStdin to use customEnvVarsToPass (the variable
that may have been updated by injectAccountEnv) instead of
effectiveCustomEnvVars so the injected account env is propagated when creating
sshCommand in this block that calls buildSshCommandWithStdin.

src/renderer/App.tsx (1)

4827-4878: ⚠️ Potential issue | 🟠 Major

Add support for clearing account assignments in Edit Agent modal.

The code only processes if (accountId), which means falsy values (null/undefined/empty) are silently ignored. If the Edit Agent flow is extended to allow users to clear an account assignment, the session fields update but the registry assignment is never cleared — there is no unassign API call, only assign and executeSwitch. Additionally, the AccountSelector component currently offers no UI affordance to unassign an account.

To properly support unassignment:

1. Add an explicit unassign handler in the account registry IPC (or extend assign to accept null/undefined).
2. Update the Edit Agent handler to call the unassign method when accountId is falsy.
3. Consider adding a "Clear" or "No Account" option to the AccountSelector dropdown if users should be able to unassign accounts.

🤖 Prompt for AI Agents

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

In `@src/renderer/App.tsx` around lines 4827 - 4878, The Edit Agent flow currently
only handles truthy accountId and never clears registry assignments; update the
handler around setSessions / sessionsRef.current to explicitly handle falsy
accountId by calling a new or existing unassign IPC (e.g.,
window.maestro.accounts.unassign(sessionId) or extend
window.maestro.accounts.assign to accept null) instead of skipping registry
updates; keep the immediate session state update (setSessions) to clear
accountId/accountName, call window.maestro.accounts.executeSwitch when switching
between accounts as before, and call window.maestro.accounts.unassign(sessionId)
when accountId is null/empty; also add a "Clear"/"No Account" option to the
AccountSelector UI so users can choose to unassign.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

rg -n "ThrottleEvent" -g'*.ts' -g'*.tsx' -C3

Repository: RunMaestro/Maestro

Length of output: 17364

---

🏁 Script executed:

rg -n "getThrottleEvents" -g'*.ts' -g'*.tsx' -C3

Repository: RunMaestro/Maestro

Length of output: 8037

---

🏁 Script executed:

rg -n "tokensAtThrottle" -g'*.ts' -g'*.tsx' -C3

Repository: RunMaestro/Maestro

Length of output: 8450

---

🏁 Script executed:

rg -n "totalTokens\|recoveryAction" -g'*.ts' -g'*.tsx' -C2

Repository: RunMaestro/Maestro

Length of output: 44

---

🏁 Script executed:

sed -n '575,639p' src/renderer/components/UsageDashboard/AccountUsageDashboard.tsx

Repository: RunMaestro/Maestro

Length of output: 2813

---

🏁 Script executed:

rg -n "totalTokens|recoveryAction" src/renderer/components/UsageDashboard/ -C2

Repository: RunMaestro/Maestro

Length of output: 9969

---

🏁 Script executed:

# Check if throttleEvents are iterated/rendered
rg -n "throttleEvents\." src/renderer/components/UsageDashboard/ -A2

Repository: RunMaestro/Maestro

Length of output: 1041

---

Fix field mismatch between throttle event payload and UI interface.

The renderer's ThrottleEvent interface expects totalTokens and recoveryAction, but the backend returns tokensAtThrottle and doesn't provide recoveryAction at all. The throttle history table at lines 607–637 accesses event.totalTokens (line 633) and event.recoveryAction (line 636), which are undefined in the received data, causing the UI to render broken values instead of token counts and recovery information.

Align the backend ThrottleEvent shape in src/main/stats/account-usage.ts to match the renderer's expected fields, or rename the fields in the renderer interface to match what the backend actually returns.

🤖 Prompt for AI Agents

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

In `@src/renderer/components/UsageDashboard/AccountUsageDashboard.tsx` around
lines 80 - 87, The renderer's AccountUsageDashboard ThrottleEvent interface
declares totalTokens and recoveryAction but the backend payload uses
tokensAtThrottle and omits recoveryAction; update either side so the shapes
match: either change the backend stats/event emitter to include totalTokens and
recoveryAction (map tokensAtThrottle -> totalTokens and add a recoveryAction
value) or modify the AccountUsageDashboard ThrottleEvent interface and the
throttle history table usage (references to event.totalTokens and
event.recoveryAction) to use event.tokensAtThrottle and handle a missing
recoveryAction (e.g., show placeholder/null guard). Ensure you update the
interface name ThrottleEvent and the table cell render logic accordingly so
rendered values are never undefined.

[openasocket]

Encore Feature Gating for Virtuosos

Virtuosos is now gated behind the Encore Features toggle system (disabled by default), following the same pattern established by Director's Notes.

Why Encore gating?

Virtuosos (multi-account multiplexing) is a power-user feature that most users won't need out of the box. Gating it behind Encore ensures:

• Clean default UX — no account-related UI clutter for users who don't use multiple accounts
• Zero overhead when disabled — all 6 IPC event listeners, session reconciliation, and default account assignment are skipped entirely
• Gradual adoption — users opt in when ready, reducing confusion for new users

Gate points (8 files, 12 gate locations)

Location	What's gated
types/index.ts	EncoreFeatureFlags.virtuosos boolean flag
settingsStore.ts	Default virtuosos: false
AccountSelector.tsx	Self-gates via useSettingsStore — returns null when disabled
App.tsx (×8)	6 account event useEffects, session reconciliation, default account assignment, both modals (AccountSwitchModal, VirtuososModal), setVirtuososOpen prop
SessionList.tsx	Optional setVirtuososOpen prop, hamburger menu button conditional
useSessionListProps.ts	Optional setVirtuososOpen in deps interface
SettingsModal.tsx	Virtuosos toggle card in Encore tab
AccountSelector.test.tsx	Mock useSettingsStore with virtuosos: true

Design decisions

• Frontend-only gating: Backend (main process) account infrastructure stays always-on — only renderer UI and event listeners are gated. This avoids complexity in the IPC layer.
• Self-gating pattern for AccountSelector: Rather than threading an enabled prop through InputArea and NewInstanceModal, AccountSelector reads the store directly and returns null. This is the same pattern used by Director's Notes.
• Reconciliation uses getState(): The session restore reconciliation runs in an async callback where the closure value of encoreFeatures could be stale, so it reads directly from the store via useSettingsStore.getState().

✅ TypeScript compiles clean, 482/482 test files pass (20,186 tests)

[coderabbitai]

Actionable comments posted: 3

🤖 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/App.tsx`:
- Around line 1245-1289: Replace the silent console.error and empty catch usage
around account reconciliation and assignment with Sentry reporting: import and
call captureException from src/utils/sentry inside the catch blocks for
window.maestro.accounts.reconcileSessions and the per-session
window.maestro.accounts.assign promise rejections (and the other listed ranges),
include contextual metadata (e.g., session.id, session.accountId, reconciliation
details) when calling captureException, and either rethrow/return a structured
failure result instead of swallowing the error so callers can handle it; update
handling in the setSessions/reconciliation flow (functions/variables:
setSessions, restoredSessions, reconciliation,
window.maestro.accounts.reconcileSessions, window.maestro.accounts.assign) to
propagate or surface errors after reporting.

In `@src/renderer/components/AccountSelector.tsx`:
- Around line 56-65: The current try/catch in the useEffect around
window.maestro.accounts.list() silently logs failures with console.warn;
instead, handle only expected/recoverable errors explicitly (e.g., check known
error codes from the accounts.list() response) and for any unexpected errors
call Sentry utilities (import captureException or captureMessage from
src/utils/sentry) with context (e.g., component name "AccountSelector" and
operation "fetch accounts"), then rethrow or let the error bubble so it is
tracked; keep the cancelled flag and setAccounts(list) behavior unchanged for
success paths and avoid swallowing unknown exceptions in the useEffect wrapper.

In `@src/renderer/components/SessionList.tsx`:
- Around line 974-977: The tooltip currently shows account info only when
session.accountName exists; update the rendering in SessionList (the JSX block
that renders the div with className "text-[10px] mb-2") to fall back to
session.accountId when session.accountName is falsy so the tooltip content
becomes Account: (session.accountName || session.accountId), and ensure the
element is rendered whenever either value is present while preserving the
existing styling using theme.colors.textDim and theme.colors.accent.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Replace silent/console-only catches with Sentry reporting.

These new account-related flows use console.error and empty .catch(() => {}), which silently swallow failures (reconcile/assign/switch/cleanup/default-assign). This both violates the renderer error-handling guideline and can leave session/account state inconsistent. Use captureException from src/utils/sentry with context and either rethrow or return a structured failure; avoid empty catches.

♻️ Example pattern (apply similarly across the listed ranges)

+import { captureException } from './utils/sentry';
...
-} catch (reconcileError) {
-	console.error('[App] Account reconciliation failed:', reconcileError);
-}
+} catch (reconcileError) {
+	captureException(reconcileError, { tags: { area: 'accounts.reconcile' } });
+	throw reconcileError;
+}
...
-window.maestro.accounts.assign(session.id, session.accountId).catch(() => {});
+window.maestro.accounts
+	.assign(session.id, session.accountId)
+	.catch((err) =>
+		captureException(err, { tags: { area: 'accounts.assign' }, extra: { sessionId: session.id } })
+	);

As per coding guidelines: “Do NOT silently swallow exceptions with try-catch-console.error blocks. Let unhandled exceptions bubble up to Sentry… Use Sentry utilities (captureException, captureMessage) from 'src/utils/sentry' for explicit error reporting with context.”

Also applies to: 1755-1812, 4855-4885, 5415-5419, 5675-5687

🤖 Prompt for AI Agents

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

In `@src/renderer/App.tsx` around lines 1245 - 1289, Replace the silent
console.error and empty catch usage around account reconciliation and assignment
with Sentry reporting: import and call captureException from src/utils/sentry
inside the catch blocks for window.maestro.accounts.reconcileSessions and the
per-session window.maestro.accounts.assign promise rejections (and the other
listed ranges), include contextual metadata (e.g., session.id,
session.accountId, reconciliation details) when calling captureException, and
either rethrow/return a structured failure result instead of swallowing the
error so callers can handle it; update handling in the
setSessions/reconciliation flow (functions/variables: setSessions,
restoredSessions, reconciliation, window.maestro.accounts.reconcileSessions,
window.maestro.accounts.assign) to propagate or surface errors after reporting.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Don’t swallow account list failures—report via Sentry.

console.warn hides failures and bypasses error tracking. Handle only expected error codes; otherwise capture and let unexpected errors bubble.

🐛 Suggested fix

@@
-import type { AccountProfile } from '../../shared/account-types';
+import type { AccountProfile } from '../../shared/account-types';
+import { captureException } from '../utils/sentry';
@@
-		} catch (err) {
-			console.warn('[AccountSelector] Failed to fetch accounts:', err);
-		}
+		} catch (err) {
+			captureException(err, {
+				tags: { area: 'AccountSelector', action: 'accounts.list' },
+			});
+			throw err;
+		}

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. Handle only expected/recoverable errors explicitly with specific error codes. Use Sentry utilities (captureException, captureMessage) from 'src/utils/sentry' for explicit error reporting with context."

🤖 Prompt for AI Agents

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

In `@src/renderer/components/AccountSelector.tsx` around lines 56 - 65, The
current try/catch in the useEffect around window.maestro.accounts.list()
silently logs failures with console.warn; instead, handle only
expected/recoverable errors explicitly (e.g., check known error codes from the
accounts.list() response) and for any unexpected errors call Sentry utilities
(import captureException or captureMessage from src/utils/sentry) with context
(e.g., component name "AccountSelector" and operation "fetch accounts"), then
rethrow or let the error bubble so it is tracked; keep the cancelled flag and
setAccounts(list) behavior unchanged for success paths and avoid swallowing
unknown exceptions in the useEffect wrapper.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Tooltip should fall back to accountId when accountName is missing.

Right now the tooltip omits account info when accountName is undefined, while the context menu shows accountId. Using the same fallback keeps the UI consistent.

🔧 Suggested tweak

-{session.accountName && (
+{(session.accountName || session.accountId) && (
 	<div className="text-[10px] mb-2" style={{ color: theme.colors.textDim }}>
-		Account: <span style={{ color: theme.colors.accent }}>{session.accountName}</span>
+		Account:{' '}
+		<span style={{ color: theme.colors.accent }}>
+			{session.accountName || session.accountId}
+		</span>
 	</div>
 )}

📝 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

	{session.accountName && (
	<div className="text-[10px] mb-2" style={{ color: theme.colors.textDim }}>
	Account: <span style={{ color: theme.colors.accent }}>{session.accountName}</span>
	</div>
	{(session.accountName || session.accountId) && (
	<div className="text-[10px] mb-2" style={{ color: theme.colors.textDim }}>
	Account:{' '}
	<span style={{ color: theme.colors.accent }}>
	{session.accountName || session.accountId}
	</span>
	</div>
	)}

🤖 Prompt for AI Agents

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

In `@src/renderer/components/SessionList.tsx` around lines 974 - 977, The tooltip
currently shows account info only when session.accountName exists; update the
rendering in SessionList (the JSX block that renders the div with className
"text-[10px] mb-2") to fall back to session.accountId when session.accountName
is falsy so the tooltip content becomes Account: (session.accountName ||
session.accountId), and ensure the element is rendered whenever either value is
present while preserving the existing styling using theme.colors.textDim and
theme.colors.accent.

[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.