start-command 0.17.2 → 0.17.4

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # start-command
 
+## 0.17.4
+
+### Patch Changes
+
+- 89d04d6: fix: Ensure execution status is updated when process is interrupted
+
+  This fix addresses Issue #60 where `$ --status` shows "executing" for finished commands.
+
+  Changes:
+  - Added signal handlers (SIGINT, SIGTERM, SIGHUP) to update execution status when process is interrupted
+  - Added `--cleanup` and `--cleanup-dry-run` flags to clean up stale records from crashed/killed processes
+  - Added `cleanupStale()` method to ExecutionStore to detect and clean stale records
+
+  The cleanup logic detects stale records by:
+  1. Checking if the PID is still running (if on same platform)
+  2. Checking if the record has exceeded max age (default: 24 hours)
+
+  Stale records are marked as "executed" with exit code -1 to indicate abnormal termination.
+
+## 0.17.3
+
+### Patch Changes
+
+- a61f1a9: fix: Use Bun.spawn for reliable stdout capture on macOS (Issue #57)
+
+  The previous fix (v0.17.2) using `close` event instead of `exit` did not resolve the issue on macOS. After deeper investigation, we discovered the root cause: Bun's event loop may exit before the `close` event callback can be scheduled, especially for fast commands like `echo`.
+
+  This fix uses Bun's native `Bun.spawn` API with async/await for stream handling when running on Bun runtime. This approach keeps the event loop alive until all streams are consumed and the process exits.
+  - Use `Bun.spawn` instead of `node:child_process` when running on Bun
+  - Use async stream readers with `getReader()` for real-time output display
+  - Use `await proc.exited` to ensure process completion before exiting
+  - Fall back to `node:child_process` with `close` event for Node.js compatibility
+  - Add verbose logging with `--verbose` flag for debugging
+
 ## 0.17.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/bin/cli.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env bun
 
-const { spawn } = require('child_process');
 const process = require('process');
 const os = require('os');
 const fs = require('fs');
@@ -35,6 +34,7 @@ const { ExecutionStore, ExecutionRecord } = require('../lib/execution-store');
 const { queryStatus } = require('../lib/status-formatter');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
+const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
 
 // Configuration from environment variables
 const config = {
@@ -73,6 +73,10 @@ const config = {
 // Global execution store instance (initialized lazily)
 let executionStore = null;
 
+// Global reference to current execution record for cleanup on signals
+// This allows us to mark the execution as completed if the process is interrupted
+let currentExecutionRecord = null;
+
 /**
  * Get the execution store instance
  * @returns {ExecutionStore}
@@ -87,6 +91,57 @@ function getExecutionStore() {
   return executionStore;
 }
 
+/**
+ * Cleanup handler for signals and process exit
+ * Marks the current execution as completed with an appropriate exit code
+ * @param {string} signal - The signal that triggered the cleanup (e.g., 'SIGINT', 'SIGTERM')
+ * @param {number} exitCode - The exit code to use
+ */
+function cleanupExecution(signal, exitCode) {
+  if (currentExecutionRecord && executionStore) {
+    // Signal-based exit codes:
+    // SIGINT (Ctrl+C): 130 (128 + 2)
+    // SIGTERM: 143 (128 + 15)
+    // SIGHUP: 129 (128 + 1)
+    currentExecutionRecord.complete(exitCode);
+    try {
+      executionStore.save(currentExecutionRecord);
+      if (config.verbose) {
+        console.error(
+          `\n[Tracking] Execution ${currentExecutionRecord.uuid} marked as completed (${signal}, exit code: ${exitCode})`
+        );
+      }
+    } catch (err) {
+      if (config.verbose) {
+        console.error(
+          `[Tracking] Warning: Could not save execution record on ${signal}: ${err.message}`
+        );
+      }
+    }
+    // Clear the reference to prevent double cleanup
+    currentExecutionRecord = null;
+  }
+}
+
+// Set up signal handlers to ensure execution status is updated on interruption
+// SIGINT (Ctrl+C) - exit code 130 (128 + signal number 2)
+process.on('SIGINT', () => {
+  cleanupExecution('SIGINT', 130);
+  process.exit(130);
+});
+
+// SIGTERM (kill command) - exit code 143 (128 + signal number 15)
+process.on('SIGTERM', () => {
+  cleanupExecution('SIGTERM', 143);
+  process.exit(143);
+});
+
+// SIGHUP (terminal closed) - exit code 129 (128 + signal number 1)
+process.on('SIGHUP', () => {
+  cleanupExecution('SIGHUP', 129);
+  process.exit(129);
+});
+
 // Get all arguments passed after the command
 const args = process.argv.slice(2);
 
@@ -138,6 +193,12 @@ if (wrapperOptions.status) {
   process.exit(0);
 }
 
+// Handle --cleanup flag
+if (wrapperOptions.cleanup) {
+  handleCleanup(wrapperOptions.cleanupDryRun);
+  process.exit(0);
+}
+
 // Check if no command was provided
 if (!parsedCommand || parsedCommand.trim() === '') {
   console.error('Error: No command provided');
@@ -206,6 +267,53 @@ function handleStatusQuery(uuid, outputFormat) {
   }
 }
 
+/**
+ * Handle --cleanup flag
+ * Cleans up stale "executing" records (processes that crashed or were killed)
+ * @param {boolean} dryRun - If true, just report what would be cleaned
+ */
+function handleCleanup(dryRun) {
+  const store = getExecutionStore();
+  if (!store) {
+    console.error('Error: Execution tracking is disabled.');
+    process.exit(1);
+  }
+
+  const result = store.cleanupStale({ dryRun });
+
+  if (result.errors.length > 0) {
+    for (const error of result.errors) {
+      console.error(`Error: ${error}`);
+    }
+  }
+
+  if (result.records.length === 0) {
+    console.log('No stale records found.');
+    return;
+  }
+
+  if (dryRun) {
+    console.log(
+      `Found ${result.records.length} stale record(s) that would be cleaned up:\n`
+    );
+  } else {
+    console.log(`Cleaned up ${result.cleaned} stale record(s):\n`);
+  }
+
+  for (const record of result.records) {
+    const startTime = new Date(record.startTime).toLocaleString();
+    console.log(`  UUID: ${record.uuid}`);
+    console.log(`  Command: ${record.command}`);
+    console.log(`  Started: ${startTime}`);
+    console.log(`  PID: ${record.pid || 'N/A'}`);
+    console.log('');
+  }
+
+  if (dryRun) {
+    console.log('Run with --cleanup to actually clean up these records.');
+  }
+}
+
 /** Print usage information */
 function printUsage() {
   console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>]
@@ -225,6 +333,8 @@ Options:
   --auto-remove-docker-container  Auto-remove docker container after exit
   --use-command-stream  Use command-stream library for execution (experimental)
   --status <uuid>       Show status of execution by UUID (--output-format: links-notation|json|text)
+  --cleanup             Clean up stale "executing" records (crashed/killed processes)
+  --cleanup-dry-run     Show stale records that would be cleaned up (without cleaning)
   --version, -v         Show version information
 
 Examples:
@@ -411,8 +521,9 @@ async function runWithIsolation(
   );
   console.log('');
 
-  // Save initial execution record
+  // Save initial execution record and set global reference for signal cleanup
   if (executionRecord && store) {
+    currentExecutionRecord = executionRecord;
     try {
       store.save(executionRecord);
     } catch (err) {
@@ -478,7 +589,7 @@ async function runWithIsolation(
   // Write log file
   writeLogFile(logFilePath, logContent);
 
-  // Update execution record as completed
+  // Update execution record as completed and clear global reference
   if (executionRecord && store) {
     executionRecord.complete(exitCode);
     try {
@@ -490,6 +601,8 @@ async function runWithIsolation(
         );
       }
     }
+    // Clear global reference since we've completed normally
+    currentExecutionRecord = null;
   }
 
   // Cleanup: delete the created user if we created one (unless --keep-user)
@@ -529,11 +642,18 @@ async function runWithIsolation(
 }
 
 /**
- * Run command directly (without isolation) - original synchronous version
+ * Run command directly (without isolation)
+ *
+ * Uses Bun.spawn when running on Bun for reliable event handling on macOS.
+ * Falls back to node:child_process for Node.js compatibility.
+ *
+ * Issue #57: On macOS with Bun, node:child_process events may not fire reliably
+ * before the event loop exits. Bun.spawn provides more reliable stream handling.
+ *
  * @param {string} cmd - Command to execute
  * @param {string} sessionId - Session UUID for tracking
  */
-function runDirect(cmd, sessionId) {
+async function runDirect(cmd, sessionId) {
   // Get the command name (first word of the actual command to execute)
   const commandName = cmd.split(' ')[0];
 
@@ -573,6 +693,8 @@ function runDirect(cmd, sessionId) {
         runtimeVersion,
       },
     });
+    // Set global reference for signal cleanup
+    currentExecutionRecord = executionRecord;
   }
 
   // Log header
@@ -606,76 +728,10 @@ function runDirect(cmd, sessionId) {
   );
   console.log('');
 
-  // Execute the command with captured output
-  const child = spawn(shell, shellArgs, {
-    stdio: ['inherit', 'pipe', 'pipe'],
-    shell: false,
-  });
-
-  // Update execution record with PID and save initial state
-  if (executionRecord && store) {
-    executionRecord.pid = child.pid;
-    try {
-      store.save(executionRecord);
-    } catch (err) {
-      if (config.verbose) {
-        console.error(
-          `[Tracking] Warning: Could not save execution record: ${err.message}`
-        );
-      }
-    }
-  }
-
-  // Capture stdout
-  child.stdout.on('data', (data) => {
-    const text = data.toString();
-    process.stdout.write(text);
-    logContent += text;
-  });
-
-  // Capture stderr
-  child.stderr.on('data', (data) => {
-    const text = data.toString();
-    process.stderr.write(text);
-    logContent += text;
-  });
-
-  // Handle process close (not 'exit' - we need to wait for all stdio to be closed)
-  // The 'close' event fires after all stdio streams have been closed, ensuring
-  // all stdout/stderr data has been received. The 'exit' event can fire before
-  // buffered data is received, causing output loss on macOS (Issue #57).
-  child.on('close', (code) => {
-    const exitCode = code || 0;
-    const endTime = getTimestamp();
-
-    // Log footer
-    logContent += `\n${'='.repeat(50)}\n`;
-    logContent += `Finished: ${endTime}\n`;
-    logContent += `Exit Code: ${exitCode}\n`;
-
-    // Write log file
-    try {
-      fs.writeFileSync(logFilePath, logContent, 'utf8');
-    } catch (err) {
-      console.error(`\nWarning: Could not save log file: ${err.message}`);
-    }
-
-    // Update execution record as completed
-    if (executionRecord && store) {
-      executionRecord.complete(exitCode);
-      try {
-        store.save(executionRecord);
-      } catch (err) {
-        if (config.verbose) {
-          console.error(
-            `[Tracking] Warning: Could not update execution record: ${err.message}`
-          );
-        }
-      }
-    }
-
-    // Print finish block
-    const durationMs = Date.now() - startTimeMs;
+  // Completion callback
+  const onComplete = (exitCode, endTime, _logContent, durationMs) => {
+    // Clear global reference since execution completed normally
+    currentExecutionRecord = null;
     console.log('');
     console.log(
       createFinishBlock({
@@ -686,47 +742,16 @@ function runDirect(cmd, sessionId) {
         durationMs,
       })
     );
-
-    // If command failed, try to auto-report
     if (exitCode !== 0) {
       handleFailure(config, commandName, cmd, exitCode, logFilePath);
     }
-
     process.exit(exitCode);
-  });
-
-  // Handle spawn errors
-  child.on('error', (err) => {
-    const endTime = getTimestamp();
-    const durationMs = Date.now() - startTimeMs;
-    const errorMessage = `Error executing command: ${err.message}`;
-
-    logContent += `\n${errorMessage}\n`;
-    logContent += `\n${'='.repeat(50)}\n`;
-    logContent += `Finished: ${endTime}\n`;
-    logContent += `Exit Code: 1\n`;
-
-    // Write log file
-    try {
-      fs.writeFileSync(logFilePath, logContent, 'utf8');
-    } catch (writeErr) {
-      console.error(`\nWarning: Could not save log file: ${writeErr.message}`);
-    }
-
-    // Update execution record as failed
-    if (executionRecord && store) {
-      executionRecord.complete(1);
-      try {
-        store.save(executionRecord);
-      } catch (storeErr) {
-        if (config.verbose) {
-          console.error(
-            `[Tracking] Warning: Could not update execution record: ${storeErr.message}`
-          );
-        }
-      }
-    }
+  };
 
+  // Error callback
+  const onError = (errorMessage, endTime, durationMs) => {
+    // Clear global reference since execution completed (with error)
+    currentExecutionRecord = null;
     console.error(`\n${errorMessage}`);
     console.log('');
     console.log(
@@ -738,11 +763,30 @@ function runDirect(cmd, sessionId) {
         durationMs,
       })
     );
-
     handleFailure(config, commandName, cmd, 1, logFilePath);
-
     process.exit(1);
-  });
+  };
+
+  // Use Bun.spawn when running on Bun for reliable event handling on macOS
+  // Fall back to node:child_process for Node.js compatibility
+  const spawnOptions = {
+    shell,
+    shellArgs,
+    logFilePath,
+    logContent,
+    startTimeMs,
+    executionRecord,
+    store,
+    config,
+    onComplete,
+    onError,
+  };
+
+  if (typeof Bun !== 'undefined') {
+    await runWithBunSpawn(spawnOptions);
+  } else {
+    runWithNodeSpawn(spawnOptions);
+  }
 }
 
 /**
@@ -801,6 +845,8 @@ async function runDirectWithCommandStream(
         executionMode: 'command-stream',
       },
     });
+    // Set global reference for signal cleanup
+    currentExecutionRecord = executionRecord;
   }
 
   // Log header
@@ -892,7 +938,7 @@ async function runDirectWithCommandStream(
     console.error(`\nWarning: Could not save log file: ${err.message}`);
   }
 
-  // Update execution record as completed
+  // Update execution record as completed and clear global reference
   if (executionRecord && store) {
     executionRecord.complete(exitCode);
     try {
@@ -904,6 +950,8 @@ async function runDirectWithCommandStream(
         );
       }
     }
+    // Clear global reference since we've completed normally
+    currentExecutionRecord = null;
   }
 
   // Print finish block

package/src/lib/args-parser.js

@@ -19,6 +19,8 @@
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --status <uuid>                  Show status of a previous command execution by UUID
  * --output-format <format>         Output format for status (links-notation, json, text)
+ * --cleanup                        Clean up stale "executing" records (processes that crashed or were killed)
+ * --cleanup-dry-run                Show stale records that would be cleaned up (without actually cleaning)
  */
 
 // Debug mode from environment
@@ -91,6 +93,8 @@ function parseArgs(args) {
     useCommandStream: false, // Use command-stream library for command execution
     status: null, // UUID to show status for
     outputFormat: null, // Output format for status (links-notation, json, text)
+    cleanup: false, // Clean up stale "executing" records
+    cleanupDryRun: false, // Show what would be cleaned without actually cleaning
   };
 
   let commandArgs = [];
@@ -339,6 +343,19 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --cleanup
+  if (arg === '--cleanup') {
+    options.cleanup = true;
+    return 1;
+  }
+
+  // --cleanup-dry-run
+  if (arg === '--cleanup-dry-run') {
+    options.cleanup = true;
+    options.cleanupDryRun = true;
+    return 1;
+  }
+
   // Not a recognized wrapper option
   return 0;
 }

package/src/lib/execution-store.js

@@ -517,6 +517,112 @@ class ExecutionStore {
     return records.slice(0, limit);
   }
 
+  /**
+   * Clean up stale "executing" records
+   *
+   * Stale records are those that:
+   * 1. Have status "executing"
+   * 2. Either:
+   *    - Their process (by PID) is no longer running (on same hostname)
+   *    - They have been "executing" for longer than maxAgeMs (default: 24 hours)
+   *
+   * @param {object} options - Cleanup options
+   * @param {number} options.maxAgeMs - Max age for executing records (default: 24 hours)
+   * @param {boolean} options.dryRun - If true, just report what would be cleaned (default: false)
+   * @returns {{cleaned: number, records: ExecutionRecord[], errors: string[]}}
+   */
+  cleanupStale(options = {}) {
+    const maxAgeMs = options.maxAgeMs || 24 * 60 * 60 * 1000; // 24 hours
+    const dryRun = options.dryRun || false;
+
+    const result = {
+      cleaned: 0,
+      records: [],
+      errors: [],
+    };
+
+    const records = this.readLinoRecords();
+    const executingRecords = records.filter(
+      (r) => r.status === ExecutionStatus.EXECUTING
+    );
+
+    const staleRecords = [];
+
+    for (const record of executingRecords) {
+      let isStale = false;
+      let reason = '';
+
+      // Check if the process is still running (only if on same platform)
+      if (record.pid && record.platform === process.platform) {
+        try {
+          // Signal 0 just checks if process exists
+          process.kill(record.pid, 0);
+          // Process exists, check age
+        } catch {
+          // Process doesn't exist - record is stale
+          isStale = true;
+          reason = `process ${record.pid} no longer running`;
+        }
+      }
+
+      // Check age if not already determined to be stale
+      if (!isStale) {
+        const startTime = new Date(record.startTime).getTime();
+        const age = Date.now() - startTime;
+        if (age > maxAgeMs) {
+          isStale = true;
+          reason = `running for ${Math.round(age / 1000 / 60)} minutes (max: ${Math.round(maxAgeMs / 1000 / 60)} minutes)`;
+        }
+      }
+
+      if (isStale) {
+        this.log(`Stale record found: ${record.uuid} (${reason})`);
+        staleRecords.push(record);
+      }
+    }
+
+    result.records = staleRecords;
+
+    if (!dryRun && staleRecords.length > 0) {
+      const lock = new LockManager(this.lockFilePath);
+
+      if (!lock.acquire()) {
+        result.errors.push('Failed to acquire lock for cleanup');
+        return result;
+      }
+
+      try {
+        // Re-read records to ensure consistency
+        const currentRecords = this.readLinoRecords();
+
+        // Update stale records to "executed" status with exit code -1 (abnormal termination)
+        for (const staleRecord of staleRecords) {
+          const index = currentRecords.findIndex(
+            (r) => r.uuid === staleRecord.uuid
+          );
+          if (index >= 0) {
+            // Mark as executed with exit code -1 to indicate abnormal termination
+            currentRecords[index].status = ExecutionStatus.EXECUTED;
+            currentRecords[index].exitCode = -1;
+            currentRecords[index].endTime = new Date().toISOString();
+            result.cleaned++;
+          }
+        }
+
+        this.writeLinoRecords(currentRecords);
+        this.log(`Cleaned up ${result.cleaned} stale records`);
+      } catch (err) {
+        result.errors.push(`Cleanup error: ${err.message}`);
+      } finally {
+        lock.release();
+      }
+    } else if (dryRun) {
+      result.cleaned = staleRecords.length;
+    }
+
+    return result;
+  }
+
   /**
    * Delete an execution record
    * @param {string} uuid

package/src/lib/spawn-helpers.js

@@ -0,0 +1,346 @@
+/**
+ * Spawn helper functions for reliable cross-platform command execution
+ *
+ * Issue #57: On macOS with Bun, node:child_process events may not fire reliably
+ * before the event loop exits. Bun.spawn provides more reliable stream handling.
+ *
+ * This module provides two implementations:
+ * - runWithBunSpawn: Uses Bun.spawn with async/await for reliable event handling
+ * - runWithNodeSpawn: Uses node:child_process with close event for Node.js compatibility
+ */
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+
+/**
+ * Run command using Bun.spawn (for Bun runtime)
+ * Uses async/await for reliable stream handling on macOS
+ *
+ * @param {Object} options - Execution options
+ * @param {string} options.shell - Shell to use
+ * @param {string[]} options.shellArgs - Shell arguments
+ * @param {string} options.logFilePath - Path to log file
+ * @param {string} options.logContent - Initial log content
+ * @param {number} options.startTimeMs - Start timestamp
+ * @param {Object} options.executionRecord - Execution tracking record
+ * @param {Object} options.store - Execution store
+ * @param {Object} options.config - CLI configuration
+ * @param {Function} options.onComplete - Callback for completion (exitCode, endTime, logContent, durationMs)
+ * @param {Function} options.onError - Callback for errors (errorMessage, endTime, durationMs)
+ */
+async function runWithBunSpawn(options) {
+  const {
+    shell,
+    shellArgs,
+    logFilePath,
+    startTimeMs,
+    executionRecord,
+    store,
+    config,
+    onComplete,
+    onError,
+  } = options;
+
+  let logContent = options.logContent || '';
+
+  try {
+    // Spawn the process using Bun's native API
+    const proc = Bun.spawn([shell, ...shellArgs], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: 'inherit',
+    });
+
+    // Update execution record with PID and save initial state
+    if (executionRecord && store) {
+      executionRecord.pid = proc.pid;
+      try {
+        store.save(executionRecord);
+      } catch (err) {
+        if (config && config.verbose) {
+          console.error(
+            `[Tracking] Warning: Could not save execution record: ${err.message}`
+          );
+        }
+      }
+    }
+
+    if (config && config.verbose) {
+      console.log(`[verbose] Using Bun.spawn for reliable macOS handling`);
+      console.log(`[verbose] Process PID: ${proc.pid}`);
+    }
+
+    // Read stdout and stderr streams concurrently
+    // TextDecoder is a global in modern runtimes (Bun, Node.js 16+)
+    // eslint-disable-next-line no-undef
+    const decoder = new TextDecoder();
+
+    // Read stdout in real-time
+    const stdoutReader = proc.stdout.getReader();
+    const readStdout = async () => {
+      let output = '';
+      try {
+        while (true) {
+          const { done, value } = await stdoutReader.read();
+          if (done) {
+            break;
+          }
+          const text = decoder.decode(value);
+          process.stdout.write(text);
+          output += text;
+        }
+      } catch (err) {
+        if (config && config.verbose) {
+          console.error(`[verbose] stdout read error: ${err.message}`);
+        }
+      }
+      return output;
+    };
+
+    // Read stderr in real-time
+    const stderrReader = proc.stderr.getReader();
+    const readStderr = async () => {
+      let output = '';
+      try {
+        while (true) {
+          const { done, value } = await stderrReader.read();
+          if (done) {
+            break;
+          }
+          const text = decoder.decode(value);
+          process.stderr.write(text);
+          output += text;
+        }
+      } catch (err) {
+        if (config && config.verbose) {
+          console.error(`[verbose] stderr read error: ${err.message}`);
+        }
+      }
+      return output;
+    };
+
+    // Read both streams concurrently and wait for process to exit
+    const [stdoutContent, stderrContent, exitCode] = await Promise.all([
+      readStdout(),
+      readStderr(),
+      proc.exited,
+    ]);
+
+    // Add captured output to log content
+    logContent += stdoutContent;
+    logContent += stderrContent;
+
+    const durationMs = Date.now() - startTimeMs;
+    const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
+
+    // Write log file
+    try {
+      logContent += `\n${'='.repeat(50)}\n`;
+      logContent += `Finished: ${endTime}\n`;
+      logContent += `Exit Code: ${exitCode}\n`;
+      fs.writeFileSync(logFilePath, logContent, 'utf8');
+    } catch (err) {
+      console.error(`\nWarning: Could not save log file: ${err.message}`);
+    }
+
+    // Update execution record as completed
+    if (executionRecord && store) {
+      executionRecord.complete(exitCode);
+      try {
+        store.save(executionRecord);
+      } catch (err) {
+        if (config && config.verbose) {
+          console.error(
+            `[Tracking] Warning: Could not update execution record: ${err.message}`
+          );
+        }
+      }
+    }
+
+    // Call completion callback
+    if (onComplete) {
+      onComplete(exitCode, endTime, logContent, durationMs);
+    }
+
+    return exitCode;
+  } catch (err) {
+    const durationMs = Date.now() - startTimeMs;
+    const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
+    const errorMessage = `Error executing command: ${err.message}`;
+
+    logContent += `\n${errorMessage}\n`;
+    logContent += `\n${'='.repeat(50)}\n`;
+    logContent += `Finished: ${endTime}\n`;
+    logContent += `Exit Code: 1\n`;
+
+    // Write log file
+    try {
+      fs.writeFileSync(logFilePath, logContent, 'utf8');
+    } catch (writeErr) {
+      console.error(`\nWarning: Could not save log file: ${writeErr.message}`);
+    }
+
+    // Update execution record as failed
+    if (executionRecord && store) {
+      executionRecord.complete(1);
+      try {
+        store.save(executionRecord);
+      } catch (storeErr) {
+        if (config && config.verbose) {
+          console.error(
+            `[Tracking] Warning: Could not update execution record: ${storeErr.message}`
+          );
+        }
+      }
+    }
+
+    // Call error callback
+    if (onError) {
+      onError(errorMessage, endTime, durationMs);
+    }
+
+    return 1;
+  }
+}
+
+/**
+ * Run command using node:child_process (for Node.js compatibility)
+ * Uses event-based handling with close event
+ *
+ * @param {Object} options - Execution options (same as runWithBunSpawn)
+ */
+function runWithNodeSpawn(options) {
+  const {
+    shell,
+    shellArgs,
+    logFilePath,
+    startTimeMs,
+    executionRecord,
+    store,
+    config,
+    onComplete,
+    onError,
+  } = options;
+
+  let logContent = options.logContent || '';
+
+  // Execute the command with captured output
+  const child = spawn(shell, shellArgs, {
+    stdio: ['inherit', 'pipe', 'pipe'],
+    shell: false,
+  });
+
+  // Update execution record with PID and save initial state
+  if (executionRecord && store) {
+    executionRecord.pid = child.pid;
+    try {
+      store.save(executionRecord);
+    } catch (err) {
+      if (config && config.verbose) {
+        console.error(
+          `[Tracking] Warning: Could not save execution record: ${err.message}`
+        );
+      }
+    }
+  }
+
+  // Capture stdout
+  child.stdout.on('data', (data) => {
+    const text = data.toString();
+    process.stdout.write(text);
+    logContent += text;
+  });
+
+  // Capture stderr
+  child.stderr.on('data', (data) => {
+    const text = data.toString();
+    process.stderr.write(text);
+    logContent += text;
+  });
+
+  // Handle process close (not 'exit' - we need to wait for all stdio to be closed)
+  // The 'close' event fires after all stdio streams have been closed, ensuring
+  // all stdout/stderr data has been received. The 'exit' event can fire before
+  // buffered data is received, causing output loss on macOS (Issue #57).
+  child.on('close', (code) => {
+    const exitCode = code || 0;
+    const durationMs = Date.now() - startTimeMs;
+    const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
+
+    // Log footer
+    logContent += `\n${'='.repeat(50)}\n`;
+    logContent += `Finished: ${endTime}\n`;
+    logContent += `Exit Code: ${exitCode}\n`;
+
+    // Write log file
+    try {
+      fs.writeFileSync(logFilePath, logContent, 'utf8');
+    } catch (err) {
+      console.error(`\nWarning: Could not save log file: ${err.message}`);
+    }
+
+    // Update execution record as completed
+    if (executionRecord && store) {
+      executionRecord.complete(exitCode);
+      try {
+        store.save(executionRecord);
+      } catch (err) {
+        if (config && config.verbose) {
+          console.error(
+            `[Tracking] Warning: Could not update execution record: ${err.message}`
+          );
+        }
+      }
+    }
+
+    // Call completion callback
+    if (onComplete) {
+      onComplete(exitCode, endTime, logContent, durationMs);
+    }
+  });
+
+  // Handle spawn errors
+  child.on('error', (err) => {
+    const durationMs = Date.now() - startTimeMs;
+    const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
+    const errorMessage = `Error executing command: ${err.message}`;
+
+    logContent += `\n${errorMessage}\n`;
+    logContent += `\n${'='.repeat(50)}\n`;
+    logContent += `Finished: ${endTime}\n`;
+    logContent += `Exit Code: 1\n`;
+
+    // Write log file
+    try {
+      fs.writeFileSync(logFilePath, logContent, 'utf8');
+    } catch (writeErr) {
+      console.error(`\nWarning: Could not save log file: ${writeErr.message}`);
+    }
+
+    // Update execution record as failed
+    if (executionRecord && store) {
+      executionRecord.complete(1);
+      try {
+        store.save(executionRecord);
+      } catch (storeErr) {
+        if (config && config.verbose) {
+          console.error(
+            `[Tracking] Warning: Could not update execution record: ${storeErr.message}`
+          );
+        }
+      }
+    }
+
+    // Call error callback
+    if (onError) {
+      onError(errorMessage, endTime, durationMs);
+    }
+  });
+
+  return child;
+}
+
+module.exports = {
+  runWithBunSpawn,
+  runWithNodeSpawn,
+};

package/test/args-parser.test.js

@@ -889,3 +889,25 @@ describe('VALID_OUTPUT_FORMATS', () => {
     assert.ok(VALID_OUTPUT_FORMATS.includes('text'));
   });
 });
+
+describe('cleanup options', () => {
+  it('should parse --cleanup flag', () => {
+    const result = parseArgs(['--cleanup']);
+    assert.strictEqual(result.wrapperOptions.cleanup, true);
+    assert.strictEqual(result.wrapperOptions.cleanupDryRun, false);
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --cleanup-dry-run flag', () => {
+    const result = parseArgs(['--cleanup-dry-run']);
+    assert.strictEqual(result.wrapperOptions.cleanup, true);
+    assert.strictEqual(result.wrapperOptions.cleanupDryRun, true);
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should default cleanup to false', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.cleanup, false);
+    assert.strictEqual(result.wrapperOptions.cleanupDryRun, false);
+  });
+});

package/test/execution-store.test.js

@@ -480,4 +480,125 @@ describe('ExecutionStore verifyConsistency', () => {
   });
 });
 
+describe('ExecutionStore cleanupStale', () => {
+  let store;
+
+  beforeEach(() => {
+    cleanupTestDir();
+    store = new ExecutionStore({
+      appFolder: TEST_APP_FOLDER,
+      useLinks: false,
+    });
+  });
+
+  afterEach(() => {
+    cleanupTestDir();
+  });
+
+  it('should return empty result when no stale records exist', () => {
+    // Create a completed record
+    const record = new ExecutionRecord({
+      command: 'echo 1',
+      pid: process.pid, // Current process
+    });
+    record.complete(0);
+    store.save(record);
+
+    const result = store.cleanupStale();
+    expect(result.cleaned).toBe(0);
+    expect(result.records.length).toBe(0);
+    expect(result.errors.length).toBe(0);
+  });
+
+  it('should detect stale records with non-existent PIDs', () => {
+    // Create an "executing" record with a non-existent PID
+    const record = new ExecutionRecord({
+      command: 'echo stale',
+      pid: 999999999, // Non-existent PID
+      platform: process.platform,
+    });
+    store.save(record);
+
+    const result = store.cleanupStale({ dryRun: true });
+    expect(result.records.length).toBe(1);
+    expect(result.records[0].uuid).toBe(record.uuid);
+    expect(result.cleaned).toBe(1);
+  });
+
+  it('should detect stale records that exceed max age', () => {
+    // Create an "executing" record with an old start time
+    const oldTime = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString(); // 25 hours ago
+    const record = new ExecutionRecord({
+      command: 'echo old',
+      pid: process.pid, // Current process (still running)
+      startTime: oldTime,
+      platform: process.platform,
+    });
+    store.save(record);
+
+    // Use default max age (24 hours)
+    const result = store.cleanupStale({ dryRun: true });
+    expect(result.records.length).toBe(1);
+    expect(result.records[0].uuid).toBe(record.uuid);
+  });
+
+  it('should not detect records within max age as stale', () => {
+    // Create an "executing" record with a recent start time
+    const record = new ExecutionRecord({
+      command: 'echo recent',
+      pid: process.pid, // Current process (still running)
+      platform: process.platform,
+    });
+    store.save(record);
+
+    const result = store.cleanupStale({ dryRun: true });
+    // Should not find this as stale because process is running and not too old
+    expect(result.records.length).toBe(0);
+  });
+
+  it('should clean up stale records when dryRun is false', () => {
+    // Create an "executing" record with a non-existent PID
+    const record = new ExecutionRecord({
+      command: 'echo cleanup-me',
+      pid: 999999999, // Non-existent PID
+      platform: process.platform,
+    });
+    store.save(record);
+
+    // Verify it's still "executing"
+    let retrieved = store.get(record.uuid);
+    expect(retrieved.status).toBe(ExecutionStatus.EXECUTING);
+
+    // Clean it up
+    const result = store.cleanupStale({ dryRun: false });
+    expect(result.cleaned).toBe(1);
+
+    // Verify it's now "executed" with exit code -1
+    retrieved = store.get(record.uuid);
+    expect(retrieved.status).toBe(ExecutionStatus.EXECUTED);
+    expect(retrieved.exitCode).toBe(-1);
+    expect(retrieved.endTime).toBeTruthy();
+  });
+
+  it('should handle custom max age', () => {
+    // Create an "executing" record with start time 5 minutes ago
+    const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+    const record = new ExecutionRecord({
+      command: 'echo custom-age',
+      pid: process.pid, // Current process (still running)
+      startTime: fiveMinutesAgo,
+      platform: process.platform,
+    });
+    store.save(record);
+
+    // Should not find as stale with default 24h max age
+    let result = store.cleanupStale({ dryRun: true });
+    expect(result.records.length).toBe(0);
+
+    // Should find as stale with 1 minute max age
+    result = store.cleanupStale({ dryRun: true, maxAgeMs: 60 * 1000 });
+    expect(result.records.length).toBe(1);
+  });
+});
+
 console.log('=== Execution Store Unit Tests ===');