command-stream 0.1.0 → 0.3.0

package/$.mjs

@@ -6,37 +6,351 @@
 // 4. Stream access: $`command`.stdout, $`command`.stderr
 
 import { createRequire } from 'module';
-import { fileURLToPath } from 'url';
+import cp from 'child_process';
+import fs from 'fs';
+import path from 'path';
 
 const isBun = typeof globalThis.Bun !== 'undefined';
 
-// Verbose tracing for debugging (enabled in CI or when COMMAND_STREAM_VERBOSE is set)
 const VERBOSE = process.env.COMMAND_STREAM_VERBOSE === 'true' || process.env.CI === 'true';
 
+// Interactive commands that need TTY forwarding by default
+const INTERACTIVE_COMMANDS = new Set([
+  'top', 'htop', 'btop', 'less', 'more', 'vi', 'vim', 'nano', 'emacs',
+  'man', 'pager', 'watch', 'tmux', 'screen', 'ssh', 'ftp', 'sftp',
+  'mysql', 'psql', 'redis-cli', 'mongo', 'sqlite3', 'irb', 'python',
+  'node', 'repl', 'gdb', 'lldb', 'bc', 'dc', 'ed'
+]);
+
 // Trace function for verbose logging
-function trace(category, message, data = {}) {
+function trace(category, messageOrFunc) {
   if (!VERBOSE) return;
-  
+  const message = typeof messageOrFunc === 'function' ? messageOrFunc() : messageOrFunc;
   const timestamp = new Date().toISOString();
-  const dataStr = Object.keys(data).length > 0 ? ' | ' + JSON.stringify(data) : '';
-  console.error(`[TRACE ${timestamp}] [${category}] ${message}${dataStr}`);
+  console.error(`[TRACE ${timestamp}] [${category}] ${message}`);
 }
 
-// Trace decision branches
-function traceBranch(category, condition, branch, data = {}) {
-  if (!VERBOSE) return;
+// Check if a command is interactive and needs TTY forwarding
+function isInteractiveCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  
+  // Extract command and arguments from shell command string
+  const parts = command.trim().split(/\s+/);
+  const commandName = parts[0];
+  const baseName = path.basename(commandName);
+  
+  // Special handling for commands that are only interactive when run without arguments/scripts
+  if (baseName === 'node' || baseName === 'python' || baseName === 'python3') {
+    // These are only interactive when run without a script file
+    // If there are additional arguments (like a script file), they're not interactive
+    return parts.length === 1;
+  }
   
-  trace(category, `BRANCH: ${condition} => ${branch}`, data);
+  return INTERACTIVE_COMMANDS.has(baseName);
 }
 
-// Trace function entry/exit
-function traceFunc(category, funcName, phase, data = {}) {
-  if (!VERBOSE) return;
-  
-  trace(category, `${funcName} ${phase}`, data);
+
+// Track parent stream state for graceful shutdown
+let parentStreamsMonitored = false;
+const activeProcessRunners = new Set();
+
+function monitorParentStreams() {
+  if (parentStreamsMonitored) return;
+  parentStreamsMonitored = true;
+
+  const checkParentStream = (stream, name) => {
+    if (stream && typeof stream.on === 'function') {
+      stream.on('close', () => {
+        trace('ProcessRunner', () => `Parent ${name} closed - triggering graceful shutdown | ${JSON.stringify({ activeProcesses: activeProcessRunners.size }, null, 2)}`);
+        for (const runner of activeProcessRunners) {
+          runner._handleParentStreamClosure();
+        }
+      });
+    }
+  };
+
+  checkParentStream(process.stdout, 'stdout');
+  checkParentStream(process.stderr, 'stderr');
 }
 
-// Global shell settings (like bash set -e / set +e)
+function safeWrite(stream, data, processRunner = null) {
+  monitorParentStreams();
+
+  if (!StreamUtils.isStreamWritable(stream)) {
+    trace('ProcessRunner', () => `safeWrite skipped - stream not writable | ${JSON.stringify({
+      hasStream: !!stream,
+      writable: stream?.writable,
+      destroyed: stream?.destroyed,
+      closed: stream?.closed
+    }, null, 2)}`);
+
+    if (processRunner && (stream === process.stdout || stream === process.stderr)) {
+      processRunner._handleParentStreamClosure();
+    }
+
+    return false;
+  }
+
+  try {
+    return stream.write(data);
+  } catch (error) {
+    trace('ProcessRunner', () => `safeWrite error | ${JSON.stringify({
+      error: error.message,
+      code: error.code,
+      writable: stream.writable,
+      destroyed: stream.destroyed
+    }, null, 2)}`);
+
+    if (error.code === 'EPIPE' && processRunner &&
+      (stream === process.stdout || stream === process.stderr)) {
+      processRunner._handleParentStreamClosure();
+    }
+
+    return false;
+  }
+}
+
+// Stream utility functions for safe operations and error handling
+const StreamUtils = {
+  /**
+   * Check if a stream is safe to write to
+   */
+  isStreamWritable(stream) {
+    return stream && stream.writable && !stream.destroyed && !stream.closed;
+  },
+
+  /**
+   * Add standardized error handler to stdin streams
+   */
+  addStdinErrorHandler(stream, contextName = 'stdin', onNonEpipeError = null) {
+    if (stream && typeof stream.on === 'function') {
+      stream.on('error', (error) => {
+        const handled = this.handleStreamError(error, `${contextName} error event`, false);
+        if (!handled && onNonEpipeError) {
+          onNonEpipeError(error);
+        }
+      });
+    }
+  },
+
+  /**
+   * Safely write to a stream with comprehensive error handling
+   */
+  safeStreamWrite(stream, data, contextName = 'stream') {
+    if (!this.isStreamWritable(stream)) {
+      trace('ProcessRunner', () => `${contextName} write skipped - not writable | ${JSON.stringify({
+        hasStream: !!stream,
+        writable: stream?.writable,
+        destroyed: stream?.destroyed,
+        closed: stream?.closed
+      }, null, 2)}`);
+      return false;
+    }
+
+    try {
+      const result = stream.write(data);
+      trace('ProcessRunner', () => `${contextName} write successful | ${JSON.stringify({
+        dataLength: data?.length || 0
+      }, null, 2)}`);
+      return result;
+    } catch (error) {
+      if (error.code !== 'EPIPE') {
+        trace('ProcessRunner', () => `${contextName} write error | ${JSON.stringify({
+          error: error.message,
+          code: error.code,
+          isEPIPE: false
+        }, null, 2)}`);
+        throw error; // Re-throw non-EPIPE errors
+      } else {
+        trace('ProcessRunner', () => `${contextName} EPIPE error (ignored) | ${JSON.stringify({
+          error: error.message,
+          code: error.code,
+          isEPIPE: true
+        }, null, 2)}`);
+      }
+      return false;
+    }
+  },
+
+  /**
+   * Safely end a stream with error handling
+   */
+  safeStreamEnd(stream, contextName = 'stream') {
+    if (!this.isStreamWritable(stream) || typeof stream.end !== 'function') {
+      trace('ProcessRunner', () => `${contextName} end skipped - not available | ${JSON.stringify({
+        hasStream: !!stream,
+        hasEnd: stream && typeof stream.end === 'function',
+        writable: stream?.writable
+      }, null, 2)}`);
+      return false;
+    }
+
+    try {
+      stream.end();
+      trace('ProcessRunner', () => `${contextName} ended successfully`);
+      return true;
+    } catch (error) {
+      if (error.code !== 'EPIPE') {
+        trace('ProcessRunner', () => `${contextName} end error | ${JSON.stringify({
+          error: error.message,
+          code: error.code
+        }, null, 2)}`);
+      } else {
+        trace('ProcessRunner', () => `${contextName} EPIPE on end (ignored) | ${JSON.stringify({
+          error: error.message,
+          code: error.code
+        }, null, 2)}`);
+      }
+      return false;
+    }
+  },
+
+  /**
+   * Setup comprehensive stdin handling (error handler + safe operations)
+   */
+  setupStdinHandling(stream, contextName = 'stdin') {
+    this.addStdinErrorHandler(stream, contextName);
+
+    return {
+      write: (data) => this.safeStreamWrite(stream, data, contextName),
+      end: () => this.safeStreamEnd(stream, contextName),
+      isWritable: () => this.isStreamWritable(stream)
+    };
+  },
+
+  /**
+   * Handle stream errors with consistent EPIPE behavior
+   */
+  handleStreamError(error, contextName, shouldThrow = true) {
+    if (error.code !== 'EPIPE') {
+      trace('ProcessRunner', () => `${contextName} error | ${JSON.stringify({
+        error: error.message,
+        code: error.code,
+        isEPIPE: false
+      }, null, 2)}`);
+      if (shouldThrow) throw error;
+      return false;
+    } else {
+      trace('ProcessRunner', () => `${contextName} EPIPE error (ignored) | ${JSON.stringify({
+        error: error.message,
+        code: error.code,
+        isEPIPE: true
+      }, null, 2)}`);
+      return true; // EPIPE handled gracefully
+    }
+  },
+
+  /**
+   * Detect if stream supports Bun-style writing
+   */
+  isBunStream(stream) {
+    return isBun && stream && typeof stream.getWriter === 'function';
+  },
+
+  /**
+   * Detect if stream supports Node.js-style writing  
+   */
+  isNodeStream(stream) {
+    return stream && typeof stream.write === 'function';
+  },
+
+  /**
+   * Write to either Bun or Node.js style stream
+   */
+  async writeToStream(stream, data, contextName = 'stream') {
+    if (this.isBunStream(stream)) {
+      try {
+        const writer = stream.getWriter();
+        await writer.write(data);
+        writer.releaseLock();
+        return true;
+      } catch (error) {
+        return this.handleStreamError(error, `${contextName} Bun writer`, false);
+      }
+    } else if (this.isNodeStream(stream)) {
+      try {
+        stream.write(data);
+        return true;
+      } catch (error) {
+        return this.handleStreamError(error, `${contextName} Node writer`, false);
+      }
+    }
+    return false;
+  }
+};
+
+// 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
@@ -45,24 +359,20 @@ let globalShellSettings = {
   nounset: false     // set -u equivalent: error on undefined variables
 };
 
-// Helper function to create result objects with Bun.$ compatibility
 function createResult({ code, stdout = '', stderr = '', stdin = '' }) {
   return {
     code,
     stdout,
     stderr,
     stdin,
-    // Bun.$ compatibility method
     async text() {
       return stdout;
     }
   };
 }
 
-// Virtual command registry - unified system for all commands
 const virtualCommands = new Map();
 
-// Global flag to enable/disable virtual commands (for backward compatibility)
 let virtualCommandsEnabled = true;
 
 // EventEmitter-like implementation
@@ -76,9 +386,9 @@ class StreamEmitter {
       this.listeners.set(event, []);
     }
     this.listeners.get(event).push(listener);
-    
+
     // No auto-start - explicit start() or await will start the process
-    
+
     return this;
   }
 
@@ -113,28 +423,28 @@ function quote(value) {
 }
 
 function buildShellCommand(strings, values) {
-  traceFunc('Utils', 'buildShellCommand', 'ENTER', { 
+  trace('Utils', () => `buildShellCommand ENTER | ${JSON.stringify({
     stringsLength: strings.length,
     valuesLength: values.length
-  });
-  
+  }, null, 2)}`);
+
   let out = '';
   for (let i = 0; i < strings.length; i++) {
     out += strings[i];
     if (i < values.length) {
       const v = values[i];
       if (v && typeof v === 'object' && Object.prototype.hasOwnProperty.call(v, 'raw')) {
-        traceBranch('Utils', 'buildShellCommand', 'RAW_VALUE', { value: String(v.raw) });
+        trace('Utils', () => `BRANCH: buildShellCommand => RAW_VALUE | ${JSON.stringify({ value: String(v.raw) }, null, 2)}`);
         out += String(v.raw);
       } else {
         const quoted = quote(v);
-        traceBranch('Utils', 'buildShellCommand', 'QUOTED_VALUE', { original: v, quoted });
+        trace('Utils', () => `BRANCH: buildShellCommand => QUOTED_VALUE | ${JSON.stringify({ original: v, quoted }, null, 2)}`);
         out += quoted;
       }
     }
   }
-  
-  traceFunc('Utils', 'buildShellCommand', 'EXIT', { command: out });
+
+  trace('Utils', () => `buildShellCommand EXIT | ${JSON.stringify({ command: out }, null, 2)}`);
   return out;
 }
 
@@ -155,12 +465,12 @@ async function pumpReadable(readable, onChunk) {
 class ProcessRunner extends StreamEmitter {
   constructor(spec, options = {}) {
     super();
-    
-    traceFunc('ProcessRunner', 'constructor', 'ENTER', { 
+
+    trace('ProcessRunner', () => `constructor ENTER | ${JSON.stringify({
       spec: typeof spec === 'object' ? { ...spec, command: spec.command?.slice(0, 100) } : spec,
-      options 
-    });
-    
+      options
+    }, null, 2)}`);
+
     this.spec = spec;
     this.options = {
       mirror: true,
@@ -170,168 +480,293 @@ class ProcessRunner extends StreamEmitter {
       env: undefined,
       ...options
     };
-    
+
     this.outChunks = this.options.capture ? [] : null;
     this.errChunks = this.options.capture ? [] : null;
-    this.inChunks = this.options.capture && this.options.stdin === 'inherit' ? [] : 
-                   this.options.capture && (typeof this.options.stdin === 'string' || Buffer.isBuffer(this.options.stdin)) ? 
-                   [Buffer.from(this.options.stdin)] : [];
-    
+    this.inChunks = this.options.capture && this.options.stdin === 'inherit' ? [] :
+      this.options.capture && (typeof this.options.stdin === 'string' || Buffer.isBuffer(this.options.stdin)) ?
+        [Buffer.from(this.options.stdin)] : [];
+
     this.result = null;
     this.child = null;
     this.started = false;
     this.finished = false;
-    
+
     // Promise for awaiting final result
     this.promise = null;
-    
-    // Track the execution mode
+
     this._mode = null; // 'async' or 'sync'
-    
-    // Cancellation support for virtual commands
+
     this._cancelled = false;
     this._virtualGenerator = null;
     this._abortController = new AbortController();
+
+    activeProcessRunners.add(this);
+
+    // Track finished state changes to trigger cleanup
+    this._finished = false;
+  }
+
+  get finished() {
+    return this._finished;
+  }
+
+  _emitProcessedData(type, buf) {
+    const processedBuf = processOutput(buf, this.options.ansi);
+    this.emit(type, processedBuf);
+    this.emit('data', { type, data: processedBuf });
+  }
+
+  async _forwardTTYStdin() {
+    if (!process.stdin.isTTY || !this.child.stdin) {
+      return;
+    }
+
+    try {
+      // Set raw mode to forward keystrokes immediately
+      if (process.stdin.setRawMode) {
+        process.stdin.setRawMode(true);
+      }
+      process.stdin.resume();
+
+      // Forward stdin data to child process
+      const onData = (chunk) => {
+        if (this.child.stdin) {
+          if (isBun && this.child.stdin.write) {
+            this.child.stdin.write(chunk);
+          } else if (this.child.stdin.write) {
+            this.child.stdin.write(chunk);
+          }
+        }
+      };
+
+      const cleanup = () => {
+        process.stdin.removeListener('data', onData);
+        if (process.stdin.setRawMode) {
+          process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+      };
+
+      process.stdin.on('data', onData);
+
+      // Clean up when child process exits
+      const childExit = isBun ? this.child.exited : new Promise((resolve) => {
+        this.child.once('close', resolve);
+        this.child.once('exit', resolve);
+      });
+
+      childExit.then(cleanup).catch(cleanup);
+
+      return childExit;
+    } catch (error) {
+      trace('ProcessRunner', () => `TTY stdin forwarding error | ${JSON.stringify({ error: error.message }, null, 2)}`);
+    }
+  }
+
+  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;
+
+    trace('ProcessRunner', () => `Handling parent stream closure | ${JSON.stringify({
+      started: this.started,
+      hasChild: !!this.child,
+      command: this.spec.command?.slice(0, 50) || this.spec.file
+    }, null, 2)}`);
+
+    this._cancelled = true;
+
+    // Cancel abort controller for virtual commands
+    if (this._abortController) {
+      this._abortController.abort();
+    }
+
+    // Gracefully close child process if it exists
+    if (this.child) {
+      try {
+        // Close stdin first to signal completion
+        if (this.child.stdin && typeof this.child.stdin.end === 'function') {
+          this.child.stdin.end();
+        } else if (isBun && this.child.stdin && typeof this.child.stdin.getWriter === 'function') {
+          const writer = this.child.stdin.getWriter();
+          writer.close().catch(() => { }); // Ignore close errors
+        }
+
+        setTimeout(() => {
+          if (this.child && !this.finished) {
+            trace('ProcessRunner', () => 'Terminating child process after parent stream closure');
+            if (typeof this.child.kill === 'function') {
+              this.child.kill('SIGTERM');
+            }
+          }
+        }, 100);
+
+      } catch (error) {
+        trace('ProcessRunner', () => `Error during graceful shutdown | ${JSON.stringify({ error: error.message }, null, 2)}`);
+      }
+    }
+
+    activeProcessRunners.delete(this);
+  }
+
+  _cleanup() {
+    activeProcessRunners.delete(this);
   }
 
   // Unified start method that can work in both async and sync modes
   start(options = {}) {
     const mode = options.mode || 'async';
-    
-    traceFunc('ProcessRunner', 'start', 'ENTER', { mode, options });
-    
+
+    trace('ProcessRunner', () => `start ENTER | ${JSON.stringify({ mode, options }, null, 2)}`);
+
     if (mode === 'sync') {
-      traceBranch('ProcessRunner', 'mode', 'sync', {});
+      trace('ProcessRunner', () => `BRANCH: mode => sync | ${JSON.stringify({}, null, 2)}`);
       return this._startSync();
     } else {
-      traceBranch('ProcessRunner', 'mode', 'async', {});
+      trace('ProcessRunner', () => `BRANCH: mode => async | ${JSON.stringify({}, null, 2)}`);
       return this._startAsync();
     }
   }
-  
+
   // Shortcut for sync mode
   sync() {
     return this.start({ mode: 'sync' });
   }
-  
+
   // Shortcut for async mode
   async() {
     return this.start({ mode: 'async' });
   }
-  
+
   async _startAsync() {
     if (this.started) return this.promise;
     if (this.promise) return this.promise;
-    
+
     this.promise = this._doStartAsync();
     return this.promise;
   }
-  
+
   async _doStartAsync() {
-    traceFunc('ProcessRunner', '_doStartAsync', 'ENTER', { 
+    trace('ProcessRunner', () => `_doStartAsync ENTER | ${JSON.stringify({
       mode: this.spec.mode,
       command: this.spec.command?.slice(0, 100)
-    });
-    
+    }, null, 2)}`);
+
     this.started = true;
     this._mode = 'async';
 
     const { cwd, env, stdin } = this.options;
-    
-    // Handle programmatic pipeline mode
+
     if (this.spec.mode === 'pipeline') {
-      traceBranch('ProcessRunner', 'spec.mode', 'pipeline', { 
+      trace('ProcessRunner', () => `BRANCH: spec.mode => pipeline | ${JSON.stringify({
         hasSource: !!this.spec.source,
         hasDestination: !!this.spec.destination
-      });
+      }, null, 2)}`);
       return await this._runProgrammaticPipeline(this.spec.source, this.spec.destination);
     }
-    
-    // Check if this is a virtual command first
+
     if (this.spec.mode === 'shell') {
-      traceBranch('ProcessRunner', 'spec.mode', 'shell', {});
-      
-      // Parse the command to check for virtual commands or pipelines
+      trace('ProcessRunner', () => `BRANCH: spec.mode => shell | ${JSON.stringify({}, null, 2)}`);
+
       const parsed = this._parseCommand(this.spec.command);
-      trace('ProcessRunner', 'Parsed command', { 
+      trace('ProcessRunner', () => `Parsed command | ${JSON.stringify({
         type: parsed?.type,
         cmd: parsed?.cmd,
         argsCount: parsed?.args?.length
-      });
-      
+      }, null, 2)}`);
+
       if (parsed) {
         if (parsed.type === 'pipeline') {
-          traceBranch('ProcessRunner', 'parsed.type', 'pipeline', { 
-            commandCount: parsed.commands?.length 
-          });
+          trace('ProcessRunner', () => `BRANCH: parsed.type => pipeline | ${JSON.stringify({
+            commandCount: parsed.commands?.length
+          }, null, 2)}`);
           return await this._runPipeline(parsed.commands);
         } else if (parsed.type === 'simple' && virtualCommandsEnabled && virtualCommands.has(parsed.cmd)) {
-          traceBranch('ProcessRunner', 'virtualCommand', parsed.cmd, { 
+          trace('ProcessRunner', () => `BRANCH: virtualCommand => ${parsed.cmd} | ${JSON.stringify({
             isVirtual: true,
-            args: parsed.args 
-          });
+            args: parsed.args
+          }, null, 2)}`);
           return await this._runVirtual(parsed.cmd, parsed.args);
         }
       }
     }
-    
-    const spawnBun = (argv) => {
-      return Bun.spawn(argv, { cwd, env, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
-    };
-    const spawnNode = async (argv) => {
-      const cp = await import('child_process');
-      return cp.spawn(argv[0], argv.slice(1), { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
-    };
 
     const argv = this.spec.mode === 'shell' ? ['sh', '-lc', this.spec.command] : [this.spec.file, ...this.spec.args];
-    
-    // Shell tracing (set -x equivalent)
+
     if (globalShellSettings.xtrace) {
       const traceCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
       console.log(`+ ${traceCmd}`);
     }
-    
-    // Verbose mode (set -v equivalent)
+
     if (globalShellSettings.verbose) {
       const verboseCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
       console.log(verboseCmd);
     }
-    
+
+    // Detect if this is an interactive command that needs direct TTY access
+    // Only activate for interactive commands when we have a real TTY and the command is likely to need it
+    const isInteractive = stdin === 'inherit' && 
+      process.stdin.isTTY === true && 
+      process.stdout.isTTY === true && 
+      process.stderr.isTTY === true &&
+      (this.spec.mode === 'shell' ? isInteractiveCommand(this.spec.command) : isInteractiveCommand(this.spec.file));
+
+    const spawnBun = (argv) => {
+      if (isInteractive) {
+        // For interactive commands, use inherit to provide direct TTY access
+        return Bun.spawn(argv, { cwd, env, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' });
+      }
+      return Bun.spawn(argv, { cwd, env, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+    };
+    const spawnNode = async (argv) => {
+      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'] });
+    };
+
     const needsExplicitPipe = stdin !== 'inherit' && stdin !== 'ignore';
     const preferNodeForInput = isBun && needsExplicitPipe;
     this.child = preferNodeForInput ? await spawnNode(argv) : (isBun ? spawnBun(argv) : await spawnNode(argv));
 
-    // Setup stdout streaming
-    const outPump = pumpReadable(this.child.stdout, async (buf) => {
+    // For interactive commands with stdio: 'inherit', stdout/stderr will be null
+    const outPump = this.child.stdout ? pumpReadable(this.child.stdout, async (buf) => {
       if (this.options.capture) this.outChunks.push(buf);
-      if (this.options.mirror) process.stdout.write(buf);
-      
+      if (this.options.mirror) safeWrite(process.stdout, buf);
+
       // Emit chunk events
-      this.emit('stdout', buf);
-      this.emit('data', { type: 'stdout', data: buf });
-    });
+      this._emitProcessedData('stdout', buf);
+    }) : Promise.resolve();
 
-    // Setup stderr streaming  
-    const errPump = pumpReadable(this.child.stderr, async (buf) => {
+    const errPump = this.child.stderr ? pumpReadable(this.child.stderr, async (buf) => {
       if (this.options.capture) this.errChunks.push(buf);
-      if (this.options.mirror) process.stderr.write(buf);
-      
+      if (this.options.mirror) safeWrite(process.stderr, buf);
+
       // Emit chunk events
-      this.emit('stderr', buf);
-      this.emit('data', { type: 'stderr', data: buf });
-    });
+      this._emitProcessedData('stderr', buf);
+    }) : Promise.resolve();
 
-    // Handle stdin
     let stdinPumpPromise = Promise.resolve();
     if (stdin === 'inherit') {
-      const isPipedIn = process.stdin && process.stdin.isTTY === false;
-      if (isPipedIn) {
-        stdinPumpPromise = this._pumpStdinTo(this.child, this.options.capture ? this.inChunks : null);
+      if (isInteractive) {
+        // For interactive commands with stdio: 'inherit', stdin is handled automatically
+        stdinPumpPromise = Promise.resolve();
       } else {
-        if (this.child.stdin && typeof this.child.stdin.end === 'function') {
-          try { this.child.stdin.end(); } catch {}
-        } else if (isBun && this.child.stdin && typeof this.child.stdin.getWriter === 'function') {
-          try { const w = this.child.stdin.getWriter(); await w.close(); } catch {}
+        const isPipedIn = process.stdin && process.stdin.isTTY === false;
+        if (isPipedIn) {
+          stdinPumpPromise = this._pumpStdinTo(this.child, this.options.capture ? this.inChunks : null);
+        } else {
+          // For TTY (interactive terminal), forward stdin directly for non-interactive commands
+          stdinPumpPromise = this._forwardTTYStdin();
         }
       }
     } else if (stdin === 'ignore') {
@@ -347,12 +782,12 @@ class ProcessRunner extends StreamEmitter {
     await Promise.all([outPump, errPump, stdinPumpPromise]);
 
     // Debug: Check the raw exit code
-    trace('ProcessRunner', 'Raw exit code from child', { 
+    trace('ProcessRunner', () => `Raw exit code from child | ${JSON.stringify({
       code,
       codeType: typeof code,
       childExitCode: this.child?.exitCode,
       isBun
-    });
+    }, null, 2)}`);
 
     const resultData = {
       code: code ?? 0,  // Default to 0 if exit code is null/undefined
@@ -361,10 +796,9 @@ class ProcessRunner extends StreamEmitter {
       stdin: this.options.capture && this.inChunks ? Buffer.concat(this.inChunks).toString('utf8') : undefined,
       child: this.child
     };
-    
+
     this.result = {
       ...resultData,
-      // Bun.$ compatibility method
       async text() {
         return resultData.stdout || '';
       }
@@ -373,8 +807,7 @@ class ProcessRunner extends StreamEmitter {
     this.finished = true;
     this.emit('end', this.result);
     this.emit('exit', this.result.code);
-    
-    // Handle shell settings (set -e equivalent)
+
     if (globalShellSettings.errexit && this.result.code !== 0) {
       const error = new Error(`Command failed with exit code ${this.result.code}`);
       error.code = this.result.code;
@@ -383,7 +816,7 @@ class ProcessRunner extends StreamEmitter {
       error.result = this.result;
       throw error;
     }
-    
+
     return this.result;
   }
 
@@ -394,7 +827,11 @@ class ProcessRunner extends StreamEmitter {
       const buf = asBuffer(chunk);
       captureChunks && captureChunks.push(buf);
       if (bunWriter) await bunWriter.write(buf);
-      else if (typeof child.stdin.write === 'function') child.stdin.write(buf);
+      else if (typeof child.stdin.write === 'function') {
+        // Use StreamUtils for consistent stdin handling
+        StreamUtils.addStdinErrorHandler(child.stdin, 'child stdin buffer');
+        StreamUtils.safeStreamWrite(child.stdin, buf, 'child stdin buffer');
+      }
       else if (isBun && typeof Bun.write === 'function') await Bun.write(child.stdin, buf);
     }
     if (bunWriter) await bunWriter.close();
@@ -402,13 +839,14 @@ class ProcessRunner extends StreamEmitter {
   }
 
   async _writeToStdin(buf) {
-    if (isBun && this.child.stdin && typeof this.child.stdin.getWriter === 'function') {
-      const w = this.child.stdin.getWriter();
-      const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf.buffer, buf.byteOffset ?? 0, buf.byteLength);
-      await w.write(bytes);
-      await w.close();
-    } else if (this.child.stdin && typeof this.child.stdin.write === 'function') {
-      this.child.stdin.end(buf);
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf.buffer, buf.byteOffset ?? 0, buf.byteLength);
+    if (await StreamUtils.writeToStream(this.child.stdin, bytes, 'stdin')) {
+      // Successfully wrote to stream
+      if (StreamUtils.isBunStream(this.child.stdin)) {
+        // Stream was already closed by writeToStream utility
+      } else if (StreamUtils.isNodeStream(this.child.stdin)) {
+        try { this.child.stdin.end(); } catch { }
+      }
     } else if (isBun && typeof Bun.write === 'function') {
       await Bun.write(this.child.stdin, buf);
     }
@@ -417,26 +855,25 @@ class ProcessRunner extends StreamEmitter {
   _parseCommand(command) {
     const trimmed = command.trim();
     if (!trimmed) return null;
-    
-    // Check for pipes
+
     if (trimmed.includes('|')) {
       return this._parsePipeline(trimmed);
     }
-    
+
     // Simple command parsing
     const parts = trimmed.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
     if (parts.length === 0) return null;
-    
+
     const cmd = parts[0];
     const args = parts.slice(1).map(arg => {
       // Keep track of whether the arg was quoted
-      if ((arg.startsWith('"') && arg.endsWith('"')) || 
-          (arg.startsWith("'") && arg.endsWith("'"))) {
+      if ((arg.startsWith('"') && arg.endsWith('"')) ||
+        (arg.startsWith("'") && arg.endsWith("'"))) {
         return { value: arg.slice(1, -1), quoted: true, quoteChar: arg[0] };
       }
       return { value: arg, quoted: false };
     });
-    
+
     return { cmd, args, type: 'simple' };
   }
 
@@ -446,10 +883,10 @@ class ProcessRunner extends StreamEmitter {
     let current = '';
     let inQuotes = false;
     let quoteChar = '';
-    
+
     for (let i = 0; i < command.length; i++) {
       const char = command[i];
-      
+
       if (!inQuotes && (char === '"' || char === "'")) {
         inQuotes = true;
         quoteChar = char;
@@ -465,46 +902,44 @@ class ProcessRunner extends StreamEmitter {
         current += char;
       }
     }
-    
+
     if (current.trim()) {
       segments.push(current.trim());
     }
-    
-    // Parse each segment as a simple command
+
     const commands = segments.map(segment => {
       const parts = segment.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
       if (parts.length === 0) return null;
-      
+
       const cmd = parts[0];
       const args = parts.slice(1).map(arg => {
         // Keep track of whether the arg was quoted
-        if ((arg.startsWith('"') && arg.endsWith('"')) || 
-            (arg.startsWith("'") && arg.endsWith("'"))) {
-          // Store the original with quotes for system commands
+        if ((arg.startsWith('"') && arg.endsWith('"')) ||
+          (arg.startsWith("'") && arg.endsWith("'"))) {
           return { value: arg.slice(1, -1), quoted: true, quoteChar: arg[0] };
         }
         return { value: arg, quoted: false };
       });
-      
+
       return { cmd, args };
     }).filter(Boolean);
-    
+
     return { type: 'pipeline', commands };
   }
 
   async _runVirtual(cmd, args) {
-    traceFunc('ProcessRunner', '_runVirtual', 'ENTER', { cmd, args });
-    
+    trace('ProcessRunner', () => `_runVirtual ENTER | ${JSON.stringify({ cmd, args }, null, 2)}`);
+
     const handler = virtualCommands.get(cmd);
     if (!handler) {
-      trace('ProcessRunner', 'Virtual command not found', { cmd });
+      trace('ProcessRunner', () => `Virtual command not found | ${JSON.stringify({ cmd }, null, 2)}`);
       throw new Error(`Virtual command not found: ${cmd}`);
     }
 
-    trace('ProcessRunner', 'Found virtual command handler', { 
+    trace('ProcessRunner', () => `Found virtual command handler | ${JSON.stringify({
       cmd,
       isGenerator: handler.constructor.name === 'AsyncGeneratorFunction'
-    });
+    }, null, 2)}`);
 
     try {
       // Prepare stdin
@@ -526,40 +961,34 @@ class ProcessRunner extends StreamEmitter {
         console.log(`${cmd} ${argValues.join(' ')}`);
       }
 
-      // Execute the virtual command
       let result;
-      
-      // Check if handler is async generator (streaming)
+
       if (handler.constructor.name === 'AsyncGeneratorFunction') {
-        // Handle streaming virtual command with cancellation support
         const chunks = [];
-        
-        // Create options with cancellation check and abort signal
+
         const commandOptions = {
           ...this.options,
           isCancelled: () => this._cancelled,
           signal: this._abortController.signal
         };
-        
-        const generator = handler(argValues, stdinData, commandOptions);
+
+        const generator = handler({ args: argValues, stdin: stdinData, ...commandOptions });
         this._virtualGenerator = generator;
-        
-        // Create a promise that resolves when cancelled
+
         const cancelPromise = new Promise(resolve => {
           this._cancelResolve = resolve;
         });
-        
+
         try {
           const iterator = generator[Symbol.asyncIterator]();
           let done = false;
-          
+
           while (!done && !this._cancelled) {
-            // Race between getting next value and cancellation
             const result = await Promise.race([
               iterator.next(),
               cancelPromise.then(() => ({ done: true, cancelled: true }))
             ]);
-            
+
             if (result.cancelled || this._cancelled) {
               // Cancelled - close the generator
               if (iterator.return) {
@@ -567,22 +996,21 @@ class ProcessRunner extends StreamEmitter {
               }
               break;
             }
-            
+
             done = result.done;
-            
+
             if (!done) {
               const chunk = result.value;
               const buf = Buffer.from(chunk);
               chunks.push(buf);
-              
+
               // Only output if not cancelled
               if (!this._cancelled) {
                 if (this.options.mirror) {
-                  process.stdout.write(buf);
+                  safeWrite(process.stdout, buf);
                 }
-                
-                this.emit('stdout', buf);
-                this.emit('data', { type: 'stdout', data: buf });
+
+                this._emitProcessedData('stdout', buf);
               }
             }
           }
@@ -591,7 +1019,7 @@ class ProcessRunner extends StreamEmitter {
           this._virtualGenerator = null;
           this._cancelResolve = null;
         }
-        
+
         result = {
           code: 0,
           stdout: this.options.capture ? Buffer.concat(chunks).toString('utf8') : undefined,
@@ -600,9 +1028,8 @@ class ProcessRunner extends StreamEmitter {
         };
       } else {
         // Regular async function
-        result = await handler(argValues, stdinData, this.options);
-        
-        // Ensure result has required fields, respecting capture option
+        result = await handler({ args: argValues, stdin: stdinData, ...this.options });
+
         result = {
           code: result.code ?? 0,
           stdout: this.options.capture ? (result.stdout ?? '') : undefined,
@@ -610,36 +1037,33 @@ class ProcessRunner extends StreamEmitter {
           stdin: this.options.capture ? stdinData : undefined,
           ...result
         };
-        
+
         // Mirror and emit output
         if (result.stdout) {
           const buf = Buffer.from(result.stdout);
           if (this.options.mirror) {
-            process.stdout.write(buf);
+            safeWrite(process.stdout, buf);
           }
-          this.emit('stdout', buf);
-          this.emit('data', { type: 'stdout', data: buf });
+          this._emitProcessedData('stdout', buf);
         }
-        
+
         if (result.stderr) {
           const buf = Buffer.from(result.stderr);
           if (this.options.mirror) {
-            process.stderr.write(buf);
+            safeWrite(process.stderr, buf);
           }
-          this.emit('stderr', buf);
-          this.emit('data', { type: 'stderr', data: buf });
+          this._emitProcessedData('stderr', buf);
         }
       }
 
       // Store result
       this.result = result;
       this.finished = true;
-      
+
       // Emit completion events
       this.emit('end', result);
       this.emit('exit', result.code);
-      
-      // Handle shell settings
+
       if (globalShellSettings.errexit && result.code !== 0) {
         const error = new Error(`Command failed with exit code ${result.code}`);
         error.code = result.code;
@@ -648,87 +1072,84 @@ class ProcessRunner extends StreamEmitter {
         error.result = result;
         throw error;
       }
-      
+
       return result;
     } catch (error) {
-      // Handle errors from virtual commands
       const result = {
         code: error.code ?? 1,
         stdout: error.stdout ?? '',
         stderr: error.stderr ?? error.message,
         stdin: ''
       };
-      
+
       this.result = result;
       this.finished = true;
-      
+
       if (result.stderr) {
         const buf = Buffer.from(result.stderr);
         if (this.options.mirror) {
-          process.stderr.write(buf);
+          safeWrite(process.stderr, buf);
         }
-        this.emit('stderr', buf);
-        this.emit('data', { type: 'stderr', data: buf });
+        this._emitProcessedData('stderr', buf);
       }
-      
+
       this.emit('end', result);
       this.emit('exit', result.code);
-      
+
       if (globalShellSettings.errexit) {
         throw error;
       }
-      
+
       return result;
     }
   }
 
   async _runStreamingPipelineBun(commands) {
-    traceFunc('ProcessRunner', '_runStreamingPipelineBun', 'ENTER', { 
-      commandsCount: commands.length 
-    });
-    
+    trace('ProcessRunner', () => `_runStreamingPipelineBun ENTER | ${JSON.stringify({
+      commandsCount: commands.length
+    }, null, 2)}`);
+
     // For true streaming, we need to handle virtual and real commands differently
-    // but make them work together seamlessly
-    
+
     // First, analyze the pipeline to identify virtual vs real commands
     const pipelineInfo = commands.map(command => {
       const { cmd, args } = command;
       const isVirtual = virtualCommandsEnabled && virtualCommands.has(cmd);
       return { ...command, isVirtual };
     });
-    
-    trace('ProcessRunner', 'Pipeline analysis', { 
+
+    trace('ProcessRunner', () => `Pipeline analysis | ${JSON.stringify({
       virtualCount: pipelineInfo.filter(p => p.isVirtual).length,
-      realCount: pipelineInfo.filter(p => !p.isVirtual).length 
-    });
-    
+      realCount: pipelineInfo.filter(p => !p.isVirtual).length
+    }, null, 2)}`);
+
     // If pipeline contains virtual commands, use advanced streaming
     if (pipelineInfo.some(info => info.isVirtual)) {
-      traceBranch('ProcessRunner', '_runStreamingPipelineBun', 'MIXED_PIPELINE', {});
+      trace('ProcessRunner', () => `BRANCH: _runStreamingPipelineBun => MIXED_PIPELINE | ${JSON.stringify({}, null, 2)}`);
       return this._runMixedStreamingPipeline(commands);
     }
-    
+
     // For pipelines with commands that buffer (like jq), use tee streaming
-    const needsStreamingWorkaround = commands.some(c => 
+    const needsStreamingWorkaround = commands.some(c =>
       c.cmd === 'jq' || c.cmd === 'grep' || c.cmd === 'sed' || c.cmd === 'cat' || c.cmd === 'awk'
     );
     if (needsStreamingWorkaround) {
-      traceBranch('ProcessRunner', '_runStreamingPipelineBun', 'TEE_STREAMING', { 
-        bufferedCommands: commands.filter(c => 
+      trace('ProcessRunner', () => `BRANCH: _runStreamingPipelineBun => TEE_STREAMING | ${JSON.stringify({
+        bufferedCommands: commands.filter(c =>
           ['jq', 'grep', 'sed', 'cat', 'awk'].includes(c.cmd)
         ).map(c => c.cmd)
-      });
+      }, null, 2)}`);
       return this._runTeeStreamingPipeline(commands);
     }
-    
+
     // All real commands - use native pipe connections
     const processes = [];
     let allStderr = '';
-    
+
     for (let i = 0; i < commands.length; i++) {
       const command = commands[i];
       const { cmd, args } = command;
-      
+
       // Build command string
       const commandParts = [cmd];
       for (const arg of args) {
@@ -749,12 +1170,12 @@ class ProcessRunner extends StreamEmitter {
         }
       }
       const commandStr = commandParts.join(' ');
-      
+
       // Determine stdin for this process
       let stdin;
       let needsManualStdin = false;
       let stdinData;
-      
+
       if (i === 0) {
         // First command - use provided stdin or pipe
         if (this.options.stdin && typeof this.options.stdin === 'string') {
@@ -772,18 +1193,17 @@ class ProcessRunner extends StreamEmitter {
         // Connect to previous process stdout
         stdin = processes[i - 1].stdout;
       }
-      
-      // Spawn the process directly (not through sh) for better streaming
+
       // Only use sh -c for complex commands that need shell features
-      const needsShell = commandStr.includes('*') || commandStr.includes('$') || 
-                         commandStr.includes('>') || commandStr.includes('<') ||
-                         commandStr.includes('&&') || commandStr.includes('||') ||
-                         commandStr.includes(';') || commandStr.includes('`');
-      
-      const spawnArgs = needsShell 
+      const needsShell = commandStr.includes('*') || commandStr.includes('$') ||
+        commandStr.includes('>') || commandStr.includes('<') ||
+        commandStr.includes('&&') || commandStr.includes('||') ||
+        commandStr.includes(';') || commandStr.includes('`');
+
+      const spawnArgs = needsShell
         ? ['sh', '-c', commandStr]
         : [cmd, ...args.map(a => a.value !== undefined ? a.value : a)];
-      
+
       const proc = Bun.spawn(spawnArgs, {
         cwd: this.options.cwd,
         env: this.options.env,
@@ -791,22 +1211,28 @@ class ProcessRunner extends StreamEmitter {
         stdout: 'pipe',
         stderr: 'pipe'
       });
-      
+
       // Write stdin data if needed for first process
       if (needsManualStdin && stdinData && proc.stdin) {
+        // Use StreamUtils for consistent stdin handling
+        const stdinHandler = StreamUtils.setupStdinHandling(proc.stdin, 'Bun process stdin');
+
         (async () => {
           try {
-            // Bun's FileSink has write and end methods
-            await proc.stdin.write(stdinData);
-            await proc.stdin.end();
+            if (stdinHandler.isWritable()) {
+              await proc.stdin.write(stdinData); // Bun's FileSink async write
+              await proc.stdin.end();
+            }
           } catch (e) {
-            console.error('Error writing stdin:', e);
+            if (e.code !== 'EPIPE') {
+              trace('ProcessRunner', () => `Error with Bun stdin async operations | ${JSON.stringify({ error: e.message, code: e.code }, null, 2)}`);
+            }
           }
         })();
       }
-      
+
       processes.push(proc);
-      
+
       // Collect stderr from all processes
       (async () => {
         for await (const chunk of proc.stderr) {
@@ -815,35 +1241,32 @@ class ProcessRunner extends StreamEmitter {
           // Only emit stderr for the last command
           if (i === commands.length - 1) {
             if (this.options.mirror) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
-            this.emit('stderr', buf);
-            this.emit('data', { type: 'stderr', data: buf });
+            this._emitProcessedData('stderr', buf);
           }
         }
       })();
     }
-    
+
     // Stream output from the last process
     const lastProc = processes[processes.length - 1];
     let finalOutput = '';
-    
+
     // Stream stdout from last process
     for await (const chunk of lastProc.stdout) {
       const buf = Buffer.from(chunk);
       finalOutput += buf.toString();
       if (this.options.mirror) {
-        process.stdout.write(buf);
+        safeWrite(process.stdout, buf);
       }
-      this.emit('stdout', buf);
-      this.emit('data', { type: 'stdout', data: buf });
+      this._emitProcessedData('stdout', buf);
     }
-    
+
     // Wait for all processes to complete
     const exitCodes = await Promise.all(processes.map(p => p.exited));
     const lastExitCode = exitCodes[exitCodes.length - 1];
-    
-    // Check for pipeline failures if pipefail is set
+
     if (globalShellSettings.pipefail) {
       const failedIndex = exitCodes.findIndex(code => code !== 0);
       if (failedIndex !== -1) {
@@ -852,21 +1275,21 @@ class ProcessRunner extends StreamEmitter {
         throw error;
       }
     }
-    
+
     const result = createResult({
       code: lastExitCode || 0,
       stdout: finalOutput,
       stderr: allStderr,
-      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-             this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+        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);
-    
+
     if (globalShellSettings.errexit && result.code !== 0) {
       const error = new Error(`Pipeline failed with exit code ${result.code}`);
       error.code = result.code;
@@ -875,26 +1298,26 @@ class ProcessRunner extends StreamEmitter {
       error.result = result;
       throw error;
     }
-    
+
     return result;
   }
 
   async _runTeeStreamingPipeline(commands) {
-    traceFunc('ProcessRunner', '_runTeeStreamingPipeline', 'ENTER', { 
-      commandsCount: commands.length 
-    });
-    
+    trace('ProcessRunner', () => `_runTeeStreamingPipeline ENTER | ${JSON.stringify({
+      commandsCount: commands.length
+    }, null, 2)}`);
+
     // Use tee() to split streams for real-time reading
     // This works around jq and similar commands that buffer when piped
-    
+
     const processes = [];
     let allStderr = '';
     let currentStream = null;
-    
+
     for (let i = 0; i < commands.length; i++) {
       const command = commands[i];
       const { cmd, args } = command;
-      
+
       // Build command string
       const commandParts = [cmd];
       for (const arg of args) {
@@ -915,12 +1338,12 @@ class ProcessRunner extends StreamEmitter {
         }
       }
       const commandStr = commandParts.join(' ');
-      
+
       // Determine stdin for this process
       let stdin;
       let needsManualStdin = false;
       let stdinData;
-      
+
       if (i === 0) {
         // First command - use provided stdin or ignore
         if (this.options.stdin && typeof this.options.stdin === 'string') {
@@ -935,20 +1358,18 @@ class ProcessRunner extends StreamEmitter {
           stdin = 'ignore';
         }
       } else {
-        // Use the stream from previous process
         stdin = currentStream;
       }
-      
-      // Spawn the process directly (not through sh) for better control
-      const needsShell = commandStr.includes('*') || commandStr.includes('$') || 
-                         commandStr.includes('>') || commandStr.includes('<') ||
-                         commandStr.includes('&&') || commandStr.includes('||') ||
-                         commandStr.includes(';') || commandStr.includes('`');
-      
-      const spawnArgs = needsShell 
+
+      const needsShell = commandStr.includes('*') || commandStr.includes('$') ||
+        commandStr.includes('>') || commandStr.includes('<') ||
+        commandStr.includes('&&') || commandStr.includes('||') ||
+        commandStr.includes(';') || commandStr.includes('`');
+
+      const spawnArgs = needsShell
         ? ['sh', '-c', commandStr]
         : [cmd, ...args.map(a => a.value !== undefined ? a.value : a)];
-      
+
       const proc = Bun.spawn(spawnArgs, {
         cwd: this.options.cwd,
         env: this.options.env,
@@ -956,50 +1377,41 @@ class ProcessRunner extends StreamEmitter {
         stdout: 'pipe',
         stderr: 'pipe'
       });
-      
+
       // Write stdin data if needed for first process
       if (needsManualStdin && stdinData && proc.stdin) {
+        // Use StreamUtils for consistent stdin handling
+        const stdinHandler = StreamUtils.setupStdinHandling(proc.stdin, 'Node process stdin');
+
         try {
-          await proc.stdin.write(stdinData);
-          await proc.stdin.end();
+          if (stdinHandler.isWritable()) {
+            await proc.stdin.write(stdinData); // Node async write
+            await proc.stdin.end();
+          }
         } catch (e) {
-          // Ignore stdin errors
+          if (e.code !== 'EPIPE') {
+            trace('ProcessRunner', () => `Error with Node stdin async operations | ${JSON.stringify({ error: e.message, code: e.code }, null, 2)}`);
+          }
         }
       }
-      
+
       processes.push(proc);
-      
+
       // For non-last processes, tee the output so we can both pipe and read
       if (i < commands.length - 1) {
         const [readStream, pipeStream] = proc.stdout.tee();
         currentStream = pipeStream;
-        
-        // Read from the tee'd stream for real-time updates
-        // Always read from the first process for best streaming
-        if (i === 0) {
-          (async () => {
-            for await (const chunk of readStream) {
-              // Emit from the first process for real-time updates
-              const buf = Buffer.from(chunk);
-              if (this.options.mirror) {
-                process.stdout.write(buf);
-              }
-              this.emit('stdout', buf);
-              this.emit('data', { type: 'stdout', data: buf });
-            }
-          })();
-        } else {
-          // Consume other tee'd streams to prevent blocking
-          (async () => {
-            for await (const chunk of readStream) {
-              // Just consume to keep flowing
-            }
-          })();
-        }
+
+        // Read from the tee'd stream to keep it flowing
+        (async () => {
+          for await (const chunk of readStream) {
+            // Just consume to keep flowing - don't emit intermediate output
+          }
+        })();
       } else {
         currentStream = proc.stdout;
       }
-      
+
       // Collect stderr from all processes
       (async () => {
         for await (const chunk of proc.stderr) {
@@ -1007,39 +1419,32 @@ class ProcessRunner extends StreamEmitter {
           allStderr += buf.toString();
           if (i === commands.length - 1) {
             if (this.options.mirror) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
-            this.emit('stderr', buf);
-            this.emit('data', { type: 'stderr', data: buf });
+            this._emitProcessedData('stderr', buf);
           }
         }
       })();
     }
-    
+
     // Read final output from the last process
     const lastProc = processes[processes.length - 1];
     let finalOutput = '';
-    
-    // If we haven't emitted stdout yet (no tee), emit from last process
-    const shouldEmitFromLast = commands.length === 1;
-    
+
+    // Always emit from the last process for proper pipeline output
     for await (const chunk of lastProc.stdout) {
       const buf = Buffer.from(chunk);
       finalOutput += buf.toString();
-      if (shouldEmitFromLast) {
-        if (this.options.mirror) {
-          process.stdout.write(buf);
-        }
-        this.emit('stdout', buf);
-        this.emit('data', { type: 'stdout', data: buf });
+      if (this.options.mirror) {
+        safeWrite(process.stdout, buf);
       }
+      this._emitProcessedData('stdout', buf);
     }
-    
+
     // Wait for all processes to complete
     const exitCodes = await Promise.all(processes.map(p => p.exited));
     const lastExitCode = exitCodes[exitCodes.length - 1];
-    
-    // Check for pipeline failures if pipefail is set
+
     if (globalShellSettings.pipefail) {
       const failedIndex = exitCodes.findIndex(code => code !== 0);
       if (failedIndex !== -1) {
@@ -1048,21 +1453,21 @@ class ProcessRunner extends StreamEmitter {
         throw error;
       }
     }
-    
+
     const result = createResult({
       code: lastExitCode || 0,
       stdout: finalOutput,
       stderr: allStderr,
-      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-             this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+        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);
-    
+
     if (globalShellSettings.errexit && result.code !== 0) {
       const error = new Error(`Pipeline failed with exit code ${result.code}`);
       error.code = result.code;
@@ -1071,30 +1476,27 @@ class ProcessRunner extends StreamEmitter {
       error.result = result;
       throw error;
     }
-    
+
     return result;
   }
 
 
   async _runMixedStreamingPipeline(commands) {
-    traceFunc('ProcessRunner', '_runMixedStreamingPipeline', 'ENTER', { 
-      commandsCount: commands.length 
-    });
-    
-    // Handle pipelines with both virtual and real commands
+    trace('ProcessRunner', () => `_runMixedStreamingPipeline ENTER | ${JSON.stringify({
+      commandsCount: commands.length
+    }, null, 2)}`);
+
     // Each stage reads from previous stage's output stream
-    
+
     let currentInputStream = null;
     let finalOutput = '';
     let allStderr = '';
-    
-    // Set up initial input stream if provided
+
     if (this.options.stdin) {
-      const inputData = typeof this.options.stdin === 'string' 
-        ? this.options.stdin 
+      const inputData = typeof this.options.stdin === 'string'
+        ? this.options.stdin
         : this.options.stdin.toString('utf8');
-      
-      // Create a readable stream from the input
+
       currentInputStream = new ReadableStream({
         start(controller) {
           controller.enqueue(new TextEncoder().encode(inputData));
@@ -1102,21 +1504,20 @@ class ProcessRunner extends StreamEmitter {
         }
       });
     }
-    
+
     for (let i = 0; i < commands.length; i++) {
       const command = commands[i];
       const { cmd, args } = command;
       const isLastCommand = i === commands.length - 1;
-      
+
       if (virtualCommandsEnabled && virtualCommands.has(cmd)) {
-        // Handle virtual command with streaming
-        traceBranch('ProcessRunner', '_runMixedStreamingPipeline', 'VIRTUAL_COMMAND', { 
+        trace('ProcessRunner', () => `BRANCH: _runMixedStreamingPipeline => VIRTUAL_COMMAND | ${JSON.stringify({
           cmd,
-          commandIndex: i 
-        });
+          commandIndex: i
+        }, null, 2)}`);
         const handler = virtualCommands.get(cmd);
         const argValues = args.map(arg => arg.value !== undefined ? arg.value : arg);
-        
+
         // Read input from stream if available
         let inputData = '';
         if (currentInputStream) {
@@ -1131,30 +1532,29 @@ class ProcessRunner extends StreamEmitter {
             reader.releaseLock();
           }
         }
-        
-        // Check if handler is async generator (streaming)
+
         if (handler.constructor.name === 'AsyncGeneratorFunction') {
-          // Create output stream from generator
           const chunks = [];
           const self = this; // Capture this context
           currentInputStream = new ReadableStream({
             async start(controller) {
-              for await (const chunk of handler(argValues, inputData, {})) {
+              const { stdin: _, ...optionsWithoutStdin } = self.options;
+              for await (const chunk of handler({ args: argValues, stdin: inputData, ...optionsWithoutStdin })) {
                 const data = Buffer.from(chunk);
                 controller.enqueue(data);
-                
+
                 // Emit for last command
                 if (isLastCommand) {
                   chunks.push(data);
                   if (self.options.mirror) {
-                    process.stdout.write(data);
+                    safeWrite(process.stdout, data);
                   }
                   self.emit('stdout', data);
                   self.emit('data', { type: 'stdout', data });
                 }
               }
               controller.close();
-              
+
               if (isLastCommand) {
                 finalOutput = Buffer.concat(chunks).toString('utf8');
               }
@@ -1162,33 +1562,31 @@ class ProcessRunner extends StreamEmitter {
           });
         } else {
           // Regular async function
-          const result = await handler(argValues, inputData, {});
+          const { stdin: _, ...optionsWithoutStdin } = this.options;
+          const result = await handler({ args: argValues, stdin: inputData, ...optionsWithoutStdin });
           const outputData = result.stdout || '';
-          
+
           if (isLastCommand) {
             finalOutput = outputData;
             const buf = Buffer.from(outputData);
             if (this.options.mirror) {
-              process.stdout.write(buf);
+              safeWrite(process.stdout, buf);
             }
-            this.emit('stdout', buf);
-            this.emit('data', { type: 'stdout', data: buf });
+            this._emitProcessedData('stdout', buf);
           }
-          
-          // Create stream from output
+
           currentInputStream = new ReadableStream({
             start(controller) {
               controller.enqueue(new TextEncoder().encode(outputData));
               controller.close();
             }
           });
-          
+
           if (result.stderr) {
             allStderr += result.stderr;
           }
         }
       } else {
-        // Handle real command - spawn with streaming
         const commandParts = [cmd];
         for (const arg of args) {
           if (arg.value !== undefined) {
@@ -1208,8 +1606,7 @@ class ProcessRunner extends StreamEmitter {
           }
         }
         const commandStr = commandParts.join(' ');
-        
-        // Spawn the process
+
         const proc = Bun.spawn(['sh', '-c', commandStr], {
           cwd: this.options.cwd,
           env: this.options.env,
@@ -1217,23 +1614,33 @@ class ProcessRunner extends StreamEmitter {
           stdout: 'pipe',
           stderr: 'pipe'
         });
-        
+
         // Write input stream to process stdin if needed
         if (currentInputStream && proc.stdin) {
           const reader = currentInputStream.getReader();
           const writer = proc.stdin.getWriter ? proc.stdin.getWriter() : proc.stdin;
-          
+
           (async () => {
             try {
               while (true) {
                 const { done, value } = await reader.read();
                 if (done) break;
                 if (writer.write) {
-                  await writer.write(value);
+                  try {
+                    await writer.write(value);
+                  } catch (error) {
+                    StreamUtils.handleStreamError(error, 'stream writer', false);
+                    break; // Stop streaming if write fails
+                  }
                 } else if (writer.getWriter) {
-                  const w = writer.getWriter();
-                  await w.write(value);
-                  w.releaseLock();
+                  try {
+                    const w = writer.getWriter();
+                    await w.write(value);
+                    w.releaseLock();
+                  } catch (error) {
+                    StreamUtils.handleStreamError(error, 'stream writer (getWriter)', false);
+                    break; // Stop streaming if write fails
+                  }
                 }
               }
             } finally {
@@ -1243,25 +1650,22 @@ class ProcessRunner extends StreamEmitter {
             }
           })();
         }
-        
-        // Set up output stream
+
         currentInputStream = proc.stdout;
-        
-        // Handle stderr
+
         (async () => {
           for await (const chunk of proc.stderr) {
             const buf = Buffer.from(chunk);
             allStderr += buf.toString();
             if (isLastCommand) {
               if (this.options.mirror) {
-                process.stderr.write(buf);
+                safeWrite(process.stderr, buf);
               }
-              this.emit('stderr', buf);
-              this.emit('data', { type: 'stderr', data: buf });
+              this._emitProcessedData('stderr', buf);
             }
           }
         })();
-        
+
         // For last command, stream output
         if (isLastCommand) {
           const chunks = [];
@@ -1269,44 +1673,41 @@ class ProcessRunner extends StreamEmitter {
             const buf = Buffer.from(chunk);
             chunks.push(buf);
             if (this.options.mirror) {
-              process.stdout.write(buf);
+              safeWrite(process.stdout, buf);
             }
-            this.emit('stdout', buf);
-            this.emit('data', { type: 'stdout', data: buf });
+            this._emitProcessedData('stdout', buf);
           }
           finalOutput = Buffer.concat(chunks).toString('utf8');
           await proc.exited;
         }
       }
     }
-    
+
     const result = createResult({
       code: 0, // TODO: Track exit codes properly
       stdout: finalOutput,
       stderr: allStderr,
-      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-             this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+        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);
-    
+
     return result;
   }
 
   async _runPipelineNonStreaming(commands) {
-    traceFunc('ProcessRunner', '_runPipelineNonStreaming', 'ENTER', { 
-      commandsCount: commands.length 
-    });
-    
-    // Original non-streaming implementation for fallback (e.g., virtual commands)
+    trace('ProcessRunner', () => `_runPipelineNonStreaming ENTER | ${JSON.stringify({
+      commandsCount: commands.length
+    }, null, 2)}`);
+
     let currentOutput = '';
     let currentInput = '';
-    
-    // Get initial stdin from options
+
     if (this.options.stdin && typeof this.options.stdin === 'string') {
       currentInput = this.options.stdin;
     } else if (this.options.stdin && Buffer.isBuffer(this.options.stdin)) {
@@ -1317,21 +1718,20 @@ class ProcessRunner extends StreamEmitter {
     for (let i = 0; i < commands.length; i++) {
       const command = commands[i];
       const { cmd, args } = command;
-      
-      // Check if this is a virtual command (only if virtual commands are enabled)
+
       if (virtualCommandsEnabled && virtualCommands.has(cmd)) {
-        traceBranch('ProcessRunner', '_runPipelineNonStreaming', 'VIRTUAL_COMMAND', { 
+        trace('ProcessRunner', () => `BRANCH: _runPipelineNonStreaming => VIRTUAL_COMMAND | ${JSON.stringify({
           cmd,
-          argsCount: args.length 
-        });
-        
+          argsCount: args.length
+        }, null, 2)}`);
+
         // Run virtual command with current input
         const handler = virtualCommands.get(cmd);
-        
+
         try {
           // Extract actual values for virtual command
           const argValues = args.map(arg => arg.value !== undefined ? arg.value : arg);
-          
+
           // Shell tracing for virtual commands
           if (globalShellSettings.xtrace) {
             console.log(`+ ${cmd} ${argValues.join(' ')}`);
@@ -1341,12 +1741,11 @@ class ProcessRunner extends StreamEmitter {
           }
 
           let result;
-          
-          // Check if handler is async generator (streaming)
+
           if (handler.constructor.name === 'AsyncGeneratorFunction') {
-            traceBranch('ProcessRunner', '_runPipelineNonStreaming', 'ASYNC_GENERATOR', { cmd });
+            trace('ProcessRunner', () => `BRANCH: _runPipelineNonStreaming => ASYNC_GENERATOR | ${JSON.stringify({ cmd }, null, 2)}`);
             const chunks = [];
-            for await (const chunk of handler(argValues, currentInput, this.options)) {
+            for await (const chunk of handler({ args: argValues, stdin: currentInput, ...this.options })) {
               chunks.push(Buffer.from(chunk));
             }
             result = {
@@ -1357,7 +1756,7 @@ class ProcessRunner extends StreamEmitter {
             };
           } else {
             // Regular async function
-            result = await handler(argValues, currentInput, this.options);
+            result = await handler({ args: argValues, stdin: currentInput, ...this.options });
             result = {
               code: result.code ?? 0,
               stdout: this.options.capture ? (result.stdout ?? '') : undefined,
@@ -1366,50 +1765,46 @@ class ProcessRunner extends StreamEmitter {
               ...result
             };
           }
-          
+
           // If this isn't the last command, pass stdout as stdin to next command
           if (i < commands.length - 1) {
             currentInput = result.stdout;
           } else {
             // This is the last command - emit output and store final result
             currentOutput = result.stdout;
-            
+
             // Mirror and emit output for final command
             if (result.stdout) {
               const buf = Buffer.from(result.stdout);
               if (this.options.mirror) {
-                process.stdout.write(buf);
+                safeWrite(process.stdout, buf);
               }
-              this.emit('stdout', buf);
-              this.emit('data', { type: 'stdout', data: buf });
+              this._emitProcessedData('stdout', buf);
             }
-            
+
             if (result.stderr) {
               const buf = Buffer.from(result.stderr);
               if (this.options.mirror) {
-                process.stderr.write(buf);
+                safeWrite(process.stderr, buf);
               }
-              this.emit('stderr', buf);
-              this.emit('data', { type: 'stderr', data: buf });
+              this._emitProcessedData('stderr', buf);
             }
-            
-            // Store final result using createResult helper for .text() method compatibility
+
             const finalResult = createResult({
               code: result.code,
               stdout: currentOutput,
               stderr: result.stderr,
-              stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-                     this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+              stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+                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);
-            
-            // Handle shell settings
+
             if (globalShellSettings.errexit && finalResult.code !== 0) {
               const error = new Error(`Pipeline failed with exit code ${finalResult.code}`);
               error.code = finalResult.code;
@@ -1418,11 +1813,10 @@ class ProcessRunner extends StreamEmitter {
               error.result = finalResult;
               throw error;
             }
-            
+
             return finalResult;
           }
-          
-          // Handle errors from intermediate commands
+
           if (globalShellSettings.errexit && result.code !== 0) {
             const error = new Error(`Pipeline command failed with exit code ${result.code}`);
             error.code = result.code;
@@ -1432,34 +1826,32 @@ class ProcessRunner extends StreamEmitter {
             throw error;
           }
         } catch (error) {
-          // Handle errors from virtual commands in pipeline
           const result = createResult({
             code: error.code ?? 1,
             stdout: currentOutput,
             stderr: error.stderr ?? error.message,
-            stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-                   this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+            stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+              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) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
-            this.emit('stderr', buf);
-            this.emit('data', { type: 'stderr', data: buf });
+            this._emitProcessedData('stderr', buf);
           }
-          
+
           this.emit('end', result);
           this.emit('exit', result.code);
-          
+
           if (globalShellSettings.errexit) {
             throw error;
           }
-          
+
           return result;
         }
       } else {
@@ -1469,7 +1861,6 @@ class ProcessRunner extends StreamEmitter {
           const commandParts = [cmd];
           for (const arg of args) {
             if (arg.value !== undefined) {
-              // Handle our parsed arg structure
               if (arg.quoted) {
                 // Preserve original quotes
                 commandParts.push(`${arg.quoteChar}${arg.value}${arg.quoteChar}`);
@@ -1480,7 +1871,6 @@ class ProcessRunner extends StreamEmitter {
                 commandParts.push(arg.value);
               }
             } else {
-              // Handle plain string args (backward compatibility)
               if (typeof arg === 'string' && arg.includes(' ') && !arg.startsWith('"') && !arg.startsWith("'")) {
                 commandParts.push(`"${arg}"`);
               } else {
@@ -1489,7 +1879,7 @@ class ProcessRunner extends StreamEmitter {
             }
           }
           const commandStr = commandParts.join(' ');
-          
+
           // Shell tracing for system commands
           if (globalShellSettings.xtrace) {
             console.log(`+ ${commandStr}`);
@@ -1497,46 +1887,41 @@ class ProcessRunner extends StreamEmitter {
           if (globalShellSettings.verbose) {
             console.log(commandStr);
           }
-          
-          // Execute the system command with current input as stdin (ASYNC VERSION)
+
           const spawnNodeAsync = async (argv, stdin, isLastCommand = false) => {
-            const require = createRequire(import.meta.url);
-            const cp = require('child_process');
-            
+
             return new Promise((resolve, reject) => {
               const proc = cp.spawn(argv[0], argv.slice(1), {
                 cwd: this.options.cwd,
                 env: this.options.env,
                 stdio: ['pipe', 'pipe', 'pipe']
               });
-              
+
               let stdout = '';
               let stderr = '';
-              
+
               proc.stdout.on('data', (chunk) => {
                 stdout += chunk.toString();
                 // If this is the last command, emit streaming data
                 if (isLastCommand) {
                   if (this.options.mirror) {
-                    process.stdout.write(chunk);
+                    safeWrite(process.stdout, chunk);
                   }
-                  this.emit('stdout', chunk);
-                  this.emit('data', { type: 'stdout', data: chunk });
+                  this._emitProcessedData('stdout', chunk);
                 }
               });
-              
+
               proc.stderr.on('data', (chunk) => {
                 stderr += chunk.toString();
                 // If this is the last command, emit streaming data
                 if (isLastCommand) {
                   if (this.options.mirror) {
-                    process.stderr.write(chunk);
+                    safeWrite(process.stderr, chunk);
                   }
-                  this.emit('stderr', chunk);
-                  this.emit('data', { type: 'stderr', data: chunk });
+                  this._emitProcessedData('stderr', chunk);
                 }
               });
-              
+
               proc.on('close', (code) => {
                 resolve({
                   status: code,
@@ -1544,29 +1929,43 @@ class ProcessRunner extends StreamEmitter {
                   stderr
                 });
               });
-              
+
               proc.on('error', reject);
-              
+
+              // Use StreamUtils for comprehensive stdin handling
+              if (proc.stdin) {
+                StreamUtils.addStdinErrorHandler(proc.stdin, 'spawnNodeAsync stdin', reject);
+              }
+
               if (stdin) {
-                proc.stdin.write(stdin);
+                trace('ProcessRunner', () => `Attempting to write stdin to spawnNodeAsync | ${JSON.stringify({
+                  hasStdin: !!proc.stdin,
+                  writable: proc.stdin?.writable,
+                  destroyed: proc.stdin?.destroyed,
+                  closed: proc.stdin?.closed,
+                  stdinLength: stdin.length
+                }, null, 2)}`);
+
+                StreamUtils.safeStreamWrite(proc.stdin, stdin, 'spawnNodeAsync stdin');
               }
-              proc.stdin.end();
+
+              // Safely end the stdin stream
+              StreamUtils.safeStreamEnd(proc.stdin, 'spawnNodeAsync stdin');
             });
           };
-          
+
           // Execute using shell to handle complex commands
           const argv = ['sh', '-c', commandStr];
           const isLastCommand = (i === commands.length - 1);
           const proc = await spawnNodeAsync(argv, currentInput, isLastCommand);
-          
+
           let result = {
             code: proc.status || 0,
             stdout: proc.stdout || '',
             stderr: proc.stderr || '',
             stdin: currentInput
           };
-          
-          // If command failed and pipefail is set, fail the entire pipeline
+
           if (globalShellSettings.pipefail && result.code !== 0) {
             const error = new Error(`Pipeline command '${commandStr}' failed with exit code ${result.code}`);
             error.code = result.code;
@@ -1574,7 +1973,7 @@ class ProcessRunner extends StreamEmitter {
             error.stderr = result.stderr;
             throw error;
           }
-          
+
           // If this isn't the last command, pass stdout as stdin to next command
           if (i < commands.length - 1) {
             currentInput = result.stdout;
@@ -1586,7 +1985,7 @@ class ProcessRunner extends StreamEmitter {
           } else {
             // This is the last command - store final result (streaming already handled during execution)
             currentOutput = result.stdout;
-            
+
             // Collect all accumulated stderr
             let allStderr = '';
             if (this.errChunks && this.errChunks.length > 0) {
@@ -1595,24 +1994,22 @@ class ProcessRunner extends StreamEmitter {
             if (result.stderr) {
               allStderr += result.stderr;
             }
-            
-            // Store final result using createResult helper for .text() method compatibility
+
             const finalResult = createResult({
               code: result.code,
               stdout: currentOutput,
               stderr: allStderr,
-              stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-                     this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+              stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+                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);
-            
-            // Handle shell settings
+
             if (globalShellSettings.errexit && finalResult.code !== 0) {
               const error = new Error(`Pipeline failed with exit code ${finalResult.code}`);
               error.code = finalResult.code;
@@ -1621,39 +2018,37 @@ class ProcessRunner extends StreamEmitter {
               error.result = finalResult;
               throw error;
             }
-            
+
             return finalResult;
           }
-          
+
         } catch (error) {
-          // Handle errors from system commands in pipeline
           const result = createResult({
             code: error.code ?? 1,
             stdout: currentOutput,
             stderr: error.stderr ?? error.message,
-            stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-                   this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+            stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+              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) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
-            this.emit('stderr', buf);
-            this.emit('data', { type: 'stderr', data: buf });
+            this._emitProcessedData('stderr', buf);
           }
-          
+
           this.emit('end', result);
           this.emit('exit', result.code);
-          
+
           if (globalShellSettings.errexit) {
             throw error;
           }
-          
+
           return result;
         }
       }
@@ -1661,110 +2056,103 @@ class ProcessRunner extends StreamEmitter {
   }
 
   async _runPipeline(commands) {
-    traceFunc('ProcessRunner', '_runPipeline', 'ENTER', { 
-      commandsCount: commands.length 
-    });
-    
+    trace('ProcessRunner', () => `_runPipeline ENTER | ${JSON.stringify({
+      commandsCount: commands.length
+    }, null, 2)}`);
+
     if (commands.length === 0) {
-      traceBranch('ProcessRunner', '_runPipeline', 'NO_COMMANDS', {});
+      trace('ProcessRunner', () => `BRANCH: _runPipeline => NO_COMMANDS | ${JSON.stringify({}, null, 2)}`);
       return createResult({ code: 1, stdout: '', stderr: 'No commands in pipeline', stdin: '' });
     }
 
 
     // For true streaming, we need to connect processes via pipes
     if (isBun) {
-      traceBranch('ProcessRunner', '_runPipeline', 'BUN_STREAMING', {});
+      trace('ProcessRunner', () => `BRANCH: _runPipeline => BUN_STREAMING | ${JSON.stringify({}, null, 2)}`);
       return this._runStreamingPipelineBun(commands);
     }
-    
+
     // For Node.js, fall back to non-streaming implementation for now
-    traceBranch('ProcessRunner', '_runPipeline', 'NODE_NON_STREAMING', {});
+    trace('ProcessRunner', () => `BRANCH: _runPipeline => NODE_NON_STREAMING | ${JSON.stringify({}, null, 2)}`);
     return this._runPipelineNonStreaming(commands);
   }
 
   // Run programmatic pipeline (.pipe() method)
   async _runProgrammaticPipeline(source, destination) {
-    traceFunc('ProcessRunner', '_runProgrammaticPipeline', 'ENTER', {});
-    
+    trace('ProcessRunner', () => `_runProgrammaticPipeline ENTER | ${JSON.stringify({}, null, 2)}`);
+
     try {
-      // Execute the source command first
-      trace('ProcessRunner', 'Executing source command', {});
+      trace('ProcessRunner', () => 'Executing source command');
       const sourceResult = await source;
-      
+
       if (sourceResult.code !== 0) {
-        // If source failed, return its result
-        traceBranch('ProcessRunner', '_runProgrammaticPipeline', 'SOURCE_FAILED', { 
+        trace('ProcessRunner', () => `BRANCH: _runProgrammaticPipeline => SOURCE_FAILED | ${JSON.stringify({
           code: sourceResult.code,
-          stderr: sourceResult.stderr 
-        });
+          stderr: sourceResult.stderr
+        }, null, 2)}`);
         return sourceResult;
       }
-      
-      // Create a new ProcessRunner with the correct stdin for the destination
+
       const destWithStdin = new ProcessRunner(destination.spec, {
         ...destination.options,
         stdin: sourceResult.stdout
       });
-      
-      // Execute the destination command
+
       const destResult = await destWithStdin;
-      
+
       // Debug: Log what destResult looks like
-      trace('ProcessRunner', 'destResult debug', { 
-        code: destResult.code, 
+      trace('ProcessRunner', () => `destResult debug | ${JSON.stringify({
+        code: destResult.code,
         codeType: typeof destResult.code,
         hasCode: 'code' in destResult,
         keys: Object.keys(destResult),
         resultType: typeof destResult,
         fullResult: JSON.stringify(destResult, null, 2).slice(0, 200)
-      });
+      }, null, 2)}`);
 
-      // Return the final result with combined information
       return createResult({
         code: destResult.code,
         stdout: destResult.stdout,
         stderr: sourceResult.stderr + destResult.stderr,
         stdin: sourceResult.stdin
       });
-      
+
     } catch (error) {
       const result = createResult({
         code: error.code ?? 1,
         stdout: '',
         stderr: error.message || 'Pipeline execution failed',
-        stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-               this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+        stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin :
+          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) {
-        process.stderr.write(buf);
+        safeWrite(process.stderr, buf);
       }
-      this.emit('stderr', buf);
-      this.emit('data', { type: 'stderr', data: buf });
-      
+      this._emitProcessedData('stderr', buf);
+
       this.emit('end', result);
       this.emit('exit', result.code);
-      
+
       return result;
     }
   }
 
-  // Async iteration support
   async* stream() {
-    traceFunc('ProcessRunner', 'stream', 'ENTER', { 
+    trace('ProcessRunner', () => `stream ENTER | ${JSON.stringify({
       started: this.started,
-      finished: this.finished 
-    });
-    
+      finished: this.finished
+    }, null, 2)}`);
+
     if (!this.started) {
-      trace('ProcessRunner', 'Auto-starting async process from stream()', {});
+      trace('ProcessRunner', () => 'Auto-starting async process from stream()');
       this._startAsync(); // Start but don't await
     }
-    
+
     let buffer = [];
     let resolve, reject;
     let ended = false;
@@ -1804,115 +2192,108 @@ class ProcessRunner extends StreamEmitter {
       cleanedUp = true;
       this.off('data', onData);
       this.off('end', onEnd);
-      
-      // Kill the process if it's still running when iteration is stopped
+
       // This happens when breaking from a for-await loop
       if (!this.finished) {
         this.kill();
       }
     }
   }
-  
-  // Kill the running process or cancel virtual command
+
   kill() {
-    traceFunc('ProcessRunner', 'kill', 'ENTER', { 
+    trace('ProcessRunner', () => `kill ENTER | ${JSON.stringify({
       cancelled: this._cancelled,
       finished: this.finished,
       hasChild: !!this.child,
       hasVirtualGenerator: !!this._virtualGenerator
-    });
-    
+    }, null, 2)}`);
+
     // Mark as cancelled for virtual commands
     this._cancelled = true;
-    
-    // Resolve the cancel promise to break the race in virtual command execution
+
     if (this._cancelResolve) {
-      trace('ProcessRunner', 'Resolving cancel promise', {});
+      trace('ProcessRunner', () => 'Resolving cancel promise');
       this._cancelResolve();
     }
-    
+
     // Abort any async operations
     if (this._abortController) {
-      trace('ProcessRunner', 'Aborting controller', {});
+      trace('ProcessRunner', () => 'Aborting controller');
       this._abortController.abort();
     }
-    
+
     // If it's a virtual generator, try to close it
     if (this._virtualGenerator && this._virtualGenerator.return) {
-      trace('ProcessRunner', 'Closing virtual generator', {});
+      trace('ProcessRunner', () => 'Closing virtual generator');
       try {
         this._virtualGenerator.return();
       } catch (err) {
-        trace('ProcessRunner', 'Error closing generator', { error: err.message });
+        trace('ProcessRunner', () => `Error closing generator | ${JSON.stringify({ error: err.message }, null, 2)}`);
       }
     }
-    
+
     // Kill child process if it exists
     if (this.child && !this.finished) {
-      traceBranch('ProcessRunner', 'hasChild', 'killing', { pid: this.child.pid });
+      trace('ProcessRunner', () => `BRANCH: hasChild => killing | ${JSON.stringify({ pid: this.child.pid }, null, 2)}`);
       try {
-        // Kill the process group to ensure all child processes are terminated
         if (this.child.pid) {
           if (isBun) {
-            trace('ProcessRunner', 'Killing Bun process', { pid: this.child.pid });
+            trace('ProcessRunner', () => `Killing Bun process | ${JSON.stringify({ pid: this.child.pid }, null, 2)}`);
             this.child.kill();
           } else {
             // In Node.js, kill the process group
-            trace('ProcessRunner', 'Killing Node process group', { pid: this.child.pid });
+            trace('ProcessRunner', () => `Killing Node process group | ${JSON.stringify({ pid: this.child.pid }, null, 2)}`);
             process.kill(-this.child.pid, 'SIGTERM');
           }
         }
         this.finished = true;
       } catch (err) {
         // Process might already be dead
-        trace('ProcessRunner', 'Error killing process', { error: err.message });
+        trace('ProcessRunner', () => `Error killing process | ${JSON.stringify({ error: err.message }, null, 2)}`);
         console.error('Error killing process:', err.message);
       }
     }
-    
+
     // Mark as finished
     this.finished = true;
-    
-    traceFunc('ProcessRunner', 'kill', 'EXIT', { 
+
+    trace('ProcessRunner', () => `kill EXIT | ${JSON.stringify({
       cancelled: this._cancelled,
-      finished: this.finished 
-    });
+      finished: this.finished
+    }, null, 2)}`);
   }
 
-  // Programmatic piping support
   pipe(destination) {
-    traceFunc('ProcessRunner', 'pipe', 'ENTER', { 
+    trace('ProcessRunner', () => `pipe ENTER | ${JSON.stringify({
       hasDestination: !!destination,
-      destinationType: destination?.constructor?.name 
-    });
-    
-    // If destination is a ProcessRunner, create a pipeline
+      destinationType: destination?.constructor?.name
+    }, null, 2)}`);
+
     if (destination instanceof ProcessRunner) {
-      traceBranch('ProcessRunner', 'pipe', 'PROCESS_RUNNER_DEST', {});
-      // Create a new ProcessRunner that represents the piped operation
+      trace('ProcessRunner', () => `BRANCH: pipe => PROCESS_RUNNER_DEST | ${JSON.stringify({}, null, 2)}`);
       const pipeSpec = {
         mode: 'pipeline',
         source: this,
         destination: destination
       };
-      
+
       const pipeRunner = new ProcessRunner(pipeSpec, {
         ...this.options,
         capture: destination.options.capture ?? true
       });
-      
-      traceFunc('ProcessRunner', 'pipe', 'EXIT', { mode: 'pipeline' });
+
+      trace('ProcessRunner', () => `pipe EXIT | ${JSON.stringify({ mode: 'pipeline' }, null, 2)}`);
       return pipeRunner;
     }
-    
+
     // If destination is a template literal result (from $`command`), use its spec
     if (destination && destination.spec) {
-      traceBranch('ProcessRunner', 'pipe', 'TEMPLATE_LITERAL_DEST', {});
+      trace('ProcessRunner', () => `BRANCH: pipe => TEMPLATE_LITERAL_DEST | ${JSON.stringify({}, null, 2)}`);
       const destRunner = new ProcessRunner(destination.spec, destination.options);
       return this.pipe(destRunner);
     }
-    
-    traceBranch('ProcessRunner', 'pipe', 'INVALID_DEST', {});
+
+    trace('ProcessRunner', () => `BRANCH: pipe => INVALID_DEST | ${JSON.stringify({}, null, 2)}`);
     throw new Error('pipe() destination must be a ProcessRunner or $`command` result');
   }
 
@@ -1940,110 +2321,103 @@ class ProcessRunner extends StreamEmitter {
 
   // Internal sync execution
   _startSync() {
-    traceFunc('ProcessRunner', '_startSync', 'ENTER', { 
+    trace('ProcessRunner', () => `_startSync ENTER | ${JSON.stringify({
       started: this.started,
-      spec: this.spec 
-    });
-    
+      spec: this.spec
+    }, null, 2)}`);
+
     if (this.started) {
-      traceBranch('ProcessRunner', '_startSync', 'ALREADY_STARTED', {});
+      trace('ProcessRunner', () => `BRANCH: _startSync => ALREADY_STARTED | ${JSON.stringify({}, null, 2)}`);
       throw new Error('Command already started - cannot run sync after async start');
     }
-    
+
     this.started = true;
     this._mode = 'sync';
-    trace('ProcessRunner', 'Starting sync execution', { mode: this._mode });
-    
+    trace('ProcessRunner', () => `Starting sync execution | ${JSON.stringify({ mode: this._mode }, null, 2)}`);
+
     const { cwd, env, stdin } = this.options;
     const argv = this.spec.mode === 'shell' ? ['sh', '-lc', this.spec.command] : [this.spec.file, ...this.spec.args];
-    
-    // Shell tracing (set -x equivalent)
+
     if (globalShellSettings.xtrace) {
       const traceCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
       console.log(`+ ${traceCmd}`);
     }
-    
-    // Verbose mode (set -v equivalent)
+
     if (globalShellSettings.verbose) {
       const verboseCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
       console.log(verboseCmd);
     }
-    
+
     let result;
-    
+
     if (isBun) {
       // Use Bun's synchronous spawn
       const proc = Bun.spawnSync(argv, {
         cwd,
         env,
-        stdin: typeof stdin === 'string' ? Buffer.from(stdin) : 
-               Buffer.isBuffer(stdin) ? stdin : 
-               stdin === 'ignore' ? undefined : undefined,
+        stdin: typeof stdin === 'string' ? Buffer.from(stdin) :
+          Buffer.isBuffer(stdin) ? stdin :
+            stdin === 'ignore' ? undefined : undefined,
         stdout: 'pipe',
         stderr: 'pipe'
       });
-      
+
       result = createResult({
         code: proc.exitCode || 0,
         stdout: proc.stdout?.toString('utf8') || '',
         stderr: proc.stderr?.toString('utf8') || '',
-        stdin: typeof stdin === 'string' ? stdin : 
-               Buffer.isBuffer(stdin) ? stdin.toString('utf8') : ''
+        stdin: typeof stdin === 'string' ? stdin :
+          Buffer.isBuffer(stdin) ? stdin.toString('utf8') : ''
       });
       result.child = proc;
     } else {
       // Use Node's synchronous spawn
-      const require = createRequire(import.meta.url);
-      const cp = require('child_process');
       const proc = cp.spawnSync(argv[0], argv.slice(1), {
         cwd,
         env,
-        input: typeof stdin === 'string' ? stdin : 
-               Buffer.isBuffer(stdin) ? stdin : undefined,
+        input: typeof stdin === 'string' ? stdin :
+          Buffer.isBuffer(stdin) ? stdin : undefined,
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe']
       });
-      
+
       result = createResult({
         code: proc.status || 0,
         stdout: proc.stdout || '',
         stderr: proc.stderr || '',
-        stdin: typeof stdin === 'string' ? stdin : 
-               Buffer.isBuffer(stdin) ? stdin.toString('utf8') : ''
+        stdin: typeof stdin === 'string' ? stdin :
+          Buffer.isBuffer(stdin) ? stdin.toString('utf8') : ''
       });
       result.child = proc;
     }
-    
+
     // Mirror output if requested (but always capture for result)
     if (this.options.mirror) {
-      if (result.stdout) process.stdout.write(result.stdout);
-      if (result.stderr) process.stderr.write(result.stderr);
+      if (result.stdout) safeWrite(process.stdout, result.stdout);
+      if (result.stderr) safeWrite(process.stderr, result.stderr);
     }
-    
+
     // Store chunks for events (batched after completion)
     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);
-      this.emit('stdout', stdoutBuf);
-      this.emit('data', { type: 'stdout', data: stdoutBuf });
+      this._emitProcessedData('stdout', stdoutBuf);
     }
-    
+
     if (result.stderr) {
       const stderrBuf = Buffer.from(result.stderr);
-      this.emit('stderr', stderrBuf);
-      this.emit('data', { type: 'stderr', data: stderrBuf });
+      this._emitProcessedData('stderr', stderrBuf);
     }
-    
+
     this.emit('end', result);
     this.emit('exit', result.code);
-    
-    // Handle shell settings (set -e equivalent)
+
     if (globalShellSettings.errexit && result.code !== 0) {
       const error = new Error(`Command failed with exit code ${result.code}`);
       error.code = result.code;
@@ -2052,7 +2426,7 @@ class ProcessRunner extends StreamEmitter {
       error.result = result;
       throw error;
     }
-    
+
     return result;
   }
 
@@ -2072,93 +2446,91 @@ class ProcessRunner extends StreamEmitter {
 
 // Public APIs
 async function sh(commandString, options = {}) {
-  traceFunc('API', 'sh', 'ENTER', { 
+  trace('API', () => `sh ENTER | ${JSON.stringify({
     command: commandString,
-    options 
-  });
-  
+    options
+  }, null, 2)}`);
+
   const runner = new ProcessRunner({ mode: 'shell', command: commandString }, options);
   const result = await runner._startAsync();
-  
-  traceFunc('API', 'sh', 'EXIT', { code: result.code });
+
+  trace('API', () => `sh EXIT | ${JSON.stringify({ code: result.code }, null, 2)}`);
   return result;
 }
 
 async function exec(file, args = [], options = {}) {
-  traceFunc('API', 'exec', 'ENTER', { 
+  trace('API', () => `exec ENTER | ${JSON.stringify({
     file,
     argsCount: args.length,
-    options 
-  });
-  
+    options
+  }, null, 2)}`);
+
   const runner = new ProcessRunner({ mode: 'exec', file, args }, options);
   const result = await runner._startAsync();
-  
-  traceFunc('API', 'exec', 'EXIT', { code: result.code });
+
+  trace('API', () => `exec EXIT | ${JSON.stringify({ code: result.code }, null, 2)}`);
   return result;
 }
 
 async function run(commandOrTokens, options = {}) {
-  traceFunc('API', 'run', 'ENTER', { 
+  trace('API', () => `run ENTER | ${JSON.stringify({
     type: typeof commandOrTokens,
-    options 
-  });
-  
+    options
+  }, null, 2)}`);
+
   if (typeof commandOrTokens === 'string') {
-    traceBranch('API', 'run', 'STRING_COMMAND', { command: commandOrTokens });
+    trace('API', () => `BRANCH: run => STRING_COMMAND | ${JSON.stringify({ command: commandOrTokens }, null, 2)}`);
     return sh(commandOrTokens, { ...options, mirror: false, capture: true });
   }
-  
+
   const [file, ...args] = commandOrTokens;
-  traceBranch('API', 'run', 'TOKEN_ARRAY', { file, argsCount: args.length });
+  trace('API', () => `BRANCH: run => TOKEN_ARRAY | ${JSON.stringify({ file, argsCount: args.length }, null, 2)}`);
   return exec(file, args, { ...options, mirror: false, capture: true });
 }
 
-// Enhanced tagged template that returns ProcessRunner
 function $tagged(strings, ...values) {
-  traceFunc('API', '$tagged', 'ENTER', { 
+  trace('API', () => `$tagged ENTER | ${JSON.stringify({
     stringsLength: strings.length,
-    valuesLength: values.length 
-  });
-  
+    valuesLength: values.length
+  }, null, 2)}`);
+
   const cmd = buildShellCommand(strings, values);
   const runner = new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true });
-  
-  traceFunc('API', '$tagged', 'EXIT', { command: cmd });
+
+  trace('API', () => `$tagged EXIT | ${JSON.stringify({ command: cmd }, null, 2)}`);
   return runner;
 }
 
 function create(defaultOptions = {}) {
-  traceFunc('API', 'create', 'ENTER', { defaultOptions });
-  
+  trace('API', () => `create ENTER | ${JSON.stringify({ defaultOptions }, null, 2)}`);
+
   const tagged = (strings, ...values) => {
-    traceFunc('API', 'create.tagged', 'ENTER', { 
+    trace('API', () => `create.tagged ENTER | ${JSON.stringify({
       stringsLength: strings.length,
-      valuesLength: values.length 
-    });
-    
+      valuesLength: values.length
+    }, null, 2)}`);
+
     const cmd = buildShellCommand(strings, values);
     const runner = new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true, ...defaultOptions });
-    
-    traceFunc('API', 'create.tagged', 'EXIT', { command: cmd });
+
+    trace('API', () => `create.tagged EXIT | ${JSON.stringify({ command: cmd }, null, 2)}`);
     return runner;
   };
-  
-  traceFunc('API', 'create', 'EXIT', {});
+
+  trace('API', () => `create EXIT | ${JSON.stringify({}, null, 2)}`);
   return tagged;
 }
 
-function raw(value) { 
-  return { raw: String(value) }; 
+function raw(value) {
+  return { raw: String(value) };
 }
 
-// Shell setting control functions (like bash set/unset)
 function set(option) {
   const mapping = {
     'e': 'errexit',     // set -e: exit on error
     'errexit': 'errexit',
     'v': 'verbose',     // set -v: verbose
-    'verbose': 'verbose', 
+    'verbose': 'verbose',
     'x': 'xtrace',      // set -x: trace execution
     'xtrace': 'xtrace',
     'u': 'nounset',     // set -u: error on unset vars
@@ -2166,7 +2538,7 @@ function set(option) {
     'o pipefail': 'pipefail',  // set -o pipefail
     'pipefail': 'pipefail'
   };
-  
+
   if (mapping[option]) {
     globalShellSettings[mapping[option]] = true;
     if (globalShellSettings.verbose) {
@@ -2180,7 +2552,7 @@ function unset(option) {
   const mapping = {
     'e': 'errexit',
     'errexit': 'errexit',
-    'v': 'verbose', 
+    'v': 'verbose',
     'verbose': 'verbose',
     'x': 'xtrace',
     'xtrace': 'xtrace',
@@ -2189,7 +2561,7 @@ function unset(option) {
     'o pipefail': 'pipefail',
     'pipefail': 'pipefail'
   };
-  
+
   if (mapping[option]) {
     globalShellSettings[mapping[option]] = false;
     if (globalShellSettings.verbose) {
@@ -2204,10 +2576,10 @@ const shell = {
   set,
   unset,
   settings: () => ({ ...globalShellSettings }),
-  
+
   // Bash-like shortcuts
   errexit: (enable = true) => enable ? set('e') : unset('e'),
-  verbose: (enable = true) => enable ? set('v') : unset('v'), 
+  verbose: (enable = true) => enable ? set('v') : unset('v'),
   xtrace: (enable = true) => enable ? set('x') : unset('x'),
   pipefail: (enable = true) => enable ? set('o pipefail') : unset('o pipefail'),
   nounset: (enable = true) => enable ? set('u') : unset('u'),
@@ -2215,20 +2587,16 @@ const shell = {
 
 // Virtual command registration API
 function register(name, handler) {
-  traceFunc('VirtualCommands', 'register', 'ENTER', { name });
-  
+  trace('VirtualCommands', () => `register ENTER | ${JSON.stringify({ name }, null, 2)}`);
   virtualCommands.set(name, handler);
-  
-  traceFunc('VirtualCommands', 'register', 'EXIT', { registered: true });
+  trace('VirtualCommands', () => `register EXIT | ${JSON.stringify({ registered: true }, null, 2)}`);
   return virtualCommands;
 }
 
 function unregister(name) {
-  traceFunc('VirtualCommands', 'unregister', 'ENTER', { name });
-  
+  trace('VirtualCommands', () => `unregister ENTER | ${JSON.stringify({ name }, null, 2)}`);
   const deleted = virtualCommands.delete(name);
-  
-  traceFunc('VirtualCommands', 'unregister', 'EXIT', { deleted });
+  trace('VirtualCommands', () => `unregister EXIT | ${JSON.stringify({ deleted }, null, 2)}`);
   return deleted;
 }
 
@@ -2249,62 +2617,62 @@ function disableVirtualCommands() {
 // Built-in commands that match Bun.$ functionality
 function registerBuiltins() {
   // cd - change directory
-  register('cd', async (args) => {
+  register('cd', async ({ args }) => {
     const target = args[0] || process.env.HOME || process.env.USERPROFILE || '/';
-    trace('VirtualCommand', 'cd: changing directory', { target });
-    
+    trace('VirtualCommand', () => `cd: changing directory | ${JSON.stringify({ target }, null, 2)}`);
+
     try {
       process.chdir(target);
       const newDir = process.cwd();
-      trace('VirtualCommand', 'cd: success', { newDir });
-      return { stdout: newDir, code: 0 };
+      trace('VirtualCommand', () => `cd: success | ${JSON.stringify({ newDir }, null, 2)}`);
+      return VirtualUtils.success(newDir);
     } catch (error) {
-      trace('VirtualCommand', 'cd: failed', { error: error.message });
+      trace('VirtualCommand', () => `cd: failed | ${JSON.stringify({ error: error.message }, null, 2)}`);
       return { stderr: `cd: ${error.message}`, code: 1 };
     }
   });
 
   // pwd - print working directory
-  register('pwd', async (args, stdin, options) => {
+  register('pwd', async ({ args, stdin, cwd }) => {
     // If cwd option is provided, return that instead of process.cwd()
-    const dir = options?.cwd || process.cwd();
-    trace('VirtualCommand', 'pwd: getting directory', { dir });
-    return { stdout: dir, code: 0 };
+    const dir = cwd || process.cwd();
+    trace('VirtualCommand', () => `pwd: getting directory | ${JSON.stringify({ dir }, null, 2)}`);
+    return VirtualUtils.success(dir);
   });
 
   // echo - print arguments
-  register('echo', async (args) => {
-    trace('VirtualCommand', 'echo: processing', { argsCount: args.length });
-    
+  register('echo', async ({ args }) => {
+    trace('VirtualCommand', () => `echo: processing | ${JSON.stringify({ argsCount: args.length }, null, 2)}`);
+
     let output = args.join(' ');
     if (args.includes('-n')) {
       // Don't add newline
-      traceBranch('VirtualCommand', 'echo', 'NO_NEWLINE', {});
+      trace('VirtualCommand', () => `BRANCH: echo => NO_NEWLINE | ${JSON.stringify({}, null, 2)}`);
       output = args.filter(arg => arg !== '-n').join(' ');
     } else {
       output += '\n';
     }
-    return { stdout: output, code: 0 };
+    return VirtualUtils.success(output);
   });
 
   // sleep - wait for specified time
-  register('sleep', async (args) => {
+  register('sleep', async ({ args }) => {
     const seconds = parseFloat(args[0] || 0);
-    trace('VirtualCommand', 'sleep: starting', { seconds });
-    
+    trace('VirtualCommand', () => `sleep: starting | ${JSON.stringify({ seconds }, null, 2)}`);
+
     if (isNaN(seconds) || seconds < 0) {
-      trace('VirtualCommand', 'sleep: invalid interval', { input: args[0] });
+      trace('VirtualCommand', () => `sleep: invalid interval | ${JSON.stringify({ input: args[0] }, null, 2)}`);
       return { stderr: 'sleep: invalid time interval', code: 1 };
     }
-    
+
     await new Promise(resolve => setTimeout(resolve, seconds * 1000));
-    trace('VirtualCommand', 'sleep: completed', { seconds });
+    trace('VirtualCommand', () => `sleep: completed | ${JSON.stringify({ seconds }, null, 2)}`);
     return { stdout: '', code: 0 };
   });
 
   // true - always succeed
   register('true', async () => {
-    return { stdout: '', code: 0 };
+    return VirtualUtils.success();
   });
 
   // false - always fail
@@ -2313,38 +2681,35 @@ function registerBuiltins() {
   });
 
   // which - locate command
-  register('which', async (args) => {
-    if (args.length === 0) {
-      return { stderr: 'which: missing operand', code: 1 };
-    }
-    
+  register('which', async ({ args }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'which');
+    if (argError) return argError;
+
     const cmd = args[0];
-    
-    // Check virtual commands first
+
     if (virtualCommands.has(cmd)) {
-      return { stdout: `${cmd}: shell builtin\n`, code: 0 };
+      return VirtualUtils.success(`${cmd}: shell builtin\n`);
     }
-    
-    // Check PATH for system commands
+
     const paths = (process.env.PATH || '').split(process.platform === 'win32' ? ';' : ':');
     const extensions = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
-    
-    for (const path of paths) {
+
+    for (const pathDir of paths) {
       for (const ext of extensions) {
-        const fullPath = require('path').join(path, cmd + ext);
+        const fullPath = path.join(pathDir, cmd + ext);
         try {
-          if (require('fs').statSync(fullPath).isFile()) {
-            return { stdout: fullPath, code: 0 };
+          if (fs.statSync(fullPath).isFile()) {
+            return VirtualUtils.success(fullPath + '\n');
           }
-        } catch {}
+        } catch { }
       }
     }
-    
-    return { stderr: `which: no ${cmd} in PATH`, code: 1 };
+
+    return VirtualUtils.error(`which: no ${cmd} in PATH`);
   });
 
   // exit - exit with code
-  register('exit', async (args) => {
+  register('exit', async ({ args }) => {
     const code = parseInt(args[0] || 0);
     if (globalShellSettings.errexit || code !== 0) {
       // For virtual commands, we simulate exit by returning the code
@@ -2354,54 +2719,50 @@ function registerBuiltins() {
   });
 
   // env - print environment variables
-  register('env', async (args, stdin, options) => {
+  register('env', async ({ args, stdin, env }) => {
     if (args.length === 0) {
       // Use custom env if provided, otherwise use process.env
-      const env = options?.env || process.env;
-      const output = Object.entries(env)
+      const envVars = env || process.env;
+      const output = Object.entries(envVars)
         .map(([key, value]) => `${key}=${value}`)
         .join('\n') + '\n';
       return { stdout: output, code: 0 };
     }
-    
+
     // TODO: Support env VAR=value command syntax
     return { stderr: 'env: command execution not yet supported', code: 1 };
   });
 
   // cat - read and display file contents
-  register('cat', async (args, stdin, options) => {
+  register('cat', async ({ args, stdin, cwd }) => {
     if (args.length === 0) {
       // Read from stdin if no files specified
       return { stdout: stdin || '', code: 0 };
     }
-    
+
     try {
-      const fs = await import('fs');
-      const path = await import('path');
       let output = '';
-      
+
       for (const filename of args) {
-        // Handle special flags
         if (filename === '-n') continue; // Line numbering (basic support)
-        
+
         try {
           // Resolve path relative to cwd if provided
-          const basePath = options?.cwd || process.cwd();
+          const basePath = cwd || process.cwd();
           const fullPath = path.isAbsolute(filename) ? filename : path.join(basePath, filename);
-          
+
           const content = fs.readFileSync(fullPath, 'utf8');
           output += content;
         } catch (error) {
-          // Format error message to match bash/sh style
           const errorMsg = error.code === 'ENOENT' ? 'No such file or directory' : error.message;
-          return { 
-            stderr: `cat: ${filename}: ${errorMsg}`, 
+          return {
+            stderr: `cat: ${filename}: ${errorMsg}`,
             stdout: output,
-            code: 1 
+            code: 1
           };
         }
       }
-      
+
       return { stdout: output, code: 0 };
     } catch (error) {
       return { stderr: `cat: ${error.message}`, code: 1 };
@@ -2409,37 +2770,34 @@ function registerBuiltins() {
   });
 
   // ls - list directory contents
-  register('ls', async (args, stdin, options) => {
+  register('ls', async ({ args, stdin, cwd }) => {
     try {
-      const fs = await import('fs');
-      const path = await import('path');
-      
-      // Parse flags and paths
+
       const flags = args.filter(arg => arg.startsWith('-'));
       const paths = args.filter(arg => !arg.startsWith('-'));
       const isLongFormat = flags.includes('-l');
       const showAll = flags.includes('-a');
       const showAlmostAll = flags.includes('-A');
-      
+
       // Default to current directory if no paths specified
       const targetPaths = paths.length > 0 ? paths : ['.'];
-      
+
       let output = '';
-      
+
       for (const targetPath of targetPaths) {
         // Resolve path relative to cwd if provided
-        const basePath = options?.cwd || process.cwd();
+        const basePath = cwd || process.cwd();
         const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(basePath, targetPath);
-        
+
         try {
           const stat = fs.statSync(fullPath);
-          
+
           if (stat.isFile()) {
             // Just show the file name if it's a file
             output += path.basename(targetPath) + '\n';
           } else if (stat.isDirectory()) {
             const entries = fs.readdirSync(fullPath);
-            
+
             // Filter hidden files unless -a or -A is specified
             let filteredEntries = entries;
             if (!showAll && !showAlmostAll) {
@@ -2447,9 +2805,8 @@ function registerBuiltins() {
             } else if (showAlmostAll) {
               filteredEntries = entries.filter(entry => entry !== '.' && entry !== '..');
             }
-            
+
             if (isLongFormat) {
-              // Long format: permissions, links, owner, group, size, date, name
               for (const entry of filteredEntries) {
                 const entryPath = path.join(fullPath, entry);
                 try {
@@ -2464,56 +2821,51 @@ function registerBuiltins() {
                 }
               }
             } else {
-              // Simple format: just names
               output += filteredEntries.join('\n') + (filteredEntries.length > 0 ? '\n' : '');
             }
           }
         } catch (error) {
-          return { 
-            stderr: `ls: cannot access '${targetPath}': ${error.message}`, 
-            code: 2 
+          return {
+            stderr: `ls: cannot access '${targetPath}': ${error.message}`,
+            code: 2
           };
         }
       }
-      
+
       return { stdout: output, code: 0 };
     } catch (error) {
       return { stderr: `ls: ${error.message}`, code: 1 };
     }
   });
 
-  // mkdir - create directories
-  register('mkdir', async (args, stdin, options) => {
-    if (args.length === 0) {
-      return { stderr: 'mkdir: missing operand', code: 1 };
-    }
-    
+  register('mkdir', async ({ args, stdin, cwd }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'mkdir');
+    if (argError) return argError;
+
     try {
-      const fs = await import('fs');
-      const path = await import('path');
-      
+
       const flags = args.filter(arg => arg.startsWith('-'));
       const dirs = args.filter(arg => !arg.startsWith('-'));
       const recursive = flags.includes('-p');
-      
+
       for (const dir of dirs) {
         try {
-          const basePath = options?.cwd || process.cwd();
+          const basePath = cwd || process.cwd();
           const fullPath = path.isAbsolute(dir) ? dir : path.join(basePath, dir);
-          
+
           if (recursive) {
             fs.mkdirSync(fullPath, { recursive: true });
           } else {
             fs.mkdirSync(fullPath);
           }
         } catch (error) {
-          return { 
-            stderr: `mkdir: cannot create directory '${dir}': ${error.message}`, 
-            code: 1 
+          return {
+            stderr: `mkdir: cannot create directory '${dir}': ${error.message}`,
+            code: 1
           };
         }
       }
-      
+
       return { stdout: '', code: 0 };
     } catch (error) {
       return { stderr: `mkdir: ${error.message}`, code: 1 };
@@ -2521,32 +2873,29 @@ function registerBuiltins() {
   });
 
   // rm - remove files and directories
-  register('rm', async (args, stdin, options) => {
-    if (args.length === 0) {
-      return { stderr: 'rm: missing operand', code: 1 };
-    }
-    
+  register('rm', async ({ args, stdin, cwd }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'rm');
+    if (argError) return argError;
+
     try {
-      const fs = await import('fs');
-      const path = await import('path');
-      
+
       const flags = args.filter(arg => arg.startsWith('-'));
       const targets = args.filter(arg => !arg.startsWith('-'));
       const recursive = flags.includes('-r') || flags.includes('-R');
       const force = flags.includes('-f');
-      
+
       for (const target of targets) {
         try {
-          const basePath = options?.cwd || process.cwd();
+          const basePath = cwd || process.cwd();
           const fullPath = path.isAbsolute(target) ? target : path.join(basePath, target);
-          
+
           const stat = fs.statSync(fullPath);
-          
+
           if (stat.isDirectory()) {
             if (!recursive) {
-              return { 
-                stderr: `rm: cannot remove '${target}': Is a directory`, 
-                code: 1 
+              return {
+                stderr: `rm: cannot remove '${target}': Is a directory`,
+                code: 1
               };
             }
             fs.rmSync(fullPath, { recursive: true, force });
@@ -2555,14 +2904,14 @@ function registerBuiltins() {
           }
         } catch (error) {
           if (!force) {
-            return { 
-              stderr: `rm: cannot remove '${target}': ${error.message}`, 
-              code: 1 
+            return {
+              stderr: `rm: cannot remove '${target}': ${error.message}`,
+              code: 1
             };
           }
         }
       }
-      
+
       return { stdout: '', code: 0 };
     } catch (error) {
       return { stderr: `rm: ${error.message}`, code: 1 };
@@ -2570,25 +2919,21 @@ function registerBuiltins() {
   });
 
   // mv - move/rename files and directories
-  register('mv', async (args, stdin, options) => {
-    if (args.length < 2) {
-      return { stderr: 'mv: missing destination file operand', code: 1 };
-    }
-    
+  register('mv', async ({ args, stdin, cwd }) => {
+    const argError = VirtualUtils.validateArgs(args, 2, 'mv');
+    if (argError) return VirtualUtils.invalidArgumentError('mv', 'missing destination file operand');
+
     try {
-      const fs = await import('fs');
-      const path = await import('path');
-      
-      const basePath = options?.cwd || process.cwd();
-      
+
+      const basePath = cwd || process.cwd();
+
       if (args.length === 2) {
         // Simple rename/move
         const [source, dest] = args;
         const sourcePath = path.isAbsolute(source) ? source : path.join(basePath, source);
         let destPath = path.isAbsolute(dest) ? dest : path.join(basePath, dest);
-        
+
         try {
-          // Check if destination is an existing directory
           try {
             const destStat = fs.statSync(destPath);
             if (destStat.isDirectory()) {
@@ -2599,12 +2944,12 @@ function registerBuiltins() {
           } catch {
             // Destination doesn't exist, proceed with direct rename
           }
-          
+
           fs.renameSync(sourcePath, destPath);
         } catch (error) {
-          return { 
-            stderr: `mv: cannot move '${source}' to '${dest}': ${error.message}`, 
-            code: 1 
+          return {
+            stderr: `mv: cannot move '${source}' to '${dest}': ${error.message}`,
+            code: 1
           };
         }
       } else {
@@ -2612,23 +2957,22 @@ function registerBuiltins() {
         const sources = args.slice(0, -1);
         const dest = args[args.length - 1];
         const destPath = path.isAbsolute(dest) ? dest : path.join(basePath, dest);
-        
-        // Check if destination is a directory
+
         try {
           const destStat = fs.statSync(destPath);
           if (!destStat.isDirectory()) {
-            return { 
-              stderr: `mv: target '${dest}' is not a directory`, 
-              code: 1 
+            return {
+              stderr: `mv: target '${dest}' is not a directory`,
+              code: 1
             };
           }
         } catch {
-          return { 
-            stderr: `mv: cannot access '${dest}': No such file or directory`, 
-            code: 1 
+          return {
+            stderr: `mv: cannot access '${dest}': No such file or directory`,
+            code: 1
           };
         }
-        
+
         for (const source of sources) {
           try {
             const sourcePath = path.isAbsolute(source) ? source : path.join(basePath, source);
@@ -2636,14 +2980,14 @@ function registerBuiltins() {
             const newDestPath = path.join(destPath, fileName);
             fs.renameSync(sourcePath, newDestPath);
           } catch (error) {
-            return { 
-              stderr: `mv: cannot move '${source}' to '${dest}': ${error.message}`, 
-              code: 1 
+            return {
+              stderr: `mv: cannot move '${source}' to '${dest}': ${error.message}`,
+              code: 1
             };
           }
         }
       }
-      
+
       return { stdout: '', code: 0 };
     } catch (error) {
       return { stderr: `mv: ${error.message}`, code: 1 };
@@ -2651,35 +2995,32 @@ function registerBuiltins() {
   });
 
   // cp - copy files and directories
-  register('cp', async (args, stdin, options) => {
-    if (args.length < 2) {
-      return { stderr: 'cp: missing destination file operand', code: 1 };
-    }
-    
+  register('cp', async ({ args, stdin, cwd }) => {
+    const argError = VirtualUtils.validateArgs(args, 2, 'cp');
+    if (argError) return VirtualUtils.invalidArgumentError('cp', 'missing destination file operand');
+
     try {
-      const fs = await import('fs');
-      const path = await import('path');
-      
+
       const flags = args.filter(arg => arg.startsWith('-'));
       const paths = args.filter(arg => !arg.startsWith('-'));
       const recursive = flags.includes('-r') || flags.includes('-R');
-      
-      const basePath = options?.cwd || process.cwd();
-      
+
+      const basePath = cwd || process.cwd();
+
       if (paths.length === 2) {
         // Simple copy
         const [source, dest] = paths;
         const sourcePath = path.isAbsolute(source) ? source : path.join(basePath, source);
         const destPath = path.isAbsolute(dest) ? dest : path.join(basePath, dest);
-        
+
         try {
           const sourceStat = fs.statSync(sourcePath);
-          
+
           if (sourceStat.isDirectory()) {
             if (!recursive) {
-              return { 
-                stderr: `cp: -r not specified; omitting directory '${source}'`, 
-                code: 1 
+              return {
+                stderr: `cp: -r not specified; omitting directory '${source}'`,
+                code: 1
               };
             }
             fs.cpSync(sourcePath, destPath, { recursive: true });
@@ -2687,9 +3028,9 @@ function registerBuiltins() {
             fs.copyFileSync(sourcePath, destPath);
           }
         } catch (error) {
-          return { 
-            stderr: `cp: cannot copy '${source}' to '${dest}': ${error.message}`, 
-            code: 1 
+          return {
+            stderr: `cp: cannot copy '${source}' to '${dest}': ${error.message}`,
+            code: 1
           };
         }
       } else {
@@ -2697,35 +3038,34 @@ function registerBuiltins() {
         const sources = paths.slice(0, -1);
         const dest = paths[paths.length - 1];
         const destPath = path.isAbsolute(dest) ? dest : path.join(basePath, dest);
-        
-        // Check if destination is a directory
+
         try {
           const destStat = fs.statSync(destPath);
           if (!destStat.isDirectory()) {
-            return { 
-              stderr: `cp: target '${dest}' is not a directory`, 
-              code: 1 
+            return {
+              stderr: `cp: target '${dest}' is not a directory`,
+              code: 1
             };
           }
         } catch {
-          return { 
-            stderr: `cp: cannot access '${dest}': No such file or directory`, 
-            code: 1 
+          return {
+            stderr: `cp: cannot access '${dest}': No such file or directory`,
+            code: 1
           };
         }
-        
+
         for (const source of sources) {
           try {
             const sourcePath = path.isAbsolute(source) ? source : path.join(basePath, source);
             const fileName = path.basename(source);
             const newDestPath = path.join(destPath, fileName);
-            
+
             const sourceStat = fs.statSync(sourcePath);
             if (sourceStat.isDirectory()) {
               if (!recursive) {
-                return { 
-                  stderr: `cp: -r not specified; omitting directory '${source}'`, 
-                  code: 1 
+                return {
+                  stderr: `cp: -r not specified; omitting directory '${source}'`,
+                  code: 1
                 };
               }
               fs.cpSync(sourcePath, newDestPath, { recursive: true });
@@ -2733,14 +3073,14 @@ function registerBuiltins() {
               fs.copyFileSync(sourcePath, newDestPath);
             }
           } catch (error) {
-            return { 
-              stderr: `cp: cannot copy '${source}' to '${dest}': ${error.message}`, 
-              code: 1 
+            return {
+              stderr: `cp: cannot copy '${source}' to '${dest}': ${error.message}`,
+              code: 1
             };
           }
         }
       }
-      
+
       return { stdout: '', code: 0 };
     } catch (error) {
       return { stderr: `cp: ${error.message}`, code: 1 };
@@ -2748,37 +3088,33 @@ function registerBuiltins() {
   });
 
   // touch - create or update file timestamps
-  register('touch', async (args, stdin, options) => {
-    if (args.length === 0) {
-      return { stderr: 'touch: missing file operand', code: 1 };
-    }
-    
+  register('touch', async ({ args, stdin, cwd }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'touch');
+    if (argError) return VirtualUtils.missingOperandError('touch', 'touch: missing file operand');
+
     try {
-      const fs = await import('fs');
-      const path = await import('path');
-      
-      const basePath = options?.cwd || process.cwd();
-      
+
+      const basePath = cwd || process.cwd();
+
       for (const file of args) {
         try {
           const fullPath = path.isAbsolute(file) ? file : path.join(basePath, file);
-          
+
           // Try to update timestamps if file exists
           try {
             const now = new Date();
             fs.utimesSync(fullPath, now, now);
           } catch {
-            // File doesn't exist, create it
             fs.writeFileSync(fullPath, '', { flag: 'w' });
           }
         } catch (error) {
-          return { 
-            stderr: `touch: cannot touch '${file}': ${error.message}`, 
-            code: 1 
+          return {
+            stderr: `touch: cannot touch '${file}': ${error.message}`,
+            code: 1
           };
         }
       }
-      
+
       return { stdout: '', code: 0 };
     } catch (error) {
       return { stderr: `touch: ${error.message}`, code: 1 };
@@ -2786,24 +3122,22 @@ function registerBuiltins() {
   });
 
   // basename - extract filename from path
-  register('basename', async (args) => {
-    if (args.length === 0) {
-      return { stderr: 'basename: missing operand', code: 1 };
-    }
-    
+  register('basename', async ({ args }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'basename');
+    if (argError) return argError;
+
     try {
-      const path = await import('path');
-      
+
       const pathname = args[0];
       const suffix = args[1];
-      
+
       let result = path.basename(pathname);
-      
+
       // Remove suffix if provided
       if (suffix && result.endsWith(suffix)) {
         result = result.slice(0, -suffix.length);
       }
-      
+
       return { stdout: result + '\n', code: 0 };
     } catch (error) {
       return { stderr: `basename: ${error.message}`, code: 1 };
@@ -2811,17 +3145,15 @@ function registerBuiltins() {
   });
 
   // dirname - extract directory from path
-  register('dirname', async (args) => {
-    if (args.length === 0) {
-      return { stderr: 'dirname: missing operand', code: 1 };
-    }
-    
+  register('dirname', async ({ args }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'dirname');
+    if (argError) return argError;
+
     try {
-      const path = await import('path');
-      
+
       const pathname = args[0];
       const result = path.dirname(pathname);
-      
+
       return { stdout: result + '\n', code: 0 };
     } catch (error) {
       return { stderr: `dirname: ${error.message}`, code: 1 };
@@ -2829,42 +3161,38 @@ function registerBuiltins() {
   });
 
   // yes - output a string repeatedly
-  register('yes', async function* (args, stdin, options) {
+  register('yes', async function* ({ args, stdin, isCancelled, signal, ...rest }) {
     const output = args.length > 0 ? args.join(' ') : 'y';
-    trace('VirtualCommand', 'yes: starting infinite generator', { output });
-    
+    trace('VirtualCommand', () => `yes: starting infinite generator | ${JSON.stringify({ output }, null, 2)}`);
+
     // Generate infinite stream of the output
     while (true) {
-      // Check if cancelled via function or abort signal
-      if (options) {
-        if (options.isCancelled && options.isCancelled()) {
-          trace('VirtualCommand', 'yes: cancelled via function', {});
-          return;
-        }
-        if (options.signal && options.signal.aborted) {
-          trace('VirtualCommand', 'yes: cancelled via abort signal', {});
-          return;
-        }
+      if (isCancelled && isCancelled()) {
+        trace('VirtualCommand', () => 'yes: cancelled via function');
+        return;
+      }
+      if (signal && signal.aborted) {
+        trace('VirtualCommand', () => 'yes: cancelled via abort signal');
+        return;
       }
-      
+
       yield output + '\n';
-      
-      // Small delay with abort signal support
+
       try {
         await new Promise((resolve, reject) => {
           const timeout = setTimeout(resolve, 0);
-          
+
           // Listen for abort signal if available
-          if (options && options.signal) {
+          if (signal) {
             const abortHandler = () => {
               clearTimeout(timeout);
               reject(new Error('Aborted'));
             };
-            
-            if (options.signal.aborted) {
+
+            if (signal.aborted) {
               abortHandler();
             } else {
-              options.signal.addEventListener('abort', abortHandler, { once: true });
+              signal.addEventListener('abort', abortHandler, { once: true });
             }
           }
         });
@@ -2876,14 +3204,13 @@ function registerBuiltins() {
   });
 
   // seq - generate sequence of numbers
-  register('seq', async (args) => {
-    if (args.length === 0) {
-      return { stderr: 'seq: missing operand', code: 1 };
-    }
-    
+  register('seq', async ({ args }) => {
+    const argError = VirtualUtils.validateArgs(args, 1, 'seq');
+    if (argError) return argError;
+
     try {
       let start, step, end;
-      
+
       if (args.length === 1) {
         start = 1;
         step = 1;
@@ -2899,11 +3226,11 @@ function registerBuiltins() {
       } else {
         return { stderr: 'seq: too many operands', code: 1 };
       }
-      
+
       if (isNaN(start) || isNaN(step) || isNaN(end)) {
         return { stderr: 'seq: invalid number', code: 1 };
       }
-      
+
       let output = '';
       if (step > 0) {
         for (let i = start; i <= end; i += step) {
@@ -2916,7 +3243,7 @@ function registerBuiltins() {
       } else {
         return { stderr: 'seq: invalid increment', code: 1 };
       }
-      
+
       return { stdout: output, code: 0 };
     } catch (error) {
       return { stderr: `seq: ${error.message}`, code: 1 };
@@ -2924,38 +3251,114 @@ function registerBuiltins() {
   });
 
   // test - test file conditions (basic implementation)
-  register('test', async (args) => {
+  register('test', async ({ args }) => {
     if (args.length === 0) {
       return { stdout: '', code: 1 };
     }
-    
+
     // Very basic test implementation
     const arg = args[0];
-    
+
     try {
       if (arg === '-d' && args[1]) {
         // Test if directory
-        const stat = require('fs').statSync(args[1]);
+        const stat = fs.statSync(args[1]);
         return { stdout: '', code: stat.isDirectory() ? 0 : 1 };
       } else if (arg === '-f' && args[1]) {
         // Test if file
-        const stat = require('fs').statSync(args[1]);
+        const stat = fs.statSync(args[1]);
         return { stdout: '', code: stat.isFile() ? 0 : 1 };
       } else if (arg === '-e' && args[1]) {
         // Test if exists
-        require('fs').statSync(args[1]);
+        fs.statSync(args[1]);
         return { stdout: '', code: 0 };
       }
     } catch {
       return { stdout: '', code: 1 };
     }
-    
+
     return { stdout: '', code: 1 };
   });
 }
 
+// ANSI control character utilities
+const AnsiUtils = {
+  stripAnsi(text) {
+    if (typeof text !== 'string') return text;
+    return text.replace(/\x1b\[[0-9;]*[mGKHFJ]/g, '');
+  },
+
+  stripControlChars(text) {
+    if (typeof text !== 'string') return text;
+    return text.replace(/[\x00-\x1F\x7F]/g, '');
+  },
+
+  stripAll(text) {
+    if (typeof text !== 'string') return text;
+    return text.replace(/[\x00-\x1F\x7F]|\x1b\[[0-9;]*[mGKHFJ]/g, '');
+  },
+
+  cleanForProcessing(data) {
+    if (Buffer.isBuffer(data)) {
+      return Buffer.from(this.stripAll(data.toString('utf8')));
+    }
+    return this.stripAll(data);
+  }
+};
+
+let globalAnsiConfig = {
+  preserveAnsi: true,
+  preserveControlChars: true
+};
+
+function configureAnsi(options = {}) {
+  globalAnsiConfig = { ...globalAnsiConfig, ...options };
+  return globalAnsiConfig;
+}
+
+function getAnsiConfig() {
+  return { ...globalAnsiConfig };
+}
+
+function processOutput(data, options = {}) {
+  const config = { ...globalAnsiConfig, ...options };
+  if (!config.preserveAnsi && !config.preserveControlChars) {
+    return AnsiUtils.cleanForProcessing(data);
+  } else if (!config.preserveAnsi) {
+    return Buffer.isBuffer(data)
+      ? Buffer.from(AnsiUtils.stripAnsi(data.toString('utf8')))
+      : AnsiUtils.stripAnsi(data);
+  } else if (!config.preserveControlChars) {
+    return Buffer.isBuffer(data)
+      ? Buffer.from(AnsiUtils.stripControlChars(data.toString('utf8')))
+      : AnsiUtils.stripControlChars(data);
+  }
+  return data;
+}
+
 // Initialize built-in commands
 registerBuiltins();
 
-export { $tagged as $, sh, exec, run, quote, create, raw, ProcessRunner, shell, set, unset, register, unregister, listCommands, enableVirtualCommands, disableVirtualCommands };
+export {
+  $tagged as $,
+  sh,
+  exec,
+  run,
+  quote,
+  create,
+  raw,
+  ProcessRunner,
+  shell,
+  set,
+  unset,
+  register,
+  unregister,
+  listCommands,
+  enableVirtualCommands,
+  disableVirtualCommands,
+  AnsiUtils,
+  configureAnsi,
+  getAnsiConfig,
+  processOutput
+};
 export default $tagged;