@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/index.js

@@ -8,32 +8,48 @@ process.env.FORCE_COLOR = '3';
  * AI-powered coding assistant CLI using @compilr-dev/agents.
  * A terminal-based REPL for interacting with AI agents.
  */
+import { perf, flushStartupPerf } from './utils/startup-perf.js';
+perf('imports-start');
 import { createAgent } from './agent.js';
+import { getModelForTier } from './models/index.js';
 import { ReplV2 } from './repl-v2.js';
-import * as fs from 'fs';
-import * as diff from './ui/diff.js';
-import * as terminal from './ui/terminal.js';
+import { AgentTeam, setActiveSharedContext } from './multi-agent/index.js';
 import { getStyles } from './themes/index.js';
-import { getDefaultProvider, getDefaultModel as getDefaultModelSetting, getProjectStartupMode, getLastProjectId } from './settings/index.js';
-import { showAskUserOverlay } from './ui/ask-user-overlay.js';
+import { getDefaultProvider, getDefaultModel as getDefaultModelSetting, getProjectStartupMode, getLastProjectId, isCheckUpdatesEnabled, getLastUpdateCheck, recordUpdateCheck, isFirstRunComplete, setSetting, getSetting } from './settings/index.js';
+import { checkForUpdates, performUpdate } from './utils/update-checker.js';
 import { showAskUserSimpleOverlay } from './ui/ask-user-simple-overlay.js';
-import { showPermissionOverlay } from './ui/permission-overlay.js';
-import { showIterationLimitOverlay } from './ui/iteration-limit-overlay.js';
-import { showGuardrailOverlay } from './ui/guardrail-overlay.js';
 import { showKeysOverlay } from './ui/keys-overlay.js';
 import { projectRepository, workItemRepository } from './db/repositories/index.js';
 import { setActiveProject } from './tools/project-db.js';
 import { getFullGuidedPrompt, shouldInjectGuidedContext, } from './workflow/index.js';
 import { hasApiKey, settingsProviderToCredentialKey } from './utils/credentials.js';
-import { loadProjectMemory, formatBytes, getSizeCategory } from './utils/project-memory.js';
+import { loadProjectMemory } from './utils/project-memory.js';
 import { getGlobalAnchorManager, getAnchorManager } from './anchors/index.js';
-import { registerAskUserHandler, registerAskUserSimpleHandler, setOverlayActive, } from './shared-handlers.js';
-import chalk from 'chalk';
-const sharedState = { mode: 'normal', pendingSuggestion: null };
+import { getAuthManager } from './auth/index.js';
+import { loadMCPConfig } from './settings/mcp-config.js';
+import { isInVSCode } from './utils/vscode-detect.js';
+import { cleanupStaleDiffs } from './ui/vscode-diff-ipc.js';
+import { createPermissionHandler } from './handlers/permission-handler.js';
+import { registerDelegationHandlers } from './handlers/delegation-handlers.js';
+import { registerAskUserHandlers } from './handlers/ask-user-handlers.js';
+import { EpisodeRecorder, FileEpisodeStore, setGlobalEpisodeStore } from './episodes/index.js';
+import { updateWorkSummaryAnchor } from './episodes/work-summary-anchor.js';
+import { getSessionsPath } from './settings/paths.js';
+import * as path from 'path';
+perf('imports-done');
+const sharedState = {
+    mode: 'normal',
+    pendingSuggestion: null,
+    pendingDelegation: null,
+    vsDiffEnabled: false,
+    sessionPrefix: '',
+    vsDiffExtensionChecked: false,
+};
 // =============================================================================
 // Version
 // =============================================================================
-const VERSION = '0.4.0';
+import { VERSION } from './utils/version.js';
+export { VERSION };
 function parseArgs() {
     const args = process.argv.slice(2);
     const options = {};
@@ -51,6 +67,9 @@ function parseArgs() {
         else if (arg === '--show-filtering') {
             options.showFiltering = true;
         }
+        else if (arg === '--update') {
+            options.update = true;
+        }
         else if (arg === '--help' || arg === '-h') {
             showHelp();
             process.exit(0);
@@ -69,6 +88,7 @@ Options:
   --model, -m <model>         Model name (e.g., claude-3-5-haiku-20241022)
   --minimal                   Use minimal tool set
   --show-filtering            Show tool filtering analysis
+  --update                    Check for and install updates
   --help, -h                  Show this help
 
 Environment Variables:
@@ -81,67 +101,236 @@ Examples:
   npm run dev -- --model claude-3-5-haiku-20241022
   npm run dev -- --provider gemini --model gemini-2.0-flash
   npm run dev -- --minimal --show-filtering
+  npm run dev -- --update
 `);
 }
 // =============================================================================
+// MCP Initialization
+// =============================================================================
+/** MCPManager instance — stored at module level for /mcp command and cleanup */
+let mcpManagerInstance = null;
+async function createMCPManager(servers) {
+    // Dynamic import to avoid loading MCP code when not needed
+    perf('mcp-dynamic-import');
+    const { MCPManager } = await import('@compilr-dev/sdk');
+    perf('mcp-dynamic-import-done');
+    const manager = new MCPManager({ toolPrefix: 'mcp', autoConnect: true });
+    // Connect all servers in parallel — each addServer is independent
+    perf(`mcp-connect-${String(servers.length)}-servers`);
+    await Promise.allSettled(servers.map(server => manager.addServer(server)));
+    perf('mcp-connect-done');
+    return manager;
+}
+/**
+ * Initialize MCP servers and discover tools.
+ * Returns empty array if no servers configured or on error.
+ * Non-blocking: failures are silently ignored.
+ */
+async function initializeMCP(projectPath) {
+    const servers = loadMCPConfig(projectPath);
+    if (servers.length === 0) {
+        return [];
+    }
+    try {
+        const manager = await createMCPManager(servers);
+        mcpManagerInstance = manager;
+        perf('mcp-discover-tools');
+        const tools = await manager.discoverTools();
+        perf('mcp-discover-tools-done');
+        return tools;
+    }
+    catch {
+        // MCP initialization failed — continue without MCP tools
+        return [];
+    }
+}
+/** Get the MCPManager instance (for /mcp command) */
+export function getMCPManager() {
+    return mcpManagerInstance;
+}
+/**
+ * Get or lazily create an MCPManager instance.
+ * When no servers were configured at startup, mcpManagerInstance is null.
+ * This creates one on demand so the /mcp overlay can add servers at runtime.
+ */
+export async function ensureMCPManager() {
+    if (mcpManagerInstance)
+        return mcpManagerInstance;
+    const { MCPManager: MCPManagerClass } = await import('@compilr-dev/sdk');
+    mcpManagerInstance = new MCPManagerClass({ toolPrefix: 'mcp', autoConnect: true });
+    return mcpManagerInstance;
+}
+// =============================================================================
 // Main Entry Point
 // =============================================================================
 async function main() {
+    perf('main-start');
     const options = parseArgs();
+    const s = getStyles();
+    // ==========================================================================
+    // Handle --update flag: perform update and exit
+    // ==========================================================================
+    if (options.update) {
+        console.log('Checking for updates...');
+        const updateInfo = await checkForUpdates();
+        if (updateInfo.updateAvailable) {
+            console.log(s.primary(`Update available: v${updateInfo.currentVersion} → v${updateInfo.latestVersion}`));
+            console.log('Installing update...\n');
+            const result = await performUpdate();
+            console.log(result.success ? s.success(result.message) : s.error(result.message));
+        }
+        else {
+            console.log(s.success(`You're on the latest version (v${updateInfo.currentVersion})`));
+        }
+        process.exit(0);
+    }
+    // ==========================================================================
+    // Update check (deferred to background — don't block startup)
+    // ==========================================================================
+    let updateAvailable = null;
+    // Fire update check in background (result used later if available before REPL starts)
+    let updateCheckPromise = null;
+    if (isCheckUpdatesEnabled()) {
+        const lastCheck = getLastUpdateCheck();
+        const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
+        if (!lastCheck || lastCheck < oneDayAgo) {
+            updateCheckPromise = checkForUpdates()
+                .then((updateInfo) => {
+                recordUpdateCheck();
+                if (updateInfo.updateAvailable) {
+                    updateAvailable = {
+                        current: updateInfo.currentVersion,
+                        latest: updateInfo.latestVersion,
+                    };
+                }
+            })
+                .catch(() => {
+                // Silently ignore update check failures
+            });
+        }
+    }
+    // ==========================================================================
+    // VS Code diff IPC: clean up stale files from previous sessions
+    // ==========================================================================
+    perf('stale-diff-cleanup');
+    cleanupStaleDiffs(300_000); // 5 minutes
+    // ==========================================================================
+    // Authentication check (mandatory — but fast with API tokens)
+    // ==========================================================================
+    perf('auth-start');
+    const auth = getAuthManager();
+    const isAuthenticated = await auth.isAuthenticated();
+    perf('auth-done');
+    const showLogin = !isAuthenticated;
+    // Auth status is used by REPL to skip login overlay
+    // (email displayed in welcome banner, not here)
     // Resolve provider: CLI arg > settings > auto-detect
     const settingsProvider = getDefaultProvider();
-    const provider = options.provider
+    let provider = options.provider
         ?? (settingsProvider !== 'auto' ? settingsProvider : null)
         ?? detectProvider();
     // Resolve model: CLI arg > settings > provider default
     const settingsModel = getDefaultModelSetting();
-    const model = options.model ?? settingsModel ?? getDefaultModel(provider);
+    let model = options.model ?? settingsModel ?? getDefaultModel(provider);
     // Check if API key is available for selected provider (skip for ollama)
     if (provider !== 'ollama') {
         const credentialKey = settingsProviderToCredentialKey(provider === 'claude' ? 'claude' : provider);
         if (!hasApiKey(credentialKey)) {
-            const s = getStyles();
             console.log(s.warning('⚠ No API key found for ' + provider));
             console.log(s.muted('  Use --provider ollama for local models without an API key.'));
             console.log('');
-            // Show keys overlay to let user set up their key
-            const result = await showKeysOverlay();
-            // Check again after overlay closes
-            if (!result.changed || !hasApiKey(credentialKey)) {
-                console.log('');
+            // Ask user what they want to do
+            const choice = await showAskUserSimpleOverlay({
+                question: 'What would you like to do?',
+                options: [
+                    `Set API key for ${provider}`,
+                    'Switch to a different provider',
+                ],
+            });
+            if (choice.skipped) {
                 console.log(s.error('No API key configured. Cannot start.'));
-                console.log(s.muted('  Set a key with /keys or use: export ANTHROPIC_API_KEY=sk-ant-...'));
-                console.log('');
                 process.exit(1);
             }
-            console.log(s.success('✓ API key configured'));
-            console.log('');
+            if (choice.answer.includes('Switch')) {
+                // Let user pick a different provider
+                const providerChoice = await showAskUserSimpleOverlay({
+                    question: 'Select a provider:',
+                    options: [
+                        'Claude (Anthropic)',
+                        'OpenAI (GPT)',
+                        'Gemini (Google)',
+                        'Ollama (local, no key needed)',
+                    ],
+                });
+                if (providerChoice.skipped) {
+                    console.log(s.error('No provider selected. Cannot start.'));
+                    process.exit(1);
+                }
+                // Map choice to provider
+                let newProvider;
+                if (providerChoice.answer.includes('Claude')) {
+                    newProvider = 'claude';
+                }
+                else if (providerChoice.answer.includes('OpenAI')) {
+                    newProvider = 'openai';
+                }
+                else if (providerChoice.answer.includes('Gemini')) {
+                    newProvider = 'gemini';
+                }
+                else if (providerChoice.answer.includes('Ollama')) {
+                    newProvider = 'ollama';
+                }
+                else {
+                    newProvider = 'claude'; // Default fallback
+                }
+                // Update settings (provider AND model) and restart check
+                const newModel = getDefaultModel(newProvider);
+                setSetting('defaultProvider', newProvider);
+                setSetting('defaultModel', newModel);
+                provider = newProvider;
+                model = newModel;
+                console.log(s.success(`✓ Switched to ${newProvider} (${newModel})`));
+                console.log('');
+                // Re-check API key for new provider
+                if (newProvider !== 'ollama') {
+                    const newCredKey = settingsProviderToCredentialKey(newProvider);
+                    if (!hasApiKey(newCredKey)) {
+                        console.log(s.warning(`⚠ No API key found for ${newProvider}`));
+                        const result = await showKeysOverlay();
+                        if (!result.changed || !hasApiKey(newCredKey)) {
+                            console.log(s.error('No API key configured. Cannot start.'));
+                            process.exit(1);
+                        }
+                    }
+                }
+            }
+            else {
+                // Show keys overlay to set API key
+                const result = await showKeysOverlay();
+                // Check again after overlay closes
+                if (!result.changed || !hasApiKey(credentialKey)) {
+                    console.log('');
+                    console.log(s.error('No API key configured. Cannot start.'));
+                    console.log(s.muted('  Set a key with /keys or use: export ANTHROPIC_API_KEY=sk-ant-...'));
+                    console.log('');
+                    process.exit(1);
+                }
+                console.log(s.success('✓ API key configured'));
+                console.log('');
+            }
         }
     }
     // Load project memory (COMPILR.md or CLAUDE.md)
+    perf('project-memory-start');
     const projectMemory = loadProjectMemory();
     let projectContext;
     if (projectMemory.found && projectMemory.filePath) {
-        const s = getStyles();
-        const filename = projectMemory.filePath.split('/').pop() ?? 'COMPILR.md';
-        const sizeCategory = getSizeCategory(projectMemory.originalSize);
-        if (projectMemory.truncated) {
-            // Large file - was truncated
-            console.log(s.warning(`⚠ Loaded ${filename} (${formatBytes(projectMemory.originalSize)} → truncated to 100KB)`));
-        }
-        else if (sizeCategory === 'medium') {
-            // Medium file - loaded with note
-            console.log(s.muted(`  Loaded ${filename} (${formatBytes(projectMemory.originalSize)}, ~${projectMemory.estimatedTokens.toLocaleString()} tokens)`));
-        }
-        else {
-            // Small file - loaded silently (just a subtle note)
-            console.log(s.muted(`  Loaded ${filename}`));
-        }
         projectContext = projectMemory.content;
     }
     // ==========================================================================
     // Load guided mode context from database (if project uses guided mode)
     // ==========================================================================
+    perf('project-db-start');
     let guidedModeContext;
     // Determine which project to load based on projectStartup setting
     const projectStartupMode = getProjectStartupMode();
@@ -193,6 +382,7 @@ async function main() {
     // ==========================================================================
     // Load persisted anchors (critical info that survives compaction)
     // ==========================================================================
+    perf('anchors-start');
     // Load global anchors (always)
     const globalAnchors = getGlobalAnchorManager().getAll({ scope: 'persistent' });
     // Load project-specific anchors (if in a tracked project)
@@ -220,223 +410,32 @@ async function main() {
     // ==========================================================================
     // Create handlers and agent BEFORE menu (so menu can access agent info)
     // ==========================================================================
-    // Create permission handler that respects mode state
-    const onPermissionRequest = async (request) => {
-        // Auto-accept mode: allow everything without prompting
-        if (sharedState.mode === 'auto-accept') {
-            return true;
-        }
-        // V2 mode: use TerminalUI overlay system
-        if (sharedState.showPermissionOverlayV2) {
-            // Flush any accumulated text BEFORE showing the permission overlay
-            // This ensures agent's "I'll help you..." text appears before the permission prompt
-            sharedState.flushTextBuffer?.();
-            // For edit operations, pre-render diff lines for the overlay
-            let diffLines;
-            if (request.toolName === 'edit') {
-                // DEBUG: Write to file to see field names (temporary)
-                fs.appendFileSync('/tmp/compilr-debug.log', `[${new Date().toISOString()}] edit request.input: ${JSON.stringify(request.input)}\n`);
-                const filePath = ((typeof request.input.filePath === 'string' ? request.input.filePath : null) ||
-                    (typeof request.input.file_path === 'string' ? request.input.file_path : null) ||
-                    (typeof request.input.path === 'string' ? request.input.path : null) || '');
-                const oldText = ((typeof request.input.oldString === 'string' ? request.input.oldString : null) ||
-                    (typeof request.input.old_string === 'string' ? request.input.old_string : null) ||
-                    (typeof request.input.old_text === 'string' ? request.input.old_text : null) || '');
-                const newText = ((typeof request.input.newString === 'string' ? request.input.newString : null) ||
-                    (typeof request.input.new_string === 'string' ? request.input.new_string : null) ||
-                    (typeof request.input.new_text === 'string' ? request.input.new_text : null) || '');
-                const replaceAll = Boolean(request.input.replaceAll);
-                // DEBUG: Log extracted values
-                fs.appendFileSync('/tmp/compilr-debug.log', `  filePath: "${filePath}", oldText len: ${String(oldText.length)}, newText len: ${String(newText.length)}, replaceAll: ${String(replaceAll)}\n`);
-                if (filePath && oldText && newText) {
-                    const editDiff = diff.generateEditDiff(filePath, oldText, newText, replaceAll);
-                    fs.appendFileSync('/tmp/compilr-debug.log', `  editDiff: ${editDiff ? `${String(editDiff.lines.length)} lines` : 'null'}\n`);
-                    if (editDiff) {
-                        const s = getStyles();
-                        diffLines = [
-                            s.warning('● ') + chalk.bold(`Edit(${filePath.split('/').pop() ?? 'unknown'})`),
-                            diff.formatDiffHeader(filePath, editDiff.additions, editDiff.removals),
-                            ...editDiff.lines,
-                        ];
-                    }
-                }
-            }
-            const result = await sharedState.showPermissionOverlayV2({
-                toolName: request.toolName,
-                args: request.input,
-                description: request.description,
-                diffLines,
-            });
-            // Handle result
-            if (result === 'allow-always') {
-                sharedState.grantSession?.(request.toolName);
-                sharedState.setMode?.('auto-accept');
-            }
-            // null result means cancelled, treat as deny
-            return result !== null && result !== 'deny';
-        }
-        // Legacy mode: show permission prompt with manual footer coordination
-        // Flush any accumulated text BEFORE showing the permission overlay
-        // This ensures agent's "I'll help you..." text appears before the permission prompt
-        sharedState.flushTextBuffer?.();
-        // Pause footer to prevent interference with the overlay
-        sharedState.pauseFooter?.();
-        // Set overlay active flag so REPL buffers any text output
-        setOverlayActive(true);
-        // For edit operations, show the diff BEFORE the permission prompt
-        if (request.toolName === 'edit') {
-            const filePath = ((typeof request.input.filePath === 'string' ? request.input.filePath : null) ||
-                (typeof request.input.file_path === 'string' ? request.input.file_path : null) ||
-                (typeof request.input.path === 'string' ? request.input.path : null) || '');
-            const oldText = ((typeof request.input.oldString === 'string' ? request.input.oldString : null) ||
-                (typeof request.input.old_string === 'string' ? request.input.old_string : null) ||
-                (typeof request.input.old_text === 'string' ? request.input.old_text : null) || '');
-            const newText = ((typeof request.input.newString === 'string' ? request.input.newString : null) ||
-                (typeof request.input.new_string === 'string' ? request.input.new_string : null) ||
-                (typeof request.input.new_text === 'string' ? request.input.new_text : null) || '');
-            const replaceAll = Boolean(request.input.replaceAll);
-            if (filePath && oldText && newText) {
-                const editDiff = diff.generateEditDiff(filePath, oldText, newText, replaceAll);
-                const s = getStyles();
-                terminal.writeLine('');
-                if (editDiff) {
-                    terminal.writeLine(s.warning('● ') + chalk.bold(`Edit(${filePath.split('/').pop() ?? 'unknown'})`));
-                    terminal.writeLine(diff.formatDiffHeader(filePath, editDiff.additions, editDiff.removals));
-                    for (const line of editDiff.lines) {
-                        terminal.writeLine(line);
-                    }
-                    terminal.writeLine('');
-                }
-                else {
-                    // Fallback: show simple edit info
-                    terminal.writeLine(s.warning('● ') + chalk.bold(`Edit(${filePath.split('/').pop() ?? 'unknown'})`));
-                    terminal.writeLine(`  ${s.muted('⎿')}  Will replace text in ${s.primary(filePath.split('/').pop() ?? filePath)}`);
-                    terminal.writeLine(`     ${chalk.bgRed.white(' - ')} ${s.muted(oldText.slice(0, 60))}${oldText.length > 60 ? '...' : ''}`);
-                    terminal.writeLine(`     ${chalk.bgGreen.black(' + ')} ${s.muted(newText.slice(0, 60))}${newText.length > 60 ? '...' : ''}`);
-                    terminal.writeLine('');
-                }
-            }
-        }
-        try {
-            const result = await showPermissionOverlay({
-                toolName: request.toolName,
-                args: request.input,
-                description: request.description,
-            });
-            // If user chose 'allow-always', grant session permission and switch to auto-accept mode
-            if (result === 'allow-always') {
-                sharedState.grantSession?.(request.toolName);
-                // Switch to auto-accept mode so user can see and toggle back if needed
-                sharedState.setMode?.('auto-accept');
-            }
-            // Convert result to boolean (allow/allow-always = true, deny = false)
-            return result !== 'deny';
-        }
-        finally {
-            // Clear overlay active flag and resume footer
-            setOverlayActive(false);
-            sharedState.resumeFooter?.();
-        }
-    };
-    // Register ask_user handler that coordinates with footer
-    registerAskUserHandler(async (input) => {
-        // Wait for event loop to process any pending tool_end events
-        await new Promise((resolve) => setImmediate(resolve));
-        // Flush any accumulated text BEFORE showing the overlay
-        sharedState.flushTextBuffer?.();
-        // V2 mode: use TerminalUI overlay system
-        if (sharedState.showAskUserOverlayV2) {
-            return sharedState.showAskUserOverlayV2({
-                questions: input.questions,
-                context: input.context,
-            });
-        }
-        // Legacy mode: pause footer and use InlineOverlay
-        sharedState.pauseFooter?.();
-        setOverlayActive(true);
-        try {
-            // Show the overlay and get answers
-            const result = await showAskUserOverlay({
-                questions: input.questions,
-                context: input.context,
-            });
-            return result;
-        }
-        finally {
-            // Clear overlay active flag and resume footer
-            setOverlayActive(false);
-            sharedState.resumeFooter?.();
-        }
-    });
-    // Register ask_user_simple handler for smaller models (flat schema)
-    registerAskUserSimpleHandler(async (input) => {
-        // Wait for event loop to process any pending tool_end events
-        await new Promise((resolve) => setImmediate(resolve));
-        // Flush any accumulated text BEFORE showing the overlay
-        sharedState.flushTextBuffer?.();
-        // V2 mode: use TerminalUI overlay system
-        if (sharedState.showAskUserSimpleOverlayV2) {
-            return sharedState.showAskUserSimpleOverlayV2({
-                question: input.question,
-                options: input.options,
-                allowCustom: input.allowCustom,
-            });
-        }
-        // Legacy mode: pause footer and use InlineOverlay
-        sharedState.pauseFooter?.();
-        setOverlayActive(true);
-        try {
-            // Show the simple overlay and get answer
-            const result = await showAskUserSimpleOverlay({
-                question: input.question,
-                options: input.options,
-                allowCustom: input.allowCustom,
-            });
-            return result;
-        }
-        finally {
-            // Clear overlay active flag and resume footer
-            setOverlayActive(false);
-            sharedState.resumeFooter?.();
-        }
-    });
+    perf('handlers-start');
+    // Create permission handler that respects mode state and custom rules
+    const onPermissionRequest = createPermissionHandler(sharedState);
+    // Register ask_user and ask_user_simple handlers
+    registerAskUserHandlers(sharedState);
+    // Register delegate, delegate_background, and handoff handlers for multi-agent delegation
+    registerDelegationHandlers(sharedState);
     // Create iteration limit handler that shows overlay
     const onIterationLimitReached = async (context) => {
         // Wait for event loop to process any pending tool_end events
         await new Promise((resolve) => setImmediate(resolve));
         // Flush any accumulated text BEFORE showing the overlay
         sharedState.flushTextBuffer?.();
-        // V2 mode: use TerminalUI overlay system
-        if (sharedState.showIterationLimitOverlayV2) {
-            const result = await sharedState.showIterationLimitOverlayV2({
-                iteration: context.iteration,
-                maxIterations: context.maxIterations,
-                toolCallCount: context.toolCallCount,
-            });
-            if (result.continue) {
-                return result.additionalIterations;
-            }
-            return false;
+        // Use TerminalUI overlay system
+        if (!sharedState.showIterationLimitOverlayV2) {
+            throw new Error('iteration_limit overlay not initialized');
         }
-        // Legacy mode: pause footer and use InlineOverlay
-        sharedState.pauseFooter?.();
-        setOverlayActive(true);
-        try {
-            const result = await showIterationLimitOverlay({
-                iteration: context.iteration,
-                maxIterations: context.maxIterations,
-                toolCallCount: context.toolCallCount,
-            });
-            if (result.continue) {
-                return result.additionalIterations;
-            }
-            return false;
-        }
-        finally {
-            // Clear overlay active flag and resume footer
-            setOverlayActive(false);
-            sharedState.resumeFooter?.();
+        const result = await sharedState.showIterationLimitOverlayV2({
+            iteration: context.iteration,
+            maxIterations: context.maxIterations,
+            toolCallCount: context.toolCallCount,
+        });
+        if (result.continue) {
+            return result.additionalIterations;
         }
+        return false;
     };
     // Create guardrail confirmation handler (for risky operations that need approval)
     const onGuardrailTriggered = async (result, context) => {
@@ -452,35 +451,63 @@ async function main() {
             matchedInput: result.match ?? context.inputString,
             category: result.guardrail?.tags?.[0],
         };
-        // V2 mode: use TerminalUI overlay system
-        if (sharedState.showGuardrailOverlayV2) {
-            const overlayResult = await sharedState.showGuardrailOverlayV2(overlayOptions);
-            return overlayResult.approved;
-        }
-        // Legacy mode: pause footer and use InlineOverlay
-        sharedState.pauseFooter?.();
-        setOverlayActive(true);
-        try {
-            const overlayResult = await showGuardrailOverlay(overlayOptions);
-            return overlayResult.approved;
-        }
-        finally {
-            // Clear overlay active flag and resume footer
-            setOverlayActive(false);
-            sharedState.resumeFooter?.();
+        // Use TerminalUI overlay system
+        if (!sharedState.showGuardrailOverlayV2) {
+            throw new Error('guardrail overlay not initialized');
         }
+        const overlayResult = await sharedState.showGuardrailOverlayV2(overlayOptions);
+        return overlayResult.approved;
+    };
+    // ==========================================================================
+    // MCP Server Initialization (deferred — connects in background after REPL starts)
+    // ==========================================================================
+    perf('mcp-init-fire');
+    // Check if there are MCP servers to connect — fire the promise but don't await yet
+    const mcpServerCount = loadMCPConfig(dbProject?.path).length;
+    const mcpInitPromise = mcpServerCount > 0 ? initializeMCP(dbProject?.path) : null;
+    // Mutable ref for MCP tools — read by team agent factory when creating new agents.
+    // Updated when background MCP init completes.
+    let mcpToolsRef = [];
+    // ==========================================================================
+    // Episode Recorder Setup (work history tracking)
+    // ==========================================================================
+    const createEpisodeRecorder = (agentId) => {
+        if (!dbProject)
+            return undefined;
+        const episodesPath = path.join(getSessionsPath(), `project-${String(dbProject.id)}`, 'episodes.json');
+        const store = new FileEpisodeStore({ filePath: episodesPath });
+        // Set global store for recall_work tool access
+        setGlobalEpisodeStore(store);
+        return new EpisodeRecorder({
+            store,
+            agentId,
+            terminalPrefix: sharedState.sessionPrefix || 'unknown',
+            sessionId: sharedState.sessionPrefix || 'unknown',
+            onBatchFlushed: () => {
+                updateWorkSummaryAnchor({
+                    store,
+                    projectId: String(dbProject.id),
+                    getAnchorManager,
+                });
+            },
+        });
     };
-    // Create agent with permission handler and suggestion callback
+    const defaultEpisodeRecorder = createEpisodeRecorder('default');
+    // Create agent with permission handler and suggestion callback (no MCP tools yet)
+    perf('create-agent-start');
     const agent = createAgent({
         provider,
         model,
         minimal: options.minimal,
+        quiet: true,
+        enableMetaTools: !options.minimal, // Use meta-tools for token optimization
         onPermissionRequest,
         onIterationLimitReached,
         onSuggest: (event) => {
             // Store suggestion to be applied after agent finishes
             sharedState.pendingSuggestion = event.action;
         },
+        projectName: dbProject?.displayName,
         projectContext,
         guidedModeContext,
         // Anchors - library handles re-injection on every LLM call
@@ -505,19 +532,110 @@ async function main() {
         onSubagentTrackingReady: (clearTracking) => {
             sharedState.clearSubagentTracking = clearTracking;
         },
+        // MCP tools injected later via agent.registerTools() when background init completes
+        // Episode recorder for work history tracking
+        episodeRecorder: defaultEpisodeRecorder,
     });
+    perf('create-agent-done');
     // Bind grantSession for the permission handler to use
     sharedState.grantSession = (toolName) => {
         agent.grantSessionPermission(toolName);
     };
     // ==========================================================================
+    // Create AgentTeam with the default agent (or restore from persistence)
+    // ==========================================================================
+    perf('team-setup-start');
+    // Define agent factory for creating team agents
+    const agentFactory = (_config, systemPromptAddition, useMinimalSystemPrompt, noTools, toolFilter, modelTier) => {
+        // Resolve model from tier if provided, otherwise use global model
+        const agentModel = modelTier ? getModelForTier(provider, modelTier) : model;
+        // Create new agent with same base options plus role-specific system prompt
+        return Promise.resolve(createAgent({
+            provider,
+            model: agentModel,
+            minimal: options.minimal,
+            enableMetaTools: !options.minimal && !noTools, // Disable meta-tools if noTools is set
+            onPermissionRequest,
+            onIterationLimitReached,
+            onSuggest: (event) => {
+                sharedState.pendingSuggestion = event.action;
+            },
+            projectName: dbProject?.displayName,
+            projectContext,
+            guidedModeContext,
+            enableAnchors: true,
+            persistedAnchors: persistedAnchors.length > 0 ? persistedAnchors : undefined,
+            enableGuardrails: true,
+            onGuardrailTriggered,
+            onSubagentStart: (toolUseId, agentType, description) => {
+                sharedState.onSubagentStart?.(toolUseId, agentType, description);
+            },
+            onSubagentEnd: (toolUseId, success, tokenCount, error) => {
+                sharedState.onSubagentEnd?.(toolUseId, success, tokenCount, error);
+            },
+            onSubagentToolUse: (toolUseId, toolName, summary) => {
+                sharedState.onSubagentToolUse?.(toolUseId, toolName, summary);
+            },
+            onSubagentTrackingReady: (clearTracking) => {
+                sharedState.clearSubagentTracking = clearTracking;
+            },
+            // Add role-specific system prompt
+            systemPromptAddition,
+            // Use minimal system prompt (skip all modules) - for testing role identity
+            useMinimalSystemPrompt,
+            // Skip all tool registration - for testing role identity without tool interference
+            noTools,
+            // Tool filter - limit which tools this agent can use
+            toolFilter,
+            // MCP tools from external servers (reads mutable ref — includes tools once MCP init completes)
+            mcpTools: mcpToolsRef.length > 0 ? mcpToolsRef : undefined,
+            // Suppress startup logs for team agents (avoid UI interference)
+            quiet: true,
+            // Episode recorder for work history tracking (team agents share project store)
+            episodeRecorder: createEpisodeRecorder('team-agent'),
+        }));
+    };
+    // Create fresh team — team restoration happens through session restore in ReplV2.
+    // This ensures team state is always bound to a session (no independent team loading).
+    const team = new AgentTeam({
+        name: 'Team',
+        agentFactory,
+    });
+    team.setDefaultAgent(agent);
+    // Set the active shared context for activity recording
+    setActiveSharedContext(team.sharedContext);
+    // Populate shared context with actual project info so agents know the project name
+    if (dbProject) {
+        team.sharedContext.setProject({
+            id: dbProject.id,
+            name: dbProject.displayName,
+            path: dbProject.path,
+        });
+    }
+    // ==========================================================================
     // Create and run REPL
     // ==========================================================================
+    perf('repl-setup-start');
+    // Store team reference in sharedState for delegate handler access
+    sharedState.team = team;
+    // Await background update check (ran in parallel with auth + project loading)
+    if (updateCheckPromise) {
+        perf('update-check-wait');
+        await updateCheckPromise;
+        perf('update-check-done');
+    }
+    // VS Code diff: set enabled state based on settings + environment
+    perf('vscode-detect');
+    sharedState.vsDiffEnabled = isInVSCode() && getSetting('vsDiffExtension');
+    perf('repl-v2-create');
     const replV2 = new ReplV2({
         agent,
+        team,
+        agentFactory,
         model,
         provider,
         version: VERSION,
+        updateAvailable,
         projectName: dbProject?.displayName ?? process.cwd().split('/').pop(),
         // Set up V2 permission overlay callback when UI is ready
         onUIReady: (showOverlay) => {
@@ -543,6 +661,16 @@ async function main() {
         onIterationLimitReady: (showOverlay) => {
             sharedState.showIterationLimitOverlayV2 = showOverlay;
         },
+        // Set up delegate V2 overlay callback
+        onDelegateReady: (showOverlay) => {
+            sharedState.showDelegateOverlayV2 = showOverlay;
+        },
+        // Callback to handle pending delegation after agent finishes
+        onPendingDelegation: () => {
+            const pending = sharedState.pendingDelegation;
+            sharedState.pendingDelegation = null;
+            return pending ?? null;
+        },
         // Set up subagent tracking callbacks for LiveRegion rendering
         onSubagentReady: (callbacks) => {
             sharedState.onSubagentStart = callbacks.onStart;
@@ -562,13 +690,62 @@ async function main() {
                 sharedState.pendingSuggestion = null;
             }
         },
+        // Phase 3b: Set up background agent tracking callbacks for permission routing
+        onBackgroundAgentReady: (callbacks) => {
+            sharedState.isBackgroundAgent = callbacks.isBackgroundAgent;
+            sharedState.getActiveBackgroundAgentId = callbacks.getActiveBackgroundAgentId;
+            sharedState.getBackgroundAgentInfo = callbacks.getBackgroundAgentInfo;
+        },
+        // Phase 3d-beta: Set up background delegation callback for coordinator mode
+        onBackgroundDelegationReady: (runDelegation) => {
+            sharedState.runBackgroundDelegation = runDelegation;
+        },
+        // Update sharedState.team when session restore replaces the team object
+        // (so delegation handlers see restored agents, not just 'default')
+        onTeamReplaced: (newTeam) => {
+            sharedState.team = newTeam;
+        },
+        // Set session prefix for VS Code diff IPC after session registration
+        onSessionRegistered: (sessionId) => {
+            sharedState.sessionPrefix = sessionId.slice(0, 8);
+        },
+        // Show onboarding wizard on first run
+        showOnboarding: !isFirstRunComplete(),
+        // Show login overlay if not authenticated
+        showLogin,
     });
     // Handle Ctrl+C gracefully
     process.on('SIGINT', () => {
+        // Flush episode recorder before exit
+        defaultEpisodeRecorder?.flush();
         replV2.stop();
+        // Clean up MCP servers (kill child processes)
+        void mcpManagerInstance?.disconnectAll();
         process.exit(0);
     });
+    perf('repl-v2-start');
     replV2.start();
+    perf('startup-complete');
+    flushStartupPerf();
+    // Complete MCP initialization in background — inject tools once connected.
+    // Shows "mcp: connecting..." in footer status bar while loading.
+    // MCP timing details available in ~/.compilr-dev/startup-perf.log.
+    if (mcpInitPromise) {
+        replV2.setMCPLoading(true);
+        mcpInitPromise
+            .then((tools) => {
+            perf('mcp-background-done');
+            replV2.setMCPLoading(false, tools.length);
+            if (tools.length > 0) {
+                agent.registerTools(tools);
+                mcpToolsRef = tools;
+            }
+        })
+            .catch(() => {
+            // MCP failure is non-fatal — agent works without MCP tools
+            replV2.setMCPLoading(false);
+        });
+    }
     // REPL V2 runs in event loop - the ReplV2 manages its own lifecycle
 }
 // =============================================================================
@@ -587,15 +764,15 @@ function detectProvider() {
 function getDefaultModel(provider) {
     switch (provider) {
         case 'claude':
-            return 'claude-sonnet-4-20250514';
+            return 'claude-sonnet-4-5-20250929';
         case 'openai':
-            return 'gpt-4o';
+            return 'gpt-5-mini-2025-08-07';
         case 'gemini':
-            return 'gemini-2.0-flash';
+            return 'gemini-3-flash-preview';
         case 'ollama':
-            return 'llama3.2';
+            return 'llama3.2:8b';
         default:
-            return 'claude-sonnet-4-20250514';
+            return 'claude-sonnet-4-5-20250929';
     }
 }
 // =============================================================================