@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/shell-executor.js

@@ -0,0 +1,1201 @@
+/**
+ * Shell command execution service using execa for cross-platform command execution,
+ * streaming output, timeout handling, and environment management.
+ */
+import { execa } from 'execa';
+import { execSync } from 'child_process';
+import { logger } from '../utils/logger.js';
+import { SHELL_COMMAND_TIMEOUT_MS } from '../constants/defaults.js';
+import { getSystemEventLogger } from './system-event-logger.js';
+import { getEventEmitter } from '../core/event-emitter.js';
+import { randomUUID } from 'crypto';
+/**
+ * Cached preferred shell to avoid repeated detection
+ */
+let cachedPreferredShell = null;
+/**
+ * Detects the preferred shell for the current platform.
+ * On Windows, prefers PowerShell over cmd.exe for better capabilities.
+ * Result is cached for performance.
+ *
+ * @returns The path or name of the preferred shell
+ */
+export function getPreferredShell() {
+    if (cachedPreferredShell !== null) {
+        return cachedPreferredShell;
+    }
+    if (process.platform === 'win32') {
+        // Check for PowerShell Core (pwsh) first - cross-platform, modern
+        try {
+            execSync('pwsh -Version', { stdio: 'pipe' });
+            cachedPreferredShell = 'pwsh';
+            logger.debug('Detected shell: pwsh (PowerShell Core)');
+            return cachedPreferredShell;
+        }
+        catch {
+            // pwsh not available
+        }
+        // Check for Windows PowerShell - always available on modern Windows
+        try {
+            execSync('powershell -Command "$PSVersionTable.PSVersion"', { stdio: 'pipe' });
+            cachedPreferredShell = 'powershell';
+            logger.debug('Detected shell: powershell (Windows PowerShell)');
+            return cachedPreferredShell;
+        }
+        catch {
+            // PowerShell not available (very rare)
+        }
+        // Fallback to cmd.exe
+        cachedPreferredShell = process.env.COMSPEC || 'cmd.exe';
+        logger.debug(`Detected shell: ${cachedPreferredShell} (fallback)`);
+    }
+    else {
+        // Unix-like systems - use SHELL env var or default to /bin/sh
+        cachedPreferredShell = process.env.SHELL || '/bin/sh';
+        logger.debug(`Detected shell: ${cachedPreferredShell}`);
+    }
+    return cachedPreferredShell;
+}
+/**
+ * Clears the cached shell detection (useful for testing)
+ */
+export function clearShellCache() {
+    cachedPreferredShell = null;
+}
+/**
+ * ShellExecutor class provides safe shell command execution with configurable
+ * allowlists, blocklists, timeout handling, and streaming output support.
+ *
+ * Features:
+ * - Cross-platform command execution using execa
+ * - Configurable command allowlist and blocklist
+ * - Timeout handling with configurable defaults
+ * - Streaming output support for real-time feedback
+ * - Sequential command execution
+ * - Command existence checking
+ */
+class ShellExecutor {
+    allowedCommands = [];
+    blockedCommands = [];
+    defaultTimeout = SHELL_COMMAND_TIMEOUT_MS;
+    backgroundProcesses = new Map();
+    /**
+     * Configures the shell executor with allowed/blocked commands and timeout settings.
+     *
+     * @param options - Configuration options
+     */
+    configure(options) {
+        if (options.allowedCommands) {
+            this.allowedCommands = options.allowedCommands;
+        }
+        if (options.blockedCommands) {
+            this.blockedCommands = options.blockedCommands;
+        }
+        if (options.defaultTimeout !== undefined) {
+            this.defaultTimeout = options.defaultTimeout;
+        }
+        logger.debug('ShellExecutor configured', {
+            allowedCommands: this.allowedCommands.length,
+            blockedCommands: this.blockedCommands.length,
+            defaultTimeout: this.defaultTimeout,
+        });
+    }
+    /**
+     * Checks if a command is allowed to be executed based on the configured
+     * allowlist and blocklist.
+     *
+     * @param command - The command string to check
+     * @returns True if the command is allowed, false otherwise
+     */
+    isCommandAllowed(command) {
+        const trimmedCommand = command.trim();
+        const baseCommand = trimmedCommand.split(/\s+/)[0];
+        // Check blocked commands first (patterns that should never be allowed)
+        for (const blocked of this.blockedCommands) {
+            // Check if the blocked pattern appears anywhere in the command
+            if (trimmedCommand.includes(blocked)) {
+                logger.warn(`Command blocked by pattern: ${blocked}`);
+                return false;
+            }
+        }
+        // If allowlist is empty, allow all non-blocked commands
+        if (this.allowedCommands.length === 0) {
+            return true;
+        }
+        // Check if the base command is in the allowlist
+        const isAllowed = this.allowedCommands.some((allowed) => {
+            // Exact match
+            if (baseCommand === allowed) {
+                return true;
+            }
+            // Match command at end of path (e.g., /usr/bin/npm matches npm)
+            if (baseCommand.endsWith(`/${allowed}`)) {
+                return true;
+            }
+            // Match npx-style commands (e.g., npx eslint)
+            if (baseCommand === 'npx' && this.allowedCommands.includes(trimmedCommand.split(/\s+/)[1])) {
+                return true;
+            }
+            return false;
+        });
+        if (!isAllowed) {
+            logger.warn(`Command not in allowlist: ${baseCommand}`);
+        }
+        return isAllowed;
+    }
+    /**
+     * Executes a shell command and returns the result.
+     * If toolCallId is provided, emits real-time status updates with the last 3 lines of output.
+     *
+     * @param command - The command to execute
+     * @param options - Execution options
+     * @returns Promise resolving to the execution result
+     */
+    async execute(command, options = {}) {
+        const startTime = Date.now();
+        const trimmedCommand = command.trim();
+        // Check if command is allowed
+        if (!this.isCommandAllowed(trimmedCommand)) {
+            logger.warn(`Command blocked: ${trimmedCommand}`);
+            return {
+                success: false,
+                stdout: '',
+                stderr: `Command not allowed: ${trimmedCommand}`,
+                exitCode: 1,
+                duration: 0,
+                timedOut: false,
+                killed: false,
+                command: trimmedCommand,
+            };
+        }
+        const cwd = options.cwd || process.cwd();
+        // If toolCallId is provided, use streaming execution with status updates
+        if (options.toolCallId) {
+            return this.executeWithStatusUpdates(trimmedCommand, options, cwd, startTime);
+        }
+        // Standard execution (no streaming status updates)
+        // Use preferred shell for consistent cross-platform behavior
+        const preferredShell = getPreferredShell();
+        const execaOptions = {
+            cwd,
+            env: { ...process.env, ...options.env },
+            timeout: options.timeout ?? this.defaultTimeout,
+            shell: options.shell === false ? false : preferredShell,
+            reject: false,
+            input: options.stdin,
+            stripFinalNewline: options.stripFinalNewline ?? true,
+            cancelSignal: options.signal,
+        };
+        try {
+            logger.debug(`Executing command: ${trimmedCommand}`, {
+                cwd: execaOptions.cwd,
+                timeout: execaOptions.timeout,
+            });
+            const result = await execa(trimmedCommand, execaOptions);
+            const duration = Date.now() - startTime;
+            const executionResult = {
+                success: result.exitCode === 0,
+                stdout: String(result.stdout || ''),
+                stderr: String(result.stderr || ''),
+                exitCode: result.exitCode ?? 1,
+                duration,
+                timedOut: result.timedOut ?? false,
+                killed: result.isTerminated ?? false,
+                command: trimmedCommand,
+            };
+            logger.debug(`Command completed: ${trimmedCommand}`, {
+                exitCode: executionResult.exitCode,
+                duration: executionResult.duration,
+                timedOut: executionResult.timedOut,
+            });
+            // Log to system event logger
+            getSystemEventLogger().logBashExecuted({
+                command: trimmedCommand,
+                cwd: execaOptions.cwd,
+                exitCode: executionResult.exitCode,
+                duration_ms: executionResult.duration,
+                stdout: executionResult.stdout,
+                stderr: executionResult.stderr,
+                timedOut: executionResult.timedOut,
+                killed: executionResult.killed,
+            });
+            return executionResult;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const execaError = error;
+            logger.error(`Command failed: ${trimmedCommand}`, {
+                error: execaError.message,
+                exitCode: execaError.exitCode,
+            });
+            const errorResult = {
+                success: false,
+                stdout: String(execaError.stdout || ''),
+                stderr: String(execaError.stderr || execaError.message || 'Unknown error'),
+                exitCode: execaError.exitCode ?? 1,
+                duration,
+                timedOut: execaError.timedOut ?? false,
+                killed: execaError.isTerminated ?? false,
+                command: trimmedCommand,
+            };
+            // Log to system event logger
+            getSystemEventLogger().logBashExecuted({
+                command: trimmedCommand,
+                cwd,
+                exitCode: errorResult.exitCode,
+                duration_ms: errorResult.duration,
+                stdout: errorResult.stdout,
+                stderr: errorResult.stderr,
+                timedOut: errorResult.timedOut,
+                killed: errorResult.killed,
+            });
+            return errorResult;
+        }
+    }
+    /**
+     * Executes a command with real-time status updates showing the last 3 lines of output.
+     * This provides visibility into long-running commands in the UI.
+     */
+    async executeWithStatusUpdates(command, options, cwd, startTime) {
+        const eventEmitter = getEventEmitter();
+        const toolCallId = options.toolCallId;
+        const lastLines = [];
+        const MAX_LINES = 5;
+        let hasMoreLines = false; // Track if we've dropped lines
+        // Buffer to accumulate incomplete lines
+        let stdoutBuffer = '';
+        let stderrBuffer = '';
+        let fullStdout = '';
+        let fullStderr = '';
+        // Emit initial status
+        eventEmitter.emit('tool-status-message', {
+            toolId: toolCallId,
+            message: 'Executing...',
+        });
+        let abortCleanup = null;
+        try {
+            logger.debug(`Executing command with status updates: ${command}`, { cwd });
+            const preferredShell = getPreferredShell();
+            const subprocess = execa(command, {
+                cwd,
+                env: { ...process.env, ...options.env },
+                timeout: options.timeout ?? this.defaultTimeout,
+                shell: options.shell === false ? false : preferredShell,
+                reject: false,
+                input: options.stdin,
+                stripFinalNewline: options.stripFinalNewline ?? true,
+                // NOTE: cancelSignal intentionally omitted — execa's cancel sends SIGTERM
+                // which on Windows doesn't force-kill the process tree. Instead, we listen
+                // for the abort event below and force-kill the entire process tree immediately.
+            });
+            // Force-kill the process tree immediately when Ctrl+X abort fires.
+            // On Windows, `taskkill /F /T /PID` kills the whole tree (child processes
+            // spawned by npm scripts, etc.) without waiting for graceful shutdown.
+            if (options.signal) {
+                const onAbort = () => {
+                    const pid = subprocess.pid;
+                    if (pid) {
+                        logger.debug(`Force-killing process tree (PID ${pid}) after user abort`);
+                        if (process.platform === 'win32') {
+                            try {
+                                execSync(`taskkill /F /T /PID ${pid}`, { stdio: 'ignore' });
+                            }
+                            catch {
+                                // Process may have already exited
+                                subprocess.kill('SIGKILL');
+                            }
+                        }
+                        else {
+                            // On Unix, kill the process group (negative PID)
+                            try {
+                                process.kill(-pid, 'SIGKILL');
+                            }
+                            catch {
+                                subprocess.kill('SIGKILL');
+                            }
+                        }
+                    }
+                    else {
+                        subprocess.kill('SIGKILL');
+                    }
+                };
+                if (options.signal.aborted) {
+                    onAbort();
+                }
+                else {
+                    options.signal.addEventListener('abort', onAbort, { once: true });
+                    abortCleanup = () => options.signal.removeEventListener('abort', onAbort);
+                }
+            }
+            // Process stdout chunks
+            if (subprocess.stdout) {
+                subprocess.stdout.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    fullStdout += text;
+                    stdoutBuffer += text;
+                    // Process complete lines
+                    const lines = stdoutBuffer.split('\n');
+                    stdoutBuffer = lines.pop() || ''; // Keep incomplete line in buffer
+                    for (const line of lines) {
+                        if (line.trim()) {
+                            lastLines.push(line.trim());
+                            if (lastLines.length > MAX_LINES) {
+                                lastLines.shift();
+                                hasMoreLines = true;
+                            }
+                        }
+                    }
+                    // Emit status update with last lines (add ... if there are more lines)
+                    if (lastLines.length > 0) {
+                        const message = hasMoreLines
+                            ? lastLines.join('\n') + '\n...'
+                            : lastLines.join('\n');
+                        eventEmitter.emit('tool-status-message', {
+                            toolId: toolCallId,
+                            message,
+                        });
+                    }
+                });
+            }
+            // Process stderr chunks
+            if (subprocess.stderr) {
+                subprocess.stderr.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    fullStderr += text;
+                    stderrBuffer += text;
+                    // Process complete lines
+                    const lines = stderrBuffer.split('\n');
+                    stderrBuffer = lines.pop() || '';
+                    for (const line of lines) {
+                        if (line.trim()) {
+                            lastLines.push(line.trim());
+                            if (lastLines.length > MAX_LINES) {
+                                lastLines.shift();
+                                hasMoreLines = true;
+                            }
+                        }
+                    }
+                    // Emit status update (add ... if there are more lines)
+                    if (lastLines.length > 0) {
+                        const message = hasMoreLines
+                            ? lastLines.join('\n') + '\n...'
+                            : lastLines.join('\n');
+                        eventEmitter.emit('tool-status-message', {
+                            toolId: toolCallId,
+                            message,
+                        });
+                    }
+                });
+            }
+            // Wait for process to complete
+            const result = await subprocess;
+            abortCleanup?.();
+            const duration = Date.now() - startTime;
+            const executionResult = {
+                success: result.exitCode === 0,
+                stdout: fullStdout || String(result.stdout || ''),
+                stderr: fullStderr || String(result.stderr || ''),
+                exitCode: result.exitCode ?? 1,
+                duration,
+                timedOut: result.timedOut ?? false,
+                killed: result.isTerminated ?? false,
+                command,
+            };
+            logger.debug(`Command completed: ${command}`, {
+                exitCode: executionResult.exitCode,
+                duration: executionResult.duration,
+                timedOut: executionResult.timedOut,
+            });
+            // Log to system event logger
+            getSystemEventLogger().logBashExecuted({
+                command,
+                cwd,
+                exitCode: executionResult.exitCode,
+                duration_ms: executionResult.duration,
+                stdout: executionResult.stdout,
+                stderr: executionResult.stderr,
+                timedOut: executionResult.timedOut,
+                killed: executionResult.killed,
+            });
+            return executionResult;
+        }
+        catch (error) {
+            abortCleanup?.();
+            const duration = Date.now() - startTime;
+            const execaError = error;
+            logger.error(`Command failed: ${command}`, {
+                error: execaError.message,
+                exitCode: execaError.exitCode,
+            });
+            const errorResult = {
+                success: false,
+                stdout: fullStdout || String(execaError.stdout || ''),
+                stderr: fullStderr || String(execaError.stderr || execaError.message || 'Unknown error'),
+                exitCode: execaError.exitCode ?? 1,
+                duration,
+                timedOut: execaError.timedOut ?? false,
+                killed: execaError.isTerminated ?? false,
+                command,
+            };
+            // Log to system event logger
+            getSystemEventLogger().logBashExecuted({
+                command,
+                cwd,
+                exitCode: errorResult.exitCode,
+                duration_ms: errorResult.duration,
+                stdout: errorResult.stdout,
+                stderr: errorResult.stderr,
+                timedOut: errorResult.timedOut,
+                killed: errorResult.killed,
+            });
+            return errorResult;
+        }
+    }
+    /**
+     * Executes a command and yields streaming output chunks.
+     * This allows for real-time output display during long-running commands.
+     *
+     * @param command - The command to execute
+     * @param options - Execution options
+     * @yields Streaming output chunks
+     */
+    async *executeStreaming(command, options = {}) {
+        const trimmedCommand = command.trim();
+        // Check if command is allowed
+        if (!this.isCommandAllowed(trimmedCommand)) {
+            yield { type: 'stderr', data: `Command not allowed: ${trimmedCommand}` };
+            yield { type: 'exit', data: 1 };
+            return;
+        }
+        const preferredShell = getPreferredShell();
+        const execaOptions = {
+            cwd: options.cwd || process.cwd(),
+            env: { ...process.env, ...options.env },
+            timeout: options.timeout ?? this.defaultTimeout,
+            shell: options.shell === false ? false : preferredShell,
+            input: options.stdin,
+            stripFinalNewline: options.stripFinalNewline ?? true,
+        };
+        try {
+            logger.debug(`Executing streaming command: ${trimmedCommand}`);
+            // For streaming, we need to handle the subprocess differently
+            // Since execa v9 uses a different API, we'll collect output and yield it
+            const subprocess = execa(trimmedCommand, {
+                ...execaOptions,
+                reject: false,
+                cancelSignal: options.signal,
+            });
+            // Wait for the process to complete
+            const result = await subprocess;
+            // Yield stdout if present
+            if (result.stdout) {
+                yield { type: 'stdout', data: String(result.stdout) };
+            }
+            // Yield stderr if present
+            if (result.stderr) {
+                yield { type: 'stderr', data: String(result.stderr) };
+            }
+            // Yield exit code
+            yield { type: 'exit', data: result.exitCode ?? 0 };
+        }
+        catch (error) {
+            const execaError = error;
+            // Yield any output that was captured
+            if (execaError.stdout) {
+                yield { type: 'stdout', data: String(execaError.stdout) };
+            }
+            // Yield error message
+            yield {
+                type: 'stderr',
+                data: String(execaError.stderr || execaError.message || 'Command execution failed'),
+            };
+            // Yield exit code
+            yield { type: 'exit', data: execaError.exitCode ?? 1 };
+        }
+    }
+    /**
+     * Executes multiple commands in sequence, stopping on first failure.
+     *
+     * @param commands - Array of commands to execute
+     * @param options - Execution options applied to all commands
+     * @returns Array of execution results (may be shorter than input if a command fails)
+     */
+    async executeSequence(commands, options = {}) {
+        const results = [];
+        for (const command of commands) {
+            const result = await this.execute(command, options);
+            results.push(result);
+            // Stop on first failure
+            if (!result.success) {
+                logger.debug(`Sequence stopped due to failure at command: ${command}`);
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Executes multiple commands in parallel.
+     *
+     * @param commands - Array of commands to execute
+     * @param options - Execution options applied to all commands
+     * @returns Array of execution results in the same order as input commands
+     */
+    async executeParallel(commands, options = {}) {
+        const promises = commands.map((command) => this.execute(command, options));
+        return Promise.all(promises);
+    }
+    /**
+     * Gets the preferred shell being used for command execution.
+     *
+     * @returns The path to the preferred shell
+     */
+    getShell() {
+        return getPreferredShell();
+    }
+    /**
+     * Checks if a command exists and is executable.
+     *
+     * @param command - The command name to check
+     * @returns True if the command exists, false otherwise
+     */
+    async commandExists(command) {
+        // Use where.exe explicitly on Windows because 'where' is aliased to Where-Object in PowerShell
+        const checkCommand = process.platform === 'win32' ? `where.exe ${command}` : `which ${command}`;
+        try {
+            const result = await this.execute(checkCommand, {
+                timeout: 5000,
+                shell: true,
+            });
+            return result.success && result.stdout.trim().length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Gets the version of a command if it supports --version flag.
+     *
+     * @param command - The command to get version for
+     * @returns The version string or null if not available
+     */
+    async getCommandVersion(command) {
+        try {
+            const result = await this.execute(`${command} --version`, {
+                timeout: 5000,
+            });
+            if (result.success && result.stdout) {
+                // Extract first line which usually contains version
+                const firstLine = result.stdout.split('\n')[0].trim();
+                return firstLine || null;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Validates a command string for basic safety checks.
+     * This is a supplementary check to the allowlist/blocklist system.
+     *
+     * @param command - The command to validate
+     * @returns Object with validation result and optional error message
+     */
+    validateCommand(command) {
+        const trimmed = command.trim();
+        // Check for empty command
+        if (!trimmed) {
+            return { valid: false, error: 'Command cannot be empty' };
+        }
+        // Check for command injection patterns
+        const dangerousPatterns = [
+            /;\s*rm\s+-rf/i,
+            /&&\s*rm\s+-rf/i,
+            /\|\s*rm\s+-rf/i,
+            /`.*`/, // Backtick command substitution
+            /\$\(.*\)/, // $() command substitution in dangerous context
+        ];
+        for (const pattern of dangerousPatterns) {
+            if (pattern.test(trimmed)) {
+                return {
+                    valid: false,
+                    error: 'Command contains potentially dangerous patterns',
+                };
+            }
+        }
+        // Check against blocklist
+        if (!this.isCommandAllowed(trimmed)) {
+            return { valid: false, error: 'Command is not allowed' };
+        }
+        return { valid: true };
+    }
+    /**
+     * Creates a safe command string by escaping special characters.
+     * Note: This is a basic implementation; for complex cases, use proper escaping libraries.
+     *
+     * @param parts - Command parts to join safely
+     * @returns Escaped command string
+     */
+    escapeCommand(parts) {
+        return parts
+            .map((part) => {
+            // If part contains spaces or special characters, quote it
+            if (/[\s"'`$\\]/.test(part)) {
+                // Escape existing quotes and wrap in quotes
+                return `"${part.replace(/"/g, '\\"')}"`;
+            }
+            return part;
+        })
+            .join(' ');
+    }
+    // ============================================================
+    // VERIFICATION MODE EXECUTION
+    // ============================================================
+    /**
+     * Executes a command and monitors output for success/error patterns.
+     * Useful for verifying that long-running commands like dev servers start correctly.
+     * The process is automatically terminated after verification or timeout.
+     *
+     * @param command - The command to execute
+     * @param options - Verification options including success/error patterns
+     * @returns Promise resolving to the verification result
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.executeAndVerify('npm start', {
+     *   successPatterns: ['Listening on port', 'Server started'],
+     *   errorPatterns: ['Error:', 'EADDRINUSE'],
+     *   verificationTimeout: 15000,
+     * });
+     * if (result.verified) {
+     *   console.log('Server started successfully!');
+     * }
+     * ```
+     */
+    async executeAndVerify(command, options = {}) {
+        const startTime = Date.now();
+        const trimmedCommand = command.trim();
+        // Check if command is allowed
+        if (!this.isCommandAllowed(trimmedCommand)) {
+            logger.warn(`Command blocked: ${trimmedCommand}`);
+            return {
+                success: false,
+                stdout: '',
+                stderr: `Command not allowed: ${trimmedCommand}`,
+                exitCode: 1,
+                duration: 0,
+                timedOut: false,
+                killed: false,
+                command: trimmedCommand,
+                verified: false,
+                terminatedAfterVerification: false,
+            };
+        }
+        const cwd = options.cwd || process.cwd();
+        const verificationTimeout = options.verificationTimeout ?? 15000;
+        const eventEmitter = getEventEmitter();
+        const toolCallId = options.toolCallId;
+        // Default patterns for common dev servers
+        const successPatterns = (options.successPatterns ?? [
+            'listening on',
+            'server started',
+            'server running',
+            'ready on',
+            'started server',
+            'compiled successfully',
+            'webpack compiled',
+            'dev server running',
+            'localhost:',
+            '127.0.0.1:',
+        ]).map(p => new RegExp(p, 'i'));
+        const errorPatterns = (options.errorPatterns ?? [
+            'error:',
+            'eaddrinuse',
+            'eacces',
+            'enoent',
+            'failed to',
+            'cannot find',
+            'module not found',
+            'command not found',
+            'npm err!',
+        ]).map(p => new RegExp(p, 'i'));
+        let fullStdout = '';
+        let fullStderr = '';
+        let verified = false;
+        let matchedPattern;
+        let isError = false;
+        const lastLines = [];
+        const MAX_LINES = 5;
+        let hasMoreLines = false;
+        // Emit initial status
+        if (toolCallId) {
+            eventEmitter.emit('tool-status-message', {
+                toolId: toolCallId,
+                message: 'Starting and verifying...',
+            });
+        }
+        return new Promise((resolve) => {
+            logger.debug(`Executing with verification: ${trimmedCommand}`, { cwd, verificationTimeout });
+            const preferredShell = getPreferredShell();
+            const subprocess = execa(trimmedCommand, {
+                cwd,
+                env: { ...process.env, ...options.env },
+                timeout: 0, // No timeout - we handle it ourselves
+                shell: options.shell === false ? false : preferredShell,
+                reject: false,
+                stripFinalNewline: options.stripFinalNewline ?? true,
+                cancelSignal: options.signal,
+            });
+            let resolved = false;
+            const finishVerification = (success, pattern, error = false) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                verified = success && !error;
+                matchedPattern = pattern;
+                isError = error;
+                // Kill the process gracefully
+                try {
+                    subprocess.kill('SIGTERM');
+                    // Give it a moment, then force kill if needed
+                    setTimeout(() => {
+                        try {
+                            subprocess.kill('SIGKILL');
+                        }
+                        catch {
+                            // Process may already be dead
+                        }
+                    }, 1000);
+                }
+                catch {
+                    // Process may already be dead
+                }
+                const duration = Date.now() - startTime;
+                const result = {
+                    success: verified,
+                    stdout: fullStdout,
+                    stderr: fullStderr,
+                    exitCode: verified ? 0 : 1,
+                    duration,
+                    timedOut: !verified && !isError,
+                    killed: true,
+                    command: trimmedCommand,
+                    verified,
+                    matchedPattern,
+                    terminatedAfterVerification: true,
+                };
+                logger.debug(`Verification complete: ${trimmedCommand}`, {
+                    verified,
+                    matchedPattern,
+                    duration,
+                });
+                // Log to system event logger
+                getSystemEventLogger().logBashExecuted({
+                    command: trimmedCommand,
+                    cwd,
+                    exitCode: result.exitCode,
+                    duration_ms: duration,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    timedOut: result.timedOut,
+                    killed: result.killed,
+                });
+                resolve(result);
+            };
+            // Set up verification timeout
+            const timeoutId = setTimeout(() => {
+                logger.debug(`Verification timeout reached for: ${trimmedCommand}`);
+                if (toolCallId) {
+                    eventEmitter.emit('tool-status-message', {
+                        toolId: toolCallId,
+                        message: 'Verification timeout - terminating process',
+                    });
+                }
+                finishVerification(false, undefined, false);
+            }, verificationTimeout);
+            const checkOutput = (text, _source) => {
+                // Check for success patterns
+                for (const pattern of successPatterns) {
+                    if (pattern.test(text)) {
+                        logger.debug(`Success pattern matched: ${pattern.source}`);
+                        clearTimeout(timeoutId);
+                        if (toolCallId) {
+                            eventEmitter.emit('tool-status-message', {
+                                toolId: toolCallId,
+                                message: `✓ Verified: ${pattern.source}`,
+                            });
+                        }
+                        finishVerification(true, pattern.source, false);
+                        return;
+                    }
+                }
+                // Check for error patterns
+                for (const pattern of errorPatterns) {
+                    if (pattern.test(text)) {
+                        logger.debug(`Error pattern matched: ${pattern.source}`);
+                        clearTimeout(timeoutId);
+                        if (toolCallId) {
+                            eventEmitter.emit('tool-status-message', {
+                                toolId: toolCallId,
+                                message: `✗ Error: ${pattern.source}`,
+                            });
+                        }
+                        finishVerification(false, pattern.source, true);
+                        return;
+                    }
+                }
+            };
+            // Process stdout
+            if (subprocess.stdout) {
+                subprocess.stdout.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    fullStdout += text;
+                    // Update status display
+                    const lines = text.split('\n').filter(l => l.trim());
+                    for (const line of lines) {
+                        lastLines.push(line.trim());
+                        if (lastLines.length > MAX_LINES) {
+                            lastLines.shift();
+                            hasMoreLines = true;
+                        }
+                    }
+                    if (toolCallId && lastLines.length > 0) {
+                        const message = hasMoreLines
+                            ? lastLines.join('\n') + '\n...'
+                            : lastLines.join('\n');
+                        eventEmitter.emit('tool-status-message', {
+                            toolId: toolCallId,
+                            message,
+                        });
+                    }
+                    checkOutput(text, 'stdout');
+                });
+            }
+            // Process stderr
+            if (subprocess.stderr) {
+                subprocess.stderr.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    fullStderr += text;
+                    // Update status display
+                    const lines = text.split('\n').filter(l => l.trim());
+                    for (const line of lines) {
+                        lastLines.push(line.trim());
+                        if (lastLines.length > MAX_LINES) {
+                            lastLines.shift();
+                            hasMoreLines = true;
+                        }
+                    }
+                    if (toolCallId && lastLines.length > 0) {
+                        const message = hasMoreLines
+                            ? lastLines.join('\n') + '\n...'
+                            : lastLines.join('\n');
+                        eventEmitter.emit('tool-status-message', {
+                            toolId: toolCallId,
+                            message,
+                        });
+                    }
+                    checkOutput(text, 'stderr');
+                });
+            }
+            // Handle process exit (in case it exits on its own before verification)
+            subprocess.then((result) => {
+                clearTimeout(timeoutId);
+                if (!resolved) {
+                    const exitSuccess = result.exitCode === 0;
+                    fullStdout = String(result.stdout || fullStdout);
+                    fullStderr = String(result.stderr || fullStderr);
+                    const duration = Date.now() - startTime;
+                    resolve({
+                        success: exitSuccess,
+                        stdout: fullStdout,
+                        stderr: fullStderr,
+                        exitCode: result.exitCode ?? 1,
+                        duration,
+                        timedOut: false,
+                        killed: false,
+                        command: trimmedCommand,
+                        verified: exitSuccess,
+                        matchedPattern: exitSuccess ? 'process exited successfully' : undefined,
+                        terminatedAfterVerification: false,
+                    });
+                }
+            }).catch((error) => {
+                clearTimeout(timeoutId);
+                if (!resolved) {
+                    fullStdout = String(error.stdout || fullStdout);
+                    fullStderr = String(error.stderr || fullStderr);
+                    const duration = Date.now() - startTime;
+                    resolve({
+                        success: false,
+                        stdout: fullStdout,
+                        stderr: fullStderr,
+                        exitCode: error.exitCode ?? 1,
+                        duration,
+                        timedOut: error.timedOut ?? false,
+                        killed: error.isTerminated ?? false,
+                        command: trimmedCommand,
+                        verified: false,
+                        matchedPattern: undefined,
+                        terminatedAfterVerification: false,
+                    });
+                }
+            });
+        });
+    }
+    // ============================================================
+    // BACKGROUND PROCESS MANAGEMENT
+    // ============================================================
+    /**
+     * Executes a command in the background and returns a process ID for tracking.
+     * The process will continue running and can be monitored or killed later.
+     *
+     * @param command - The command to execute
+     * @param options - Execution options
+     * @returns Object containing the process ID and initial status
+     */
+    executeBackground(command, options = {}) {
+        const trimmedCommand = command.trim();
+        // Check if command is allowed
+        if (!this.isCommandAllowed(trimmedCommand)) {
+            logger.warn(`Background command blocked: ${trimmedCommand}`);
+            return {
+                id: '',
+                command: trimmedCommand,
+                status: 'blocked',
+            };
+        }
+        const id = randomUUID().substring(0, 8);
+        const cwd = options.cwd || process.cwd();
+        const preferredShell = getPreferredShell();
+        const execaOptions = {
+            cwd,
+            env: { ...process.env, ...options.env },
+            timeout: options.timeout ?? 0, // No timeout for background processes by default
+            shell: options.shell === false ? false : preferredShell,
+            reject: false,
+            input: options.stdin,
+            stripFinalNewline: options.stripFinalNewline ?? true,
+        };
+        logger.debug(`Starting background command [${id}]: ${trimmedCommand}`);
+        const subprocess = execa(trimmedCommand, execaOptions);
+        const backgroundProcess = {
+            id,
+            command: trimmedCommand,
+            cwd,
+            startedAt: new Date(),
+            status: 'running',
+            stdout: '',
+            stderr: '',
+            process: subprocess,
+        };
+        this.backgroundProcesses.set(id, backgroundProcess);
+        // Handle process completion
+        subprocess.then((result) => {
+            const proc = this.backgroundProcesses.get(id);
+            if (proc && proc.status === 'running') {
+                proc.status = result.exitCode === 0 ? 'completed' : 'failed';
+                proc.exitCode = result.exitCode ?? 1;
+                proc.stdout = String(result.stdout || '');
+                proc.stderr = String(result.stderr || '');
+                logger.debug(`Background command [${id}] completed with exit code ${proc.exitCode}`);
+            }
+        }).catch((error) => {
+            const proc = this.backgroundProcesses.get(id);
+            if (proc && proc.status === 'running') {
+                proc.status = 'failed';
+                proc.exitCode = error.exitCode ?? 1;
+                proc.stdout = String(error.stdout || '');
+                proc.stderr = String(error.stderr || error.message || 'Command failed');
+                logger.debug(`Background command [${id}] failed: ${error.message}`);
+            }
+        });
+        return {
+            id,
+            command: trimmedCommand,
+            status: 'running',
+        };
+    }
+    /**
+     * Kills a background process by its ID.
+     *
+     * @param id - The process ID to kill
+     * @param signal - The signal to send (default: SIGTERM)
+     * @returns Object with success status and details
+     */
+    killProcess(id, signal = 'SIGTERM') {
+        const proc = this.backgroundProcesses.get(id);
+        if (!proc) {
+            return {
+                success: false,
+                message: `No process found with ID: ${id}`,
+            };
+        }
+        if (proc.status !== 'running') {
+            return {
+                success: false,
+                message: `Process ${id} is not running (status: ${proc.status})`,
+                process: { ...proc, process: undefined },
+            };
+        }
+        try {
+            // Kill the process
+            proc.process.kill(signal);
+            proc.status = 'killed';
+            logger.info(`Killed background process [${id}]: ${proc.command}`);
+            // Log to system event logger
+            getSystemEventLogger().logBashExecuted({
+                command: proc.command,
+                cwd: proc.cwd,
+                exitCode: -1,
+                duration_ms: Date.now() - proc.startedAt.getTime(),
+                stdout: proc.stdout,
+                stderr: proc.stderr,
+                timedOut: false,
+                killed: true,
+            });
+            return {
+                success: true,
+                message: `Process ${id} killed successfully`,
+                process: { ...proc, process: undefined },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error(`Failed to kill process [${id}]: ${errorMessage}`);
+            return {
+                success: false,
+                message: `Failed to kill process: ${errorMessage}`,
+                process: { ...proc, process: undefined },
+            };
+        }
+    }
+    /**
+     * Gets the status of a background process.
+     *
+     * @param id - The process ID to check
+     * @returns The process info or null if not found
+     */
+    getProcessStatus(id) {
+        const proc = this.backgroundProcesses.get(id);
+        if (!proc) {
+            return null;
+        }
+        // Return without the process object (not serializable)
+        const { process: _process, ...rest } = proc;
+        return rest;
+    }
+    /**
+     * Lists all tracked background processes.
+     *
+     * @param filter - Optional filter by status
+     * @returns Array of process info objects
+     */
+    listProcesses(filter) {
+        const processes = [];
+        for (const proc of this.backgroundProcesses.values()) {
+            if (!filter || proc.status === filter) {
+                const { process: _process, ...rest } = proc;
+                processes.push(rest);
+            }
+        }
+        return processes;
+    }
+    /**
+     * Cleans up completed/failed/killed processes from tracking.
+     *
+     * @param olderThan - Optional: only clean processes older than this many milliseconds
+     * @returns Number of processes cleaned up
+     */
+    cleanupProcesses(olderThan) {
+        let cleaned = 0;
+        const now = Date.now();
+        for (const [id, proc] of this.backgroundProcesses) {
+            if (proc.status !== 'running') {
+                if (!olderThan || (now - proc.startedAt.getTime() > olderThan)) {
+                    this.backgroundProcesses.delete(id);
+                    cleaned++;
+                }
+            }
+        }
+        if (cleaned > 0) {
+            logger.debug(`Cleaned up ${cleaned} background processes`);
+        }
+        return cleaned;
+    }
+    /**
+     * Kills all running background processes.
+     *
+     * @param signal - The signal to send (default: SIGTERM)
+     * @returns Number of processes killed
+     */
+    killAllProcesses(signal = 'SIGTERM') {
+        let killed = 0;
+        for (const [id, proc] of this.backgroundProcesses) {
+            if (proc.status === 'running') {
+                const result = this.killProcess(id, signal);
+                if (result.success) {
+                    killed++;
+                }
+            }
+        }
+        if (killed > 0) {
+            logger.info(`Killed ${killed} background processes`);
+        }
+        return killed;
+    }
+    /**
+     * Gets the current configuration of the executor.
+     *
+     * @returns Current configuration
+     */
+    getConfig() {
+        return {
+            allowedCommands: [...this.allowedCommands],
+            blockedCommands: [...this.blockedCommands],
+            defaultTimeout: this.defaultTimeout,
+        };
+    }
+    /**
+     * Resets the executor configuration to defaults.
+     * Also kills all running background processes.
+     */
+    reset() {
+        // Kill any running background processes
+        this.killAllProcesses();
+        this.backgroundProcesses.clear();
+        this.allowedCommands = [];
+        this.blockedCommands = [];
+        this.defaultTimeout = SHELL_COMMAND_TIMEOUT_MS;
+        logger.debug('ShellExecutor reset to defaults');
+    }
+}
+// Singleton instance
+let shellExecutorInstance = null;
+/**
+ * Gets the singleton ShellExecutor instance.
+ * Creates the instance on first call.
+ *
+ * @returns The ShellExecutor singleton instance
+ */
+export function getShellExecutor() {
+    if (!shellExecutorInstance) {
+        shellExecutorInstance = new ShellExecutor();
+    }
+    return shellExecutorInstance;
+}
+/**
+ * Creates a new ShellExecutor instance with optional configuration.
+ * Use this when you need a separate instance from the singleton.
+ *
+ * @param config - Optional configuration options
+ * @returns A new ShellExecutor instance
+ */
+export function createShellExecutor(config) {
+    const executor = new ShellExecutor();
+    if (config) {
+        executor.configure(config);
+    }
+    return executor;
+}
+export { ShellExecutor };
+//# sourceMappingURL=shell-executor.js.map