@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/repl-v2.js

@@ -9,35 +9,174 @@
  * Can be run standalone: npx tsx src/repl-v2.ts
  * Or imported and used with a real agent from index.ts
  */
+import { appendFileSync } from 'fs';
+import { generateEditDiff, generateWriteDiff } from './ui/diff.js';
+import { getPendingRequestsManager, setActiveSharedContext } from './multi-agent/index.js';
+import { parseInputForMentions, hasReferences, buildMessageWithContext, ContextResolver, buildContextMap, } from './multi-agent/index.js';
+import { getTeamCheckpointer } from './multi-agent/checkpointer.js';
+import { getDelegationTracker } from './multi-agent/delegation-tracker.js';
+import { initSessionRegistry, getSessionRegistry, setActiveTerminalSessionId, getActiveTerminalSessionId } from './multi-agent/session-registry.js';
+import { initFileLockManager } from './multi-agent/file-locks.js';
+import { initNotificationManager, getNotificationManager } from './multi-agent/notification-manager.js';
+import { getSessionsPath } from './settings/paths.js';
+import { setMetaToolFilter } from './tools.js';
+import { getCurrentProject } from './tools/project-db.js';
 import { TerminalUI } from './ui/terminal-ui.js';
 import * as terminal from './ui/terminal.js';
 import { getStyles } from './themes/index.js';
-import { getSettings, getStartupMode } from './settings/index.js';
+import { getSettings, getStartupMode, syncPermissionModeFromUI, getPermissionMode, permissionModeToAgentMode, getProjectSessionMode, isFirstRunComplete, getSessionRetentionDays, updateSettings } from './settings/index.js';
 import { renderMascotWithLogo } from './ui/mascot/renderer.js';
-import { registerCommands, executeCommand, allCommands, } from './commands-v2/index.js';
+import { getStartupHighlights } from './changelog/index.js';
+import { registerCommands, executeCommand, allCommands, getAutocompleteCommands, saveCurrentSession, saveCurrentTeam, loadProjectSession, archiveCurrentSession, convertMessagesToItems, } from './commands-v2/index.js';
 import { getCustomCommandRegistry } from './commands/custom-registry.js';
+import { getPlanModePrompt } from './prompts/plan-mode-prompt.js';
+import { planRepository } from './db/repositories/index.js';
+import { PlanApprovalOverlayV2, } from './ui/overlay/impl/plan-approval-overlay-v2.js';
 import { PermissionOverlayV2, } from './ui/overlay/impl/permission-overlay-v2.js';
+import { stripThinkingBlocks } from './utils/message-utils.js';
+import { truncate } from './ui/base/index.js';
 import { AskUserSimpleOverlayV2, } from './ui/overlay/impl/ask-user-simple-overlay-v2.js';
 import { GuardrailOverlayV2, } from './ui/overlay/impl/guardrail-overlay-v2.js';
 import { AskUserOverlayV2, } from './ui/overlay/impl/ask-user-overlay-v2.js';
 import { IterationLimitOverlayV2, } from './ui/overlay/impl/iteration-limit-overlay-v2.js';
+import { OnboardingWizardOverlayV2, } from './ui/overlay/impl/onboarding-wizard-overlay-v2.js';
+import { LoginOverlayV2, } from './ui/overlay/impl/login-overlay-v2.js';
+import { getAuthManager } from './auth/index.js';
+import { KeysOverlayV2 } from './ui/overlay/impl/keys-overlay-v2.js';
+import { SessionModeOverlayV2, } from './ui/overlay/impl/session-mode-overlay-v2.js';
+import { DocumentDetailOverlayV2 } from './ui/overlay/impl/document-detail-overlay-v2.js';
 import { formatToolResult } from './ui/tool-formatters.js';
+import { formatTokens } from './ui/base/index.js';
 import { isMemoryInput } from './input-handlers/index.js';
 import { addAnchor } from './anchors/index.js';
 import { getActiveProject } from './tools/project-db.js';
+import { getProjectSessionManager } from './session/project-session-manager.js';
+import { ResumeOverlayV2 } from './ui/overlay/impl/resume-overlay-v2.js';
+import { updateCacheInfo, updateHistoryEstimate, formatBreakdownCompact, formatCacheInfo, estimateTokens } from './utils/token-tracker.js';
 // Version for display (when running standalone)
 const STANDALONE_VERSION = '0.4.0-v2';
 // Register all commands on module load
 registerCommands(allCommands);
+/** Maximum messages per agent queue */
+const MAX_QUEUE_SIZE = 10;
+// =============================================================================
+// Debug Logging (set DEBUG_AGENT_REQUESTS=1 to enable)
+// =============================================================================
+const DEBUG_LOG_FILE = '/tmp/compilr-agent-debug.log';
+const DEBUG_ENABLED = process.env.DEBUG_AGENT_REQUESTS === '1';
+let debugRequestCount = 0;
+// Import tool registry functions for debug logging
+import { getDirectTools, getMetaTools, getToolStats } from './tools.js';
+import { getRegisteredMetaTools } from './tools/meta-tools.js';
+/**
+ * Write debug info to log file before agent request.
+ * Enable with: DEBUG_AGENT_REQUESTS=1 compilr
+ * View with: tail -f /tmp/compilr-agent-debug.log
+ */
+function debugLogAgentRequest(agent, message) {
+    if (!DEBUG_ENABLED)
+        return;
+    try {
+        debugRequestCount++;
+        const state = agent.serialize();
+        const timestamp = new Date().toISOString();
+        const systemPromptChars = state.systemPrompt.length;
+        const systemPromptTokens = estimateTokens(state.systemPrompt);
+        const messagesJson = JSON.stringify(state.messages);
+        const messagesTokens = estimateTokens(messagesJson);
+        // Get tool definitions for logging
+        const directTools = getDirectTools();
+        const metaTools = getMetaTools();
+        const metaRegistryTools = getRegisteredMetaTools();
+        const toolStats = getToolStats();
+        // Calculate tool definition sizes
+        const directToolsJson = JSON.stringify(directTools.map(t => ({
+            name: t.definition.name,
+            description: t.definition.description,
+            inputSchema: t.definition.inputSchema,
+        })));
+        const metaToolsJson = JSON.stringify(metaTools.map(t => ({
+            name: t.definition.name,
+            description: t.definition.description,
+            inputSchema: t.definition.inputSchema,
+        })));
+        const directToolsTokens = estimateTokens(directToolsJson);
+        const metaToolsTokens = estimateTokens(metaToolsJson);
+        const totalToolTokens = directToolsTokens + metaToolsTokens;
+        const totalEstimate = systemPromptTokens + messagesTokens + totalToolTokens;
+        const logEntry = `
+################################################################################
+# REQUEST #${String(debugRequestCount)} @ ${timestamp}
+################################################################################
+
+USER MESSAGE:
+${message.slice(0, 500)}${message.length > 500 ? '...(truncated)' : ''}
+
+CONTEXT SIZES:
+- System Prompt:  ${systemPromptChars.toLocaleString()} chars (~${systemPromptTokens.toLocaleString()} tokens)
+- Messages:       ${messagesJson.length.toLocaleString()} chars (~${messagesTokens.toLocaleString()} tokens)
+- Message Count:  ${String(state.messages.length)}
+- Direct Tools:   ${directToolsJson.length.toLocaleString()} chars (~${directToolsTokens.toLocaleString()} tokens) [${String(directTools.length)} tools]
+- Meta Tools:     ${metaToolsJson.length.toLocaleString()} chars (~${metaToolsTokens.toLocaleString()} tokens) [${String(metaTools.length)} tools]
+- Meta Registry:  ${String(metaRegistryTools.length)} tools (accessed via use_tool)
+--------------------------------------------------------------------------------
+ESTIMATED TOTAL: ~${totalEstimate.toLocaleString()} tokens
+  (prompt: ${systemPromptTokens.toLocaleString()} + messages: ${messagesTokens.toLocaleString()} + tools: ${totalToolTokens.toLocaleString()})
+
+Tool Stats: Direct=${String(toolStats.directTools)}, MetaRegistry=${String(toolStats.metaRegistryTools)}, Savings=~${String(toolStats.tokenSavings)}
+
+================================================================================
+FULL SYSTEM PROMPT (${systemPromptChars.toLocaleString()} chars):
+================================================================================
+${state.systemPrompt}
+
+================================================================================
+DIRECT TOOLS (${String(directTools.length)} tools, ~${directToolsTokens.toLocaleString()} tokens):
+================================================================================
+${directTools.map(t => `- ${t.definition.name}: ${t.definition.description.slice(0, 100)}...`).join('\n')}
+
+================================================================================
+META TOOLS (${String(metaTools.length)} tools, ~${metaToolsTokens.toLocaleString()} tokens):
+================================================================================
+${metaTools.map(t => `- ${t.definition.name}: ${t.definition.description.slice(0, 100)}...`).join('\n')}
+
+================================================================================
+META REGISTRY TOOLS (${String(metaRegistryTools.length)} tools, accessed via use_tool):
+================================================================================
+${metaRegistryTools.map(t => `- ${t.definition.name}`).join('\n')}
+
+================================================================================
+MESSAGES HISTORY (${String(state.messages.length)} messages):
+================================================================================
+${JSON.stringify(state.messages, null, 2)}
+
+`;
+        appendFileSync(DEBUG_LOG_FILE, logEntry);
+        console.log(`[DEBUG] Request #${String(debugRequestCount)} logged to ${DEBUG_LOG_FILE}`);
+        console.log(`[DEBUG] Estimated: sys:${String(systemPromptTokens)}tok + msg:${String(messagesTokens)}tok + tools:${String(totalToolTokens)}tok = ${String(totalEstimate)}tok`);
+    }
+    catch (error) {
+        console.error('[DEBUG] Failed to log agent request:', error);
+    }
+}
 // =============================================================================
 // REPL V2 Class
 // =============================================================================
 export class ReplV2 {
     agent;
+    team;
+    agentFactory;
     model;
     provider;
     version;
+    updateAvailable;
     projectName;
+    // Multi-session tracking for background agents (Phase 3)
+    sessions = new Map();
+    foregroundAgentId = null;
+    // Per-agent message queues (Phase 3 - queued messages when agent is busy)
+    agentMessageQueues = new Map();
+    // Foreground session (backward compatible - will be replaced by sessions map)
     currentSession = null;
     ui;
     onUIReady;
@@ -50,6 +189,20 @@ export class ReplV2 {
     onSuggestionReady;
     onSubagentReady;
     clearSubagentTracking;
+    showOnboarding;
+    showLogin;
+    onDelegateReady;
+    onPendingDelegation;
+    onBackgroundAgentReady;
+    onBackgroundDelegationReady;
+    onSessionRegistered;
+    onTeamReplaced;
+    authOnly;
+    restoredSessionInfo = null;
+    // Phase 3b: Track which background agent is currently executing (for permission routing)
+    // This is set during the background agent's stream loop so the permission handler knows
+    // which agent is making the request.
+    currentExecutingBackgroundAgentId = null;
     // Session stats
     startTime = new Date();
     sessionInputTokens = 0;
@@ -59,11 +212,17 @@ export class ReplV2 {
     textAccumulator = '';
     // Note: Subagent tracking is now simplified - callbacks receive toolUseId directly
     // from agent.ts, so no more FIFO queue correlation needed!
+    // Bash abort controllers for Ctrl+B backgrounding feature
+    // Maps toolUseId -> AbortController for each running bash command
+    bashAbortControllers = new Map();
     constructor(options = {}) {
         this.agent = options.agent;
+        this.team = options.team;
+        this.agentFactory = options.agentFactory;
         this.model = options.model ?? 'simulation';
         this.provider = options.provider ?? 'simulation';
         this.version = options.version ?? STANDALONE_VERSION;
+        this.updateAvailable = options.updateAvailable ?? null;
         this.projectName = options.projectName ?? process.cwd().split('/').pop() ?? 'Project';
         this.onUIReady = options.onUIReady;
         this.onTextBufferReady = options.onTextBufferReady;
@@ -75,6 +234,15 @@ export class ReplV2 {
         this.onSuggestionReady = options.onSuggestionReady;
         this.onSubagentReady = options.onSubagentReady;
         this.clearSubagentTracking = options.clearSubagentTracking;
+        this.showOnboarding = options.showOnboarding ?? false;
+        this.showLogin = options.showLogin ?? false;
+        this.onDelegateReady = options.onDelegateReady;
+        this.onPendingDelegation = options.onPendingDelegation;
+        this.onBackgroundAgentReady = options.onBackgroundAgentReady;
+        this.onBackgroundDelegationReady = options.onBackgroundDelegationReady;
+        this.onSessionRegistered = options.onSessionRegistered;
+        this.onTeamReplaced = options.onTeamReplaced;
+        this.authOnly = options.authOnly ?? false;
     }
     /**
      * Flush accumulated agent text to the UI.
@@ -83,22 +251,582 @@ export class ReplV2 {
      */
     flushTextBuffer() {
         if (this.textAccumulator.trim()) {
-            this.ui.print({ type: 'agent-text', text: this.textAccumulator.trim() });
+            this.ui.print({
+                type: 'agent-text',
+                text: this.textAccumulator.trim(),
+                expression: this.getActiveAgentMascot(),
+            });
             this.textAccumulator = '';
         }
     }
+    /**
+     * Get the mascot expression for the currently active agent.
+     * Returns the team agent's mascot if active, otherwise default neutral.
+     */
+    getActiveAgentMascot() {
+        if (this.team) {
+            const activeAgent = this.team.getActive();
+            return activeAgent.mascot;
+        }
+        return '[•_•]'; // Default neutral mascot
+    }
+    // ===========================================================================
+    // Session Management (Phase 3 - Background Agents)
+    // ===========================================================================
+    /**
+     * Start a new agent session (foreground or background).
+     * For foreground: sets currentSession and foregroundAgentId
+     * For background: only adds to sessions map
+     */
+    startSession(session) {
+        this.sessions.set(session.agentId, session);
+        if (!session.isBackground) {
+            this.currentSession = session;
+            this.foregroundAgentId = session.agentId;
+        }
+    }
+    /**
+     * End an agent session.
+     * Removes from sessions map, clears currentSession if foreground,
+     * and processes any queued messages for this agent.
+     */
+    endSession(agentId) {
+        this.sessions.delete(agentId);
+        if (this.foregroundAgentId === agentId) {
+            this.currentSession = null;
+            this.foregroundAgentId = null;
+        }
+        // Update background agent count in UI
+        this.ui.setBackgroundAgentCount(this.getBackgroundSessions().length);
+        // Process any queued messages for this agent
+        this.processAgentQueue(agentId);
+    }
+    /**
+     * Get a session by agent ID.
+     */
+    getSession(agentId) {
+        return this.sessions.get(agentId);
+    }
+    /**
+     * Get all background sessions (non-foreground).
+     */
+    getBackgroundSessions() {
+        return Array.from(this.sessions.values()).filter(s => s.isBackground);
+    }
+    /**
+     * Check if an agent has a running session.
+     */
+    hasActiveSession(agentId) {
+        return this.sessions.has(agentId);
+    }
+    /**
+     * Check if any background agents are running.
+     */
+    hasBackgroundAgents() {
+        return this.getBackgroundSessions().length > 0;
+    }
+    // ===========================================================================
+    // Per-Agent Message Queue (Phase 3)
+    // ===========================================================================
+    /**
+     * Queue a message for an agent that is currently busy.
+     * Returns the queue position (1-based).
+     */
+    queueMessage(agentId, message, displayMessage) {
+        const queue = this.agentMessageQueues.get(agentId) ?? [];
+        // Check max queue size
+        if (queue.length >= MAX_QUEUE_SIZE) {
+            return null; // Queue is full
+        }
+        const queuedMessage = {
+            id: `${agentId}-${String(Date.now())}-${Math.random().toString(36).slice(2, 8)}`,
+            message,
+            displayMessage,
+            queuedAt: new Date(),
+        };
+        queue.push(queuedMessage);
+        this.agentMessageQueues.set(agentId, queue);
+        return queue.length; // Return position (1-based)
+    }
+    /**
+     * Get the number of messages queued for an agent.
+     */
+    getQueueLength(agentId) {
+        return this.agentMessageQueues.get(agentId)?.length ?? 0;
+    }
+    /**
+     * Clear all queued messages for an agent.
+     * Returns the number of messages that were cleared.
+     */
+    clearQueue(agentId) {
+        const queue = this.agentMessageQueues.get(agentId);
+        const count = queue?.length ?? 0;
+        this.agentMessageQueues.delete(agentId);
+        return count;
+    }
+    /**
+     * Clear all message queues for all agents.
+     * Returns the total number of messages cleared.
+     */
+    clearAllQueues() {
+        let total = 0;
+        for (const queue of this.agentMessageQueues.values()) {
+            total += queue.length;
+        }
+        this.agentMessageQueues.clear();
+        return total;
+    }
+    /**
+     * Process the next message in an agent's queue.
+     * Called after an agent completes a task.
+     */
+    processAgentQueue(agentId) {
+        const queue = this.agentMessageQueues.get(agentId);
+        if (!queue || queue.length === 0) {
+            return;
+        }
+        const nextMessage = queue.shift();
+        if (!nextMessage) {
+            return; // Should never happen due to length check above
+        }
+        this.agentMessageQueues.set(agentId, queue);
+        // Show that we're processing a queued message
+        const label = this.getAgentMascotLabel(agentId);
+        const preview = truncate(nextMessage.displayMessage, 50);
+        this.ui.print({
+            type: 'info',
+            message: `${label} processing queued message: "${preview}"`,
+        });
+        // Run the queued message as a background task (non-blocking)
+        void this.runAgentBackground(agentId, nextMessage.message);
+    }
+    /**
+     * Get detailed info about background sessions (for /bg overlay).
+     * Phase 3c: Background Status & Control
+     */
+    getBackgroundSessionsInfo() {
+        const sessions = this.getBackgroundSessions();
+        const pendingManager = getPendingRequestsManager();
+        return sessions.map((session) => {
+            const teamAgent = this.team?.get(session.agentId);
+            const pendingForAgent = pendingManager.getByAgent(session.agentId);
+            const queuedCount = this.getQueueLength(session.agentId);
+            return {
+                agentId: session.agentId,
+                displayName: teamAgent?.displayName ?? session.agentId,
+                mascot: teamAgent?.mascot ?? '[•_•]',
+                currentAction: session.currentAction,
+                isBlocked: pendingForAgent.length > 0,
+                pendingCount: pendingForAgent.length,
+                queuedCount,
+            };
+        });
+    }
+    /**
+     * Send the current foreground agent to background without aborting it.
+     * The agent continues running; the user regains the input prompt.
+     * Returns the agent ID that was sent to background, or null if no foreground session.
+     */
+    sendForegroundToBackground() {
+        if (!this.currentSession || !this.foregroundAgentId) {
+            return null;
+        }
+        const agentId = this.foregroundAgentId;
+        // Reclassify session as background (agent keeps running)
+        this.currentSession.isBackground = true;
+        this.foregroundAgentId = null;
+        this.currentSession = null;
+        // Update UI state — user regains input prompt
+        this.ui.setAgentRunning(false);
+        this.ui.setThinking(false);
+        return agentId;
+    }
+    /**
+     * Consolidated agent-switching method.
+     *
+     * Performs ALL operations needed to switch the foreground to a different agent:
+     * 1. Demote current foreground agent to background (if busy + different agent)
+     * 2. team.switchTo(agentId)
+     * 3. Update this.agent reference
+     * 4. Update meta-tool filter
+     * 5. Update footer UI
+     * 6. Update foreground session tracking (restore agentRunning/spinner)
+     * 7. Record telemetry
+     *
+     * Callers handle their own messaging (different styles/wording per context).
+     */
+    async switchAgent(agentId, options = {}) {
+        const { demoteCurrentIfBusy = true, trackSession = true, recordTelemetry = true, } = options;
+        if (!this.team) {
+            throw new Error('Cannot switch agent: no team configured');
+        }
+        // 1. Demote current foreground if busy + switching to a different agent
+        let demotedAgentId = null;
+        if (demoteCurrentIfBusy &&
+            this.currentSession &&
+            this.foregroundAgentId &&
+            this.foregroundAgentId !== agentId) {
+            demotedAgentId = this.sendForegroundToBackground();
+        }
+        // 2. Switch the team's active agent
+        const teamAgent = await this.team.switchTo(agentId);
+        // 3. Update the REPL's agent reference
+        if (teamAgent.agent) {
+            this.agent = teamAgent.agent;
+        }
+        // 4. Update meta-tool filter
+        setMetaToolFilter(teamAgent.toolFilter ?? null);
+        // 5. Update footer UI
+        if (agentId !== 'default') {
+            this.ui.setActiveTeamAgent({
+                id: teamAgent.id,
+                displayName: teamAgent.displayName,
+                mascot: teamAgent.mascot,
+            });
+        }
+        else {
+            this.ui.setActiveTeamAgent(null);
+        }
+        // 5b. Update session registry with active agent
+        try {
+            const registry = getSessionRegistry();
+            if (registry) {
+                registry.setActiveAgent(agentId);
+                const agents = this.team.getAll();
+                registry.updateAgents(agents.map(a => ({
+                    id: a.id,
+                    displayName: a.displayName,
+                    mascot: a.mascot,
+                })));
+            }
+        }
+        catch {
+            // Best effort
+        }
+        // 6. Update foreground session tracking
+        if (trackSession) {
+            const existingSession = this.sessions.get(agentId);
+            if (existingSession && existingSession.isBackground) {
+                // Agent has a background session — bring it to foreground
+                existingSession.isBackground = false;
+                this.foregroundAgentId = agentId;
+                this.currentSession = existingSession;
+                // Restore busy UI state — session exists means agent is still running
+                this.ui.setAgentRunning(true);
+                if (existingSession.currentAction) {
+                    this.ui.setSpinnerText(existingSession.currentAction);
+                }
+            }
+            else if (!existingSession) {
+                // No session yet — just update foreground ID so next run creates it correctly
+                this.foregroundAgentId = agentId;
+                this.currentSession = null;
+            }
+            // If existingSession exists and is already foreground, leave it as-is
+        }
+        // 7. Record telemetry
+        if (recordTelemetry) {
+            getAuthManager().recordAgent(agentId);
+        }
+        return {
+            teamAgent: {
+                id: teamAgent.id,
+                displayName: teamAgent.displayName,
+                mascot: teamAgent.mascot,
+                agent: teamAgent.agent,
+                toolFilter: teamAgent.toolFilter,
+            },
+            demotedAgentId,
+        };
+    }
+    /**
+     * Bring a background agent to foreground.
+     * Validates the agent has a background session, then delegates to switchAgent().
+     * Phase 3c: Background Status & Control
+     */
+    async bringAgentToForeground(agentId) {
+        const session = this.sessions.get(agentId);
+        if (!session || !session.isBackground) {
+            return false;
+        }
+        const { demotedAgentId } = await this.switchAgent(agentId);
+        // Print demotion notification (if a different agent was sent to background)
+        if (demotedAgentId) {
+            const demotedLabel = this.getAgentMascotLabel(demotedAgentId);
+            this.ui.print({
+                type: 'info',
+                message: `${demotedLabel} sent to background`,
+            });
+        }
+        // Print foreground notification
+        const label = this.getAgentMascotLabel(agentId);
+        this.ui.print({
+            type: 'info',
+            message: `${label} brought to foreground`,
+        });
+        return true;
+    }
+    /**
+     * Kill/cancel a background agent.
+     * Phase 3c: Background Status & Control
+     */
+    killAgent(agentId) {
+        const session = this.sessions.get(agentId);
+        if (!session) {
+            return false;
+        }
+        // Abort the session
+        session.abortController.abort();
+        // Cancel any pending requests from this agent
+        const pendingManager = getPendingRequestsManager();
+        pendingManager.rejectAllForAgent(agentId, 'Agent killed by user');
+        // Clear queued messages (don't process on kill)
+        const discardedCount = this.clearQueue(agentId);
+        // Print notification
+        const label = this.getAgentMascotLabel(agentId);
+        let message = `${label} killed`;
+        if (discardedCount > 0) {
+            message += `. ${String(discardedCount)} queued message${discardedCount !== 1 ? 's' : ''} discarded.`;
+        }
+        this.ui.print({
+            type: 'warning',
+            message,
+        });
+        // Cancel any active delegations for this agent (no completion events)
+        getDelegationTracker().cancelAllForAgent(agentId);
+        // Session cleanup happens in the finally block of runAgentInBackground
+        // Note: We cleared the queue above, so endSession() won't process it
+        // Update background agent count immediately for responsive UI
+        this.ui.setBackgroundAgentCount(this.getBackgroundSessions().length);
+        return true;
+    }
+    /**
+     * Get mascot label for an agent (for output labeling).
+     * Format: "[◈_◈] $arch" - mascot followed by agent reference
+     */
+    getAgentMascotLabel(agentId) {
+        if (this.team) {
+            const teamAgent = this.team.get(agentId);
+            if (teamAgent) {
+                return `${teamAgent.mascot} $${agentId}`;
+            }
+        }
+        return `$${agentId}`;
+    }
+    /**
+     * Auto-expand conversation filter if user is sending to an agent not in the filter.
+     * Shows info message when filter is expanded.
+     * @returns true if filter was expanded, false otherwise
+     */
+    autoExpandFilterIfNeeded(agentId) {
+        const wasAdded = this.ui.addToConversationFilter(agentId);
+        if (wasAdded) {
+            this.ui.print({
+                type: 'info',
+                message: `Added $${agentId} to conversation filter`,
+            });
+        }
+        return wasAdded;
+    }
+    /**
+     * Regex to detect PLAN_READY marker in agent text.
+     * Format: [PLAN_READY:plan_id:plan_name]
+     */
+    static PLAN_READY_REGEX = /\[PLAN_READY:(\d+):([^\]]+)\]/;
+    /**
+     * Check if text contains PLAN_READY marker and extract plan info.
+     */
+    detectPlanReady(text) {
+        const match = ReplV2.PLAN_READY_REGEX.exec(text);
+        if (match) {
+            return {
+                planId: parseInt(match[1], 10),
+                planName: match[2],
+            };
+        }
+        return null;
+    }
+    /**
+     * Handle plan approval flow.
+     * Shows the approval overlay and handles the user's choice.
+     */
+    async handlePlanApproval(planId, planName) {
+        const overlay = new PlanApprovalOverlayV2({ planId, planName });
+        const result = await this.ui.showOverlay(overlay);
+        if (!result) {
+            // User cancelled or overlay closed without result
+            return;
+        }
+        switch (result.action) {
+            case 'approve-auto':
+                // Update plan status to approved, switch to auto-accept mode
+                try {
+                    planRepository.update(planId, { status: 'approved' });
+                    this.ui.setMode('auto-accept');
+                    this.ui.setActivePlan(planId, planName);
+                    this.ui.print({ type: 'info', message: `Plan "${planName}" approved. Switching to auto-accept mode.` });
+                }
+                catch (e) {
+                    this.ui.print({ type: 'error', message: `Failed to approve plan: ${e instanceof Error ? e.message : String(e)}` });
+                }
+                break;
+            case 'approve':
+                // Update plan status to approved, switch to normal mode
+                try {
+                    planRepository.update(planId, { status: 'approved' });
+                    this.ui.setMode('normal');
+                    this.ui.setActivePlan(planId, planName);
+                    this.ui.print({ type: 'info', message: `Plan "${planName}" approved. Switching to normal mode.` });
+                }
+                catch (e) {
+                    this.ui.print({ type: 'error', message: `Failed to approve plan: ${e instanceof Error ? e.message : String(e)}` });
+                }
+                break;
+            case 'revise':
+                // Keep plan as draft, show input for feedback
+                this.ui.print({ type: 'info', message: 'Please provide feedback on what you\'d like to change:' });
+                // The user will type their feedback as the next message
+                // The agent will receive it and update the plan
+                break;
+            case 'cancel':
+                // Mark plan as abandoned
+                try {
+                    planRepository.update(planId, { status: 'abandoned' });
+                    this.ui.clearActivePlan();
+                    this.ui.print({ type: 'warning', message: `Plan "${planName}" abandoned.` });
+                }
+                catch (e) {
+                    this.ui.print({ type: 'error', message: `Failed to abandon plan: ${e instanceof Error ? e.message : String(e)}` });
+                }
+                break;
+            case 'view':
+                // Show the full plan in document detail overlay
+                try {
+                    const plan = planRepository.getById(planId);
+                    if (plan) {
+                        // Convert Plan to ProjectDocument for the detail overlay
+                        const doc = {
+                            id: plan.id,
+                            projectId: plan.projectId,
+                            docType: 'plan',
+                            title: plan.name,
+                            content: plan.content,
+                            status: plan.status,
+                            workItemId: plan.workItemId,
+                            createdAt: plan.createdAt,
+                            updatedAt: plan.updatedAt,
+                        };
+                        const detailOverlay = new DocumentDetailOverlayV2(doc);
+                        await this.ui.showOverlay(detailOverlay);
+                    }
+                }
+                catch (e) {
+                    this.ui.print({ type: 'error', message: `Failed to load plan: ${e instanceof Error ? e.message : String(e)}` });
+                }
+                // After viewing, re-show the approval overlay
+                await this.handlePlanApproval(planId, planName);
+                break;
+        }
+    }
+    /**
+     * Restore the agent from a previous state.
+     * Called by /resume command to swap in a restored agent.
+     */
+    restoreAgent(newAgent) {
+        this.agent = newAgent;
+    }
+    /**
+     * Get the current agent instance.
+     * Used by commands that need to serialize/checkpoint the agent state.
+     */
+    getAgent() {
+        return this.agent;
+    }
     /**
      * Start the REPL.
      */
     start() {
-        // Create TerminalUI
+        // Register this terminal in the session registry (before UI so footer can subscribe)
+        try {
+            const registry = initSessionRegistry(getSessionsPath());
+            const activeProject = getActiveProject();
+            const sessionId = registry.register(activeProject?.id ?? null);
+            setActiveTerminalSessionId(sessionId);
+            // Notify index.ts of session ID (for VS Code diff IPC prefix)
+            this.onSessionRegistered?.(sessionId);
+            // Initialize file lock manager (uses same shared DB)
+            initFileLockManager();
+            // Initialize notification manager (cross-session notifications)
+            const notifManager = initNotificationManager();
+            notifManager.startPolling();
+            // Subscribe to pending requests — notify other terminals
+            getPendingRequestsManager().on('request-added', (request) => {
+                try {
+                    const sid = getActiveTerminalSessionId();
+                    const proj = getActiveProject();
+                    if (sid && proj) {
+                        notifManager.insert({
+                            projectId: proj.id,
+                            fromSessionId: sid,
+                            type: 'pending_request',
+                            title: `${request.agentId} needs ${request.type === 'permission' ? 'approval' : 'input'}`,
+                            message: request.prompt.slice(0, 200),
+                        });
+                    }
+                }
+                catch {
+                    // Best effort
+                }
+            });
+            // Sync initial team roster to registry (covers restored teams from disk)
+            if (this.team) {
+                const agents = this.team.getAll();
+                registry.updateAgents(agents.map(a => ({
+                    id: a.id,
+                    displayName: a.displayName,
+                    mascot: a.mascot,
+                })));
+            }
+        }
+        catch {
+            // Best effort — session registry is non-critical
+        }
+        // Create TerminalUI with mode synced from settings
+        const savedPermissionMode = getPermissionMode();
+        const initialUiMode = permissionModeToAgentMode(savedPermissionMode);
         this.ui = new TerminalUI({
-            initialMode: 'normal',
+            initialMode: initialUiMode,
         });
         // Print welcome screen
-        this.printWelcome();
+        // Skip if: login overlay shows its own branded welcome,
+        // or startup mode is 'menu' (the /menu command prints its own logo)
+        if (!this.showLogin && getStartupMode() !== 'menu') {
+            this.printWelcome();
+        }
         // Set initial state
         this.ui.setProjectName(this.projectName);
+        this.ui.setCommandsCallback(getAutocompleteCommands);
+        // Set up agent suggestions callback for $ autocomplete (if team is available)
+        if (this.team) {
+            const team = this.team; // Capture for closure
+            this.ui.setAgentSuggestionsCallback(() => {
+                const agents = team.getAll();
+                return agents.map((agent) => ({
+                    id: agent.id,
+                    displayName: agent.displayName,
+                    mascot: agent.mascot,
+                }));
+            });
+            // Set the active agent in the footer (for restored teams with non-default active agent)
+            const activeAgent = team.getActive();
+            if (activeAgent.id !== 'default') {
+                this.ui.setActiveTeamAgent({
+                    id: activeAgent.id,
+                    displayName: activeAgent.displayName,
+                    mascot: activeAgent.mascot,
+                });
+            }
+        }
         // Notify caller that UI is ready and provide the V2 permission overlay function
         if (this.onUIReady) {
             const ui = this.ui;
@@ -149,6 +877,24 @@ export class ReplV2 {
                 return result ?? { continue: false };
             });
         }
+        // Provide the delegate overlay function to the caller
+        // Uses AskUserSimpleOverlayV2 with a formatted delegation question
+        if (this.onDelegateReady) {
+            const ui = this.ui;
+            this.onDelegateReady(async (options) => {
+                // Build a formatted question for the delegation approval
+                const question = options.reason
+                    ? `Delegate to $${options.agentId} (${options.agentDisplayName})?\nReason: ${options.reason}\nTask: ${truncate(options.task, 100)}`
+                    : `Delegate to $${options.agentId} (${options.agentDisplayName})?\nTask: ${truncate(options.task, 100)}`;
+                const overlay = new AskUserSimpleOverlayV2({
+                    question,
+                    options: ['Yes, delegate', 'No, continue'],
+                    allowCustom: false,
+                });
+                const result = await ui.showOverlay(overlay);
+                return { approved: !result?.skipped && result?.answer === 'Yes, delegate' };
+            });
+        }
         // Provide the suggestion setter function to the caller
         if (this.onSuggestionReady) {
             const ui = this.ui;
@@ -184,6 +930,53 @@ export class ReplV2 {
                 },
             });
         }
+        // Phase 3b: Provide background agent tracking callbacks
+        if (this.onBackgroundAgentReady) {
+            this.onBackgroundAgentReady({
+                // Check if an agent is running in background
+                isBackgroundAgent: (agentId) => {
+                    if (agentId) {
+                        const session = this.sessions.get(agentId);
+                        return session?.isBackground ?? false;
+                    }
+                    // If no agentId provided, check if we're currently executing a background agent
+                    return this.currentExecutingBackgroundAgentId !== null;
+                },
+                // Get the ID of the background agent currently executing (for permission routing)
+                getActiveBackgroundAgentId: () => {
+                    return this.currentExecutingBackgroundAgentId;
+                },
+                // Get info about a background agent (mascot, etc.)
+                getBackgroundAgentInfo: (agentId) => {
+                    if (!this.team)
+                        return null;
+                    const teamAgent = this.team.get(agentId);
+                    if (!teamAgent)
+                        return null;
+                    return { mascot: teamAgent.mascot };
+                },
+            });
+        }
+        // Phase 3d-beta: Provide background delegation callback
+        if (this.onBackgroundDelegationReady) {
+            this.onBackgroundDelegationReady((agentId, message) => {
+                if (!this.agent)
+                    return null;
+                // Check if agent has an active session (busy)
+                const existingSession = this.sessions.get(agentId);
+                if (existingSession) {
+                    // Agent is busy — queue the delegation message
+                    const position = this.queueMessage(agentId, message, message.slice(0, 80));
+                    if (position === null) {
+                        return null; // Queue is full
+                    }
+                    return 'queued';
+                }
+                // Agent is free — start background session immediately
+                void this.runAgentBackground(agentId, message);
+                return 'running';
+            });
+        }
         // Event handlers
         this.ui.on('submit', (input) => {
             void this.processInput(input);
@@ -214,27 +1007,560 @@ export class ReplV2 {
         });
         this.ui.on('modeChange', () => {
             const modes = ['normal', 'auto-accept', 'plan'];
-            const currentIndex = modes.indexOf(this.ui.getMode());
+            const currentMode = this.ui.getMode();
+            const currentIndex = modes.indexOf(currentMode);
             const nextMode = modes[(currentIndex + 1) % modes.length];
             this.ui.setMode(nextMode);
-            this.ui.print({ type: 'info', message: `Mode: ${nextMode}` });
+            // Sync the permission mode setting with UI mode
+            syncPermissionModeFromUI(nextMode);
+            // Clear session grants when switching FROM auto-accept TO a more restrictive mode
+            let grantsCleared = 0;
+            if (currentMode === 'auto-accept' && nextMode !== 'auto-accept' && this.agent) {
+                const grants = this.agent.getSessionPermissions();
+                if (grants.length > 0) {
+                    grantsCleared = grants.length;
+                    this.agent.clearSessionPermissions();
+                }
+            }
+            // Show mode change message (with grant clearing info if applicable)
+            if (grantsCleared > 0) {
+                this.ui.print({
+                    type: 'info',
+                    message: `Mode: ${nextMode} (${String(grantsCleared)} grant${grantsCleared > 1 ? 's' : ''} cleared)`,
+                });
+            }
+            else {
+                this.ui.print({ type: 'info', message: `Mode: ${nextMode}` });
+            }
+        });
+        // Ctrl+B - show background tasks overlay
+        this.ui.on('showTasks', () => {
+            void (async () => {
+                const { TasksOverlayV2 } = await import('./ui/overlay/impl/tasks-overlay-v2.js');
+                const overlay = new TasksOverlayV2();
+                await this.ui.showOverlay(overlay);
+            })();
+        });
+        // Double Tab - show pending requests overlay
+        this.ui.on('showPending', () => {
+            void executeCommand('pending', '', this.createCommandContext());
+        });
+        // Ctrl+B during bash execution - move to background
+        this.ui.on('backgroundBash', (info) => {
+            const controller = this.bashAbortControllers.get(info.toolUseId);
+            if (controller) {
+                // Signal the bash tool to move process to ShellManager
+                controller.abort('background');
+                this.bashAbortControllers.delete(info.toolUseId);
+            }
+        });
+        // Start UI (skip initial render if a startup overlay will appear immediately)
+        const hasStartupOverlay = this.showLogin || this.showOnboarding || getStartupMode() === 'menu';
+        this.ui.start(hasStartupOverlay);
+        // Startup flow: login → onboarding → normal startup
+        if (this.showLogin) {
+            // Not authenticated — show branded login overlay first
+            void this.handleLoginFlow();
+        }
+        else if (this.showOnboarding) {
+            // Authenticated but first run — show onboarding wizard
+            void this.showOnboardingWizard();
+        }
+        else {
+            // Normal startup — authenticated, onboarding complete
+            void this.handleStartupSequence();
+        }
+    }
+    /**
+     * Handle login flow: show branded login overlay, then continue to onboarding or normal startup.
+     */
+    async handleLoginFlow() {
+        const loginOverlay = new LoginOverlayV2(this.version);
+        const result = await this.ui.showOverlay(loginOverlay);
+        if (!result?.success) {
+            // Login failed or cancelled — exit
+            this.stop();
+            process.exit(1);
+        }
+        // Send forced heartbeat in background (don't block UI)
+        const auth = getAuthManager();
+        void auth.sendForcedHeartbeat();
+        // Now check if first run
+        if (!isFirstRunComplete()) {
+            await this.showOnboardingWizard();
+        }
+        else {
+            // Re-login (user did /logout then /login or restarted)
+            // Print welcome banner now (was skipped before login overlay)
+            // Skip if startup mode is 'menu' — the /menu command prints its own logo
+            if (getStartupMode() !== 'menu') {
+                this.printWelcome();
+            }
+            // Start session in background, show startup immediately
+            void auth.startSession();
+            auth.setLLMInfo(this.provider, this.model);
+            await this.handleStartupSequence();
+        }
+    }
+    /**
+     * Handle startup sequence: session restoration first, then menu if applicable.
+     * This ensures proper ordering of startup overlays.
+     */
+    async handleStartupSequence() {
+        // Start heartbeat session in background (don't block UI)
+        // Note: auth was already verified in main() — no need to re-check here
+        if (!this.showLogin) {
+            const auth = getAuthManager();
+            void auth.startSession();
+            auth.setLLMInfo(this.provider, this.model);
+        }
+        // Non-blocking cleanup of legacy (pre-multi-terminal) files and old history
+        void getProjectSessionManager().cleanupLegacyFiles();
+        const retentionDays = getSessionRetentionDays();
+        if (retentionDays > 0) {
+            void getProjectSessionManager().cleanupOldSessions(retentionDays);
+        }
+        // If startup mode is 'menu', show menu first (project selection),
+        // then handle session restoration for the selected project.
+        const startupMode = getStartupMode();
+        if (startupMode === 'menu') {
+            await this.handleCommand('menu', '');
+        }
+        // Check session mode setting (runs after project is known)
+        const sessionMode = getProjectSessionMode();
+        if (sessionMode === 'auto') {
+            // Auto mode: silently restore session + team
+            await this.autoRestoreSession();
+        }
+        else if (sessionMode === 'ask') {
+            // Ask mode: show overlay to let user choose
+            await this.handleSessionModePrompt();
+        }
+        // 'fresh' mode: do nothing - start with clean session
+    }
+    /**
+     * Restore a persisted team for a given terminal prefix.
+     * Replaces the current (fresh) team with the one from disk.
+     * Returns true if a team was restored.
+     */
+    restoreTeamForPrefix(projectId, terminalPrefix) {
+        if (!this.team || !this.agentFactory)
+            return false;
+        const checkpointer = getTeamCheckpointer();
+        const persistedTeam = checkpointer.loadTeamByPrefix(projectId, terminalPrefix, this.agentFactory);
+        if (!persistedTeam || persistedTeam.size <= 1)
+            return false;
+        // Set the current agent as default in the restored team
+        const currentAgent = this.agent;
+        if (currentAgent) {
+            persistedTeam.setDefaultAgent(currentAgent);
+        }
+        // Replace the team and update UI autocomplete
+        this.team = persistedTeam;
+        this.onTeamReplaced?.(persistedTeam);
+        setActiveSharedContext(persistedTeam.sharedContext);
+        this.ui.setAgentSuggestionsCallback(() => {
+            const agents = persistedTeam.getAll();
+            return agents.map(a => ({ id: a.id, displayName: a.displayName, mascot: a.mascot }));
+        });
+        // Populate project info in shared context
+        const activeProject = getActiveProject();
+        if (activeProject) {
+            persistedTeam.sharedContext.setProject({
+                id: activeProject.id,
+                name: activeProject.displayName,
+                path: activeProject.path,
+            });
+        }
+        // Set team roster as anchor on the default agent
+        if (persistedTeam.sharedContext.hasTeamRoster() && currentAgent?.hasAnchors()) {
+            currentAgent.addAnchor({
+                id: 'team-roster',
+                content: persistedTeam.sharedContext.formatTeamRoster(),
+                priority: 'info',
+                scope: 'session',
+            });
+        }
+        // Sync roster to session registry
+        const registry = getSessionRegistry();
+        if (registry) {
+            const agents = persistedTeam.getAll();
+            registry.updateAgents(agents.map(a => ({
+                id: a.id,
+                displayName: a.displayName,
+                mascot: a.mascot,
+            })));
+        }
+        return true;
+    }
+    /**
+     * Auto-restore session silently (for 'auto' mode).
+     * Restores both conversation history AND team roster.
+     * Called at startup when projectSessionMode='auto'.
+     *
+     * Behavior depends on whether other terminals are active on the same project:
+     * - Single terminal: silently restore the most recent available session + claim it
+     * - Multiple terminals: fall back to 'ask' mode (show overlay)
+     */
+    async autoRestoreSession() {
+        if (!this.agent)
+            return;
+        const activeProject = getActiveProject();
+        const projectId = activeProject?.id ?? null;
+        const ownPrefix = getActiveTerminalSessionId()?.slice(0, 8) ?? null;
+        // Check how many terminals are active on this project
+        // (our own terminal is already registered, so count=1 means we're alone)
+        const registry = getSessionRegistry();
+        const activeCount = registry?.getActiveSessionCount(projectId) ?? 1;
+        if (activeCount > 1) {
+            // Multiple terminals — can't auto-pick, fall back to ask mode (overlay)
+            await this.offerOtherTerminalSessions(projectId);
+            return;
+        }
+        // Single terminal — silently restore the most recent available session
+        const psm = getProjectSessionManager();
+        const allSessions = await psm.listProjectSessions(projectId);
+        // Filter to available sessions (not from active terminals, has content)
+        const available = allSessions.filter(s => {
+            if (s.isActiveTerminal)
+                return false;
+            return s.messageCount > 0 || (s.teamAgentCount !== undefined && s.teamAgentCount > 1);
+        });
+        if (available.length === 0) {
+            // No sessions to restore — start fresh silently
+            return;
+        }
+        // Pick the most recent session (already sorted by updatedAt descending)
+        const target = available[0];
+        const targetPrefix = target.terminalPrefix;
+        // Restore team roster
+        if (targetPrefix) {
+            this.restoreTeamForPrefix(projectId, targetPrefix);
+        }
+        // Load and restore conversation
+        const session = targetPrefix
+            ? await psm.loadProjectSessionByPrefix(projectId, targetPrefix)
+            : null;
+        // Claim the session files (rename to our prefix)
+        if (targetPrefix && ownPrefix && targetPrefix !== ownPrefix) {
+            psm.claimSession(projectId, targetPrefix, ownPrefix);
+            getTeamCheckpointer().claimTeamFiles(projectId, targetPrefix, ownPrefix);
+        }
+        if (session && session.messages.length > 0) {
+            try {
+                const filteredMessages = stripThinkingBlocks(session.messages);
+                await this.agent.setHistory(filteredMessages, { turnCount: session.turnCount });
+                const historyItems = convertMessagesToItems(filteredMessages);
+                this.ui.setRestoredHistory(historyItems);
+                const parts = [`${String(session.messages.length)} messages`];
+                if (this.team && this.team.size > 1) {
+                    parts.push(`${String(this.team.size)} agents`);
+                }
+                const msg = `Session restored (${parts.join(', ')}). Tip: Use Ctrl+R to view conversation history.`;
+                if (getStartupMode() === 'menu') {
+                    this.restoredSessionInfo = msg;
+                }
+                else {
+                    this.ui.print({ type: 'info', message: msg });
+                }
+            }
+            catch {
+                // Silently fail - session restoration is best-effort
+            }
+        }
+        else if (this.team && this.team.size > 1) {
+            // 0-message session but team was restored
+            const msg = `Team restored (${String(this.team.size)} agents).`;
+            if (getStartupMode() === 'menu') {
+                this.restoredSessionInfo = msg;
+            }
+            else {
+                this.ui.print({ type: 'info', message: msg });
+            }
+        }
+    }
+    /**
+     * When this terminal has no session but other terminals do, show the resume
+     * overlay so the user can pick one or start fresh.
+     */
+    async offerOtherTerminalSessions(projectId) {
+        if (!this.agent)
+            return;
+        const psm = getProjectSessionManager();
+        const otherSessions = await psm.listProjectSessions(projectId);
+        // Filter out sessions from active terminals (they're "in use")
+        // but include 0-message sessions (they may have a team roster)
+        const validSessions = otherSessions.filter(s => {
+            // Exclude sessions that are actively in use by another terminal
+            if (s.isActiveTerminal)
+                return false;
+            // Include sessions that have messages OR a team roster
+            return s.messageCount > 0 || (s.teamAgentCount !== undefined && s.teamAgentCount > 1);
+        });
+        if (validSessions.length === 0)
+            return;
+        // Show info about available sessions
+        const count = validSessions.length;
+        this.ui.print({ type: 'info', message: `Found ${String(count)} previous session${count > 1 ? 's' : ''} for this project.` });
+        // Show resume overlay
+        const currentProject = getActiveProject();
+        const overlay = new ResumeOverlayV2({
+            sessions: validSessions,
+            currentProjectId: currentProject?.id ?? null,
+            onDelete: async (sessionId) => {
+                // Inline delete handler (same logic as the /resume command)
+                const parsed = this.parseCurrentSessionIdForStartup(sessionId);
+                if (parsed?.terminalPrefix) {
+                    return psm.deleteSessionByPrefix(parsed.projectId, parsed.terminalPrefix);
+                }
+                if (parsed) {
+                    return psm.deleteCurrentSession(parsed.projectId);
+                }
+                return false;
+            },
+        });
+        const result = await this.ui.showOverlay(overlay);
+        if (result?.deleted) {
+            this.ui.print({ type: 'success', message: 'Session deleted.' });
+            return;
+        }
+        if (result?.sessionId) {
+            const parsed = this.parseCurrentSessionIdForStartup(result.sessionId);
+            if (!parsed)
+                return;
+            // Restore team roster if the selected session has a terminal prefix
+            if (parsed.terminalPrefix) {
+                this.restoreTeamForPrefix(parsed.projectId, parsed.terminalPrefix);
+            }
+            const selectedSession = parsed.terminalPrefix
+                ? await psm.loadProjectSessionByPrefix(parsed.projectId, parsed.terminalPrefix)
+                : await psm.loadProjectSession(parsed.projectId);
+            if (!selectedSession) {
+                this.ui.print({ type: 'error', message: 'Failed to load session.' });
+                return;
+            }
+            // Claim: rename files from old prefix to this terminal's prefix
+            const ownPrefix = getActiveTerminalSessionId()?.slice(0, 8) ?? null;
+            if (parsed.terminalPrefix && ownPrefix && parsed.terminalPrefix !== ownPrefix) {
+                psm.claimSession(parsed.projectId, parsed.terminalPrefix, ownPrefix);
+                getTeamCheckpointer().claimTeamFiles(parsed.projectId, parsed.terminalPrefix, ownPrefix);
+            }
+            // Restore conversation messages (if any)
+            if (selectedSession.messages.length > 0) {
+                try {
+                    const filteredMessages = stripThinkingBlocks(selectedSession.messages);
+                    await this.agent.setHistory(filteredMessages, { turnCount: selectedSession.turnCount });
+                    this.ui.setRestoredHistory(convertMessagesToItems(filteredMessages));
+                }
+                catch {
+                    this.ui.print({ type: 'error', message: 'Failed to restore session.' });
+                    return;
+                }
+            }
+            // Report what was restored
+            const parts = [];
+            if (selectedSession.messages.length > 0) {
+                parts.push(`${String(selectedSession.messages.length)} messages`);
+            }
+            if (this.team && this.team.size > 1) {
+                parts.push(`${String(this.team.size)} agents`);
+            }
+            if (parts.length > 0) {
+                this.ui.print({ type: 'success', message: `Session restored (${parts.join(', ')}).` });
+            }
+            else {
+                this.ui.print({ type: 'success', message: 'Session restored.' });
+            }
+            return;
+        }
+        // User cancelled — start fresh
+    }
+    /**
+     * Parse session ID format for startup flow (duplicates session handler logic
+     * to avoid circular import).
+     */
+    parseCurrentSessionIdForStartup(sessionId) {
+        if (!sessionId.startsWith('current-'))
+            return null;
+        const rest = sessionId.slice('current-'.length);
+        const hexMatch = /^([a-f0-9]{8})-(.+)$/.exec(rest);
+        if (hexMatch) {
+            const projectIdStr = hexMatch[2];
+            return { terminalPrefix: hexMatch[1], projectId: projectIdStr === 'global' ? null : parseInt(projectIdStr, 10) };
+        }
+        return { terminalPrefix: null, projectId: rest === 'global' ? null : parseInt(rest, 10) };
+    }
+    /**
+     * Handle session mode prompt at startup when projectSessionMode='ask'.
+     * Shows overlay to let user choose how to handle existing session.
+     */
+    async handleSessionModePrompt() {
+        // Get current project
+        const activeProject = getActiveProject();
+        const projectId = activeProject?.id ?? null;
+        const projectName = activeProject?.displayName ?? 'Global';
+        // Check if there's a session to load for THIS terminal
+        const session = await loadProjectSession(projectId);
+        if (!session) {
+            // No own session — check other terminals
+            await this.offerOtherTerminalSessions(projectId);
+            return;
+        }
+        // Restore team for own session prefix
+        const ownPrefix = getActiveTerminalSessionId()?.slice(0, 8) ?? null;
+        if (ownPrefix) {
+            this.restoreTeamForPrefix(projectId, ownPrefix);
+        }
+        if (session.messages.length === 0) {
+            // Session exists but no messages — team was already restored above
+            if (this.team && this.team.size > 1) {
+                this.ui.print({ type: 'info', message: `Team restored (${String(this.team.size)} agents).` });
+            }
+            // Also check other terminals for sessions to resume
+            await this.offerOtherTerminalSessions(projectId);
+            return;
+        }
+        // Get last user message for preview
+        let lastMessagePreview;
+        const lastUserMsg = session.messages.filter(m => m.role === 'user').pop();
+        if (lastUserMsg) {
+            if (typeof lastUserMsg.content === 'string') {
+                lastMessagePreview = lastUserMsg.content;
+            }
+            else if (Array.isArray(lastUserMsg.content)) {
+                const textBlock = lastUserMsg.content.find((b) => b.type === 'text');
+                if (textBlock) {
+                    lastMessagePreview = textBlock.text;
+                }
+            }
+        }
+        // Show the session mode overlay
+        const overlay = new SessionModeOverlayV2({
+            projectName,
+            messageCount: session.messages.length,
+            lastActivity: new Date(session.updatedAt),
+            lastMessagePreview,
         });
-        // Start UI
-        this.ui.start();
-        // If startup mode is 'menu', immediately execute /menu command
+        const result = await this.ui.showOverlay(overlay);
+        if (!result) {
+            // Cancelled - default to resume-full
+            return this.handleSessionModeResult('resume-full', session);
+        }
+        await this.handleSessionModeResult(result.option, session);
+    }
+    /**
+     * Apply the user's session mode choice.
+     */
+    async handleSessionModeResult(option, session) {
+        if (!session)
+            return;
+        switch (option) {
+            case 'resume-full':
+                // Load the full session
+                if (this.agent) {
+                    try {
+                        const filteredFull = stripThinkingBlocks(session.messages);
+                        await this.agent.setHistory(filteredFull, { turnCount: session.turnCount });
+                        this.ui.setRestoredHistory(convertMessagesToItems(filteredFull));
+                        this.ui.print({ type: 'success', message: `Session restored (${String(session.messages.length)} messages).` });
+                        this.ui.print({ type: 'info', message: 'Tip: Use Ctrl+R to view conversation history.' });
+                    }
+                    catch {
+                        this.ui.print({ type: 'error', message: 'Failed to restore session.' });
+                    }
+                }
+                break;
+            case 'resume-messages':
+                // Load messages only (context refresh is deferred - same as resume-full for now)
+                if (this.agent) {
+                    try {
+                        const filteredMsgs = stripThinkingBlocks(session.messages);
+                        await this.agent.setHistory(filteredMsgs, { turnCount: session.turnCount });
+                        this.ui.setRestoredHistory(convertMessagesToItems(filteredMsgs));
+                        this.ui.print({ type: 'success', message: `Messages restored (${String(session.messages.length)} messages).` });
+                        this.ui.print({ type: 'info', message: 'Tip: Use Ctrl+R to view conversation history.' });
+                    }
+                    catch {
+                        this.ui.print({ type: 'error', message: 'Failed to restore session.' });
+                    }
+                }
+                break;
+            case 'start-fresh':
+                // Archive old session and start fresh
+                try {
+                    await archiveCurrentSession();
+                    this.ui.print({ type: 'info', message: 'Previous session archived. Starting fresh.' });
+                }
+                catch {
+                    // Silent fail - archiving is best-effort
+                    this.ui.print({ type: 'info', message: 'Starting fresh.' });
+                }
+                break;
+        }
+    }
+    /**
+     * Show the onboarding wizard for first-time users.
+     * Called on first run, or manually via /init command.
+     */
+    async showOnboardingWizard() {
+        const wizard = new OnboardingWizardOverlayV2();
+        const result = await this.ui.showOverlay(wizard);
+        // Handle result
+        if (result?.openKeys) {
+            // User chose to configure keys - show keys overlay
+            const keysOverlay = new KeysOverlayV2();
+            await this.ui.showOverlay(keysOverlay);
+            // After keys, re-show the onboarding wizard to continue
+            await this.showOnboardingWizard();
+            return;
+        }
+        // Start session heartbeat in background (don't block UI)
+        const auth = getAuthManager();
+        void auth.startSession();
         const startupMode = getStartupMode();
         if (startupMode === 'menu') {
-            void this.handleCommand('menu', '');
+            await this.handleCommand('menu', '');
         }
     }
     /**
      * Stop the REPL.
+     * Aborts all running sessions (foreground and background).
      */
+    /** Set MCP loading state on the footer status bar. */
+    setMCPLoading(loading, toolCount) {
+        this.ui.setMCPLoading(loading, toolCount);
+    }
     stop() {
-        if (this.currentSession) {
-            this.currentSession.abortController.abort();
-            this.currentSession = null;
+        // Stop notification polling before unregistering session
+        try {
+            const notifMgr = getNotificationManager();
+            if (notifMgr) {
+                notifMgr.stopPolling();
+            }
+        }
+        catch {
+            // Best effort
         }
+        // Unregister from session registry
+        try {
+            const registry = getSessionRegistry();
+            if (registry) {
+                registry.unregister();
+            }
+            setActiveTerminalSessionId(null);
+        }
+        catch {
+            // Best effort
+        }
+        // Abort all sessions
+        for (const [agentId, session] of this.sessions) {
+            session.abortController.abort();
+            this.sessions.delete(agentId);
+        }
+        // Clear all message queues (don't process on shutdown)
+        this.agentMessageQueues.clear();
+        this.currentSession = null;
+        this.foregroundAgentId = null;
         this.ui.stop();
     }
     // ===========================================================================
@@ -248,8 +1574,13 @@ export class ReplV2 {
         const settings = getSettings();
         const s = getStyles();
         terminal.clearScreen();
-        // Render mascot with logo (includes tagline)
-        const logoLines = renderMascotWithLogo(settings.mascot, this.version, null);
+        // Show "What's New" highlights only when version has changed since last seen
+        const isNewVersion = settings.lastSeenVersion !== this.version;
+        const highlights = isNewVersion ? getStartupHighlights(this.version) : undefined;
+        const logoLines = renderMascotWithLogo(settings.mascot, this.version, null, highlights);
+        if (isNewVersion) {
+            updateSettings({ lastSeenVersion: this.version });
+        }
         console.log('');
         for (const line of logoLines) {
             console.log(line);
@@ -275,6 +1606,43 @@ export class ReplV2 {
         const s = getStyles();
         // Print logo with agent/model info
         this.printLogo();
+        // Show update notification if available
+        if (this.updateAvailable) {
+            console.log(s.warning(`  ⬆ Update available: v${this.updateAvailable.current} → v${this.updateAvailable.latest}`));
+            console.log(s.muted('    Run: npm update -g @compilr-dev/cli'));
+            console.log('');
+        }
+        // Show session hint if recent session exists (< 24h)
+        // Uses fast O(1) stat check instead of scanning all session directories
+        try {
+            const activeProject = getActiveProject();
+            const psm = getProjectSessionManager();
+            if (psm.hasRecentSessionFast(activeProject?.id ?? null)) {
+                console.log(s.info('Tip: Recent session available. Use /resume to continue.'));
+                console.log('');
+            }
+        }
+        catch {
+            // Silently ignore errors checking for sessions
+        }
+        // Show in_progress plans notification
+        try {
+            const activeProject = getActiveProject();
+            if (activeProject) {
+                const inProgressPlans = planRepository.getInProgress(activeProject.id);
+                if (inProgressPlans.length === 1) {
+                    console.log(s.info(`Tip: Plan "${inProgressPlans[0].name}" is in progress. Use /docs or Plan Mode to continue.`));
+                    console.log('');
+                }
+                else if (inProgressPlans.length > 1) {
+                    console.log(s.info(`Tip: You have ${String(inProgressPlans.length)} plan(s) in progress. Use /docs to view.`));
+                    console.log('');
+                }
+            }
+        }
+        catch {
+            // Silently ignore errors checking for plans
+        }
         // Hints
         console.log(s.muted('Type a message to start'));
         console.log(s.muted('Type /help for commands, /exit to quit'));
@@ -287,10 +1655,36 @@ export class ReplV2 {
         return {
             ui: this.ui,
             version: this.version,
-            printWelcome: () => { this.printWelcome(); },
+            updateAvailable: this.updateAvailable,
+            printWelcome: () => { this.printWelcome(); return Promise.resolve(); },
             printLogo: () => { this.printLogo(); },
+            consumeRestoredSessionInfo: () => {
+                const info = this.restoredSessionInfo;
+                this.restoredSessionInfo = null;
+                return info;
+            },
             // Agent integration
             agent: this.agent,
+            team: this.team,
+            agentFactory: this.agentFactory,
+            setTeam: (newTeam) => {
+                const oldTeam = this.team;
+                this.team = newTeam;
+                this.onTeamReplaced?.(newTeam);
+                // Update agent suggestions callback with new team
+                this.ui.setAgentSuggestionsCallback(() => {
+                    const agents = newTeam.getAll();
+                    return agents.map((agent) => ({
+                        id: agent.id,
+                        displayName: agent.displayName,
+                        mascot: agent.mascot,
+                    }));
+                });
+                return oldTeam;
+            },
+            restoreAgent: (newAgent) => {
+                this.restoreAgent(newAgent);
+            },
             model: this.model,
             provider: this.provider,
             getContextManager: () => {
@@ -308,9 +1702,30 @@ export class ReplV2 {
             sessionInputTokens: this.sessionInputTokens,
             sessionOutputTokens: this.sessionOutputTokens,
             sessionRequests: this.sessionRequests,
+            // Background session management (Phase 3c)
+            getBackgroundSessions: () => {
+                return this.getBackgroundSessionsInfo();
+            },
+            bringToForeground: async (agentId) => {
+                return this.bringAgentToForeground(agentId);
+            },
+            switchAgent: async (agentId) => {
+                await this.switchAgent(agentId);
+            },
+            killBackgroundAgent: (agentId) => {
+                return this.killAgent(agentId);
+            },
+            sendForegroundToBackground: () => {
+                return this.sendForegroundToBackground();
+            },
+            clearAllQueues: () => {
+                return this.clearAllQueues();
+            },
         };
     }
     async handleCommand(cmd, args) {
+        // Record command usage for telemetry
+        getAuthManager().recordCommand(cmd);
         const ctx = this.createCommandContext();
         const result = await executeCommand(cmd, args, ctx);
         if (result === null) {
@@ -337,7 +1752,8 @@ export class ReplV2 {
             this.ui.print({ type: 'info', message: 'Type /help to see available commands' });
         }
         else if (!result) {
-            // result === false means exit
+            // result === false means exit — clean up before exiting
+            this.stop();
             process.exit(0);
         }
         // Process any queued agent messages (from commands like /arch, /design)
@@ -366,33 +1782,285 @@ export class ReplV2 {
             }
         }
     }
-    // ===========================================================================
-    // Input Processing
-    // ===========================================================================
-    async processInput(input) {
-        if (input.startsWith('/')) {
-            const spaceIndex = input.indexOf(' ');
-            const cmd = spaceIndex > 0 ? input.slice(1, spaceIndex) : input.slice(1);
-            const args = spaceIndex > 0 ? input.slice(spaceIndex + 1) : '';
-            await this.handleCommand(cmd, args);
-            await this.processQueue();
+    // ===========================================================================
+    // Input Processing
+    // ===========================================================================
+    async processInput(input) {
+        // Ignore empty input
+        if (!input.trim()) {
+            return;
+        }
+        // Auth-only mode: restrict to /login, /logout, /exit, /help
+        if (this.authOnly) {
+            const allowedCommands = ['login', 'logout', 'exit', 'help'];
+            if (input.startsWith('/')) {
+                const spaceIndex = input.indexOf(' ');
+                const cmd = spaceIndex > 0 ? input.slice(1, spaceIndex) : input.slice(1);
+                if (allowedCommands.includes(cmd.toLowerCase())) {
+                    const args = spaceIndex > 0 ? input.slice(spaceIndex + 1) : '';
+                    await this.handleCommand(cmd, args);
+                    return;
+                }
+            }
+            // Block all other input
+            this.ui.print({ type: 'warning', message: 'Please log in first to use the CLI.' });
+            this.ui.print({ type: 'info', message: 'Use /login to authenticate or /exit to quit.' });
+            return;
+        }
+        // Handle $name prefix (agent switching)
+        // e.g., "$arch Design the API" → switch to arch, send message
+        // e.g., "$arch Design the API &" → switch to arch, run in background
+        // e.g., "$pm /backlog" → switch to pm, run /backlog command
+        // e.g., "$arch" → just switch to arch (no message sent)
+        if (input.startsWith('$') && this.team) {
+            const parsed = await this.parseAgentPrefix(input);
+            if (parsed) {
+                // Only process remaining input if there is one
+                if (parsed.remainingInput.trim()) {
+                    if (parsed.isBackground) {
+                        // Background execution - fire and forget
+                        this.processInputBackground(parsed.agentId, parsed.remainingInput);
+                    }
+                    else {
+                        // Foreground execution - await
+                        await this.processInput(parsed.remainingInput);
+                    }
+                }
+                // Otherwise just switch was done, nothing more to do
+                return;
+            }
+            // If parsing failed (unknown agent), fall through to treat as regular input
+        }
+        if (input.startsWith('/')) {
+            const spaceIndex = input.indexOf(' ');
+            const cmd = spaceIndex > 0 ? input.slice(1, spaceIndex) : input.slice(1);
+            const args = spaceIndex > 0 ? input.slice(spaceIndex + 1) : '';
+            await this.handleCommand(cmd, args);
+            await this.processQueue();
+        }
+        else if (input.startsWith('!')) {
+            // Handle bash command ("!ls", "!git status", etc.)
+            await this.handleBashCommand(input.slice(1).trim());
+            await this.processQueue();
+        }
+        else if (isMemoryInput(input)) {
+            // Handle memory note ("# note")
+            this.handleMemoryInputV2(input);
+        }
+        else {
+            // Check for & suffix (background execution with current agent)
+            const isBackground = input.trim().endsWith('&');
+            const cleanInput = isBackground ? input.slice(0, -1).trim() : input;
+            if (isBackground && this.team && this.agent) {
+                // Background execution with current active agent
+                const activeAgent = this.team.getActive();
+                // Auto-expand filter if user is sending to agent not in filter
+                this.autoExpandFilterIfNeeded(activeAgent.id);
+                this.ui.print({ type: 'user-message', text: `${cleanInput} [background: $${activeAgent.id}]`, agentId: activeAgent.id });
+                const messageToSend = this.resolveAndInjectMentions(cleanInput);
+                const label = this.getAgentMascotLabel(activeAgent.id);
+                this.ui.print({
+                    type: 'info',
+                    message: `${label} Started in background`,
+                });
+                void this.runAgentBackground(activeAgent.id, messageToSend);
+                return;
+            }
+            // Get active agent ID for tracking
+            const activeAgentId = this.team?.getActive().id ?? 'default';
+            // Auto-expand filter if user is sending to agent not in filter
+            this.autoExpandFilterIfNeeded(activeAgentId);
+            // Print user message
+            this.ui.print({ type: 'user-message', text: cleanInput, agentId: activeAgentId });
+            // Resolve $agent mention references and inject context
+            const messageToSend = this.resolveAndInjectMentions(cleanInput);
+            // Check if the current agent has an active session (still running)
+            // If so, queue the message and return immediately (non-blocking)
+            const existingSession = this.sessions.get(activeAgentId);
+            if (existingSession) {
+                const label = this.getAgentMascotLabel(activeAgentId);
+                const position = this.queueMessage(activeAgentId, messageToSend, cleanInput);
+                if (position === null) {
+                    // Queue is full
+                    this.ui.print({
+                        type: 'warning',
+                        message: `${label} queue is full (${String(MAX_QUEUE_SIZE)} messages). Wait for some to complete.`,
+                    });
+                }
+                else {
+                    // Message queued successfully
+                    const queueInfo = position === 1 ? 'next in queue' : `position ${String(position)} in queue`;
+                    this.ui.print({
+                        type: 'info',
+                        message: `${label} is busy, message queued (${queueInfo})`,
+                    });
+                }
+                return; // Return immediately - user can switch agents or continue
+            }
+            // Run agent (real or simulation)
+            if (this.agent) {
+                await this.runAgentReal(messageToSend);
+            }
+            else {
+                await this.runAgentSimulation(messageToSend);
+            }
+            await this.processQueue();
+        }
+    }
+    /**
+     * Process input in background mode.
+     * Starts the agent without blocking, allowing user to continue with foreground work.
+     *
+     * @param agentId - The agent to run in background
+     * @param input - The message to send to the agent
+     */
+    processInputBackground(agentId, input) {
+        // Check if agent already has a running session
+        if (this.hasActiveSession(agentId)) {
+            this.ui.print({
+                type: 'error',
+                message: `Agent '${agentId}' is already running. Use /kill $${agentId} to stop it first.`,
+            });
+            return;
+        }
+        // Get mascot label for the agent
+        const label = this.getAgentMascotLabel(agentId);
+        // Auto-expand filter if user is sending to agent not in filter
+        this.autoExpandFilterIfNeeded(agentId);
+        // Print user message with background indicator
+        this.ui.print({ type: 'user-message', text: `${input} [background: $${agentId}]`, agentId });
+        // Resolve $agent mention references and inject context
+        const messageToSend = this.resolveAndInjectMentions(input);
+        // Show that background agent is starting
+        this.ui.print({
+            type: 'info',
+            message: `${label} Started in background`,
+        });
+        // Start agent in background (don't await)
+        if (this.agent) {
+            void this.runAgentBackground(agentId, messageToSend);
+        }
+        else {
+            // Simulation mode - just show a message
+            this.ui.print({
+                type: 'info',
+                message: `${label} [simulation] Would run: "${messageToSend}"`,
+            });
+        }
+    }
+    /**
+     * Parse $name prefix from input.
+     * Returns the agent ID, remaining input, and whether this is a background request.
+     * Returns null if the agent doesn't exist.
+     *
+     * Examples:
+     *   "$arch Design the API" → { agentId: 'arch', remainingInput: 'Design the API', isBackground: false }
+     *   "$arch Design the API &" → { agentId: 'arch', remainingInput: 'Design the API', isBackground: true }
+     *   "$pm /backlog" → { agentId: 'pm', remainingInput: '/backlog', isBackground: false }
+     *   "$arch" → { agentId: 'arch', remainingInput: '', isBackground: false }
+     */
+    async parseAgentPrefix(input) {
+        if (!this.team || !input.startsWith('$')) {
+            return null;
+        }
+        // Check for background flag (& at end of input)
+        const isBackground = input.trim().endsWith('&');
+        const cleanInput = isBackground ? input.slice(0, -1).trim() : input;
+        // Extract agent ID: everything after $ until space or end
+        // Note: Agent IDs are case-insensitive (stored lowercase by /team command)
+        const spaceIndex = cleanInput.indexOf(' ');
+        const agentId = (spaceIndex > 0 ? cleanInput.slice(1, spaceIndex) : cleanInput.slice(1)).toLowerCase();
+        const remainingInput = spaceIndex > 0 ? cleanInput.slice(spaceIndex + 1).trim() : '';
+        // Check if agent exists in team
+        if (!this.team.has(agentId)) {
+            this.ui.print({
+                type: 'error',
+                message: `Agent '${agentId}' not found in team`,
+            });
+            this.ui.print({
+                type: 'info',
+                message: `Available agents: ${this.team.getAgentIds().join(', ')}`,
+            });
+            return null;
+        }
+        // Switch to the agent (consolidated logic)
+        try {
+            const { teamAgent, demotedAgentId } = await this.switchAgent(agentId);
+            if (demotedAgentId) {
+                const demotedLabel = this.getAgentMascotLabel(demotedAgentId);
+                this.ui.print({
+                    type: 'info',
+                    message: `${demotedLabel} sent to background (still running)`,
+                });
+            }
+            this.ui.print({
+                type: 'info',
+                message: `Switched to ${teamAgent.mascot} ${teamAgent.displayName}`,
+            });
+        }
+        catch (err) {
+            this.ui.print({
+                type: 'error',
+                message: `Failed to switch to '${agentId}': ${err instanceof Error ? err.message : 'Unknown error'}`,
+            });
+            return null;
+        }
+        return { agentId, remainingInput, isBackground };
+    }
+    /**
+     * Resolve $agent mention references in input and inject context.
+     *
+     * This handles mid-sentence mentions like:
+     *   "What did $arch propose for the API?"
+     *   "Based on $pm's plan, estimate the timeline"
+     *
+     * The resolved context is prepended to the message before sending to the agent.
+     */
+    resolveAndInjectMentions(input) {
+        // Skip if no team
+        if (!this.team) {
+            return input;
         }
-        else if (isMemoryInput(input)) {
-            // Handle memory note ("# note")
-            this.handleMemoryInputV2(input);
+        // Get valid agent IDs
+        const validAgents = new Set(this.team.getAgentIds());
+        // Parse input for mentions
+        const parsed = parseInputForMentions(input, validAgents);
+        // If no references (just a switch or no mentions), return as-is
+        if (!hasReferences(parsed)) {
+            return input;
         }
-        else {
-            // Print user message
-            this.ui.print({ type: 'user-message', text: input });
-            // Run agent (real or simulation)
-            if (this.agent) {
-                await this.runAgentReal(input);
+        // Get artifact store for context resolution
+        const currentProject = getCurrentProject();
+        const projectId = currentProject?.id ?? null;
+        const checkpointer = getTeamCheckpointer();
+        const artifactStore = checkpointer.getArtifactStore(projectId);
+        // Create context resolver
+        const resolver = new ContextResolver(this.team, artifactStore);
+        // Resolve all mentions
+        const resolved = resolver.resolveAll(parsed.references);
+        // Check if any were resolved
+        let anyResolved = false;
+        for (const r of resolved.values()) {
+            if (r.resolved) {
+                anyResolved = true;
+                break;
             }
-            else {
-                await this.runAgentSimulation(input);
-            }
-            await this.processQueue();
         }
+        if (!anyResolved) {
+            return input;
+        }
+        // Build context map and inject into message
+        const contextMap = buildContextMap(resolved);
+        const enhancedMessage = buildMessageWithContext(parsed, contextMap);
+        // Log that context was injected (for debugging)
+        const resolvedAgents = Array.from(resolved.entries())
+            .filter(([_, r]) => r.resolved)
+            .map(([id, r]) => `$${id} (${r.source}: ${r.sourceName})`);
+        this.ui.print({
+            type: 'info',
+            message: `Injected context from: ${resolvedAgents.join(', ')}`,
+        });
+        return enhancedMessage;
     }
     /**
      * Handle memory note input ("# note") - V2 compatible version
@@ -422,7 +2090,7 @@ export class ReplV2 {
         // Show confirmation
         const scope = activeProject ? `project "${activeProject.displayName || activeProject.name}"` : 'global';
         const priorityLabel = priority === 'info' ? '' : ` (${priority})`;
-        const truncatedNote = note.length > 50 ? note.slice(0, 47) + '...' : note;
+        const truncatedNote = truncate(note, 50);
         this.ui.print({ type: 'success', message: `Saved${priorityLabel}: "${truncatedNote}" → ${scope}` });
         // Also add to agent's anchor manager if enabled (for current session)
         if (this.agent?.getAnchorManager()) {
@@ -435,6 +2103,67 @@ export class ReplV2 {
             });
         }
     }
+    /**
+     * Handle bash command ("!ls", "!git status", etc.)
+     * Runs the command directly and displays output.
+     * Special handling for 'cd' to change the CLI's working directory.
+     */
+    async handleBashCommand(command) {
+        if (!command) {
+            this.ui.print({ type: 'error', message: 'Usage: !<command> (e.g., !ls, !git status, !cd <path>)' });
+            return;
+        }
+        // Special handling for 'cd' command - use process.chdir() instead of subprocess
+        // This allows the CLI's working directory to actually change
+        const cdMatch = command.match(/^cd\s+(.+)$/);
+        if (cdMatch || command === 'cd') {
+            const targetDir = cdMatch ? cdMatch[1].trim() : process.env.HOME || '/';
+            // Remove quotes if present (e.g., cd "path with spaces")
+            const cleanDir = targetDir.replace(/^["']|["']$/g, '');
+            try {
+                const path = await import('path');
+                const resolvedPath = path.resolve(process.cwd(), cleanDir);
+                process.chdir(resolvedPath);
+                this.ui.print({ type: 'info', message: `$ cd ${cleanDir}` });
+                this.ui.print({ type: 'success', message: process.cwd() });
+            }
+            catch (error) {
+                this.ui.print({ type: 'info', message: `$ cd ${cleanDir}` });
+                const err = error;
+                this.ui.print({ type: 'error', message: err.message || `Cannot change to directory: ${cleanDir}` });
+            }
+            return;
+        }
+        // Show the command being run
+        this.ui.print({ type: 'info', message: `$ ${command}` });
+        try {
+            const { execSync } = await import('child_process');
+            const output = execSync(command, {
+                encoding: 'utf8',
+                cwd: process.cwd(),
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 30000, // 30 second timeout
+                maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+            });
+            if (output.trim()) {
+                // Print output using raw type (no formatting, proper footer handling)
+                this.ui.print({ type: 'raw', text: output.trimEnd() });
+            }
+        }
+        catch (error) {
+            const err = error;
+            if (err.stderr) {
+                // Print stderr using raw type
+                this.ui.print({ type: 'raw', text: err.stderr.trimEnd() });
+            }
+            else if (err.message) {
+                this.ui.print({ type: 'error', message: err.message });
+            }
+            if (err.status !== undefined) {
+                this.ui.print({ type: 'info', message: `Exit code: ${String(err.status)}` });
+            }
+        }
+    }
     async processQueue() {
         while (this.ui.hasQueuedInput()) {
             const queued = this.ui.popQueuedInput();
@@ -461,24 +2190,71 @@ export class ReplV2 {
         this.clearSubagentTracking?.();
         // - LiveRegion entries (visual display of running tools)
         this.ui.clearLiveRegion();
-        this.currentSession = {
+        // Get active agent ID for session tracking
+        const activeAgentId = this.team?.getActive().id ?? 'default';
+        // Create session object
+        const session = {
+            agentId: activeAgentId,
+            isBackground: false, // Foreground execution
             abortController,
             currentAction: null,
             promise: (async () => {
                 try {
                     this.ui.setAgentRunning(true);
+                    this.ui.resetTurnMetrics(); // Reset token tracking for this turn
                     setAction('Thinking...');
                     this.ui.setSpinnerText('Thinking...');
                     // Reset text accumulator for this run (class-level so it can be flushed externally)
                     this.textAccumulator = '';
                     let lastToolInput = null;
+                    let pendingDiffLines;
                     // Stream agent events (agent is guaranteed to exist in this method)
                     const agent = this.agent;
                     if (!agent)
                         return; // Type guard
-                    for await (const event of agent.stream(userMessage, {
+                    // Update history token estimate for breakdown display
+                    const historyMessages = agent.getHistory();
+                    const historyJson = JSON.stringify(historyMessages);
+                    updateHistoryEstimate(estimateTokens(historyJson));
+                    // In plan mode, prepend plan mode instructions to the first message
+                    // This dynamically injects the plan mode context without recreating the agent
+                    let messageToSend = userMessage;
+                    if (this.ui.getMode() === 'plan') {
+                        const activePlan = this.ui.getActivePlan();
+                        const planModePrompt = getPlanModePrompt(activePlan.id ?? undefined, activePlan.name ?? undefined);
+                        messageToSend = `${planModePrompt}\n\n---\n\nUser request: ${userMessage}`;
+                    }
+                    // Inject delegation completion notifications (deferred delivery)
+                    // If background agents completed while coordinator was busy,
+                    // prepend their results to the next coordinator message
+                    const delegationTracker = getDelegationTracker();
+                    if (delegationTracker.hasCompletionEvents()) {
+                        const completionEvents = delegationTracker.drainCompletionEvents();
+                        const completionPrefix = this.formatCompletionMessage(completionEvents);
+                        messageToSend = `${completionPrefix}\n\n---\n\n${messageToSend}`;
+                    }
+                    // Debug logging (enable with DEBUG_AGENT_REQUESTS=1)
+                    debugLogAgentRequest(agent, messageToSend);
+                    for await (const event of agent.stream(messageToSend, {
                         signal,
                         chatOptions: { model: this.model },
+                        // Provide tool-specific context for bash backgrounding (Ctrl+B)
+                        getToolContext: (toolName, toolUseId) => {
+                            if (toolName === 'bash') {
+                                // Create an AbortController for this bash command
+                                const bashAbortController = new AbortController();
+                                this.bashAbortControllers.set(toolUseId, bashAbortController);
+                                return {
+                                    abortSignal: bashAbortController.signal,
+                                    onBackground: (_shellId, _partialOutput) => {
+                                        // Clean up the controller after backgrounding
+                                        this.bashAbortControllers.delete(toolUseId);
+                                        // The UI already handled the notification
+                                    },
+                                };
+                            }
+                            return {};
+                        },
                     })) {
                         if (signal.aborted)
                             break;
@@ -486,19 +2262,87 @@ export class ReplV2 {
                             if (event.chunk.type === 'text' && event.chunk.text) {
                                 this.textAccumulator += event.chunk.text;
                             }
+                            else if (event.chunk.type === 'thinking_start') {
+                                // Extended thinking started - show indicator
+                                this.ui.setThinking(true);
+                            }
+                            else if (event.chunk.type === 'thinking_end') {
+                                // Extended thinking ended - hide indicator
+                                this.ui.setThinking(false);
+                            }
                             else if (event.chunk.type === 'done' && event.chunk.usage) {
                                 this.sessionInputTokens += event.chunk.usage.inputTokens;
                                 this.sessionOutputTokens += event.chunk.usage.outputTokens;
                                 this.sessionRequests++;
+                                // Record message for telemetry heartbeat
+                                getAuthManager().recordMessage(event.chunk.usage.inputTokens, event.chunk.usage.outputTokens);
+                                // Update live token display (including thinking tokens for Gemini 2.5+)
+                                const usage = event.chunk.usage;
+                                this.ui.addTokens(usage.inputTokens, usage.outputTokens, usage.thinkingTokens, usage.cacheReadTokens, usage.debugPayload);
+                                this.ui.incrementApiCalls();
+                                // Debug: log each API call's token usage to file (not console, to avoid UI artifacts)
+                                if (DEBUG_ENABLED) {
+                                    const metrics = this.ui.getTurnMetrics();
+                                    const debugLine = `[API Call #${String(metrics.apiCalls)}] +${String(usage.inputTokens)} in, +${String(usage.outputTokens)} out → Turn total: ${String(metrics.inputTokens)} in, ${String(metrics.outputTokens)} out\n`;
+                                    appendFileSync(DEBUG_LOG_FILE, debugLine);
+                                    // Log raw usage object to see all fields
+                                    appendFileSync(DEBUG_LOG_FILE, `  Raw usage: ${JSON.stringify(event.chunk.usage)}\n`);
+                                }
+                                // Update cache info for breakdown display
+                                updateCacheInfo(usage.cacheReadTokens ?? 0, usage.cacheCreationTokens ?? 0);
+                                // Update team agent's token tracking
+                                if (this.team) {
+                                    const activeTeamAgent = this.team.getActive();
+                                    activeTeamAgent.updateTokenUsage(event.chunk.usage.inputTokens, event.chunk.usage.outputTokens);
+                                }
                             }
                         }
                         else if (event.type === 'tool_start') {
                             // Flush accumulated text before tool
                             if (this.textAccumulator.trim()) {
-                                this.ui.print({ type: 'agent-text', text: this.textAccumulator.trim() });
+                                this.ui.print({
+                                    type: 'agent-text',
+                                    text: this.textAccumulator.trim(),
+                                    expression: this.getActiveAgentMascot(),
+                                    agentId: activeAgentId,
+                                });
                                 this.textAccumulator = '';
                             }
+                            // Track tool calls for per-turn metrics
+                            this.ui.incrementToolCalls();
+                            // Record tool usage for telemetry
+                            if (event.name) {
+                                getAuthManager().recordTool(event.name);
+                            }
                             lastToolInput = event.input;
+                            // Pre-compute diff for edit tool (must happen BEFORE tool modifies the file)
+                            pendingDiffLines = undefined;
+                            {
+                                // Determine the actual tool name (handle use_tool wrapping)
+                                const actualToolName = event.name === 'use_tool' && typeof event.input.tool_name === 'string'
+                                    ? event.input.tool_name
+                                    : event.name;
+                                const actualInput = event.name === 'use_tool' && typeof event.input.args === 'object' && event.input.args !== null
+                                    ? event.input.args
+                                    : event.input;
+                                if (actualToolName === 'edit') {
+                                    const filePath = typeof actualInput.filePath === 'string' ? actualInput.filePath : '';
+                                    const oldText = typeof actualInput.oldString === 'string' ? actualInput.oldString : '';
+                                    const newText = typeof actualInput.newString === 'string' ? actualInput.newString : '';
+                                    const replaceAll = Boolean(actualInput.replaceAll);
+                                    if (filePath && oldText && newText) {
+                                        const editDiff = generateEditDiff(filePath, oldText, newText, replaceAll);
+                                        if (editDiff) {
+                                            pendingDiffLines = editDiff.lines;
+                                        }
+                                    }
+                                }
+                            }
+                            // Debug: log tool calls to file
+                            if (DEBUG_ENABLED) {
+                                const toolDebugLine = `[Tool Call] ${event.name}(${JSON.stringify(event.input).slice(0, 200)})\n`;
+                                appendFileSync(DEBUG_LOG_FILE, toolDebugLine);
+                            }
                             // For bash tool, add to live region for streaming output
                             if (event.name === 'bash' && event.toolUseId) {
                                 const command = typeof lastToolInput.command === 'string'
@@ -506,8 +2350,8 @@ export class ReplV2 {
                                     : '';
                                 this.ui.addBashCommand(event.toolUseId, command);
                             }
-                            // Update spinner with tool name
-                            if (event.name !== 'todo_read' && event.name !== 'todo_write' && event.name !== 'suggest') {
+                            // Update spinner with tool name (skip silent tools)
+                            if (!this.agent?.isToolSilent(event.name)) {
                                 if (event.name === 'task' && event.toolUseId) {
                                     const subagentType = typeof lastToolInput.subagent_type === 'string'
                                         ? lastToolInput.subagent_type
@@ -521,6 +2365,27 @@ export class ReplV2 {
                                     // No queue needed - callbacks now receive toolUseId directly!
                                     this.ui.addSubagent(event.toolUseId, subagentType, description);
                                 }
+                                else if (event.name === 'use_tool') {
+                                    // Show the inner tool name being called
+                                    const innerToolName = typeof lastToolInput.tool_name === 'string'
+                                        ? lastToolInput.tool_name
+                                        : 'unknown';
+                                    setAction(innerToolName);
+                                    this.ui.setSpinnerText(`Running ${innerToolName}...`);
+                                }
+                                else if (event.name === 'list_tools') {
+                                    // Quiet display for list_tools
+                                    setAction('list_tools');
+                                    this.ui.setSpinnerText('Discovering tools...');
+                                }
+                                else if (event.name === 'get_tool_info') {
+                                    // Quiet display for get_tool_info
+                                    const toolName = typeof lastToolInput.tool_name === 'string'
+                                        ? lastToolInput.tool_name
+                                        : '?';
+                                    setAction('get_tool_info');
+                                    this.ui.setSpinnerText(`Getting schema for ${toolName}...`);
+                                }
                                 else if (event.name !== 'task') {
                                     setAction(event.name);
                                     this.ui.setSpinnerText(`Running ${event.name}...`);
@@ -540,6 +2405,17 @@ export class ReplV2 {
                             lastToolInput = null;
                             // Complete bash command in live region
                             if (toolName === 'bash' && event.toolUseId) {
+                                // Clean up abort controller
+                                this.bashAbortControllers.delete(event.toolUseId);
+                                // Check if command was backgrounded
+                                if (result.success && typeof result.result === 'object' && result.result !== null) {
+                                    const res = result.result;
+                                    if (res.backgrounded === true) {
+                                        // Command was moved to background - don't commit, just clear
+                                        this.ui.setCurrentTool(null);
+                                        continue;
+                                    }
+                                }
                                 let exitCode = result.success ? 0 : 1;
                                 if (result.success && typeof result.result === 'object' && result.result !== null) {
                                     const res = result.result;
@@ -564,15 +2440,100 @@ export class ReplV2 {
                                         ? t.status
                                         : 'pending');
                                     const activeForm = typeof t.activeForm === 'string' ? t.activeForm : undefined;
-                                    return { content, status, activeForm };
+                                    const owner = typeof t.owner === 'string' ? t.owner : undefined;
+                                    const blockedBy = Array.isArray(t.blockedBy)
+                                        ? t.blockedBy.filter((n) => typeof n === 'number')
+                                        : undefined;
+                                    return { content, status, activeForm, owner, blockedBy };
                                 });
                                 this.ui.setTodos(todos);
                                 this.ui.setCurrentTool(null);
                                 continue;
                             }
                             // Skip silent tools (no output needed)
-                            if (toolName === 'todo_read' || toolName === 'suggest' ||
-                                toolName === 'ask_user' || toolName === 'ask_user_simple') {
+                            if (this.agent?.isToolSilent(toolName)) {
+                                this.ui.setCurrentTool(null);
+                                continue;
+                            }
+                            // Handle list_tools - show compact summary
+                            if (toolName === 'list_tools') {
+                                const innerResult = result.success && typeof result.result === 'object'
+                                    ? result.result
+                                    : {};
+                                const count = typeof innerResult.count === 'number' ? innerResult.count : 0;
+                                const categoryParam = toolInput && typeof toolInput.category === 'string'
+                                    ? `category: ${toolInput.category}`
+                                    : '';
+                                this.ui.print({
+                                    type: 'tool-result',
+                                    name: 'list_tools',
+                                    params: categoryParam,
+                                    summary: `${String(count)} tools available`,
+                                    success: result.success,
+                                    agentId: activeAgentId,
+                                });
+                                this.ui.setCurrentTool(null);
+                                continue;
+                            }
+                            // Handle use_tool - show the inner tool name instead
+                            if (toolName === 'use_tool' && toolInput) {
+                                const innerToolName = typeof toolInput.tool_name === 'string'
+                                    ? toolInput.tool_name
+                                    : 'unknown';
+                                const innerArgs = typeof toolInput.args === 'object' && toolInput.args !== null
+                                    ? toolInput.args
+                                    : {};
+                                // Extract and format using the inner tool name
+                                const { content, summary, success } = this.extractToolResult(innerToolName, result);
+                                // Resolve diff lines for edit (pre-computed) or write_file (computed now)
+                                let innerDiffLines = pendingDiffLines;
+                                pendingDiffLines = undefined;
+                                if (!innerDiffLines && (innerToolName === 'write_file' || innerToolName === 'write')) {
+                                    const filePath = typeof innerArgs.path === 'string' ? innerArgs.path : '';
+                                    const writeContent = typeof innerArgs.content === 'string' ? innerArgs.content : '';
+                                    if (filePath && writeContent && success) {
+                                        const writeDiff = generateWriteDiff(filePath, writeContent, true);
+                                        innerDiffLines = writeDiff.lines;
+                                    }
+                                }
+                                this.ui.print({
+                                    type: 'tool-result',
+                                    name: innerToolName,
+                                    params: this.formatToolParams(innerArgs),
+                                    summary,
+                                    content: content || undefined,
+                                    diffLines: innerDiffLines,
+                                    success,
+                                    agentId: activeAgentId,
+                                });
+                                this.ui.setCurrentTool(null);
+                                continue;
+                            }
+                            // Handle get_tool_info - show compact summary
+                            if (toolName === 'get_tool_info') {
+                                let name = '?';
+                                if (result.success) {
+                                    if (typeof result.result === 'string') {
+                                        // Compact schema format (SDK 0.1.15+): "tool_name(...)\n  description"
+                                        const parenIdx = result.result.indexOf('(');
+                                        if (parenIdx > 0)
+                                            name = result.result.slice(0, parenIdx);
+                                    }
+                                    else if (typeof result.result === 'object' && result.result !== null) {
+                                        // Legacy object format: { name, description, parameters }
+                                        const obj = result.result;
+                                        if (typeof obj.name === 'string')
+                                            name = obj.name;
+                                    }
+                                }
+                                this.ui.print({
+                                    type: 'tool-result',
+                                    name: 'get_tool_info',
+                                    params: name,
+                                    summary: `Schema: ${name}`,
+                                    success: result.success,
+                                    agentId: activeAgentId,
+                                });
                                 this.ui.setCurrentTool(null);
                                 continue;
                             }
@@ -588,39 +2549,517 @@ export class ReplV2 {
                             }
                             // Extract and format tool result
                             const { content, summary, success } = this.extractToolResult(toolName, result);
+                            // Resolve diff lines for edit/write_file tools
+                            let diffLines = pendingDiffLines;
+                            pendingDiffLines = undefined;
+                            // For write_file, generate diff from input (doesn't need pre-edit state)
+                            if (!diffLines && toolInput) {
+                                const actualToolName = toolName === 'use_tool' && typeof toolInput.tool_name === 'string'
+                                    ? toolInput.tool_name
+                                    : toolName;
+                                const actualInput = toolName === 'use_tool' && typeof toolInput.args === 'object' && toolInput.args !== null
+                                    ? toolInput.args
+                                    : toolInput;
+                                if (actualToolName === 'write_file' || actualToolName === 'write') {
+                                    const filePath = typeof actualInput.path === 'string' ? actualInput.path : '';
+                                    const writeContent = typeof actualInput.content === 'string' ? actualInput.content : '';
+                                    if (filePath && writeContent && success) {
+                                        const writeDiff = generateWriteDiff(filePath, writeContent, true);
+                                        diffLines = writeDiff.lines;
+                                    }
+                                }
+                            }
                             this.ui.print({
                                 type: 'tool-result',
                                 name: toolName,
                                 params: this.formatToolParams(toolInput),
                                 summary,
-                                content: content.length > 200 ? content : undefined,
+                                content: content || undefined,
+                                diffLines,
                                 success,
+                                agentId: activeAgentId,
                             });
                             this.ui.setCurrentTool(null);
                         }
+                        else if (event.type === 'context_compacted') {
+                            // Context was compacted - show file restoration hints
+                            const hints = agent.formatRestorationHints();
+                            const savedTokens = event.tokensBefore - event.tokensAfter;
+                            const savedPct = Math.round((savedTokens / event.tokensBefore) * 100);
+                            this.ui.print({
+                                type: 'info',
+                                message: `Context compacted: ${event.tokensBefore.toLocaleString()} → ${event.tokensAfter.toLocaleString()} tokens (${String(savedPct)}% reduction)`,
+                            });
+                            if (hints) {
+                                // Display file restoration hints
+                                this.ui.print({
+                                    type: 'info',
+                                    message: hints,
+                                });
+                            }
+                            // Hint about Ctrl+O
+                            this.ui.print({
+                                type: 'info',
+                                message: 'Tip: Use Ctrl+O to view full conversation history',
+                            });
+                        }
+                        else if (event.type === 'context_summarized') {
+                            // Context was summarized (LLM-based) - more aggressive
+                            const savedTokens = event.tokensBefore - event.tokensAfter;
+                            const savedPct = Math.round((savedTokens / event.tokensBefore) * 100);
+                            this.ui.print({
+                                type: 'info',
+                                message: `Context summarized (${String(event.rounds)} round${event.rounds > 1 ? 's' : ''}): ${event.tokensBefore.toLocaleString()} → ${event.tokensAfter.toLocaleString()} tokens (${String(savedPct)}% reduction)`,
+                            });
+                            const hints = agent.formatRestorationHints();
+                            if (hints) {
+                                this.ui.print({
+                                    type: 'info',
+                                    message: hints,
+                                });
+                            }
+                        }
+                        else if (event.type === 'llm_retry') {
+                            // LLM call failed, retrying with exponential backoff
+                            const delaySec = (event.delayMs / 1000).toFixed(1);
+                            this.ui.print({
+                                type: 'warning',
+                                message: `Connection failed (attempt ${String(event.attempt)}/${String(event.maxAttempts)}): ${event.error}. Retrying in ${delaySec}s...`,
+                            });
+                        }
+                        else if (event.type === 'custom' && typeof event.name === 'string' && event.name.startsWith('delegation:')) {
+                            // Tool result delegation events
+                            const data = event.data;
+                            if (event.name === 'delegation:completed') {
+                                const originalTokens = data.originalTokens;
+                                const summaryTokens = data.summaryTokens;
+                                const toolName = data.toolName;
+                                this.ui.setSpinnerText(`Delegated ${toolName} result: ${String(originalTokens)} → ${String(summaryTokens)} tokens`);
+                            }
+                        }
+                        else if (event.type === 'llm_retry_exhausted') {
+                            // All retry attempts failed
+                            this.ui.print({
+                                type: 'error',
+                                message: `All ${String(event.attempts)} retry attempts failed: ${event.error}`,
+                            });
+                        }
                     }
-                    // Flush remaining text
+                    // Flush remaining text and check for PLAN_READY marker
                     if (this.textAccumulator.trim()) {
-                        this.ui.print({ type: 'agent-text', text: this.textAccumulator.trim(), expression: 'success' });
+                        const text = this.textAccumulator.trim();
+                        // Check for PLAN_READY marker
+                        const planReadyInfo = this.detectPlanReady(text);
+                        // Print the text (remove the marker from display if present)
+                        const displayText = planReadyInfo
+                            ? text.replace(ReplV2.PLAN_READY_REGEX, '').trim()
+                            : text;
+                        if (displayText) {
+                            this.ui.print({ type: 'agent-text', text: displayText, expression: this.getActiveAgentMascot(), agentId: activeAgentId });
+                        }
+                        // If PLAN_READY marker found, show approval overlay
+                        if (planReadyInfo) {
+                            await this.handlePlanApproval(planReadyInfo.planId, planReadyInfo.planName);
+                        }
                     }
+                    // Print per-turn summary before stopping agent
+                    this.printTurnSummary();
                     this.ui.setAgentRunning(false);
+                    this.ui.setThinking(false); // Ensure thinking indicator is cleared
                     // NOTE: Don't clear todos here - they should persist after agent finishes
                     // to show the final state. Only clear on explicit user action or new conversation.
                     // Notify that agent has finished (for applying deferred suggestions)
                     this.onAgentFinish?.();
+                    // Auto-save session after successful agent response
+                    this.autoSaveSession().catch((err) => {
+                        // Log but don't interrupt - saving is best-effort
+                        console.error('Failed to save session:', err);
+                    });
                 }
                 catch (err) {
                     if (!signal.aborted) {
                         this.ui.print({ type: 'error', message: String(err) });
                     }
                     this.ui.setAgentRunning(false);
+                    this.ui.setThinking(false); // Ensure thinking indicator is cleared
                     // Still notify on error so suggestions can be applied
                     this.onAgentFinish?.();
                 }
             })(),
         };
-        await this.currentSession.promise;
-        this.currentSession = null;
+        // Register the session (foreground)
+        this.startSession(session);
+        // Wait for session to complete
+        await session.promise;
+        this.endSession(activeAgentId);
+        // Check for pending delegation and handle it
+        await this.handlePendingDelegation();
+    }
+    // ===========================================================================
+    // Delegation Completion (Phase 2 - Coordinator Mode)
+    // ===========================================================================
+    /**
+     * Format completion events into a structured message for the coordinator.
+     * Groups events by agent and includes task, result summary, and artifact info.
+     */
+    formatCompletionMessage(events) {
+        const lines = ['[DELEGATION COMPLETIONS]', ''];
+        for (const event of events) {
+            const delegation = getDelegationTracker().get(event.delegationId);
+            const agentLabel = this.team?.get(event.agentId)?.displayName ?? event.agentId;
+            const status = event.status === 'completed' ? 'COMPLETED' : 'FAILED';
+            lines.push(`## $${event.agentId} (${agentLabel}) — ${status}`);
+            if (delegation) {
+                lines.push(`Task: ${delegation.task}`);
+            }
+            if (event.result.success) {
+                lines.push(`Result: ${event.result.summary}`);
+            }
+            else {
+                lines.push(`Error: ${event.result.error ?? event.result.summary}`);
+            }
+            if (event.result.artifactIds.length > 0) {
+                lines.push(`Artifacts: ${event.result.artifactIds.join(', ')}`);
+            }
+            lines.push('');
+        }
+        lines.push('Review the results above and decide next steps.');
+        return lines.join('\n');
+    }
+    /**
+     * Check and process delegation completions for an agent that just finished.
+     * Marks all running delegations for this agent as completed or failed,
+     * then attempts to auto-resume the coordinator if idle.
+     *
+     * @param agentId - The agent that just finished
+     * @param error - If present, the agent failed with this error
+     */
+    checkDelegationCompletion(agentId, error) {
+        const tracker = getDelegationTracker();
+        const running = tracker.getByAgent(agentId).filter(d => d.status === 'running');
+        if (running.length === 0)
+            return;
+        for (const delegation of running) {
+            if (error) {
+                tracker.fail(delegation.id, error);
+            }
+            else {
+                // Gather artifacts created during this delegation
+                const artifactIds = [];
+                if (this.team) {
+                    const currentProject = getCurrentProject();
+                    const projectId = currentProject?.id ?? null;
+                    const artifactStore = getTeamCheckpointer().getArtifactStore(projectId);
+                    const agentArtifacts = artifactStore.listByAgent(agentId);
+                    for (const artifact of agentArtifacts) {
+                        if (artifact.createdAt >= delegation.createdAt) {
+                            artifactIds.push(artifact.id);
+                        }
+                    }
+                }
+                tracker.complete(delegation.id, {
+                    success: true,
+                    summary: `Task completed successfully${artifactIds.length > 0 ? ` with ${String(artifactIds.length)} artifact(s)` : ''}`,
+                    artifactIds,
+                });
+            }
+        }
+        // Try to auto-resume the coordinator (fire-and-forget — async switch must complete before runAgentReal)
+        void this.maybeResumeCoordinator();
+    }
+    /**
+     * Auto-resume the coordinator if it's idle and there are pending completion events.
+     * If the coordinator is busy, events stay in queue for deferred delivery.
+     *
+     * Must be async to properly await switchAgent before running the coordinator.
+     * Called fire-and-forget from checkDelegationCompletion — this ensures the
+     * background agent's endSession() runs independently (no session conflicts).
+     */
+    async maybeResumeCoordinator() {
+        const tracker = getDelegationTracker();
+        if (!tracker.hasCompletionEvents())
+            return;
+        // Check if coordinator (default agent) is idle
+        if (this.sessions.has('default'))
+            return; // Coordinator is busy
+        // Drain events and format the completion message
+        const events = tracker.drainCompletionEvents();
+        const completionMessage = this.formatCompletionMessage(events);
+        // Switch to coordinator if not already active — MUST await before runAgentReal
+        // so that this.team.getActive().id returns 'default' and the foreground session
+        // is registered under the correct agent ID
+        if (this.team && this.team.getActive().id !== 'default') {
+            try {
+                await this.switchAgent('default', {
+                    demoteCurrentIfBusy: false,
+                    trackSession: false,
+                });
+            }
+            catch (err) {
+                this.ui.print({
+                    type: 'error',
+                    message: `Failed to switch to coordinator: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                return;
+            }
+        }
+        // Run coordinator foreground with the completion message
+        this.ui.print({
+            type: 'info',
+            message: 'Delegation completed — resuming coordinator...',
+        });
+        void this.runAgentReal(completionMessage);
+    }
+    /**
+     * Run an agent in background (Phase 3 - Background Agents).
+     * Similar to runAgentReal but:
+     * - Creates a background session (isBackground: true)
+     * - Labels all output with agent mascot
+     * - Doesn't block the caller
+     * - Shows completion notification when done
+     *
+     * @param agentId - The agent ID to run
+     * @param userMessage - The message to send to the agent
+     */
+    async runAgentBackground(agentId, userMessage) {
+        if (!this.agent)
+            return;
+        const abortController = new AbortController();
+        const signal = abortController.signal;
+        const label = this.getAgentMascotLabel(agentId);
+        const mascot = this.team?.get(agentId)?.mascot ?? '[•_•]';
+        // Create background session
+        const session = {
+            agentId,
+            isBackground: true,
+            abortController,
+            currentAction: null,
+            taskDescription: truncate(userMessage, 50),
+            promise: (async () => {
+                try {
+                    // Note: Don't set UI to "running" state - that's for foreground only
+                    let textAccumulator = '';
+                    // Stream agent events
+                    const agent = this.agent;
+                    if (!agent)
+                        return; // Type guard
+                    // Phase 3b: Set the executing context so permission handler knows which agent is calling
+                    this.currentExecutingBackgroundAgentId = agentId;
+                    for await (const event of agent.stream(userMessage, {
+                        signal,
+                        chatOptions: { model: this.model },
+                    })) {
+                        if (signal.aborted)
+                            break;
+                        if (event.type === 'llm_chunk') {
+                            if (event.chunk.type === 'text' && event.chunk.text) {
+                                textAccumulator += event.chunk.text;
+                            }
+                            else if (event.chunk.type === 'done' && event.chunk.usage) {
+                                // Update session token tracking
+                                this.sessionInputTokens += event.chunk.usage.inputTokens;
+                                this.sessionOutputTokens += event.chunk.usage.outputTokens;
+                                this.sessionRequests++;
+                                // Record message for telemetry heartbeat
+                                getAuthManager().recordMessage(event.chunk.usage.inputTokens, event.chunk.usage.outputTokens);
+                                // Update team agent's token tracking
+                                if (this.team) {
+                                    const teamAgent = this.team.get(agentId);
+                                    teamAgent?.updateTokenUsage(event.chunk.usage.inputTokens, event.chunk.usage.outputTokens);
+                                }
+                            }
+                        }
+                        else if (event.type === 'tool_start') {
+                            // Record tool usage for telemetry
+                            if (event.name) {
+                                getAuthManager().recordTool(event.name);
+                            }
+                            // Flush accumulated text before tool (with label)
+                            if (textAccumulator.trim()) {
+                                // Use 'background-agent' type for proper labeling without double mascot
+                                this.ui.print({
+                                    type: 'background-agent',
+                                    agentId,
+                                    mascot,
+                                    text: textAccumulator.trim(),
+                                });
+                                textAccumulator = '';
+                            }
+                            // Show tool start with label
+                            this.ui.print({
+                                type: 'background-agent',
+                                agentId,
+                                mascot,
+                                text: `Running: ${event.name}`,
+                            });
+                        }
+                    }
+                    // Flush any remaining text
+                    if (textAccumulator.trim()) {
+                        this.ui.print({
+                            type: 'background-agent',
+                            agentId,
+                            mascot,
+                            text: textAccumulator.trim(),
+                        });
+                    }
+                    // Show completion notification
+                    this.ui.print({
+                        type: 'info',
+                        message: `${label} Finished ✓`,
+                    });
+                    // Notify other terminals about completion
+                    try {
+                        const sid = getActiveTerminalSessionId();
+                        const proj = getActiveProject();
+                        if (sid && proj) {
+                            getNotificationManager()?.insert({
+                                projectId: proj.id,
+                                fromSessionId: sid,
+                                type: 'agent_finished',
+                                title: `${agentId} finished`,
+                                message: 'Task completed successfully.',
+                            });
+                        }
+                    }
+                    catch {
+                        // Best effort
+                    }
+                    // Check delegation completion (success path)
+                    this.checkDelegationCompletion(agentId);
+                }
+                catch (err) {
+                    if (!signal.aborted) {
+                        this.ui.print({ type: 'error', message: `${label} Error: ${String(err)}` });
+                        // Notify other terminals about failure
+                        try {
+                            const sid = getActiveTerminalSessionId();
+                            const proj = getActiveProject();
+                            if (sid && proj) {
+                                getNotificationManager()?.insert({
+                                    projectId: proj.id,
+                                    fromSessionId: sid,
+                                    type: 'agent_finished',
+                                    title: `${agentId} failed`,
+                                    message: String(err).slice(0, 200),
+                                });
+                            }
+                        }
+                        catch {
+                            // Best effort
+                        }
+                        // Check delegation completion (failure path)
+                        this.checkDelegationCompletion(agentId, String(err));
+                    }
+                    else {
+                        // Killed by user — cancel delegations (no completion event)
+                        getDelegationTracker().cancelAllForAgent(agentId);
+                    }
+                }
+                finally {
+                    // Phase 3b: Clear the executing context
+                    if (this.currentExecutingBackgroundAgentId === agentId) {
+                        this.currentExecutingBackgroundAgentId = null;
+                    }
+                }
+            })(),
+        };
+        // Register the background session
+        this.startSession(session);
+        this.ui.setBackgroundAgentCount(this.getBackgroundSessions().length);
+        // Wait for completion (but caller doesn't await this method)
+        await session.promise;
+        this.endSession(agentId);
+    }
+    /**
+     * Handle pending delegation after agent finishes.
+     * If a delegation was approved during the agent run, switch to the
+     * target agent and inject the task as a user message.
+     */
+    async handlePendingDelegation() {
+        if (!this.onPendingDelegation || !this.team)
+            return;
+        const pending = this.onPendingDelegation();
+        if (!pending)
+            return;
+        const { agentId, task } = pending;
+        // Validate target agent still exists
+        if (!this.team.has(agentId)) {
+            this.ui.print({
+                type: 'error',
+                message: `Delegation failed: Agent '${agentId}' no longer exists in team.`,
+            });
+            return;
+        }
+        // Switch to target agent (no demotion — delegating agent just finished, no session tracking needed)
+        try {
+            const { teamAgent } = await this.switchAgent(agentId, {
+                demoteCurrentIfBusy: false,
+                trackSession: false,
+            });
+            this.ui.print({
+                type: 'info',
+                message: `Delegating to $${agentId} (${teamAgent.displayName})...`,
+            });
+        }
+        catch (err) {
+            this.ui.print({
+                type: 'error',
+                message: `Failed to switch to $${agentId}: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            return;
+        }
+        if (!this.agent) {
+            this.ui.print({
+                type: 'error',
+                message: `Agent $${agentId} is not initialized.`,
+            });
+            return;
+        }
+        // Inject the task as a user message and run the agent
+        this.ui.print({
+            type: 'user-message',
+            text: task,
+        });
+        // Run the target agent with the delegated task
+        await this.runAgentReal(task);
+    }
+    /**
+     * Auto-save the current session and team state.
+     * Called after each successful agent response.
+     *
+     * Saves two things:
+     * 1. Default agent's session state (for /resume - conversation history)
+     * 2. Team state (for team persistence - all agent states including roles)
+     */
+    async autoSaveSession() {
+        if (!this.team)
+            return;
+        try {
+            // Save default agent's session for /resume functionality
+            const defaultAgent = this.team.get('default')?.agent;
+            if (defaultAgent) {
+                const state = defaultAgent.serialize();
+                await saveCurrentSession(state);
+            }
+            // Save team state for team persistence (all agents including custom ones)
+            // Only save if team has more than just the default agent, or if any agent has history
+            const teamAgents = this.team.getAll();
+            const hasNonDefaultAgents = teamAgents.some(ta => ta.id !== 'default');
+            const hasAnyHistory = teamAgents.some(ta => {
+                const agent = ta.agent;
+                if (!agent)
+                    return false;
+                const state = agent.serialize();
+                return state.messages.length > 0;
+            });
+            if (hasNonDefaultAgents || hasAnyHistory) {
+                saveCurrentTeam(this.team);
+            }
+        }
+        catch {
+            // Silently fail - session/team saving is best-effort
+        }
     }
     formatToolParams(input) {
         if (!input)
@@ -633,12 +3072,12 @@ export class ReplV2 {
         if ('pattern' in input)
             return String(input.pattern);
         if ('command' in input)
-            return String(input.command).slice(0, 50);
+            return truncate(String(input.command), 50);
         // Default: show first param
         const keys = Object.keys(input);
         if (keys.length > 0) {
             const val = String(input[keys[0]]);
-            return val.length > 50 ? val.slice(0, 47) + '...' : val;
+            return truncate(val, 50);
         }
         return '';
     }
@@ -660,7 +3099,12 @@ export class ReplV2 {
                 this.currentSession.currentAction = action;
             }
         };
-        this.currentSession = {
+        // Get active agent ID for session tracking
+        const activeAgentId = this.team?.getActive().id ?? 'default';
+        // Create session object
+        const session = {
+            agentId: activeAgentId,
+            isBackground: false, // Foreground execution
             abortController,
             currentAction: null,
             promise: (async () => {
@@ -673,7 +3117,7 @@ export class ReplV2 {
                     if (signal.aborted)
                         return;
                     const response = `I understand you want me to help with "${userMessage}". Let me analyze this.`;
-                    this.ui.print({ type: 'agent-text', text: response });
+                    this.ui.print({ type: 'agent-text', text: response, expression: this.getActiveAgentMascot() });
                     // 2. Add todos
                     this.ui.setTodos([
                         { content: 'Analyze the request', status: 'completed' },
@@ -719,6 +3163,7 @@ export class ReplV2 {
                         expression: 'success',
                     });
                     this.ui.setAgentRunning(false);
+                    this.ui.setThinking(false); // Ensure thinking indicator is cleared
                     // NOTE: Don't clear todos - let them persist to show final state
                     // Notify that agent has finished (for applying deferred suggestions)
                     this.onAgentFinish?.();
@@ -728,12 +3173,16 @@ export class ReplV2 {
                         this.ui.print({ type: 'error', message: String(err) });
                     }
                     this.ui.setAgentRunning(false);
+                    this.ui.setThinking(false); // Ensure thinking indicator is cleared
                     this.onAgentFinish?.();
                 }
             })(),
         };
-        await this.currentSession.promise;
-        this.currentSession = null;
+        // Register the session (foreground)
+        this.startSession(session);
+        // Wait for session to complete
+        await session.promise;
+        this.endSession(activeAgentId);
     }
     async sleep(ms, signal) {
         return new Promise((resolve) => {
@@ -745,15 +3194,83 @@ export class ReplV2 {
         });
     }
     // ===========================================================================
+    // Turn Summary
+    // ===========================================================================
+    /**
+     * Print per-turn summary (tokens, duration, tool calls)
+     */
+    printTurnSummary() {
+        const metrics = this.ui.getTurnMetrics();
+        // Only print summary if there were tokens used
+        if (metrics.inputTokens === 0 && metrics.outputTokens === 0) {
+            return;
+        }
+        const formatDuration = (ms) => {
+            const seconds = Math.floor(ms / 1000);
+            if (seconds < 60)
+                return `${String(seconds)}s`;
+            const minutes = Math.floor(seconds / 60);
+            const remainingSeconds = seconds % 60;
+            return `${String(minutes)}m ${String(remainingSeconds)}s`;
+        };
+        // Build summary parts
+        const parts = [];
+        parts.push(formatDuration(metrics.durationMs));
+        // Token display with optional thinking/cache tokens
+        let tokenDisplay = `↓ ${formatTokens(metrics.inputTokens)} ↑ ${formatTokens(metrics.outputTokens)}`;
+        const extras = [];
+        if (metrics.thinkingTokens > 0) {
+            extras.push(`think: ${formatTokens(metrics.thinkingTokens)}`);
+        }
+        if (metrics.cacheReadTokens > 0) {
+            extras.push(`cache: ${formatTokens(metrics.cacheReadTokens)}`);
+        }
+        if (extras.length > 0) {
+            tokenDisplay += ` (${extras.join(', ')})`;
+        }
+        parts.push(tokenDisplay);
+        // Add token breakdown
+        const cacheInfo = formatCacheInfo();
+        if (cacheInfo) {
+            // Show cache info if available
+            parts.push(cacheInfo);
+        }
+        else {
+            // Show component breakdown
+            const breakdown = formatBreakdownCompact();
+            if (breakdown) {
+                parts.push(breakdown);
+            }
+        }
+        if (metrics.toolCalls > 0) {
+            parts.push(`${String(metrics.toolCalls)} tool${metrics.toolCalls > 1 ? 's' : ''}`);
+        }
+        // DEBUG: Show payload debug info (chars sent to provider)
+        if (metrics.debugPayload) {
+            const { systemChars, contentsChars, toolsChars } = metrics.debugPayload;
+            const totalChars = systemChars + contentsChars + toolsChars;
+            const estTokens = Math.ceil(totalChars / 4);
+            // Format: [dbg 2calls sent:123k (~31k est) sys:10k cont:100k tools:13k]
+            parts.push(`[dbg ${String(metrics.apiCalls)}calls sent:${formatTokens(totalChars)} (~${formatTokens(estTokens)} est) sys:${formatTokens(systemChars)} cont:${formatTokens(contentsChars)} tools:${formatTokens(toolsChars)}]`);
+        }
+        // Print as muted info line
+        this.ui.print({ type: 'turn-summary', parts });
+    }
+    // ===========================================================================
     // Session Management
     // ===========================================================================
+    /**
+     * Cancel the foreground session.
+     * Background agents continue running.
+     */
     cancelSession() {
         const action = this.currentSession?.currentAction ?? undefined;
-        if (this.currentSession) {
+        if (this.currentSession && this.foregroundAgentId) {
             this.currentSession.abortController.abort();
-            this.currentSession = null;
+            this.endSession(this.foregroundAgentId);
         }
         this.ui.setAgentRunning(false);
+        this.ui.setThinking(false); // Ensure thinking indicator is cleared
         this.ui.setTodos([]);
         this.ui.clearQueue();
         this.ui.print({ type: 'interrupted', action, suggestion: 'what should I do instead?' });
@@ -765,10 +3282,16 @@ export class ReplV2 {
 // Only run main() when executed directly (not when imported)
 if (import.meta.url === `file://${process.argv[1]}`) {
     const repl = new ReplV2();
-    repl.start();
     // Handle SIGINT
     process.on('SIGINT', () => {
         console.log('\n\nInterrupted\n');
         process.exit(0);
     });
+    try {
+        repl.start();
+    }
+    catch (err) {
+        console.error('Failed to start REPL:', err);
+        process.exit(1);
+    }
 }