lattice-orchestrator 0.7.0

package/dist/services/process/claude-process-manager.js

@@ -0,0 +1,1218 @@
+import * as pty from 'node-pty';
+import { spawn } from 'child_process';
+import { LatticeError, asClaudeSessionId, asStreamingId } from '../../types/index.js';
+import { v4 as uuidv4 } from 'uuid';
+import { EventEmitter } from 'events';
+import { existsSync, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import os from 'os';
+import { JsonLinesParser } from './json-lines-parser.js';
+import { createLogger } from '../infrastructure/logger.js';
+import path from 'path';
+import { getProcessEventLog } from './process-event-log.js';
+/**
+ * Expand tilde (~) in paths to the user's home directory.
+ * Node.js spawn doesn't expand ~ like shells do, causing ENOENT errors.
+ */
+function expandTilde(filePath) {
+    if (filePath === '~' || filePath.startsWith('~/')) {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return filePath;
+}
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Manages Claude CLI processes and their lifecycle
+ */
+export class ClaudeProcessManager extends EventEmitter {
+    processes = new Map();
+    outputBuffers = new Map();
+    timeouts = new Map();
+    conversationConfigs = new Map();
+    sessionIds = new Map(); // streamingId -> claude session_id
+    claudeExecutablePath;
+    logger;
+    envOverrides;
+    historyReader;
+    mcpConfigPath;
+    statusTracker;
+    conversationStatusManager;
+    toolMetricsService;
+    sessionInfoService;
+    fileSystemService;
+    notificationService;
+    routerService;
+    killedProcesses = new Set(); // Track which processes we've killed
+    processEventLog;
+    constructor(historyReader, statusTracker, claudeExecutablePath, envOverrides, toolMetricsService, sessionInfoService, fileSystemService) {
+        super();
+        this.historyReader = historyReader;
+        this.statusTracker = statusTracker;
+        this.claudeExecutablePath = claudeExecutablePath || this.findClaudeExecutable();
+        this.logger = createLogger('ClaudeProcessManager');
+        this.envOverrides = envOverrides || {};
+        this.toolMetricsService = toolMetricsService;
+        this.sessionInfoService = sessionInfoService;
+        this.fileSystemService = fileSystemService;
+        this.processEventLog = getProcessEventLog();
+    }
+    setRouterService(service) {
+        this.routerService = service;
+    }
+    /**
+     * Find the Claude executable - check user-local and system paths
+     */
+    findClaudeExecutable() {
+        // Check common installation paths including user-local installs
+        const userLocalPath = path.join(os.homedir(), '.local', 'bin', 'claude');
+        const candidatePaths = [
+            userLocalPath, // ~/.local/bin/claude (common for user installs)
+            '/usr/local/bin/claude',
+            '/usr/bin/claude',
+        ];
+        for (const candidate of candidatePaths) {
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        // Fallback: try PATH, excluding node_modules
+        const pathEnv = process.env.PATH || '';
+        const pathDirs = pathEnv.split(path.delimiter);
+        for (const dir of pathDirs) {
+            if (dir.includes('node_modules'))
+                continue; // Skip node_modules
+            const candidate = path.join(dir, 'claude');
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        throw new Error('Claude CLI not found.\n\n' +
+            'Claudia Orchestrator requires Claude Code CLI to be installed.\n' +
+            'Install it with: npm install -g @anthropic-ai/claude-code\n' +
+            'Then authenticate with: claude\n\n' +
+            'More info: https://docs.anthropic.com/en/docs/claude-code');
+    }
+    /**
+     * Set the MCP config path to be used for all conversations
+     */
+    setMCPConfigPath(path) {
+        this.mcpConfigPath = path;
+        this.logger.debug('MCP config path set', { path });
+    }
+    /**
+     * Set the optimistic conversation service
+     */
+    setConversationStatusManager(service) {
+        this.conversationStatusManager = service;
+        this.logger.debug('Conversation status manager set');
+    }
+    /**
+     * Set the notification service
+     */
+    setNotificationService(service) {
+        this.notificationService = service;
+        this.logger.debug('Notification service set');
+    }
+    /**
+     * Start a new Claude conversation (or resume if resumedSessionId is provided)
+     */
+    async startConversation(config) {
+        const isResume = !!config.resumedSessionId;
+        // Guard against duplicate spawns for the same session
+        if (isResume && config.resumedSessionId) {
+            const resumeSessionId = asClaudeSessionId(config.resumedSessionId);
+            if (this.statusTracker.isSessionActive(resumeSessionId)) {
+                this.logger.warn('Attempted to resume already-active session', {
+                    sessionId: config.resumedSessionId
+                });
+                throw new LatticeError('SESSION_ALREADY_ACTIVE', `Cannot resume session ${config.resumedSessionId}: already has an active Claude process`, 409 // Conflict
+                );
+            }
+        }
+        this.logger.debug('Start conversation requested', {
+            hasInitialPrompt: !!config.initialPrompt,
+            promptLength: config.initialPrompt?.length,
+            workingDirectory: config.workingDirectory,
+            model: config.model,
+            allowedTools: config.allowedTools,
+            disallowedTools: config.disallowedTools,
+            hasSystemPrompt: !!config.systemPrompt,
+            claudePath: config.claudeExecutablePath || this.claudeExecutablePath,
+            isResume,
+            resumedSessionId: config.resumedSessionId,
+            previousMessageCount: config.previousMessages?.length || 0
+        });
+        // If resuming and no working directory provided, fetch from original session
+        let workingDirectory = config.workingDirectory;
+        if (isResume && !workingDirectory && config.resumedSessionId) {
+            const fetchedWorkingDirectory = await this.historyReader.getConversationWorkingDirectory(config.resumedSessionId);
+            if (!fetchedWorkingDirectory) {
+                throw new LatticeError('CONVERSATION_NOT_FOUND', `Could not find working directory for session ${config.resumedSessionId}`, 404);
+            }
+            workingDirectory = fetchedWorkingDirectory;
+            this.logger.debug('Found working directory for resume session', {
+                sessionId: config.resumedSessionId,
+                workingDirectory
+            });
+        }
+        const args = isResume && config.resumedSessionId
+            ? this.buildResumeArgs({
+                sessionId: config.resumedSessionId,
+                message: config.initialPrompt,
+                permissionMode: config.permissionMode,
+                hasMultimodalContent: !!(config.initialContent && config.initialContent.length > 0)
+            })
+            : this.buildStartArgs(config);
+        const spawnConfig = {
+            executablePath: config.claudeExecutablePath || this.claudeExecutablePath,
+            cwd: workingDirectory || config.workingDirectory || process.cwd(),
+            env: { ...process.env, ...this.envOverrides }
+        };
+        this.logger.debug('Spawn config prepared', {
+            executablePath: spawnConfig.executablePath,
+            cwd: spawnConfig.cwd,
+            hasEnvOverrides: Object.keys(this.envOverrides).length > 0,
+            envOverrideKeys: Object.keys(this.envOverrides),
+            isResume
+        });
+        return this.executeConversationFlow(isResume ? 'resuming' : 'starting', isResume && config.resumedSessionId ? { resumeSessionId: config.resumedSessionId } : {}, config, args, spawnConfig, isResume ? 'PROCESS_RESUME_FAILED' : 'PROCESS_START_FAILED', isResume ? 'Failed to resume Claude process' : 'Failed to start Claude process');
+    }
+    /**
+     * Stop a conversation gracefully (SIGTERM, then SIGKILL after 3s)
+     */
+    async stopConversation(streamingId) {
+        this.logger.debug('Stopping conversation', { streamingId });
+        const process = this.processes.get(streamingId);
+        if (!process) {
+            this.logger.warn('No process found for conversation', { streamingId });
+            return false;
+        }
+        try {
+            // Force kill if not already killed
+            if (!this.killedProcesses.has(streamingId)) {
+                this.logger.info('Sending SIGTERM to process', { streamingId, pid: process.pid });
+                // Log stop requested
+                this.processEventLog.stopRequested({
+                    traceId: streamingId,
+                    streamingId,
+                    pid: process.pid,
+                });
+                process.kill('SIGTERM');
+                this.killedProcesses.add(streamingId);
+                // If SIGTERM doesn't work, use SIGKILL after 3 seconds
+                const killTimeout = setTimeout(() => {
+                    try {
+                        if (this.processes.has(streamingId)) {
+                            this.logger.warn('Process not responding to SIGTERM, sending SIGKILL', { streamingId, pid: process.pid });
+                            // Log force kill due to SIGTERM timeout
+                            this.processEventLog.forceKill({
+                                traceId: streamingId,
+                                streamingId,
+                                pid: process.pid,
+                                reason: 'SIGTERM timeout',
+                            });
+                            process.kill('SIGKILL');
+                        }
+                    }
+                    catch {
+                        // Process may have already exited, ignore
+                    }
+                }, 3000);
+                // Track timeout for cleanup on process exit
+                const sessionTimeouts = this.timeouts.get(streamingId) || [];
+                sessionTimeouts.push(killTimeout);
+                this.timeouts.set(streamingId, sessionTimeouts);
+            }
+            // Note: Cleanup happens in handleProcessClose when process actually exits
+            // Don't clean up here - the process may still be running
+            this.logger.info('Stop signal sent to process', { streamingId });
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Error stopping conversation', error, { streamingId });
+            return false;
+        }
+    }
+    /**
+     * Interrupt a conversation (SIGINT - like Ctrl-C)
+     * This allows the process to handle the interrupt gracefully
+     */
+    interruptConversation(streamingId) {
+        this.logger.info('Interrupting conversation', { streamingId });
+        const process = this.processes.get(streamingId);
+        if (!process) {
+            this.logger.warn('No process found for interrupt', { streamingId });
+            return false;
+        }
+        try {
+            this.logger.info('Sending SIGINT to process', { streamingId, pid: process.pid });
+            process.kill('SIGINT');
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Error interrupting conversation', error, { streamingId });
+            return false;
+        }
+    }
+    /**
+     * Force kill a conversation immediately (SIGKILL)
+     */
+    forceKillConversation(streamingId) {
+        this.logger.info('Force killing conversation', { streamingId });
+        const process = this.processes.get(streamingId);
+        if (!process) {
+            this.logger.warn('No process found for force kill', { streamingId });
+            return false;
+        }
+        try {
+            this.logger.warn('Sending SIGKILL to process', { streamingId, pid: process.pid });
+            // Log force kill
+            this.processEventLog.forceKill({
+                traceId: streamingId,
+                streamingId,
+                pid: process.pid,
+                reason: 'user requested',
+            });
+            process.kill('SIGKILL');
+            this.killedProcesses.add(streamingId);
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Error force killing conversation', error, { streamingId });
+            return false;
+        }
+    }
+    /**
+     * Get active sessions with their session IDs
+     */
+    getActiveSessions() {
+        const sessions = Array.from(this.processes.keys())
+            .map(streamingId => {
+            const sessionId = this.sessionIds.get(streamingId);
+            return sessionId ? { streamingId, sessionId } : null;
+        })
+            .filter((s) => s !== null);
+        this.logger.debug('Getting active sessions', { sessionCount: sessions.length });
+        return sessions;
+    }
+    /**
+     * Check if a session is active
+     */
+    isSessionActive(streamingId) {
+        const active = this.processes.has(streamingId);
+        return active;
+    }
+    /**
+     * Get the Claude session ID for a streaming ID
+     * This mapping persists for the lifetime of the process
+     */
+    getClaudeSessionId(streamingId) {
+        return this.sessionIds.get(streamingId);
+    }
+    /**
+     * Wait for the system init message from Claude CLI
+     * This should always be the first message in the stream
+     */
+    async waitForSystemInit(streamingId) {
+        this.logger.debug('Waiting for system init message', { streamingId });
+        return new Promise((resolve, reject) => {
+            let isResolved = false;
+            let stderrOutput = '';
+            // Set up timeout (1 minute)
+            const timeout = setTimeout(() => {
+                if (!isResolved) {
+                    isResolved = true;
+                    cleanup();
+                    this.logger.error('Timeout waiting for system init message', {
+                        streamingId,
+                        stderrOutput: stderrOutput || '(no stderr output)'
+                    });
+                    // Include stderr output in error message if available
+                    let errorMessage = 'Timeout waiting for system initialization from Claude CLI';
+                    if (stderrOutput) {
+                        errorMessage += `. Error output: ${stderrOutput}`;
+                    }
+                    reject(new LatticeError('SYSTEM_INIT_TIMEOUT', errorMessage, 500));
+                }
+            }, 60000);
+            // Cleanup function to remove all listeners
+            const cleanup = () => {
+                clearTimeout(timeout);
+                this.removeListener('claude-message', messageHandler);
+                this.removeListener('process-closed', processClosedHandler);
+                this.removeListener('process-error', processErrorHandler);
+            };
+            // Register timeout for cleanup on process termination
+            const existingTimeouts = this.timeouts.get(streamingId) || [];
+            existingTimeouts.push(timeout);
+            this.timeouts.set(streamingId, existingTimeouts);
+            // Listen for process exit before system init is received
+            const processClosedHandler = ({ streamingId: closedStreamingId, code }) => {
+                if (closedStreamingId !== streamingId || isResolved) {
+                    return; // Not our process or already resolved
+                }
+                isResolved = true;
+                cleanup();
+                this.logger.error('Claude process exited before system init message', {
+                    streamingId,
+                    exitCode: code,
+                    stderrOutput: stderrOutput || '(no stderr output)'
+                });
+                // Create error message with Claude CLI output if available
+                let errorMessage = 'Claude CLI process exited before sending system initialization message';
+                if (stderrOutput) {
+                    // Extract Claude CLI's actual output from parser errors
+                    const claudeOutputMatch = stderrOutput.match(/Invalid JSON: (.+)/);
+                    if (claudeOutputMatch) {
+                        errorMessage += `. Claude CLI said: "${claudeOutputMatch[1]}"`;
+                    }
+                    else {
+                        errorMessage += `. Error output: ${stderrOutput}`;
+                    }
+                }
+                if (code !== null) {
+                    errorMessage += `. Exit code: ${code}`;
+                }
+                reject(new LatticeError('CLAUDE_PROCESS_EXITED_EARLY', errorMessage, 500));
+            };
+            // Listen for process errors (including stderr output)
+            const processErrorHandler = ({ streamingId: errorStreamingId, error }) => {
+                if (errorStreamingId !== streamingId) {
+                    return; // Not our process
+                }
+                // Capture stderr output for error context
+                stderrOutput += error;
+                this.logger.debug('Captured stderr output during system init wait', {
+                    streamingId,
+                    errorLength: error.length,
+                    totalStderrLength: stderrOutput.length
+                });
+            };
+            // Listen for the first claude-message event for this streamingId
+            const messageHandler = ({ streamingId: msgStreamingId, message }) => {
+                if (msgStreamingId !== streamingId) {
+                    return; // Not for our session
+                }
+                if (isResolved) {
+                    return; // Already resolved
+                }
+                this.logger.debug('Received message from Claude CLI during init wait', {
+                    streamingId,
+                    messageType: message?.type,
+                    messageSubtype: 'subtype' in message ? message.subtype : undefined,
+                    hasSessionId: 'session_id' in message ? !!message.session_id : false
+                });
+                // Skip hook_response messages (Claude v2 sends these before init)
+                // Cast to unknown string to compare - StreamEvent type doesn't include all system subtypes
+                if (message?.type === 'system' && 'subtype' in message && message.subtype === 'hook_response') {
+                    this.logger.debug('Skipping hook_response message, waiting for init', { streamingId });
+                    return; // Keep waiting for init message
+                }
+                // Now we have a non-hook message, mark as resolved
+                isResolved = true;
+                cleanup();
+                // Validate that this message is a system init message
+                if (!message || message.type !== 'system' || !('subtype' in message) || message.subtype !== 'init') {
+                    this.logger.error('Expected system init message', {
+                        streamingId,
+                        actualType: message?.type,
+                        actualSubtype: 'subtype' in message ? message.subtype : undefined,
+                        expectedType: 'system',
+                        expectedSubtype: 'init'
+                    });
+                    reject(new LatticeError('INVALID_SYSTEM_INIT', `Expected system init message, but got: ${message?.type}/${'subtype' in message ? message.subtype : 'undefined'}`, 500));
+                    return;
+                }
+                // At this point, TypeScript knows message is SystemInitMessage
+                const systemInitMessage = message;
+                // Validate required fields
+                const requiredFields = ['session_id', 'cwd', 'tools', 'mcp_servers', 'model', 'permissionMode', 'apiKeySource'];
+                const missingFields = requiredFields.filter(field => systemInitMessage[field] === undefined);
+                if (missingFields.length > 0) {
+                    this.logger.error('System init message missing required fields', {
+                        streamingId,
+                        missingFields,
+                        availableFields: Object.keys(systemInitMessage)
+                    });
+                    reject(new LatticeError('INCOMPLETE_SYSTEM_INIT', `System init message missing required fields: ${missingFields.join(', ')}`, 500));
+                    return;
+                }
+                this.logger.debug('Successfully received valid system init message', {
+                    streamingId,
+                    sessionId: systemInitMessage.session_id,
+                    cwd: systemInitMessage.cwd,
+                    model: systemInitMessage.model,
+                    toolCount: systemInitMessage.tools?.length || 0,
+                    mcpServerCount: systemInitMessage.mcp_servers?.length || 0
+                });
+                // Log system init to process event log
+                this.processEventLog.systemInit({
+                    traceId: streamingId,
+                    streamingId,
+                    sessionId: systemInitMessage.session_id,
+                    model: systemInitMessage.model,
+                    workingDirectory: systemInitMessage.cwd,
+                    toolCount: systemInitMessage.tools?.length || 0,
+                    mcpServerCount: systemInitMessage.mcp_servers?.length || 0,
+                });
+                // Register active session immediately when we have the session_id
+                // Include optimistic context if available
+                const config = this.conversationConfigs.get(streamingId);
+                if (this.conversationStatusManager && config) {
+                    const optimisticContext = {
+                        initialPrompt: config.initialPrompt || '',
+                        workingDirectory: config.workingDirectory || process.cwd(),
+                        model: config.model || 'default',
+                        timestamp: new Date().toISOString(),
+                        inheritedMessages: config.previousMessages
+                    };
+                    // Store in local sessionIds map (never cleaned up until process exits)
+                    const claudeSessionId = asClaudeSessionId(systemInitMessage.session_id);
+                    this.sessionIds.set(streamingId, claudeSessionId);
+                    this.conversationStatusManager.registerActiveSession(streamingId, claudeSessionId, optimisticContext);
+                    this.logger.debug('Registered conversation context', {
+                        streamingId,
+                        claudeSessionId,
+                        inheritedMessageCount: config.previousMessages?.length || 0
+                    });
+                }
+                else {
+                    // Fallback to old behavior if service not set
+                    const claudeSessionId = asClaudeSessionId(systemInitMessage.session_id);
+                    this.sessionIds.set(streamingId, claudeSessionId);
+                    this.statusTracker.registerActiveSession(streamingId, claudeSessionId);
+                    this.logger.debug('Registered active session with status tracker (no optimistic service)', {
+                        streamingId,
+                        claudeSessionId
+                    });
+                }
+                resolve(systemInitMessage);
+            };
+            // Set up all event listeners
+            this.on('claude-message', messageHandler);
+            this.on('process-closed', processClosedHandler);
+            this.on('process-error', processErrorHandler);
+        });
+    }
+    /**
+     * Execute common conversation flow for both start and resume operations
+     */
+    async executeConversationFlow(operation, loggerContext, config, args, spawnConfig, errorCode, errorPrefix) {
+        const streamingId = asStreamingId(uuidv4()); // CUI's internal streaming identifier
+        const traceId = streamingId; // Use streamingId as traceId for now
+        const isResume = operation === 'resuming';
+        // Store config for use in waitForSystemInit
+        this.conversationConfigs.set(streamingId, config);
+        // Log spawn start
+        this.processEventLog.spawnStart({
+            traceId,
+            streamingId,
+            isResume,
+            workingDirectory: spawnConfig.cwd,
+            model: config.model,
+            resumedSessionId: config.resumedSessionId,
+        });
+        try {
+            // Validate Claude executable before proceeding
+            if (this.fileSystemService) {
+                await this.fileSystemService.validateExecutable(spawnConfig.executablePath);
+            }
+            this.logger.debug(`${operation.charAt(0).toUpperCase() + operation.slice(1)} conversation`, {
+                streamingId,
+                operation,
+                configKeys: Object.keys(config),
+                argCount: args.length,
+                ...loggerContext
+            });
+            this.logger.debug(`Built Claude ${operation} args`, {
+                streamingId,
+                args,
+                argsString: args.join(' '),
+                ...loggerContext
+            });
+            // Set up system init promise before spawning process
+            const systemInitPromise = this.waitForSystemInit(streamingId);
+            // Add streamingId to environment for MCP server to use
+            // Filter out debugging-related environment variables that would cause
+            // the VSCode debugger to attach to the Claude CLI child process
+            // Also filter CLAUDECODE to prevent nested session detection issues
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { NODE_OPTIONS, VSCODE_INSPECTOR_OPTIONS, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, ...cleanEnv } = spawnConfig.env;
+            // Expand tilde to actual home directory path
+            const expandedCwd = expandTilde(spawnConfig.cwd);
+            const envWithStreamingId = {
+                ...cleanEnv,
+                CUI_STREAMING_ID: streamingId,
+                PWD: expandedCwd,
+                INIT_CWD: expandedCwd
+            };
+            // Use piped spawn for multimodal content (stdin works properly with pipes)
+            // Use PTY for text-only (better terminal experience)
+            const hasMultimodalContent = !!(config.initialContent && config.initialContent.length > 0);
+            const managedProcess = this.spawnProcess({ ...spawnConfig, env: envWithStreamingId }, args, streamingId, hasMultimodalContent // usePipe = true for multimodal
+            );
+            this.processes.set(streamingId, managedProcess);
+            this.setupProcessHandlers(streamingId, managedProcess);
+            // Emit process-spawned event so StreamManager can start buffering events
+            // This handles the race condition where events are broadcast before SSE client connects
+            this.emit('process-spawned', { streamingId });
+            // For multimodal content, send via stdin BEFORE waiting for system init
+            // The CLI will process this and emit the system init message
+            if (hasMultimodalContent && config.initialContent) {
+                const contentBlocks = [
+                    ...config.initialContent,
+                    ...(config.initialPrompt ? [{ type: 'text', text: config.initialPrompt }] : [])
+                ];
+                const stdinMessage = JSON.stringify({
+                    type: 'user',
+                    message: {
+                        role: 'user',
+                        content: contentBlocks
+                    },
+                    session_id: config.resumedSessionId || ''
+                });
+                this.logger.info('Sending multimodal content via stdin (piped mode)', {
+                    streamingId,
+                    contentBlockCount: contentBlocks.length,
+                    messageLength: stdinMessage.length
+                });
+                managedProcess.write(stdinMessage + '\n');
+                // Close stdin to signal end of input - CLI will process and respond
+                if (managedProcess.type === 'pipe') {
+                    managedProcess.endStdin();
+                }
+            }
+            // Log spawn success
+            if (managedProcess.pid) {
+                this.processEventLog.spawnSuccess({
+                    traceId,
+                    streamingId,
+                    pid: managedProcess.pid,
+                });
+            }
+            // Handle spawn errors by listening for our custom event
+            const spawnErrorPromise = new Promise((_, reject) => {
+                this.once('spawn-error', (error) => {
+                    this.processes.delete(streamingId);
+                    reject(error);
+                });
+            });
+            // Wait a bit to see if spawn fails immediately
+            this.logger.debug('Waiting for spawn validation', { streamingId, ...loggerContext });
+            const delayPromise = new Promise(resolve => {
+                setTimeout(() => {
+                    this.logger.debug('Spawn validation period passed, process appears stable', { streamingId, ...loggerContext });
+                    this.removeAllListeners('spawn-error');
+                    resolve(streamingId);
+                }, 100);
+            });
+            await Promise.race([spawnErrorPromise, delayPromise]);
+            // Now wait for the system init message
+            this.logger.debug('Process spawned successfully, waiting for system init message', { streamingId, ...loggerContext });
+            const systemInit = await systemInitPromise;
+            // Check if cwd is a git repository and set initial_commit_head for new session
+            if (this.sessionInfoService && this.fileSystemService) {
+                try {
+                    if (await this.fileSystemService.isGitRepository(systemInit.cwd)) {
+                        const gitHead = await this.fileSystemService.getCurrentGitHead(systemInit.cwd);
+                        if (gitHead) {
+                            await this.sessionInfoService.updateSessionInfo(systemInit.session_id, {
+                                initial_commit_head: gitHead
+                            });
+                            this.logger.debug('Set initial commit head for new session', {
+                                sessionId: systemInit.session_id,
+                                gitHead
+                            });
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.warn('Failed to set initial commit head for new session', {
+                        sessionId: systemInit.session_id,
+                        cwd: systemInit.cwd,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            this.logger.debug(`${operation.charAt(0).toUpperCase() + operation.slice(1)} conversation successfully`, {
+                streamingId,
+                sessionId: systemInit.session_id,
+                model: systemInit.model,
+                cwd: systemInit.cwd,
+                processCount: this.processes.size,
+                ...loggerContext
+            });
+            return { streamingId, systemInit };
+        }
+        catch (error) {
+            this.logger.error(`Error ${operation} conversation`, error, {
+                streamingId,
+                errorName: error instanceof Error ? error.name : 'Unknown',
+                errorMessage: error instanceof Error ? error.message : String(error),
+                errorCode: error instanceof LatticeError ? error.code : undefined,
+                ...loggerContext
+            });
+            // Log spawn failure
+            this.processEventLog.spawnFailed({
+                traceId,
+                streamingId,
+                errorCode: error instanceof LatticeError ? error.code : errorCode,
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
+            // Clean up any resources if process fails
+            const timeouts = this.timeouts.get(streamingId);
+            if (timeouts) {
+                timeouts.forEach(timeout => clearTimeout(timeout));
+                this.timeouts.delete(streamingId);
+            }
+            this.processes.delete(streamingId);
+            this.outputBuffers.delete(streamingId);
+            this.conversationConfigs.delete(streamingId);
+            if (error instanceof LatticeError) {
+                throw error;
+            }
+            throw new LatticeError(errorCode, `${errorPrefix}: ${error}`, 500);
+        }
+    }
+    buildBaseArgs() {
+        return [
+            '-p', // Print mode - required for programmatic use
+        ];
+    }
+    buildResumeArgs(config) {
+        this.logger.debug('Building Claude resume args', {
+            sessionId: config.sessionId,
+            messagePreview: config.message.substring(0, 50) + (config.message.length > 50 ? '...' : ''),
+            permissionMode: config.permissionMode,
+            hasMultimodalContent: config.hasMultimodalContent
+        });
+        const args = this.buildBaseArgs();
+        // Add message as CLI arg - skip if multimodal content will be sent via stdin
+        // NOTE: For very long messages, this may hit CLI arg length limits
+        if (config.message && !config.hasMultimodalContent) {
+            args.push(config.message);
+        }
+        args.push('--resume', config.sessionId, '--output-format', 'stream-json', '--input-format', 'stream-json', // Enable stdin for AskUserQuestion responses
+        '--verbose');
+        // Add MCP config if available (same as start operations)
+        // This enables the permission prompt tool for ASK mode on resume
+        if (this.mcpConfigPath) {
+            args.push('--mcp-config', this.mcpConfigPath);
+        }
+        // Apply permission mode with MCP tool support enabled
+        this.applyPermissionMode(args, config.permissionMode);
+        this.logger.debug('Built Claude resume args', { args, hasMCPConfig: !!this.mcpConfigPath });
+        return args;
+    }
+    /**
+     * Apply permission mode flags to CLI args
+     * Modes:
+     * - "bypassPermissions" (default): Skip all permission prompts (--dangerously-skip-permissions)
+     * - "default": Use Claude's default permission behavior (prompts for approval via MCP)
+     * - "acceptEdits": Auto-accept file edits but prompt for other tools
+     * - "plan": Plan mode - research only, no edits
+     */
+    applyPermissionMode(args, permissionMode) {
+        switch (permissionMode) {
+            case 'default':
+                // Use MCP permission prompt tool to delegate approval to the dashboard
+                // The tool must be pre-allowed so Claude can use it without prompting
+                if (this.mcpConfigPath) {
+                    args.push('--permission-prompt-tool', 'mcp__claudia-permissions__permission_prompt');
+                    args.push('--allowedTools', 'mcp__claudia-permissions__permission_prompt');
+                    this.logger.debug('Permission mode: default (using MCP permission prompt)');
+                }
+                else {
+                    // No MCP config available - fall back to bypass permissions
+                    args.push('--dangerously-skip-permissions');
+                    this.logger.debug('Permission mode: default but no MCP config, falling back to bypass');
+                }
+                break;
+            case 'acceptEdits':
+                args.push('--permission-mode', 'acceptEdits');
+                this.logger.debug('Permission mode: acceptEdits');
+                break;
+            case 'plan':
+                args.push('--permission-mode', 'plan');
+                this.logger.debug('Permission mode: plan');
+                break;
+            case 'bypassPermissions':
+            default:
+                // Default to bypass for backwards compatibility
+                args.push('--dangerously-skip-permissions');
+                this.logger.debug('Permission mode: bypassPermissions (dangerously skip)');
+                break;
+        }
+    }
+    buildStartArgs(config) {
+        this.logger.debug('Building Claude start args', {
+            hasInitialPrompt: !!config.initialPrompt,
+            hasInitialContent: !!(config.initialContent && config.initialContent.length > 0),
+            promptPreview: config.initialPrompt ? config.initialPrompt.substring(0, 50) + (config.initialPrompt.length > 50 ? '...' : '') : null,
+            workingDirectory: config.workingDirectory,
+            model: config.model
+        });
+        const args = this.buildBaseArgs();
+        // Add initial prompt immediately after -p
+        // Skip if initialContent is provided - multimodal content will be sent via stdin
+        if (config.initialPrompt && !(config.initialContent && config.initialContent.length > 0)) {
+            args.push(config.initialPrompt);
+        }
+        args.push('--output-format', 'stream-json', // JSONL output format
+        '--input-format', 'stream-json', // Enable stdin for AskUserQuestion responses
+        '--verbose' // Required when using stream-json with print mode
+        );
+        // Add working directory access
+        // if (config.workingDirectory) {
+        //   args.push('--add-dir', config.workingDirectory);
+        // }
+        // Add model specification
+        if (config.model) {
+            args.push('--model', config.model);
+        }
+        // Add allowed tools
+        if (config.allowedTools && config.allowedTools.length > 0) {
+            args.push('--allowedTools', config.allowedTools.join(','));
+        }
+        // Add disallowed tools
+        if (config.disallowedTools && config.disallowedTools.length > 0) {
+            args.push('--disallowedTools', config.disallowedTools.join(','));
+        }
+        // Add system prompt with Claudia environment info
+        const claudiaEnvInfo = `
+## Claudia Orchestrator Environment
+
+You are running inside the Claudia orchestrator dashboard.
+
+**Server logs** (for debugging issues):
+- \`~/.claudia/logs/server.log\` - Express server logs
+- \`~/.claudia/logs/daemon.log\` - Process daemon logs
+`;
+        const systemPrompt = config.systemPrompt
+            ? `${config.systemPrompt}\n${claudiaEnvInfo}`
+            : claudiaEnvInfo;
+        args.push('--system-prompt', systemPrompt);
+        // Add MCP config if available
+        if (this.mcpConfigPath) {
+            args.push('--mcp-config', this.mcpConfigPath);
+        }
+        // Apply permission mode
+        this.applyPermissionMode(args, config.permissionMode);
+        this.logger.debug('Built Claude args', { args, hasMCPConfig: !!this.mcpConfigPath, permissionMode: config.permissionMode });
+        return args;
+    }
+    /**
+     * Consolidated method to spawn Claude processes for both start and resume operations
+     * Uses node-pty for text-only (terminal experience) or piped spawn for multimodal (stdin works properly)
+     */
+    spawnProcess(spawnConfig, args, streamingId, usePipe = false) {
+        const { executablePath } = spawnConfig;
+        // Expand tilde to actual home directory - Node.js spawn doesn't do shell expansion
+        const cwd = expandTilde(spawnConfig.cwd);
+        let { env } = spawnConfig;
+        // Inject router proxy if enabled
+        if (this.routerService?.isEnabled()) {
+            env = {
+                ...env,
+                ANTHROPIC_BASE_URL: this.routerService.getProxyUrl(),
+                ANTHROPIC_API_KEY: 'router-managed'
+            };
+            this.logger.info('Using router proxy', {
+                streamingId,
+                proxyUrl: this.routerService.getProxyUrl()
+            });
+        }
+        // Check if MCP config is in args and validate it
+        const mcpConfigIndex = args.indexOf('--mcp-config');
+        if (mcpConfigIndex !== -1 && mcpConfigIndex + 1 < args.length) {
+            const mcpConfigPath = args[mcpConfigIndex + 1];
+            this.logger.debug('MCP config specified', {
+                streamingId,
+                mcpConfigPath,
+                exists: existsSync(mcpConfigPath)
+            });
+            // Try to read and log the MCP config content
+            try {
+                const mcpConfigContent = readFileSync(mcpConfigPath, 'utf-8');
+                this.logger.debug('MCP config content', {
+                    streamingId,
+                    mcpConfig: JSON.parse(mcpConfigContent)
+                });
+            }
+            catch (error) {
+                this.logger.error('Failed to read MCP config', { streamingId, error });
+            }
+        }
+        const spawnMode = usePipe ? 'PIPE' : 'PTY';
+        this.logger.debug(`Spawning Claude process with ${spawnMode}`, {
+            streamingId,
+            executablePath,
+            args,
+            cwd,
+            PATH: env.PATH,
+            nodeVersion: process.version,
+            platform: process.platform
+        });
+        try {
+            // Log the exact command for debugging
+            const fullCommand = `${executablePath} ${args.join(' ')}`;
+            this.logger.info(`SPAWNING CLAUDE COMMAND (${spawnMode}): ` + fullCommand, {
+                streamingId,
+                fullCommand,
+                executablePath,
+                args,
+                cwd,
+                env: Object.entries(env).reduce((acc, [key, value]) => {
+                    acc[key] = value;
+                    return acc;
+                }, {})
+            });
+            if (usePipe) {
+                // Use piped spawn for multimodal - stdin will be a pipe, not a TTY
+                // This allows CLI to block waiting for stdin input
+                const childProcess = spawn(executablePath, args, {
+                    cwd,
+                    env: env,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                if (!childProcess.pid) {
+                    this.logger.error('Failed to spawn Claude process - no PID assigned', { streamingId });
+                    throw new Error('Failed to spawn Claude process - no PID assigned');
+                }
+                this.logger.info('Claude process spawned successfully (PIPE)', {
+                    streamingId,
+                    pid: childProcess.pid
+                });
+                return {
+                    type: 'pipe',
+                    child: childProcess,
+                    pid: childProcess.pid,
+                    write: (data) => childProcess.stdin?.write(data),
+                    kill: (signal) => childProcess.kill(signal),
+                    endStdin: () => childProcess.stdin?.end(),
+                };
+            }
+            else {
+                // Use node-pty to spawn with a pseudo-terminal
+                // This is required because Claude CLI -p mode only outputs when connected to a TTY
+                const claudeProcess = pty.spawn(executablePath, args, {
+                    name: 'xterm-256color',
+                    cols: 200,
+                    rows: 50,
+                    cwd,
+                    env: env
+                });
+                if (!claudeProcess.pid) {
+                    this.logger.error('Failed to spawn Claude process - no PID assigned', { streamingId });
+                    throw new Error('Failed to spawn Claude process - no PID assigned');
+                }
+                this.logger.info('Claude process spawned successfully (PTY)', {
+                    streamingId,
+                    pid: claudeProcess.pid
+                });
+                return {
+                    type: 'pty',
+                    pty: claudeProcess,
+                    pid: claudeProcess.pid,
+                    write: (data) => claudeProcess.write(data),
+                    kill: (signal) => claudeProcess.kill(signal),
+                };
+            }
+        }
+        catch (error) {
+            this.logger.error('Error in spawnProcess', error, { streamingId });
+            if (error instanceof LatticeError) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
+                throw new LatticeError('CLAUDE_NOT_FOUND', 'Claude CLI not found. Please ensure Claude is installed and in PATH.', 500);
+            }
+            throw new LatticeError('PROCESS_SPAWN_FAILED', `Failed to spawn Claude process: ${errorMessage}`, 500);
+        }
+    }
+    setupProcessHandlers(streamingId, managedProcess) {
+        this.logger.debug(`Setting up ${managedProcess.type.toUpperCase()} process handlers`, { streamingId, pid: managedProcess.pid });
+        // Create JSONL parser for Claude output
+        const parser = new JsonLinesParser();
+        // Initialize output buffer for this session
+        this.outputBuffers.set(streamingId, '');
+        // Handle parsed JSONL messages from Claude
+        parser.on('data', (message) => {
+            // Skip echoed stdin messages - PTY echoes our input back
+            // Piped processes don't echo, but we still filter non-tool-result user messages
+            // BUT: tool_result messages are also type: 'user' (Claude API protocol:
+            // user = input TO Claude, assistant = output FROM Claude)
+            // We need to let tool_result messages through so the UI can update tool status
+            if (message?.type === 'user') {
+                const content = message.message?.content;
+                const isToolResult = Array.isArray(content) &&
+                    content.some((block) => block.type === 'tool_result');
+                if (!isToolResult) {
+                    this.logger.debug('Skipping echoed stdin message', {
+                        streamingId,
+                        messageType: message?.type
+                    });
+                    return;
+                }
+                // Fall through to emit tool_result messages
+                this.logger.debug('Allowing tool_result message through', {
+                    streamingId,
+                    toolResultCount: content.filter((b) => b.type === 'tool_result').length
+                });
+            }
+            this.logger.debug('Received Claude message', {
+                streamingId,
+                messageType: message?.type,
+                hasContent: !!message?.content,
+                contentLength: message?.content?.length,
+                messageKeys: message ? Object.keys(message) : [],
+                timestamp: new Date().toISOString()
+            });
+            this.handleClaudeMessage(streamingId, message);
+        });
+        parser.on('error', (error) => {
+            this.logger.error('Parser error', error, {
+                streamingId,
+                errorType: error.name,
+                errorMessage: error.message,
+                bufferState: this.outputBuffers.get(streamingId)?.length || 0
+            });
+            this.handleProcessError(streamingId, error);
+        });
+        if (managedProcess.type === 'pty') {
+            // Handle PTY data output (combined stdout/stderr from the pseudo-terminal)
+            // PTY combines both streams, so we need to parse JSONL from the raw output
+            managedProcess.pty.onData((data) => {
+                // Log raw PTY data for debugging (debug level - very verbose)
+                this.logger.debug('RAW PTY DATA', {
+                    streamingId,
+                    dataLength: data.length,
+                    dataPreview: data.substring(0, 200)
+                });
+                // Strip ANSI escape sequences that might interfere with JSON parsing
+                // Common PTY escape sequences: cursor control, colors, etc.
+                const cleanedData = data.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07/g, '');
+                // Feed cleaned data to the JSONL parser
+                if (cleanedData.trim()) {
+                    parser.write(cleanedData);
+                }
+            });
+            // Handle PTY process exit (node-pty uses onExit, not EventEmitter 'exit')
+            managedProcess.pty.onExit(({ exitCode }) => {
+                this.logger.debug('PTY process exited', {
+                    streamingId,
+                    exitCode,
+                    normalExit: exitCode === 0,
+                    timestamp: new Date().toISOString(),
+                    outputBuffer: this.outputBuffers.get(streamingId) || 'No output captured'
+                });
+                this.handleProcessClose(streamingId, exitCode);
+            });
+        }
+        else {
+            // Handle piped child process stdout
+            managedProcess.child.stdout?.on('data', (data) => {
+                const str = data.toString();
+                this.logger.debug('RAW PIPE STDOUT', {
+                    streamingId,
+                    dataLength: str.length,
+                    dataPreview: str.substring(0, 200)
+                });
+                if (str.trim()) {
+                    parser.write(str);
+                }
+            });
+            // Handle piped child process stderr
+            managedProcess.child.stderr?.on('data', (data) => {
+                this.logger.warn('Claude CLI stderr (piped)', { streamingId, stderr: data.toString() });
+            });
+            // Handle piped process close
+            managedProcess.child.on('close', (code) => {
+                this.logger.debug('Piped process closed', {
+                    streamingId,
+                    exitCode: code,
+                    normalExit: code === 0,
+                    timestamp: new Date().toISOString(),
+                    outputBuffer: this.outputBuffers.get(streamingId) || 'No output captured'
+                });
+                this.handleProcessClose(streamingId, code);
+            });
+            // Handle piped process error
+            managedProcess.child.on('error', (error) => {
+                this.handleProcessError(streamingId, error);
+            });
+        }
+    }
+    handleClaudeMessage(streamingId, message) {
+        this.logger.debug('Handling Claude message', {
+            streamingId,
+            messageType: message?.type,
+            isError: message?.type === 'error',
+            isResult: message?.type === 'result'
+        });
+        // Log important message types to process event log
+        const messageType = message?.type;
+        const messageSubtype = 'subtype' in message ? message.subtype : undefined;
+        this.processEventLog.message({
+            traceId: streamingId,
+            streamingId,
+            messageType: messageType || 'unknown',
+            messageSubtype,
+        });
+        // Log result messages specifically
+        if (messageType === 'result') {
+            this.processEventLog.result({
+                traceId: streamingId,
+                streamingId,
+                resultSubtype: messageSubtype,
+            });
+        }
+        // Log tool use from assistant content blocks
+        if (messageType === 'assistant' && 'message' in message && message.message?.content) {
+            const content = message.message.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === 'tool_use' && block.name && block.id) {
+                        this.processEventLog.toolUse({
+                            traceId: streamingId,
+                            streamingId,
+                            toolName: block.name,
+                            toolUseId: block.id,
+                        });
+                    }
+                }
+            }
+        }
+        this.emit('claude-message', { streamingId, message });
+        // When we receive a 'result' message, the conversation turn is complete.
+        // For PTY, we don't need to close stdin - the process will exit naturally after result.
+        // The PTY's onExit handler will clean up.
+        if (message?.type === 'result') {
+            this.logger.debug('Received result message, process will exit naturally', {
+                streamingId,
+                resultSubtype: 'subtype' in message ? message.subtype : undefined
+            });
+        }
+    }
+    handleProcessClose(streamingId, code) {
+        // Log process exit
+        this.processEventLog.processExit({
+            traceId: streamingId,
+            streamingId,
+            exitCode: code,
+        });
+        // Clear any pending timeouts for this session
+        const timeouts = this.timeouts.get(streamingId);
+        if (timeouts) {
+            timeouts.forEach(timeout => clearTimeout(timeout));
+            this.timeouts.delete(streamingId);
+        }
+        this.processes.delete(streamingId);
+        this.outputBuffers.delete(streamingId);
+        const config = this.conversationConfigs.get(streamingId);
+        this.conversationConfigs.delete(streamingId);
+        // Send notification if service is available
+        if (this.notificationService && config) {
+            // Get session ID from conversation status or config
+            const sessionId = this.statusTracker.getSessionId(streamingId) || 'unknown';
+            // Try to get conversation metadata for summary
+            this.historyReader.fetchConversationDirect(sessionId)
+                .then(({ metadata }) => {
+                if (this.notificationService && metadata) {
+                    return this.notificationService.sendConversationEndNotification(streamingId, sessionId, metadata.summary);
+                }
+            })
+                .catch((error) => {
+                this.logger.error('Failed to send conversation end notification', error);
+            });
+        }
+        this.emit('process-closed', { streamingId, code });
+    }
+    handleProcessError(streamingId, error) {
+        const errorMessage = error.toString();
+        const isBuffer = Buffer.isBuffer(error);
+        this.logger.error('Process error occurred', {
+            streamingId,
+            error: errorMessage,
+            errorType: isBuffer ? 'stderr-output' : error.constructor.name,
+            errorLength: errorMessage.length,
+            processStillActive: this.processes.has(streamingId),
+            timestamp: new Date().toISOString()
+        });
+        this.emit('process-error', { streamingId, error: errorMessage });
+    }
+    /**
+     * Send an answer to an AskUserQuestion tool via stdin.
+     * The Claude CLI with --input-format stream-json expects a tool_result message.
+     *
+     * Per the SDK docs, the answer format must include both the original questions
+     * and an answers object mapping question text to selected option labels.
+     */
+    sendQuestionAnswer(streamingId, toolUseId, questions, answers) {
+        const process = this.processes.get(streamingId);
+        if (!process) {
+            this.logger.warn('Cannot send question answer: process not found', { streamingId });
+            return false;
+        }
+        const sessionId = this.sessionIds.get(streamingId);
+        if (!sessionId) {
+            this.logger.warn('Cannot send question answer: session ID not found', { streamingId });
+            return false;
+        }
+        // Build the tool result content per SDK docs:
+        // { questions: [...], answers: { "Question text?": "Selected label" } }
+        const toolResultContent = JSON.stringify({
+            questions,
+            answers
+        });
+        // Format as a tool_result message per Claude CLI stream-json protocol
+        const stdinMessage = JSON.stringify({
+            type: 'user',
+            message: {
+                role: 'user',
+                content: [{
+                        type: 'tool_result',
+                        tool_use_id: toolUseId,
+                        content: toolResultContent
+                    }]
+            },
+            session_id: sessionId
+        });
+        this.logger.info('Sending question answer via stdin', {
+            streamingId,
+            sessionId,
+            toolUseId,
+            answerCount: Object.keys(answers).length,
+            stdinMessagePreview: stdinMessage.substring(0, 500),
+            fullMessage: stdinMessage
+        });
+        // Write to PTY stdin with newline
+        process.write(stdinMessage + '\n');
+        this.logger.info('Question answer written to PTY stdin', { streamingId, toolUseId });
+        return true;
+    }
+    /**
+     * Send a raw stdin message to a Claude process.
+     * Used by ClaudiaService for sending messages to Claudia's session.
+     * The message should already be formatted as a JSON string.
+     */
+    sendStdinMessage(streamingId, message) {
+        const process = this.processes.get(streamingId);
+        if (!process) {
+            this.logger.warn('Cannot send stdin message: process not found', { streamingId });
+            return false;
+        }
+        this.logger.info('Sending stdin message', {
+            streamingId,
+            messageLength: message.length
+        });
+        // Write to PTY stdin with newline
+        process.write(message + '\n');
+        return true;
+    }
+}
+//# sourceMappingURL=claude-process-manager.js.map