command-stream 0.3.2 → 0.4.0

package/src/$.mjs

@@ -5,9 +5,7 @@
 // 3. EventEmitter: $`command`.on('data', chunk => ...).on('end', result => ...)
 // 4. Stream access: $`command`.stdout, $`command`.stderr
 
-import { createRequire } from 'module';
 import cp from 'child_process';
-import fs from 'fs';
 import path from 'path';
 
 const isBun = typeof globalThis.Bun !== 'undefined';
@@ -54,8 +52,203 @@ function isInteractiveCommand(command) {
 let parentStreamsMonitored = false;
 const activeProcessRunners = new Set();
 
+// Track if SIGINT handler has been installed
+let sigintHandlerInstalled = false;
+let sigintHandler = null; // Store reference to remove it later
+
+function installSignalHandlers() {
+  // Check if our handler is actually installed (not just the flag)
+  // This is more robust against test cleanup that manually removes listeners
+  const currentListeners = process.listeners('SIGINT');
+  const hasOurHandler = currentListeners.some(l => {
+    const str = l.toString();
+    return str.includes('activeProcessRunners') && 
+           str.includes('ProcessRunner') && 
+           str.includes('activeChildren');
+  });
+  
+  if (sigintHandlerInstalled && hasOurHandler) {
+    trace('SignalHandler', () => 'SIGINT handler already installed, skipping');
+    return;
+  }
+  
+  // Reset flag if handler was removed externally
+  if (sigintHandlerInstalled && !hasOurHandler) {
+    trace('SignalHandler', () => 'SIGINT handler flag was set but handler missing, resetting');
+    sigintHandlerInstalled = false;
+    sigintHandler = null;
+  }
+  
+  trace('SignalHandler', () => `Installing SIGINT handler | ${JSON.stringify({ activeRunners: activeProcessRunners.size })}`);
+  sigintHandlerInstalled = true;
+  
+  // Forward SIGINT to all active child processes
+  // The parent process continues running - it's up to the parent to decide what to do
+  sigintHandler = () => {
+    // Check for other handlers immediately at the start, before doing any processing
+    const currentListeners = process.listeners('SIGINT');
+    const hasOtherHandlers = currentListeners.length > 1;
+    
+    trace('ProcessRunner', () => `SIGINT handler triggered - checking active processes`);
+    
+    // Count active processes (both child processes and virtual commands)  
+    const activeChildren = [];
+    for (const runner of activeProcessRunners) {
+      if (!runner.finished) {
+        // Real child process
+        if (runner.child && runner.child.pid) {
+          activeChildren.push(runner);
+          trace('ProcessRunner', () => `Found active child: PID ${runner.child.pid}, command: ${runner.spec?.command || 'unknown'}`);
+        }
+        // Virtual command (no child process but still active)
+        else if (!runner.child) {
+          activeChildren.push(runner);
+          trace('ProcessRunner', () => `Found active virtual command: ${runner.spec?.command || 'unknown'}`);
+        }
+      }
+    }
+    
+    trace('ProcessRunner', () => `Parent received SIGINT | ${JSON.stringify({
+      activeChildrenCount: activeChildren.length,
+      hasOtherHandlers,
+      platform: process.platform,
+      pid: process.pid,
+      ppid: process.ppid,
+      activeCommands: activeChildren.map(r => ({
+        hasChild: !!r.child,
+        childPid: r.child?.pid,
+        hasVirtualGenerator: !!r._virtualGenerator,
+        finished: r.finished,
+        command: r.spec?.command?.slice(0, 30)
+      }))
+    }, null, 2)}`);
+    
+    // Only handle SIGINT if we have active child processes
+    // Otherwise, let other handlers or default behavior handle it
+    if (activeChildren.length === 0) {
+      trace('ProcessRunner', () => `No active children - skipping SIGINT forwarding, letting other handlers handle it`);
+      return; // Let other handlers or default behavior handle it
+    }
+    
+    trace('ProcessRunner', () => `Beginning SIGINT forwarding to ${activeChildren.length} active processes`);
+    
+    // Forward signal to all active processes (child processes and virtual commands)
+    for (const runner of activeChildren) {
+      try {
+        if (runner.child && runner.child.pid) {
+          // Real child process - send SIGINT to it
+          trace('ProcessRunner', () => `Sending SIGINT to child process | ${JSON.stringify({
+            pid: runner.child.pid,
+            killed: runner.child.killed,
+            runtime: isBun ? 'Bun' : 'Node.js',
+            command: runner.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+          
+          if (isBun) {
+            runner.child.kill('SIGINT');
+            trace('ProcessRunner', () => `Bun: SIGINT sent to PID ${runner.child.pid}`);
+          } else {
+            // Send to process group if detached, otherwise to process directly
+            try {
+              process.kill(-runner.child.pid, 'SIGINT');
+              trace('ProcessRunner', () => `Node.js: SIGINT sent to process group -${runner.child.pid}`);
+            } catch (err) {
+              trace('ProcessRunner', () => `Node.js: Process group kill failed, trying direct: ${err.message}`);
+              process.kill(runner.child.pid, 'SIGINT');
+              trace('ProcessRunner', () => `Node.js: SIGINT sent directly to PID ${runner.child.pid}`);
+            }
+          }
+        } else {
+          // Virtual command - cancel it using the runner's kill method
+          trace('ProcessRunner', () => `Cancelling virtual command | ${JSON.stringify({
+            hasChild: !!runner.child,
+            hasVirtualGenerator: !!runner._virtualGenerator,
+            finished: runner.finished,
+            cancelled: runner._cancelled,
+            command: runner.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+          runner.kill('SIGINT');
+          trace('ProcessRunner', () => `Virtual command kill() called`);
+        }
+      } catch (err) {
+        trace('ProcessRunner', () => `Error in SIGINT handler for runner | ${JSON.stringify({
+          error: err.message,
+          stack: err.stack?.slice(0, 300),
+          hasPid: !!(runner.child && runner.child.pid),
+          pid: runner.child?.pid,
+          command: runner.spec?.command?.slice(0, 50)
+        }, null, 2)}`);
+      }
+    }
+    
+    // We've forwarded SIGINT to all active processes/commands
+    // Use the hasOtherHandlers flag we calculated at the start (before any processing)
+    trace('ProcessRunner', () => `SIGINT forwarded to ${activeChildren.length} active processes, other handlers: ${hasOtherHandlers}`);
+    
+    if (!hasOtherHandlers) {
+      // No other handlers - we should exit like a proper shell
+      trace('ProcessRunner', () => `No other SIGINT handlers, exiting with code 130`);
+      // Ensure stdout/stderr are flushed before exiting
+      if (process.stdout && typeof process.stdout.write === 'function') {
+        process.stdout.write('', () => {
+          process.exit(130); // 128 + 2 (SIGINT)
+        });
+      } else {
+        process.exit(130); // 128 + 2 (SIGINT)
+      }
+    } else {
+      // Other handlers exist - let them handle the exit completely
+      // Do NOT call process.exit() ourselves when other handlers are present
+      trace('ProcessRunner', () => `Other SIGINT handlers present, letting them handle the exit completely`);
+    }
+  };
+  
+  process.on('SIGINT', sigintHandler);
+}
+
+function uninstallSignalHandlers() {
+  if (!sigintHandlerInstalled || !sigintHandler) {
+    trace('SignalHandler', () => 'SIGINT handler not installed or missing, skipping removal');
+    return;
+  }
+  
+  trace('SignalHandler', () => `Removing SIGINT handler | ${JSON.stringify({ activeRunners: activeProcessRunners.size })}`);
+  process.removeListener('SIGINT', sigintHandler);
+  sigintHandlerInstalled = false;
+  sigintHandler = null;
+}
+
+// Force cleanup of all command-stream SIGINT handlers and state - for testing
+function forceCleanupAll() {
+  // Remove all command-stream SIGINT handlers
+  const sigintListeners = process.listeners('SIGINT');
+  const commandStreamListeners = sigintListeners.filter(l => {
+    const str = l.toString();
+    return str.includes('activeProcessRunners') || 
+           str.includes('ProcessRunner') ||
+           str.includes('activeChildren');
+  });
+  
+  commandStreamListeners.forEach(listener => {
+    process.removeListener('SIGINT', listener);
+  });
+  
+  // Clear activeProcessRunners
+  activeProcessRunners.clear();
+  
+  // Reset flags
+  sigintHandlerInstalled = false;
+  sigintHandler = null;
+  
+  trace('SignalHandler', () => `Force cleanup completed - removed ${commandStreamListeners.length} handlers`);
+}
+
 function monitorParentStreams() {
-  if (parentStreamsMonitored) return;
+  if (parentStreamsMonitored) {
+    trace('StreamMonitor', () => 'Parent streams already monitored, skipping');
+    return;
+  }
+  trace('StreamMonitor', () => 'Setting up parent stream monitoring');
   parentStreamsMonitored = true;
 
   const checkParentStream = (stream, name) => {
@@ -279,78 +472,6 @@ const StreamUtils = {
   }
 };
 
-// Virtual command utility functions for consistent behavior and error handling
-const VirtualUtils = {
-  /**
-   * Create standardized error response for missing operands
-   */
-  missingOperandError(commandName, customMessage = null) {
-    const message = customMessage || `${commandName}: missing operand`;
-    return { stderr: message, code: 1 };
-  },
-
-  /**
-   * Create standardized error response for invalid arguments
-   */
-  invalidArgumentError(commandName, message) {
-    return { stderr: `${commandName}: ${message}`, code: 1 };
-  },
-
-  /**
-   * Create standardized success response
-   */
-  success(stdout = '', code = 0) {
-    return { stdout, stderr: '', code };
-  },
-
-  /**
-   * Create standardized error response
-   */
-  error(stderr = '', code = 1) {
-    return { stdout: '', stderr, code };
-  },
-
-  /**
-   * Validate that command has required number of arguments
-   */
-  validateArgs(args, minCount, commandName) {
-    if (args.length < minCount) {
-      if (minCount === 1) {
-        return this.missingOperandError(commandName);
-      } else {
-        return this.invalidArgumentError(commandName, `requires at least ${minCount} arguments`);
-      }
-    }
-    return null; // No error
-  },
-
-  /**
-   * Resolve file path with optional cwd parameter
-   */
-  resolvePath(filePath, cwd = null) {
-    const basePath = cwd || process.cwd();
-    return path.isAbsolute(filePath) ? filePath : path.resolve(basePath, filePath);
-  },
-
-  /**
-   * Safe file system operation wrapper
-   */
-  async safeFsOperation(operation, errorPrefix) {
-    try {
-      return await operation();
-    } catch (error) {
-      return this.error(`${errorPrefix}: ${error.message}`);
-    }
-  },
-
-  /**
-   * Create async wrapper for Promise-based operations
-   */
-  createAsyncWrapper(promiseFactory) {
-    return new Promise(promiseFactory);
-  }
-};
-
 let globalShellSettings = {
   errexit: false,    // set -e equivalent: exit on error
   verbose: false,    // set -v equivalent: print commands
@@ -394,6 +515,11 @@ class StreamEmitter {
 
   emit(event, ...args) {
     const eventListeners = this.listeners.get(event);
+    trace('StreamEmitter', () => `Emitting event | ${JSON.stringify({ 
+      event, 
+      hasListeners: !!eventListeners,
+      listenerCount: eventListeners?.length || 0 
+    })}`);
     if (eventListeners) {
       for (const listener of eventListeners) {
         listener(...args);
@@ -498,20 +624,80 @@ class ProcessRunner extends StreamEmitter {
     this._mode = null; // 'async' or 'sync'
 
     this._cancelled = false;
+    this._cancellationSignal = null; // Track which signal caused cancellation
     this._virtualGenerator = null;
     this._abortController = new AbortController();
 
     activeProcessRunners.add(this);
+    
+    // Ensure parent stream monitoring is set up for all ProcessRunners
+    monitorParentStreams();
+    
+    trace('ProcessRunner', () => `Added to activeProcessRunners | ${JSON.stringify({ 
+      command: this.spec?.command || 'unknown',
+      totalActive: activeProcessRunners.size 
+    }, null, 2)}`);
+    installSignalHandlers();
 
-    // Track finished state changes to trigger cleanup
-    this._finished = false;
+    this.finished = false;
   }
 
-  get finished() {
-    return this._finished;
+  // Stream property getters for child process streams (null for virtual commands)
+  get stdout() {
+    return this.child ? this.child.stdout : null;
+  }
+
+  get stderr() {
+    return this.child ? this.child.stderr : null;
+  }
+
+  get stdin() {
+    return this.child ? this.child.stdin : null;
+  }
+
+  // Centralized method to properly finish a process with correct event emission order
+  finish(result) {
+    trace('ProcessRunner', () => `finish() called | ${JSON.stringify({
+      alreadyFinished: this.finished,
+      resultCode: result?.code,
+      hasStdout: !!result?.stdout,
+      hasStderr: !!result?.stderr,
+      command: this.spec?.command?.slice(0, 50)
+    }, null, 2)}`);
+    
+    // Make finish() idempotent - safe to call multiple times
+    if (this.finished) {
+      trace('ProcessRunner', () => `Already finished, returning existing result`);
+      return this.result || result;
+    }
+
+    // Store result
+    this.result = result;
+    trace('ProcessRunner', () => `Result stored, about to emit events`);
+
+    // Emit completion events BEFORE setting finished to prevent _cleanup() from clearing listeners
+    this.emit('end', result);
+    trace('ProcessRunner', () => `'end' event emitted`);
+    this.emit('exit', result.code);
+    trace('ProcessRunner', () => `'exit' event emitted with code ${result.code}`);
+
+    // Set finished after events are emitted
+    this.finished = true;
+    trace('ProcessRunner', () => `Marked as finished, calling cleanup`);
+
+    // Trigger cleanup now that process is finished
+    this._cleanup();
+    trace('ProcessRunner', () => `Cleanup completed`);
+
+    return result;
   }
 
   _emitProcessedData(type, buf) {
+    // Don't emit data if we've been cancelled
+    if (this._cancelled) {
+      trace('ProcessRunner', () => 'Skipping data emission - process cancelled');
+      return;
+    }
     const processedBuf = processOutput(buf, this.options.ansi);
     this.emit(type, processedBuf);
     this.emit('data', { type, data: processedBuf });
@@ -531,6 +717,36 @@ class ProcessRunner extends StreamEmitter {
 
       // Forward stdin data to child process
       const onData = (chunk) => {
+        // Check for CTRL+C (ASCII code 3)
+        if (chunk[0] === 3) {
+          trace('ProcessRunner', () => 'CTRL+C detected, sending SIGINT to child process');
+          // Send SIGINT to the child process
+          if (this.child && this.child.pid) {
+            try {
+              if (isBun) {
+                this.child.kill('SIGINT');
+              } else {
+                // In Node.js, send SIGINT to the process group if detached
+                // or to the process directly if not
+                if (this.child.pid > 0) {
+                  try {
+                    // Try process group first if detached
+                    process.kill(-this.child.pid, 'SIGINT');
+                  } catch (err) {
+                    // Fall back to direct process
+                    process.kill(this.child.pid, 'SIGINT');
+                  }
+                }
+              }
+            } catch (err) {
+              trace('ProcessRunner', () => `Error sending SIGINT: ${err.message}`);
+            }
+          }
+          // Don't forward CTRL+C to stdin, just handle the signal
+          return;
+        }
+        
+        // Forward other input to child stdin
         if (this.child.stdin) {
           if (isBun && this.child.stdin.write) {
             this.child.stdin.write(chunk);
@@ -564,17 +780,15 @@ class ProcessRunner extends StreamEmitter {
     }
   }
 
-  set finished(value) {
-    if (value === true && this._finished === false) {
-      this._finished = true;
-      this._cleanup(); // Trigger cleanup when process finishes
-    } else {
-      this._finished = value;
-    }
-  }
 
   _handleParentStreamClosure() {
-    if (this.finished || this._cancelled) return;
+    if (this.finished || this._cancelled) {
+      trace('ProcessRunner', () => `Parent stream closure ignored | ${JSON.stringify({
+        finished: this.finished,
+        cancelled: this._cancelled
+      })}`);
+      return;
+    }
 
     trace('ProcessRunner', () => `Handling parent stream closure | ${JSON.stringify({
       started: this.started,
@@ -614,11 +828,111 @@ class ProcessRunner extends StreamEmitter {
       }
     }
 
-    activeProcessRunners.delete(this);
+    this._cleanup();
   }
 
   _cleanup() {
+    trace('ProcessRunner', () => `_cleanup() called | ${JSON.stringify({
+      wasActiveBeforeCleanup: activeProcessRunners.has(this),
+      totalActiveBefore: activeProcessRunners.size,
+      finished: this.finished,
+      hasChild: !!this.child,
+      command: this.spec?.command?.slice(0, 50)
+    }, null, 2)}`);
+    
+    const wasActive = activeProcessRunners.has(this);
     activeProcessRunners.delete(this);
+    
+    if (wasActive) {
+      trace('ProcessRunner', () => `Removed from activeProcessRunners | ${JSON.stringify({ 
+        command: this.spec?.command || 'unknown',
+        totalActiveAfter: activeProcessRunners.size,
+        remainingCommands: Array.from(activeProcessRunners).map(r => r.spec?.command?.slice(0, 30))
+      }, null, 2)}`);
+    } else {
+      trace('ProcessRunner', () => `Was not in activeProcessRunners (already cleaned up)`);
+    }
+    
+    // If this is a pipeline runner, also clean up the source and destination
+    if (this.spec?.mode === 'pipeline') {
+      trace('ProcessRunner', () => 'Cleaning up pipeline components');
+      if (this.spec.source && typeof this.spec.source._cleanup === 'function') {
+        this.spec.source._cleanup();
+      }
+      if (this.spec.destination && typeof this.spec.destination._cleanup === 'function') {
+        this.spec.destination._cleanup();
+      }
+    }
+    
+    // If no more active ProcessRunners, remove the SIGINT handler
+    if (activeProcessRunners.size === 0) {
+      uninstallSignalHandlers();
+    }
+    
+    // Clean up event listeners from StreamEmitter
+    if (this.listeners) {
+      this.listeners.clear();
+    }
+    
+    // Clean up abort controller
+    if (this._abortController) {
+      trace('ProcessRunner', () => `Cleaning up abort controller during cleanup | ${JSON.stringify({
+        wasAborted: this._abortController?.signal?.aborted
+      }, null, 2)}`);
+      try {
+        this._abortController.abort();
+        trace('ProcessRunner', () => `Abort controller aborted successfully during cleanup`);
+      } catch (e) {
+        trace('ProcessRunner', () => `Error aborting controller during cleanup: ${e.message}`);
+      }
+      this._abortController = null;
+      trace('ProcessRunner', () => `Abort controller reference cleared during cleanup`);
+    } else {
+      trace('ProcessRunner', () => `No abort controller to clean up during cleanup`);
+    }
+    
+    // Clean up child process reference
+    if (this.child) {
+      trace('ProcessRunner', () => `Cleaning up child process reference | ${JSON.stringify({
+        hasChild: true,
+        childPid: this.child.pid,
+        childKilled: this.child.killed
+      }, null, 2)}`);
+      try {
+        this.child.removeAllListeners?.();
+        trace('ProcessRunner', () => `Child process listeners removed successfully`);
+      } catch (e) {
+        trace('ProcessRunner', () => `Error removing child process listeners: ${e.message}`);
+      }
+      this.child = null;
+      trace('ProcessRunner', () => `Child process reference cleared`);
+    } else {
+      trace('ProcessRunner', () => `No child process reference to clean up`);
+    }
+    
+    // Clean up virtual generator
+    if (this._virtualGenerator) {
+      trace('ProcessRunner', () => `Cleaning up virtual generator | ${JSON.stringify({
+        hasReturn: !!this._virtualGenerator.return
+      }, null, 2)}`);
+      try {
+        if (this._virtualGenerator.return) {
+          this._virtualGenerator.return();
+          trace('ProcessRunner', () => `Virtual generator return() called successfully`);
+        }
+      } catch (e) {
+        trace('ProcessRunner', () => `Error calling virtual generator return(): ${e.message}`);
+      }
+      this._virtualGenerator = null;
+      trace('ProcessRunner', () => `Virtual generator reference cleared`);
+    } else {
+      trace('ProcessRunner', () => `No virtual generator to clean up`);
+    }
+    
+    trace('ProcessRunner', () => `_cleanup() completed | ${JSON.stringify({
+      totalActiveAfter: activeProcessRunners.size,
+      sigintListenerCount: process.listeners('SIGINT').length
+    }, null, 2)}`);
   }
 
   // Unified start method that can work in both async and sync modes
@@ -637,6 +951,79 @@ class ProcessRunner extends StreamEmitter {
       // Create a new options object merging the current ones with the new ones
       this.options = { ...this.options, ...options };
       
+      // Handle external abort signal
+      if (this.options.signal && typeof this.options.signal.addEventListener === 'function') {
+        trace('ProcessRunner', () => `Setting up external abort signal listener | ${JSON.stringify({
+          hasSignal: !!this.options.signal,
+          signalAborted: this.options.signal.aborted,
+          hasInternalController: !!this._abortController,
+          internalAborted: this._abortController?.signal.aborted
+        }, null, 2)}`);
+        
+        this.options.signal.addEventListener('abort', () => {
+          trace('ProcessRunner', () => `External abort signal triggered | ${JSON.stringify({
+            externalSignalAborted: this.options.signal.aborted,
+            hasInternalController: !!this._abortController,
+            internalAborted: this._abortController?.signal.aborted,
+            command: this.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+          
+          // Kill the process when abort signal is triggered
+          trace('ProcessRunner', () => `External abort signal received - killing process | ${JSON.stringify({
+            hasChild: !!this.child,
+            childPid: this.child?.pid,
+            finished: this.finished,
+            command: this.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+          this.kill('SIGTERM');
+          trace('ProcessRunner', () => 'Process kill initiated due to external abort signal');
+          
+          if (this._abortController && !this._abortController.signal.aborted) {
+            trace('ProcessRunner', () => 'Aborting internal controller due to external signal');
+            this._abortController.abort();
+            trace('ProcessRunner', () => `Internal controller aborted | ${JSON.stringify({
+              internalAborted: this._abortController?.signal?.aborted
+            }, null, 2)}`);
+          } else {
+            trace('ProcessRunner', () => `Cannot abort internal controller | ${JSON.stringify({
+              hasInternalController: !!this._abortController,
+              internalAlreadyAborted: this._abortController?.signal?.aborted
+            }, null, 2)}`);
+          }
+        });
+        
+        // If the external signal is already aborted, abort immediately
+        if (this.options.signal.aborted) {
+          trace('ProcessRunner', () => `External signal already aborted, killing process and aborting internal controller | ${JSON.stringify({
+            hasInternalController: !!this._abortController,
+            internalAborted: this._abortController?.signal.aborted
+          }, null, 2)}`);
+          
+          // Kill the process immediately since signal is already aborted
+          trace('ProcessRunner', () => `Signal already aborted - killing process immediately | ${JSON.stringify({
+            hasChild: !!this.child,
+            childPid: this.child?.pid,
+            finished: this.finished,
+            command: this.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+          this.kill('SIGTERM');
+          trace('ProcessRunner', () => 'Process kill initiated due to pre-aborted signal');
+          
+          if (this._abortController && !this._abortController.signal.aborted) {
+            this._abortController.abort();
+            trace('ProcessRunner', () => `Internal controller aborted immediately | ${JSON.stringify({
+              internalAborted: this._abortController?.signal?.aborted
+            }, null, 2)}`);
+          }
+        }
+      } else {
+        trace('ProcessRunner', () => `No external signal to handle | ${JSON.stringify({
+          hasSignal: !!this.options.signal,
+          signalType: typeof this.options.signal,
+          hasAddEventListener: !!(this.options.signal && typeof this.options.signal.addEventListener === 'function')
+        }, null, 2)}`);
+      }
+      
       // Reinitialize chunks based on updated capture option
       if ('capture' in options) {
         trace('ProcessRunner', () => `BRANCH: capture => REINIT_CHUNKS | ${JSON.stringify({ 
@@ -699,6 +1086,9 @@ class ProcessRunner extends StreamEmitter {
     this.started = true;
     this._mode = 'async';
 
+    // Ensure cleanup happens even if execution fails
+    try {
+
     const { cwd, env, stdin } = this.options;
 
     if (this.spec.mode === 'pipeline') {
@@ -726,25 +1116,55 @@ class ProcessRunner extends StreamEmitter {
           }, null, 2)}`);
           return await this._runPipeline(parsed.commands);
         } else if (parsed.type === 'simple' && virtualCommandsEnabled && virtualCommands.has(parsed.cmd)) {
-          trace('ProcessRunner', () => `BRANCH: virtualCommand => ${parsed.cmd} | ${JSON.stringify({
-            isVirtual: true,
-            args: parsed.args
-          }, null, 2)}`);
-          return await this._runVirtual(parsed.cmd, parsed.args, this.spec.command);
+          // For built-in virtual commands that have real counterparts (like sleep),
+          // skip the virtual version when custom stdin is provided to ensure proper process handling
+          const hasCustomStdin = this.options.stdin && 
+                                 this.options.stdin !== 'inherit' && 
+                                 this.options.stdin !== 'ignore';
+          
+          // List of built-in virtual commands that should fallback to real commands with custom stdin
+          const builtinCommands = ['sleep', 'echo', 'pwd', 'true', 'false', 'yes', 'cat', 'ls', 'which'];
+          const shouldBypassVirtual = hasCustomStdin && builtinCommands.includes(parsed.cmd);
+          
+          if (shouldBypassVirtual) {
+            trace('ProcessRunner', () => `Bypassing built-in virtual command due to custom stdin | ${JSON.stringify({
+              cmd: parsed.cmd,
+              stdin: typeof this.options.stdin
+            }, null, 2)}`);
+            // Fall through to run as real command
+          } else {
+            trace('ProcessRunner', () => `BRANCH: virtualCommand => ${parsed.cmd} | ${JSON.stringify({
+              isVirtual: true,
+              args: parsed.args
+            }, null, 2)}`);
+            trace('ProcessRunner', () => `Executing virtual command | ${JSON.stringify({
+              cmd: parsed.cmd,
+              argsLength: parsed.args.length,
+              command: this.spec.command
+            }, null, 2)}`);
+            return await this._runVirtual(parsed.cmd, parsed.args, this.spec.command);
+          }
         }
       }
     }
 
     const argv = this.spec.mode === 'shell' ? ['sh', '-lc', this.spec.command] : [this.spec.file, ...this.spec.args];
+    trace('ProcessRunner', () => `Constructed argv | ${JSON.stringify({
+      mode: this.spec.mode,
+      argv: argv,
+      originalCommand: this.spec.command
+    }, null, 2)}`);
 
     if (globalShellSettings.xtrace) {
       const traceCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
       console.log(`+ ${traceCmd}`);
+      trace('ProcessRunner', () => `xtrace output displayed: + ${traceCmd}`);
     }
 
     if (globalShellSettings.verbose) {
       const verboseCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
       console.log(verboseCmd);
+      trace('ProcessRunner', () => `verbose output displayed: ${verboseCmd}`);
     }
 
     // Detect if this is an interactive command that needs direct TTY access
@@ -754,28 +1174,154 @@ class ProcessRunner extends StreamEmitter {
       process.stdout.isTTY === true && 
       process.stderr.isTTY === true &&
       (this.spec.mode === 'shell' ? isInteractiveCommand(this.spec.command) : isInteractiveCommand(this.spec.file));
+    
+    trace('ProcessRunner', () => `Interactive command detection | ${JSON.stringify({
+      isInteractive,
+      stdinInherit: stdin === 'inherit',
+      stdinTTY: process.stdin.isTTY,
+      stdoutTTY: process.stdout.isTTY,
+      stderrTTY: process.stderr.isTTY,
+      commandCheck: this.spec.mode === 'shell' ? isInteractiveCommand(this.spec.command) : isInteractiveCommand(this.spec.file)
+    }, null, 2)}`);
 
     const spawnBun = (argv) => {
+      trace('ProcessRunner', () => `spawnBun: Creating process | ${JSON.stringify({
+        command: argv[0],
+        args: argv.slice(1),
+        isInteractive,
+        cwd,
+        platform: process.platform
+      }, null, 2)}`);
+      
       if (isInteractive) {
         // For interactive commands, use inherit to provide direct TTY access
-        return Bun.spawn(argv, { cwd, env, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' });
+        trace('ProcessRunner', () => `spawnBun: Using interactive mode with inherited stdio`);
+        const child = Bun.spawn(argv, { cwd, env, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' });
+        trace('ProcessRunner', () => `spawnBun: Interactive process created | ${JSON.stringify({
+          pid: child.pid,
+          killed: child.killed
+        }, null, 2)}`);
+        return child;
       }
-      return Bun.spawn(argv, { cwd, env, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+      // For non-interactive commands, spawn with detached to create process group (for proper signal handling)
+      // This allows us to send signals to the entire process group, killing shell and all its children
+      trace('ProcessRunner', () => `spawnBun: Using non-interactive mode with pipes and detached=${process.platform !== 'win32'}`);
+      const child = Bun.spawn(argv, { 
+        cwd, 
+        env, 
+        stdin: 'pipe', 
+        stdout: 'pipe', 
+        stderr: 'pipe',
+        detached: process.platform !== 'win32' // Create process group on Unix-like systems
+      });
+      trace('ProcessRunner', () => `spawnBun: Non-interactive process created | ${JSON.stringify({
+        pid: child.pid,
+        killed: child.killed,
+        hasStdout: !!child.stdout,
+        hasStderr: !!child.stderr,
+        hasStdin: !!child.stdin
+      }, null, 2)}`);
+      return child;
     };
     const spawnNode = async (argv) => {
+      trace('ProcessRunner', () => `spawnNode: Creating process | ${JSON.stringify({
+        command: argv[0],
+        args: argv.slice(1),
+        isInteractive,
+        cwd,
+        platform: process.platform
+      })}`);
+      
       if (isInteractive) {
         // For interactive commands, use inherit to provide direct TTY access
         return cp.spawn(argv[0], argv.slice(1), { cwd, env, stdio: 'inherit' });
       }
-      return cp.spawn(argv[0], argv.slice(1), { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+      // For non-interactive commands, spawn with detached to create process group (for proper signal handling)
+      // This allows us to send signals to the entire process group
+      const child = cp.spawn(argv[0], argv.slice(1), { 
+        cwd, 
+        env, 
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: process.platform !== 'win32' // Create process group on Unix-like systems
+      });
+      
+      trace('ProcessRunner', () => `spawnNode: Process created | ${JSON.stringify({
+        pid: child.pid,
+        killed: child.killed,
+        hasStdout: !!child.stdout,
+        hasStderr: !!child.stderr,
+        hasStdin: !!child.stdin
+      })}`);
+      
+      return child;
     };
 
     const needsExplicitPipe = stdin !== 'inherit' && stdin !== 'ignore';
     const preferNodeForInput = isBun && needsExplicitPipe;
+    trace('ProcessRunner', () => `About to spawn process | ${JSON.stringify({ 
+      needsExplicitPipe, 
+      preferNodeForInput, 
+      runtime: isBun ? 'Bun' : 'Node',
+      command: argv[0],
+      args: argv.slice(1)
+    }, null, 2)}`);
     this.child = preferNodeForInput ? await spawnNode(argv) : (isBun ? spawnBun(argv) : await spawnNode(argv));
+    
+    // Add detailed logging for CI debugging
+    if (this.child) {
+      trace('ProcessRunner', () => `Child process created | ${JSON.stringify({ 
+        pid: this.child.pid, 
+        detached: this.child.options?.detached,
+        killed: this.child.killed,
+        exitCode: this.child.exitCode,
+        signalCode: this.child.signalCode,
+        hasStdout: !!this.child.stdout,
+        hasStderr: !!this.child.stderr,
+        hasStdin: !!this.child.stdin,
+        platform: process.platform,
+        command: this.spec?.command?.slice(0, 100)
+      }, null, 2)}`);
+      
+      // Add event listeners with detailed tracing (only for Node.js child processes)
+      if (this.child && typeof this.child.on === 'function') {
+        this.child.on('spawn', () => {
+          trace('ProcessRunner', () => `Child process spawned successfully | ${JSON.stringify({
+            pid: this.child.pid,
+            command: this.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+        });
+        
+        this.child.on('error', (error) => {
+          trace('ProcessRunner', () => `Child process error event | ${JSON.stringify({
+            pid: this.child?.pid,
+            error: error.message,
+            code: error.code,
+            errno: error.errno,
+            syscall: error.syscall,
+            command: this.spec?.command?.slice(0, 50)
+          }, null, 2)}`);
+        });
+      } else {
+        trace('ProcessRunner', () => `Skipping event listeners - child does not support .on() method (likely Bun process)`);
+      }
+    } else {
+      trace('ProcessRunner', () => `No child process created | ${JSON.stringify({
+        spec: this.spec,
+        hasVirtualGenerator: !!this._virtualGenerator
+      }, null, 2)}`);
+    }
 
     // For interactive commands with stdio: 'inherit', stdout/stderr will be null
+    const childPid = this.child?.pid; // Capture PID once at the start
     const outPump = this.child.stdout ? pumpReadable(this.child.stdout, async (buf) => {
+      trace('ProcessRunner', () => `stdout data received | ${JSON.stringify({
+        pid: childPid,
+        bufferLength: buf.length,
+        capture: this.options.capture,
+        mirror: this.options.mirror,
+        preview: buf.toString().slice(0, 100)
+      })}`);
+      
       if (this.options.capture) this.outChunks.push(buf);
       if (this.options.mirror) safeWrite(process.stdout, buf);
 
@@ -784,6 +1330,14 @@ class ProcessRunner extends StreamEmitter {
     }) : Promise.resolve();
 
     const errPump = this.child.stderr ? pumpReadable(this.child.stderr, async (buf) => {
+      trace('ProcessRunner', () => `stderr data received | ${JSON.stringify({
+        pid: childPid,
+        bufferLength: buf.length,
+        capture: this.options.capture,
+        mirror: this.options.mirror,
+        preview: buf.toString().slice(0, 100)
+      })}`);
+      
       if (this.options.capture) this.errChunks.push(buf);
       if (this.options.mirror) safeWrite(process.stderr, buf);
 
@@ -792,28 +1346,78 @@ class ProcessRunner extends StreamEmitter {
     }) : Promise.resolve();
 
     let stdinPumpPromise = Promise.resolve();
+    trace('ProcessRunner', () => `Setting up stdin handling | ${JSON.stringify({
+      stdinType: typeof stdin,
+      stdin: stdin === 'inherit' ? 'inherit' : stdin === 'ignore' ? 'ignore' : (typeof stdin === 'string' ? `string(${stdin.length})` : 'other'),
+      isInteractive,
+      hasChildStdin: !!this.child?.stdin,
+      processTTY: process.stdin.isTTY
+    }, null, 2)}`);
+    
     if (stdin === 'inherit') {
       if (isInteractive) {
         // For interactive commands with stdio: 'inherit', stdin is handled automatically
+        trace('ProcessRunner', () => `stdin: Using inherit mode for interactive command`);
         stdinPumpPromise = Promise.resolve();
       } else {
         const isPipedIn = process.stdin && process.stdin.isTTY === false;
+        trace('ProcessRunner', () => `stdin: Non-interactive inherit mode | ${JSON.stringify({
+          isPipedIn,
+          stdinTTY: process.stdin.isTTY
+        }, null, 2)}`);
         if (isPipedIn) {
+          trace('ProcessRunner', () => `stdin: Pumping piped input to child process`);
           stdinPumpPromise = this._pumpStdinTo(this.child, this.options.capture ? this.inChunks : null);
         } else {
           // For TTY (interactive terminal), forward stdin directly for non-interactive commands
+          trace('ProcessRunner', () => `stdin: Forwarding TTY stdin for non-interactive command`);
           stdinPumpPromise = this._forwardTTYStdin();
         }
       }
     } else if (stdin === 'ignore') {
-      if (this.child.stdin && typeof this.child.stdin.end === 'function') this.child.stdin.end();
+      trace('ProcessRunner', () => `stdin: Ignoring and closing stdin`);
+      if (this.child.stdin && typeof this.child.stdin.end === 'function') {
+        this.child.stdin.end();
+        trace('ProcessRunner', () => `stdin: Child stdin closed successfully`);
+      }
     } else if (typeof stdin === 'string' || Buffer.isBuffer(stdin)) {
       const buf = Buffer.isBuffer(stdin) ? stdin : Buffer.from(stdin);
+      trace('ProcessRunner', () => `stdin: Writing buffer to child | ${JSON.stringify({
+        bufferLength: buf.length,
+        willCapture: this.options.capture && !!this.inChunks
+      }, null, 2)}`);
       if (this.options.capture && this.inChunks) this.inChunks.push(Buffer.from(buf));
       stdinPumpPromise = this._writeToStdin(buf);
-    }
-
-    const exited = isBun ? this.child.exited : new Promise((resolve) => this.child.on('close', resolve));
+    } else {
+      trace('ProcessRunner', () => `stdin: Unhandled stdin type: ${typeof stdin}`);
+    }
+
+    const exited = isBun ? this.child.exited : new Promise((resolve) => {
+      trace('ProcessRunner', () => `Setting up child process event listeners for PID ${this.child.pid}`);
+      this.child.on('close', (code, signal) => {
+        trace('ProcessRunner', () => `Child process close event | ${JSON.stringify({ 
+          pid: this.child.pid, 
+          code, 
+          signal,
+          killed: this.child.killed,
+          exitCode: this.child.exitCode,
+          signalCode: this.child.signalCode,
+          command: this.command 
+        }, null, 2)}`);
+        resolve(code);
+      });
+      this.child.on('exit', (code, signal) => {
+        trace('ProcessRunner', () => `Child process exit event | ${JSON.stringify({ 
+          pid: this.child.pid, 
+          code, 
+          signal,
+          killed: this.child.killed,
+          exitCode: this.child.exitCode,
+          signalCode: this.child.signalCode,
+          command: this.command 
+        }, null, 2)}`);
+      });
+    });
     const code = await exited;
     await Promise.all([outPump, errPump, stdinPumpPromise]);
 
@@ -825,35 +1429,126 @@ class ProcessRunner extends StreamEmitter {
       isBun
     }, null, 2)}`);
 
+    // When a process is killed, it may not have an exit code
+    // If cancelled and no exit code, assume it was killed with SIGTERM
+    let finalExitCode = code;
+    trace('ProcessRunner', () => `Processing exit code | ${JSON.stringify({
+      rawCode: code,
+      cancelled: this._cancelled,
+      childKilled: this.child?.killed,
+      childExitCode: this.child?.exitCode,
+      childSignalCode: this.child?.signalCode
+    }, null, 2)}`);
+    
+    if (finalExitCode === undefined || finalExitCode === null) {
+      if (this._cancelled) {
+        // Process was killed, use SIGTERM exit code
+        finalExitCode = 143; // 128 + 15 (SIGTERM)
+        trace('ProcessRunner', () => `Process was killed, using SIGTERM exit code 143`);
+      } else {
+        // Process exited without a code, default to 0
+        finalExitCode = 0;
+        trace('ProcessRunner', () => `Process exited without code, defaulting to 0`);
+      }
+    }
+
     const resultData = {
-      code: code ?? 0,  // Default to 0 if exit code is null/undefined
+      code: finalExitCode,
       stdout: this.options.capture ? (this.outChunks && this.outChunks.length > 0 ? Buffer.concat(this.outChunks).toString('utf8') : '') : undefined,
       stderr: this.options.capture ? (this.errChunks && this.errChunks.length > 0 ? Buffer.concat(this.errChunks).toString('utf8') : '') : undefined,
       stdin: this.options.capture && this.inChunks ? Buffer.concat(this.inChunks).toString('utf8') : undefined,
       child: this.child
     };
+    
+    trace('ProcessRunner', () => `Process completed | ${JSON.stringify({
+      command: this.command,
+      finalExitCode,
+      captured: this.options.capture,
+      hasStdout: !!resultData.stdout,
+      hasStderr: !!resultData.stderr,
+      stdoutLength: resultData.stdout?.length || 0,
+      stderrLength: resultData.stderr?.length || 0,
+      stdoutPreview: resultData.stdout?.slice(0, 100),
+      stderrPreview: resultData.stderr?.slice(0, 100),
+      childPid: this.child?.pid,
+      cancelled: this._cancelled,
+      cancellationSignal: this._cancellationSignal,
+      platform: process.platform,
+      runtime: isBun ? 'Bun' : 'Node.js'
+    }, null, 2)}`);
 
-    this.result = {
+    const result = {
       ...resultData,
       async text() {
         return resultData.stdout || '';
       }
     };
 
-    this.finished = true;
-    this.emit('end', this.result);
-    this.emit('exit', this.result.code);
+    trace('ProcessRunner', () => `About to finish process with result | ${JSON.stringify({
+      exitCode: result.code,
+      finished: this.finished
+    }, null, 2)}`);
+    
+    // Finish the process with proper event emission order
+    this.finish(result);
+    
+    trace('ProcessRunner', () => `Process finished, result set | ${JSON.stringify({
+      finished: this.finished,
+      resultCode: this.result?.code
+    }, null, 2)}`);
 
     if (globalShellSettings.errexit && this.result.code !== 0) {
+      trace('ProcessRunner', () => `Errexit mode: throwing error for non-zero exit code | ${JSON.stringify({
+        exitCode: this.result.code,
+        errexit: globalShellSettings.errexit,
+        hasStdout: !!this.result.stdout,
+        hasStderr: !!this.result.stderr
+      }, null, 2)}`);
+      
       const error = new Error(`Command failed with exit code ${this.result.code}`);
       error.code = this.result.code;
       error.stdout = this.result.stdout;
       error.stderr = this.result.stderr;
       error.result = this.result;
+      
+      trace('ProcessRunner', () => `About to throw errexit error`);
       throw error;
     }
+    
+    trace('ProcessRunner', () => `Returning result successfully | ${JSON.stringify({
+      exitCode: this.result.code,
+      errexit: globalShellSettings.errexit
+    }, null, 2)}`);
 
     return this.result;
+    } catch (error) {
+      trace('ProcessRunner', () => `Caught error in _doStartAsync | ${JSON.stringify({
+        errorMessage: error.message,
+        errorCode: error.code,
+        isCommandError: error.isCommandError,
+        hasResult: !!error.result,
+        command: this.spec?.command?.slice(0, 100)
+      }, null, 2)}`);
+      
+      // Ensure cleanup happens even if execution fails
+      trace('ProcessRunner', () => `_doStartAsync caught error: ${error.message}`);
+      
+      if (!this.finished) {
+        // Create a result from the error
+        const errorResult = createResult({
+          code: error.code ?? 1,
+          stdout: error.stdout ?? '',
+          stderr: error.stderr ?? error.message ?? '',
+          stdin: ''
+        });
+        
+        // Finish to trigger cleanup
+        this.finish(errorResult);
+      }
+      
+      // Re-throw the error after cleanup
+      throw error;
+    }
   }
 
   async _pumpStdinTo(child, captureChunks) {
@@ -1005,8 +1700,18 @@ class ProcessRunner extends StreamEmitter {
         const commandOptions = {
           ...this.options,
           isCancelled: () => this._cancelled,
-          signal: this._abortController.signal
+          signal: this._abortController?.signal
         };
+        
+        trace('ProcessRunner', () => `_runVirtual signal details | ${JSON.stringify({
+          cmd,
+          hasAbortController: !!this._abortController,
+          signalAborted: this._abortController?.signal?.aborted,
+          signalExists: !!commandOptions.signal,
+          commandOptionsSignalAborted: commandOptions.signal?.aborted,
+          optionsSignalExists: !!this.options.signal,
+          optionsSignalAborted: this.options.signal?.aborted
+        }, null, 2)}`);
 
         const generator = handler({ args: argValues, stdin: stdinData, ...commandOptions });
         this._virtualGenerator = generator;
@@ -1020,12 +1725,27 @@ class ProcessRunner extends StreamEmitter {
           let done = false;
 
           while (!done && !this._cancelled) {
+            trace('ProcessRunner', () => `Virtual command iteration starting | ${JSON.stringify({
+              cancelled: this._cancelled,
+              streamBreaking: this._streamBreaking
+            }, null, 2)}`);
+            
             const result = await Promise.race([
               iterator.next(),
               cancelPromise.then(() => ({ done: true, cancelled: true }))
             ]);
 
+            trace('ProcessRunner', () => `Virtual command iteration result | ${JSON.stringify({
+              hasValue: !!result.value,
+              done: result.done,
+              cancelled: result.cancelled || this._cancelled
+            }, null, 2)}`);
+
             if (result.cancelled || this._cancelled) {
+              trace('ProcessRunner', () => `Virtual command cancelled - closing generator | ${JSON.stringify({
+                resultCancelled: result.cancelled,
+                thisCancelled: this._cancelled
+              }, null, 2)}`);
               // Cancelled - close the generator
               if (iterator.return) {
                 await iterator.return();
@@ -1036,18 +1756,35 @@ class ProcessRunner extends StreamEmitter {
             done = result.done;
 
             if (!done) {
+              // Check cancellation again before processing the chunk
+              if (this._cancelled) {
+                trace('ProcessRunner', () => 'Skipping chunk processing - cancelled during iteration');
+                break;
+              }
+              
               const chunk = result.value;
               const buf = Buffer.from(chunk);
+              
+              // Check cancelled flag once more before any output
+              if (this._cancelled || this._streamBreaking) {
+                trace('ProcessRunner', () => `Cancelled or stream breaking before output - skipping | ${JSON.stringify({ 
+                  cancelled: this._cancelled, 
+                  streamBreaking: this._streamBreaking 
+                }, null, 2)}`);
+                break;
+              }
+              
               chunks.push(buf);
 
-              // Only output if not cancelled
-              if (!this._cancelled) {
-                if (this.options.mirror) {
-                  safeWrite(process.stdout, buf);
-                }
-
-                this._emitProcessedData('stdout', buf);
+              // Only output if not cancelled and stream not breaking
+              if (!this._cancelled && !this._streamBreaking && this.options.mirror) {
+                trace('ProcessRunner', () => `Mirroring virtual command output | ${JSON.stringify({ 
+                  chunkSize: buf.length 
+                }, null, 2)}`);
+                safeWrite(process.stdout, buf);
               }
+
+              this._emitProcessedData('stdout', buf);
             }
           }
         } finally {
@@ -1063,8 +1800,53 @@ class ProcessRunner extends StreamEmitter {
           stdin: this.options.capture ? stdinData : undefined
         };
       } else {
-        // Regular async function
-        result = await handler({ args: argValues, stdin: stdinData, ...this.options });
+        // Regular async function - race with abort signal
+        const commandOptions = {
+          ...this.options,
+          isCancelled: () => this._cancelled,
+          signal: this._abortController?.signal
+        };
+        
+        trace('ProcessRunner', () => `_runVirtual signal details (non-generator) | ${JSON.stringify({
+          cmd,
+          hasAbortController: !!this._abortController,
+          signalAborted: this._abortController?.signal?.aborted,
+          signalExists: !!commandOptions.signal,
+          commandOptionsSignalAborted: commandOptions.signal?.aborted,
+          optionsSignalExists: !!this.options.signal,
+          optionsSignalAborted: this.options.signal?.aborted
+        }, null, 2)}`);
+        
+        const handlerPromise = handler({ args: argValues, stdin: stdinData, ...commandOptions });
+        
+        // Create an abort promise that rejects when cancelled
+        const abortPromise = new Promise((_, reject) => {
+          if (this._abortController && this._abortController.signal.aborted) {
+            reject(new Error('Command cancelled'));
+          }
+          if (this._abortController) {
+            this._abortController.signal.addEventListener('abort', () => {
+              reject(new Error('Command cancelled'));
+            });
+          }
+        });
+        
+        try {
+          result = await Promise.race([handlerPromise, abortPromise]);
+        } catch (err) {
+          if (err.message === 'Command cancelled') {
+            // Command was cancelled, return appropriate exit code based on signal
+            const exitCode = this._cancellationSignal === 'SIGINT' ? 130 : 143; // 130 for SIGINT, 143 for SIGTERM
+            trace('ProcessRunner', () => `Virtual command cancelled with signal ${this._cancellationSignal}, exit code: ${exitCode}`);
+            result = { 
+              code: exitCode,
+              stdout: '',
+              stderr: ''
+            };
+          } else {
+            throw err;
+          }
+        }
 
         result = {
           ...result,
@@ -1092,13 +1874,8 @@ class ProcessRunner extends StreamEmitter {
         }
       }
 
-      // Store result
-      this.result = result;
-      this.finished = true;
-
-      // Emit completion events
-      this.emit('end', result);
-      this.emit('exit', result.code);
+      // Finish the process with proper event emission order
+      this.finish(result);
 
       if (globalShellSettings.errexit && result.code !== 0) {
         const error = new Error(`Command failed with exit code ${result.code}`);
@@ -1118,9 +1895,6 @@ class ProcessRunner extends StreamEmitter {
         stdin: ''
       };
 
-      this.result = result;
-      this.finished = true;
-
       if (result.stderr) {
         const buf = Buffer.from(result.stderr);
         if (this.options.mirror) {
@@ -1129,8 +1903,7 @@ class ProcessRunner extends StreamEmitter {
         this._emitProcessedData('stderr', buf);
       }
 
-      this.emit('end', result);
-      this.emit('exit', result.code);
+      this.finish(result);
 
       if (globalShellSettings.errexit) {
         error.result = result;
@@ -1321,11 +2094,8 @@ class ProcessRunner extends StreamEmitter {
         this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
     });
 
-    this.result = result;
-    this.finished = true;
-
-    this.emit('end', result);
-    this.emit('exit', result.code);
+    // Finish the process with proper event emission order
+    this.finish(result);
 
     if (globalShellSettings.errexit && result.code !== 0) {
       const error = new Error(`Pipeline failed with exit code ${result.code}`);
@@ -1499,11 +2269,8 @@ class ProcessRunner extends StreamEmitter {
         this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
     });
 
-    this.result = result;
-    this.finished = true;
-
-    this.emit('end', result);
-    this.emit('exit', result.code);
+    // Finish the process with proper event emission order
+    this.finish(result);
 
     if (globalShellSettings.errexit && result.code !== 0) {
       const error = new Error(`Pipeline failed with exit code ${result.code}`);
@@ -1728,11 +2495,8 @@ class ProcessRunner extends StreamEmitter {
         this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
     });
 
-    this.result = result;
-    this.finished = true;
-
-    this.emit('end', result);
-    this.emit('exit', result.code);
+    // Finish the process with proper event emission order
+    this.finish(result);
 
     return result;
   }
@@ -1835,12 +2599,8 @@ class ProcessRunner extends StreamEmitter {
                 this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
             });
 
-            this.result = finalResult;
-            this.finished = true;
-
-            // Emit completion events
-            this.emit('end', finalResult);
-            this.emit('exit', finalResult.code);
+            // Finish the process with proper event emission order
+            this.finish(finalResult);
 
             if (globalShellSettings.errexit && finalResult.code !== 0) {
               const error = new Error(`Pipeline failed with exit code ${finalResult.code}`);
@@ -1871,9 +2631,6 @@ class ProcessRunner extends StreamEmitter {
               this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
           });
 
-          this.result = result;
-          this.finished = true;
-
           if (result.stderr) {
             const buf = Buffer.from(result.stderr);
             if (this.options.mirror) {
@@ -1882,8 +2639,7 @@ class ProcessRunner extends StreamEmitter {
             this._emitProcessedData('stderr', buf);
           }
 
-          this.emit('end', result);
-          this.emit('exit', result.code);
+          this.finish(result);
 
           if (globalShellSettings.errexit) {
             throw error;
@@ -1928,17 +2684,47 @@ class ProcessRunner extends StreamEmitter {
           const spawnNodeAsync = async (argv, stdin, isLastCommand = false) => {
 
             return new Promise((resolve, reject) => {
+              trace('ProcessRunner', () => `spawnNodeAsync: Creating child process | ${JSON.stringify({
+                command: argv[0],
+                args: argv.slice(1),
+                cwd: this.options.cwd,
+                isLastCommand
+              })}`);
+              
               const proc = cp.spawn(argv[0], argv.slice(1), {
                 cwd: this.options.cwd,
                 env: this.options.env,
                 stdio: ['pipe', 'pipe', 'pipe']
               });
 
+              trace('ProcessRunner', () => `spawnNodeAsync: Child process created | ${JSON.stringify({
+                pid: proc.pid,
+                killed: proc.killed,
+                hasStdout: !!proc.stdout,
+                hasStderr: !!proc.stderr
+              })}`);
+
               let stdout = '';
               let stderr = '';
+              let stdoutChunks = 0;
+              let stderrChunks = 0;
 
+              const procPid = proc.pid; // Capture PID once to avoid null reference
+              
               proc.stdout.on('data', (chunk) => {
-                stdout += chunk.toString();
+                const chunkStr = chunk.toString();
+                stdout += chunkStr;
+                stdoutChunks++;
+                
+                trace('ProcessRunner', () => `spawnNodeAsync: stdout chunk received | ${JSON.stringify({
+                  pid: procPid,
+                  chunkNumber: stdoutChunks,
+                  chunkLength: chunk.length,
+                  totalStdoutLength: stdout.length,
+                  isLastCommand,
+                  preview: chunkStr.slice(0, 100)
+                })}`);
+                
                 // If this is the last command, emit streaming data
                 if (isLastCommand) {
                   if (this.options.mirror) {
@@ -1949,7 +2735,19 @@ class ProcessRunner extends StreamEmitter {
               });
 
               proc.stderr.on('data', (chunk) => {
-                stderr += chunk.toString();
+                const chunkStr = chunk.toString();
+                stderr += chunkStr;
+                stderrChunks++;
+                
+                trace('ProcessRunner', () => `spawnNodeAsync: stderr chunk received | ${JSON.stringify({
+                  pid: procPid,
+                  chunkNumber: stderrChunks,
+                  chunkLength: chunk.length,
+                  totalStderrLength: stderr.length,
+                  isLastCommand,
+                  preview: chunkStr.slice(0, 100)
+                })}`);
+                
                 // If this is the last command, emit streaming data
                 if (isLastCommand) {
                   if (this.options.mirror) {
@@ -1960,6 +2758,15 @@ class ProcessRunner extends StreamEmitter {
               });
 
               proc.on('close', (code) => {
+                trace('ProcessRunner', () => `spawnNodeAsync: Process closed | ${JSON.stringify({
+                  pid: procPid,
+                  code,
+                  stdoutLength: stdout.length,
+                  stderrLength: stderr.length,
+                  stdoutChunks,
+                  stderrChunks
+                })}`);
+                
                 resolve({
                   status: code,
                   stdout,
@@ -2040,12 +2847,8 @@ class ProcessRunner extends StreamEmitter {
                 this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
             });
 
-            this.result = finalResult;
-            this.finished = true;
-
-            // Emit completion events
-            this.emit('end', finalResult);
-            this.emit('exit', finalResult.code);
+            // Finish the process with proper event emission order
+            this.finish(finalResult);
 
             if (globalShellSettings.errexit && finalResult.code !== 0) {
               const error = new Error(`Pipeline failed with exit code ${finalResult.code}`);
@@ -2068,9 +2871,6 @@ class ProcessRunner extends StreamEmitter {
               this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
           });
 
-          this.result = result;
-          this.finished = true;
-
           if (result.stderr) {
             const buf = Buffer.from(result.stderr);
             if (this.options.mirror) {
@@ -2079,8 +2879,7 @@ class ProcessRunner extends StreamEmitter {
             this._emitProcessedData('stderr', buf);
           }
 
-          this.emit('end', result);
-          this.emit('exit', result.code);
+          this.finish(result);
 
           if (globalShellSettings.errexit) {
             throw error;
@@ -2163,17 +2962,13 @@ class ProcessRunner extends StreamEmitter {
           this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
       });
 
-      this.result = result;
-      this.finished = true;
-
       const buf = Buffer.from(result.stderr);
       if (this.options.mirror) {
         safeWrite(process.stderr, buf);
       }
       this._emitProcessedData('stderr', buf);
 
-      this.emit('end', result);
-      this.emit('exit', result.code);
+      this.finish(result);
 
       return result;
     }
@@ -2194,12 +2989,16 @@ class ProcessRunner extends StreamEmitter {
     let resolve, reject;
     let ended = false;
     let cleanedUp = false;
+    let killed = false;
 
     const onData = (chunk) => {
-      buffer.push(chunk);
-      if (resolve) {
-        resolve();
-        resolve = reject = null;
+      // Don't buffer more data if we're being killed
+      if (!killed) {
+        buffer.push(chunk);
+        if (resolve) {
+          resolve();
+          resolve = reject = null;
+        }
       }
     };
 
@@ -2216,8 +3015,18 @@ class ProcessRunner extends StreamEmitter {
 
     try {
       while (!ended || buffer.length > 0) {
+        // Check if we've been killed and should stop immediately
+        if (killed) {
+          trace('ProcessRunner', () => 'Stream killed, stopping iteration');
+          break;
+        }
         if (buffer.length > 0) {
-          yield buffer.shift();
+          const chunk = buffer.shift();
+          // Set a flag that we're about to yield - if the consumer breaks,
+          // we'll know not to process any more data
+          this._streamYielding = true;
+          yield chunk;
+          this._streamYielding = false;
         } else if (!ended) {
           await new Promise((res, rej) => {
             resolve = res;
@@ -2232,41 +3041,97 @@ class ProcessRunner extends StreamEmitter {
 
       // This happens when breaking from a for-await loop
       if (!this.finished) {
+        killed = true;
+        buffer = []; // Clear any buffered data
+        this._streamBreaking = true; // Signal that stream is breaking
         this.kill();
       }
     }
   }
 
-  kill() {
+  kill(signal = 'SIGTERM') {
     trace('ProcessRunner', () => `kill ENTER | ${JSON.stringify({
+      signal,
       cancelled: this._cancelled,
       finished: this.finished,
       hasChild: !!this.child,
-      hasVirtualGenerator: !!this._virtualGenerator
+      hasVirtualGenerator: !!this._virtualGenerator,
+      command: this.spec?.command?.slice(0, 50) || 'unknown'
     }, null, 2)}`);
 
-    // Mark as cancelled for virtual commands
+    if (this.finished) {
+      trace('ProcessRunner', () => 'Already finished, skipping kill');
+      return;
+    }
+
+    // Mark as cancelled for virtual commands and store the signal
+    trace('ProcessRunner', () => `Marking as cancelled | ${JSON.stringify({
+      signal,
+      previouslyCancelled: this._cancelled,
+      previousSignal: this._cancellationSignal
+    }, null, 2)}`);
     this._cancelled = true;
+    this._cancellationSignal = signal;
+
+    // If this is a pipeline runner, also kill the source and destination
+    if (this.spec?.mode === 'pipeline') {
+      trace('ProcessRunner', () => 'Killing pipeline components');
+      if (this.spec.source && typeof this.spec.source.kill === 'function') {
+        this.spec.source.kill(signal);
+      }
+      if (this.spec.destination && typeof this.spec.destination.kill === 'function') {
+        this.spec.destination.kill(signal);
+      }
+    }
 
     if (this._cancelResolve) {
       trace('ProcessRunner', () => 'Resolving cancel promise');
       this._cancelResolve();
+      trace('ProcessRunner', () => 'Cancel promise resolved');
+    } else {
+      trace('ProcessRunner', () => 'No cancel promise to resolve');
     }
 
     // Abort any async operations
     if (this._abortController) {
-      trace('ProcessRunner', () => 'Aborting controller');
+      trace('ProcessRunner', () => `Aborting internal controller | ${JSON.stringify({
+        wasAborted: this._abortController?.signal?.aborted
+      }, null, 2)}`);
       this._abortController.abort();
+      trace('ProcessRunner', () => `Internal controller aborted | ${JSON.stringify({
+        nowAborted: this._abortController?.signal?.aborted
+      }, null, 2)}`);
+    } else {
+      trace('ProcessRunner', () => 'No abort controller to abort');
     }
 
     // If it's a virtual generator, try to close it
-    if (this._virtualGenerator && this._virtualGenerator.return) {
-      trace('ProcessRunner', () => 'Closing virtual generator');
-      try {
-        this._virtualGenerator.return();
-      } catch (err) {
-        trace('ProcessRunner', () => `Error closing generator | ${JSON.stringify({ error: err.message }, null, 2)}`);
+    if (this._virtualGenerator) {
+      trace('ProcessRunner', () => `Virtual generator found for cleanup | ${JSON.stringify({
+        hasReturn: typeof this._virtualGenerator.return === 'function',
+        hasThrow: typeof this._virtualGenerator.throw === 'function',
+        cancelled: this._cancelled,
+        signal
+      }, null, 2)}`);
+      
+      if (this._virtualGenerator.return) {
+        trace('ProcessRunner', () => 'Closing virtual generator with return()');
+        try {
+          this._virtualGenerator.return();
+          trace('ProcessRunner', () => 'Virtual generator closed successfully');
+        } catch (err) {
+          trace('ProcessRunner', () => `Error closing generator | ${JSON.stringify({ 
+            error: err.message,
+            stack: err.stack?.slice(0, 200)
+          }, null, 2)}`);
+        }
+      } else {
+        trace('ProcessRunner', () => 'Virtual generator has no return() method');
       }
+    } else {
+      trace('ProcessRunner', () => `No virtual generator to cleanup | ${JSON.stringify({
+        hasVirtualGenerator: !!this._virtualGenerator
+      }, null, 2)}`);
     }
 
     // Kill child process if it exists
@@ -2276,14 +3141,112 @@ class ProcessRunner extends StreamEmitter {
         if (this.child.pid) {
           if (isBun) {
             trace('ProcessRunner', () => `Killing Bun process | ${JSON.stringify({ pid: this.child.pid }, null, 2)}`);
-            this.child.kill();
+            
+            // For Bun, use the same enhanced kill logic as Node.js for CI reliability
+            const killOperations = [];
+            
+            // Try SIGTERM first
+            try {
+              process.kill(this.child.pid, 'SIGTERM');
+              trace('ProcessRunner', () => `Sent SIGTERM to Bun process ${this.child.pid}`);
+              killOperations.push('SIGTERM to process');
+            } catch (err) {
+              trace('ProcessRunner', () => `Error sending SIGTERM to Bun process: ${err.message}`);
+            }
+            
+            // Try process group SIGTERM
+            try {
+              process.kill(-this.child.pid, 'SIGTERM');
+              trace('ProcessRunner', () => `Sent SIGTERM to Bun process group -${this.child.pid}`);
+              killOperations.push('SIGTERM to group');
+            } catch (err) {
+              trace('ProcessRunner', () => `Bun process group SIGTERM failed: ${err.message}`);
+            }
+            
+            // Immediately follow with SIGKILL for both process and group
+            try {
+              process.kill(this.child.pid, 'SIGKILL');
+              trace('ProcessRunner', () => `Sent SIGKILL to Bun process ${this.child.pid}`);
+              killOperations.push('SIGKILL to process');
+            } catch (err) {
+              trace('ProcessRunner', () => `Error sending SIGKILL to Bun process: ${err.message}`);
+            }
+            
+            try {
+              process.kill(-this.child.pid, 'SIGKILL');
+              trace('ProcessRunner', () => `Sent SIGKILL to Bun process group -${this.child.pid}`);
+              killOperations.push('SIGKILL to group');
+            } catch (err) {
+              trace('ProcessRunner', () => `Bun process group SIGKILL failed: ${err.message}`);
+            }
+            
+            trace('ProcessRunner', () => `Bun kill operations attempted: ${killOperations.join(', ')}`);
+            
+            // Also call the original Bun kill method as backup
+            try {
+              this.child.kill();
+              trace('ProcessRunner', () => `Called child.kill() for Bun process ${this.child.pid}`);
+            } catch (err) {
+              trace('ProcessRunner', () => `Error calling child.kill(): ${err.message}`);
+            }
+            
+            // Force cleanup of child reference
+            if (this.child) {
+              this.child.removeAllListeners?.();
+              this.child = null;
+            }
           } else {
-            // In Node.js, kill the process group
-            trace('ProcessRunner', () => `Killing Node process group | ${JSON.stringify({ pid: this.child.pid }, null, 2)}`);
-            process.kill(-this.child.pid, 'SIGTERM');
+            // In Node.js, use a more robust approach for CI environments
+            trace('ProcessRunner', () => `Killing Node process | ${JSON.stringify({ pid: this.child.pid }, null, 2)}`);
+            
+            // Use immediate and aggressive termination for CI environments
+            const killOperations = [];
+            
+            // Try SIGTERM to the process directly
+            try {
+              process.kill(this.child.pid, 'SIGTERM');
+              trace('ProcessRunner', () => `Sent SIGTERM to process ${this.child.pid}`);
+              killOperations.push('SIGTERM to process');
+            } catch (err) {
+              trace('ProcessRunner', () => `Error sending SIGTERM to process: ${err.message}`);
+            }
+            
+            // Try process group if detached (negative PID)
+            try {
+              process.kill(-this.child.pid, 'SIGTERM');
+              trace('ProcessRunner', () => `Sent SIGTERM to process group -${this.child.pid}`);
+              killOperations.push('SIGTERM to group');
+            } catch (err) {
+              trace('ProcessRunner', () => `Process group SIGTERM failed: ${err.message}`);
+            }
+            
+            // Immediately follow up with SIGKILL for CI reliability
+            try {
+              process.kill(this.child.pid, 'SIGKILL');
+              trace('ProcessRunner', () => `Sent SIGKILL to process ${this.child.pid}`);
+              killOperations.push('SIGKILL to process');
+            } catch (err) {
+              trace('ProcessRunner', () => `Error sending SIGKILL to process: ${err.message}`);
+            }
+            
+            try {
+              process.kill(-this.child.pid, 'SIGKILL');
+              trace('ProcessRunner', () => `Sent SIGKILL to process group -${this.child.pid}`);
+              killOperations.push('SIGKILL to group');
+            } catch (err) {
+              trace('ProcessRunner', () => `Process group SIGKILL failed: ${err.message}`);
+            }
+            
+            trace('ProcessRunner', () => `Kill operations attempted: ${killOperations.join(', ')}`);
+            
+            // Force cleanup of child reference to prevent hanging awaits
+            if (this.child) {
+              this.child.removeAllListeners?.();
+              this.child = null;
+            }
           }
         }
-        this.finished = true;
+        // finished will be set by the main cleanup below
       } catch (err) {
         // Process might already be dead
         trace('ProcessRunner', () => `Error killing process | ${JSON.stringify({ error: err.message }, null, 2)}`);
@@ -2291,8 +3254,14 @@ class ProcessRunner extends StreamEmitter {
       }
     }
 
-    // Mark as finished
-    this.finished = true;
+    // Mark as finished and emit completion events
+    const result = createResult({ 
+      code: signal === 'SIGKILL' ? 137 : signal === 'SIGTERM' ? 143 : 130, 
+      stdout: '', 
+      stderr: `Process killed with ${signal}`, 
+      stdin: '' 
+    });
+    this.finish(result);
 
     trace('ProcessRunner', () => `kill EXIT | ${JSON.stringify({
       cancelled: this._cancelled,
@@ -2353,7 +3322,20 @@ class ProcessRunner extends StreamEmitter {
     if (!this.promise) {
       this.promise = this._startAsync();
     }
-    return this.promise.finally(onFinally);
+    return this.promise.finally(() => {
+      // Ensure cleanup happened
+      if (!this.finished) {
+        trace('ProcessRunner', () => 'Finally handler ensuring cleanup');
+        const fallbackResult = createResult({ 
+          code: 1, 
+          stdout: '', 
+          stderr: 'Process terminated unexpectedly', 
+          stdin: '' 
+        });
+        this.finish(fallbackResult);
+      }
+      if (onFinally) onFinally();
+    });
   }
 
   // Internal sync execution
@@ -2438,9 +3420,6 @@ class ProcessRunner extends StreamEmitter {
     this.outChunks = result.stdout ? [Buffer.from(result.stdout)] : [];
     this.errChunks = result.stderr ? [Buffer.from(result.stderr)] : [];
 
-    this.result = result;
-    this.finished = true;
-
     // Emit batched events after completion
     if (result.stdout) {
       const stdoutBuf = Buffer.from(result.stdout);
@@ -2452,8 +3431,7 @@ class ProcessRunner extends StreamEmitter {
       this._emitProcessedData('stderr', stderrBuf);
     }
 
-    this.emit('end', result);
-    this.emit('exit', result.code);
+    this.finish(result);
 
     if (globalShellSettings.errexit && result.code !== 0) {
       const error = new Error(`Command failed with exit code ${result.code}`);
@@ -2467,18 +3445,6 @@ class ProcessRunner extends StreamEmitter {
     return result;
   }
 
-  // Stream properties
-  get stdout() {
-    return this.child?.stdout;
-  }
-
-  get stderr() {
-    return this.child?.stderr;
-  }
-
-  get stdin() {
-    return this.child?.stdin;
-  }
 }
 
 // Public APIs
@@ -2526,6 +3492,28 @@ async function run(commandOrTokens, options = {}) {
 }
 
 function $tagged(strings, ...values) {
+  // Check if called as a function with options object: $({ options })
+  if (!Array.isArray(strings) && typeof strings === 'object' && strings !== null) {
+    const options = strings;
+    trace('API', () => `$tagged called with options | ${JSON.stringify({ options }, null, 2)}`);
+    
+    // Return a new tagged template function with those options
+    return (innerStrings, ...innerValues) => {
+      trace('API', () => `$tagged.withOptions ENTER | ${JSON.stringify({
+        stringsLength: innerStrings.length,
+        valuesLength: innerValues.length,
+        options
+      }, null, 2)}`);
+      
+      const cmd = buildShellCommand(innerStrings, innerValues);
+      const runner = new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true, ...options });
+      
+      trace('API', () => `$tagged.withOptions EXIT | ${JSON.stringify({ command: cmd }, null, 2)}`);
+      return runner;
+    };
+  }
+  
+  // Normal tagged template literal usage
   trace('API', () => `$tagged ENTER | ${JSON.stringify({
     stringsLength: strings.length,
     valuesLength: values.length
@@ -2779,6 +3767,7 @@ export {
   AnsiUtils,
   configureAnsi,
   getAnsiConfig,
-  processOutput
+  processOutput,
+  forceCleanupAll
 };
 export default $tagged;