lonny-agent 0.2.4 → 0.2.7

package/src/tools/{write_plan.ts → edit/write_plan.ts}

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
-import { fmtErr } from './errors.js'
-import type { Tool, ToolResult } from './types.js'
+import { fmtErr } from '../errors.js'
+import type { Tool, ToolResult } from '../types.js'
 
 /** Directory where plans are stored, relative to project root */
 export const PLAN_DIR = '.lonny'
@@ -32,6 +32,8 @@ export function createWritePlanTool(
   return {
     definition: {
       name: 'write_plan',
+      category: 'Edit',
+      group: 'Plan',
       description: `Write a plan/todo document to the project's "${PLAN_DIR}/" folder. Use this in plan mode to persist the generated plan. The file is always created under "${PLAN_DIR}/" relative to the working directory; do NOT include the folder prefix in filename. Existing files with the same name will be overwritten.`,
       parameters: {
         filename: {

package/src/tools/execute/bash/constants.ts

@@ -0,0 +1,93 @@
+/** Maximum output length (chars) to prevent context overflow. */
+export const MAX_OUTPUT_LENGTH = 10_000
+
+/** Maximum stderr length included in error messages */
+export const MAX_ERROR_LENGTH = 2_000
+
+/** Maximum allowed timeout (10 minutes) */
+export const MAX_TIMEOUT = 600_000
+
+/** Minimum allowed timeout (100ms) */
+export const MIN_TIMEOUT = 100
+
+/** Default timeout (2 minutes) */
+export const DEFAULT_TIMEOUT = 120_000
+
+/**
+ * Patterns that indicate a destructive command.
+ * If matched, the tool will warn the user instead of executing.
+ */
+export const DESTRUCTIVE_PATTERNS: { regex: RegExp; hint: string }[] = [
+  // ═══════════════════════
+  // Unix destructive
+  // ═══════════════════════
+  { regex: /\brm\s+-(?:rf|fr)\s+\/$/i, hint: 'rm -rf / would destroy the system' },
+  { regex: /\brm\s+-(?:rf|fr)\s+\/\*/i, hint: 'rm -rf /* would destroy the system' },
+  { regex: /\brm\s+-(?:rf|fr)\s+~$/i, hint: 'rm -rf ~ would delete the home directory' },
+  { regex: /\b(?:mkfs|dd)\s+(?:\/dev|\\.)/i, hint: 'mkfs/dd would destroy a disk device' },
+  { regex: /\bchmod\s+-R\s+0{4}\b/, hint: 'chmod -R 0000 would make files inaccessible' },
+  {
+    regex: /\b(?:shutdown|reboot|halt|poweroff)\s+(?:-h|-r|-now|now)\b/i,
+    hint: 'shutdown/reboot would halt the system',
+  },
+  {
+    regex: /\b(?:killall|pkill)\s+-9\s+/i,
+    hint: 'killall -9 would terminate all matching processes',
+  },
+  // ═══════════════════════
+  // Windows destructive
+  // ═══════════════════════
+  {
+    regex: /\b(?:Remove-Item|rmdir|rd)\s+.*(?:-Recurse|-R)\s+.*(?:-Force|-F)\b/i,
+    hint: 'recursive force delete would destroy data',
+  },
+  {
+    regex: /\b(?:Remove-Item|rmdir|rd)\s+\w:\s*[\\/]/i,
+    hint: 'recursive delete on drive root would destroy data',
+  },
+  {
+    regex: /\b(?:del|erase)\s+.*(?:\/F|\/S)\b/i,
+    hint: 'force delete would destroy files irreversibly',
+  },
+  { regex: /\bformat\s+\w:\s*\/[Qq]/i, hint: 'format would destroy a drive' },
+  { regex: /\b(?:diskpart|clean-all)\b/i, hint: 'diskpart clean-all would destroy all partitions' },
+  { regex: /\bClear-Item\s+/i, hint: 'Clear-Item would delete content irreversibly' },
+  { regex: /\bClear-Content\s+/i, hint: 'Clear-Content would delete file content irreversibly' },
+  { regex: /\bRemove-ItemProperty\s+/i, hint: 'Remove-ItemProperty would delete registry keys' },
+  { regex: /\bRemove-Variable\s+-Force\b/i, hint: 'Remove-Variable -Force would delete variables' },
+  { regex: /\breg\s+delete\s+/i, hint: 'reg delete would destroy registry entries' },
+  { regex: /\bwmic\s+\w+\s+delete\b/i, hint: 'wmic delete would destroy system resources' },
+  { regex: /\b(?:cipher|sdelete)\s+\/w:/i, hint: 'secure delete would irreversibly wipe data' },
+  {
+    regex: /\[System\.IO\.Directory\]::Delete\s*\(/i,
+    hint: 'Directory.Delete would destroy data irreversibly',
+  },
+  {
+    regex: /\[System\.IO\.File\]::Delete\s*\(/i,
+    hint: 'File.Delete would destroy data irreversibly',
+  },
+]
+
+/**
+ * Patterns that match sensitive data (API keys, tokens, passwords, etc.)
+ * in command output. Matching content is replaced with "[REDACTED]".
+ */
+export const SENSITIVE_PATTERNS: RegExp[] = [
+  // Generic API keys / tokens
+  /(?:api[_-]?key|apikey|token|secret|password|passwd|credential|auth[_-]?token)[=:]\s*['"]?[A-Za-z0-9_\-.]{16,}/gi,
+  // AWS keys
+  /(?:AKIA[0-9A-Z]{16}|[A-Za-z0-9+/]{40}\s*=[=]{0,2})/g,
+  // GitHub tokens
+  /gh[pousr]_[A-Za-z0-9_]{36,}/g,
+  // npm tokens
+  /npm_[A-Za-z0-9]{36,}/g,
+  // Slack tokens
+  /xox[baprs]-[A-Za-z0-9-]{24,}/g,
+  // SSH private key content (multi-line)
+  /-----BEGIN[ A-Z]+PRIVATE KEY-----[\s\S]*?-----END[ A-Z]+PRIVATE KEY-----/g,
+  // JWT tokens
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  // Generic password-like strings in env vars
+  /export\s+\w*(?:PASS|SECRET|TOKEN|KEY)\w*\s*=\s*['"]?\S+['"]?/gi,
+  /\$env:\w*(?:PASS|SECRET|TOKEN|KEY)\w*\s*=\s*['"]?\S+['"]?/gi,
+]

package/src/tools/execute/bash/errors.ts

@@ -0,0 +1,304 @@
+import * as os from 'node:os'
+
+import { MAX_ERROR_LENGTH } from './constants.js'
+import { redactSensitive } from './security.js'
+
+/**
+ * Truncate a string to maxLength chars. If truncated, appends a warning.
+ * Returns the (possibly truncated) string.
+ */
+function truncateOutput(s: string, maxLength: number, label: string): string {
+  if (s.length <= maxLength) return s
+  const truncated = s.slice(0, maxLength)
+  const warning = `\n... [${label} truncated at ${maxLength} chars, original ${s.length} chars]`
+  return truncated + warning
+}
+
+/**
+ * Check if stderr contains PowerShell NativeCommandError wrapping.
+ * This happens when a native command (like git push) writes to stderr and
+ * PowerShell wraps the output in an ErrorRecord format even though the
+ * command exited successfully (exit code 0).
+ *
+ * Example format:
+ *   git : Everything up-to-date
+ *   At line:1 char:1
+ *   + git push 2>&1
+ *   + ~~~~~~~~~~~~~
+ *       + CategoryInfo          : NotSpecified: (...) [], RemoteException
+ *       + FullyQualifiedErrorId : NativeCommandError
+ *
+ * Returns the extracted actual output if detected, null otherwise.
+ */
+function extractPowerShellNativeOutput(stderr: string): string | null {
+  // Detect PowerShell ErrorRecord wrapping around native command stderr output.
+  // The key marker is "FullyQualifiedErrorId : NativeCommandError".
+  if (!/FullyQualifiedErrorId\s*:\s*NativeCommandError/i.test(stderr)) {
+    return null
+  }
+
+  const lines = stderr.split(/\r?\n/)
+  const outputLines: string[] = []
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+
+    // Skip PowerShell error record wrapper lines:
+    //   "   + CategoryInfo          : ..."  (indented, with +)
+    //   "   + FullyQualifiedErrorId : ..."
+    //   "At line:1 char:1" or Chinese garbled equivalent
+    //   "+ command ..." (the command echo line with leading +)
+    //   "  + ~~~~~~~~~~~~~" (the caret underline)
+    if (
+      /^\s*\+/.test(trimmed) ||
+      /^At\s+line:\d+/i.test(trimmed) ||
+      /^\+?\s*CategoryInfo/i.test(trimmed) ||
+      /^\+?\s*FullyQualifiedErrorId/i.test(trimmed)
+    ) {
+      continue
+    }
+
+    // Skip blank lines within the error record block (but keep leading whitespace for formatting)
+    if (!trimmed && outputLines.length > 0) {
+      continue
+    }
+
+    // Remove leading whitespace from the first content line (the "<command> : <message>" line)
+    outputLines.push(line)
+  }
+
+  const result = outputLines.join('\n').trim()
+  return result || null
+}
+
+/**
+ * Check if stderr indicates common PowerShell errors and return a helpful message.
+ * Returns a tip string if detected, null otherwise.
+ */
+function checkPowerShellError(stderr: string, command: string): string | null {
+  const errLower = stderr.toLowerCase()
+
+  // Execution policy errors
+  if (/execution.?policy/i.test(errLower) || /running scripts is disabled/i.test(errLower)) {
+    return 'PowerShell execution policy is blocking this command. Try: `powershell -ExecutionPolicy Bypass -Command "..."`'
+  }
+
+  // Module not found
+  if (
+    /module.*not (found|available)/i.test(errLower) ||
+    /could not (find|load).*module/i.test(errLower)
+  ) {
+    const moduleMatch = stderr.match(/module\s+['"]?(\w+)['"]?/i)
+    const moduleName = moduleMatch ? moduleMatch[1]! : '<unknown>'
+    return `PowerShell module not found: "${moduleName}". Install it with: Install-Module ${moduleName} -Force`
+  }
+
+  // Cmdlet not found
+  if (/the term '(\w+)' is not recognized/i.test(errLower)) {
+    const cmdMatch = stderr.match(/the term '(\w+)'/i)
+    const cmdName = cmdMatch ? cmdMatch[1]! : command.split(/\s+/)[0] || command
+    return `Cmdlet not found: "${cmdName}". This command may need a module or be installed separately.`
+  }
+
+  // Access denied
+  if (
+    /access is denied/i.test(errLower) ||
+    /permission denied/i.test(errLower) ||
+    /unauthorized/i.test(errLower)
+  ) {
+    return 'Access denied. Try running as Administrator (on Windows) or using sudo (on Unix).'
+  }
+
+  // Path not found
+  if (/cannot find (path|drive)/i.test(errLower) || /path.*does not exist/i.test(errLower)) {
+    return 'The specified path or drive was not found. Check that the path exists and is accessible.'
+  }
+
+  return null
+}
+
+/**
+ * Check if stderr output indicates a "command not found" error.
+ * Returns a platform-appropriate suggestion if detected, null otherwise.
+ */
+function checkCommandNotFound(stderr: string, command: string): string | null {
+  const isWindows = os.platform() === 'win32'
+  const errLower = stderr.toLowerCase()
+
+  if (isWindows) {
+    // PowerShell "not recognized" patterns
+    if (
+      /not recognized/.test(errLower) ||
+      /is not recognized/.test(errLower) ||
+      /找不到/.test(errLower) ||
+      /command not found/.test(errLower) ||
+      /not found/.test(errLower) ||
+      /neither the command nor/.test(errLower)
+    ) {
+      // Extract the command name that wasn't found (first word of the command)
+      const cmdName = command.split(/\s+/)[0] || command
+      return `Command not found: "${cmdName}". It may be a Unix command not available on Windows. Use "where" to find available commands or use PowerShell-native alternatives.`
+    }
+  } else {
+    // Unix "not found" patterns
+    if (
+      /not found/.test(errLower) ||
+      /command not found/.test(errLower) ||
+      /no such file/.test(errLower)
+    ) {
+      const cmdName = command.split(/\s+/)[0] || command
+      return `Command not found: "${cmdName}". Check that it is installed, or use "which ${cmdName}" to find its location.`
+    }
+  }
+  return null
+}
+
+/**
+ * Build a helpful error message for a failed command, including
+ * platform-specific suggestions when applicable.
+ */
+function buildErrorMsg(
+  exitCode: number,
+  stderr: string,
+  command: string,
+  timedOut: boolean,
+  cwd?: string,
+): string {
+  const parts: string[] = []
+
+  if (timedOut) {
+    parts.push(`Command timed out (exit code ${exitCode})`)
+  } else {
+    parts.push(`Command exited with code ${exitCode}`)
+  }
+
+  // Check for "command not found" first (before including full stderr)
+  const notFoundMsg = checkCommandNotFound(stderr, command)
+  if (notFoundMsg) {
+    parts.push(notFoundMsg)
+  }
+
+  // Check for common PowerShell errors
+  if (os.platform() === 'win32') {
+    const psErrMsg = checkPowerShellError(stderr, command)
+    if (psErrMsg) {
+      parts.push(psErrMsg)
+    }
+  }
+
+  // Include stderr content (truncated and redacted)
+  const stderrTrimmed = stderr.trim()
+  if (stderrTrimmed) {
+    const redactedStderr = redactSensitive(stderrTrimmed)
+    parts.push(`stderr:\n${truncateOutput(redactedStderr, MAX_ERROR_LENGTH, 'stderr')}`)
+  }
+
+  // Platform-specific suggestions for common mistakes
+  const isWindows = os.platform() === 'win32'
+
+  if (isWindows) {
+    // Common Windows command mistakes
+    if (/ls\b/.test(command) && !/ls\b/.test(command.replace(/".*"/g, ''))) {
+      parts.push('💡 Tip: On Windows, use `dir` instead of `ls`, or `Get-ChildItem` in PowerShell.')
+    }
+    if (/grep\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `findstr` or `Select-String` instead of `grep`.')
+    }
+    if (/touch\b/.test(command)) {
+      parts.push(
+        '💡 Tip: On Windows, `touch` is not available. Use `New-Item` or `edit` tool to create files.',
+      )
+    }
+    if (/ps\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Get-Process` instead of `ps` for listing processes.')
+    }
+    if (/pwd\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Get-Location` or `$pwd` instead of `pwd`.')
+    }
+    if (
+      /chmod\b/.test(command) ||
+      /cp\b/.test(command) ||
+      /mv\b/.test(command) ||
+      /rm\b/.test(command) ||
+      /mkdir\b/.test(command)
+    ) {
+      parts.push(
+        '💡 Tip: On Windows, use native equivalents: `copy`, `move`, `del`, `mkdir`, `icacls` instead of Unix commands.',
+      )
+    }
+    if (/cat\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `type` or `Get-Content` instead of `cat`.')
+    }
+    if (/which\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `where` instead of `which` to find executable locations.')
+    }
+    if (/less\b/.test(command) || /more\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `more` or `Out-Host -Paging` for paging output.')
+    }
+    if (/sort\b/.test(command) && !/sort-object/i.test(command) && !/Sort-Object/i.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Sort-Object` instead of `sort`.')
+    }
+    if (/head\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Select-Object -First` instead of `head`.')
+    }
+    if (/tail\b/.test(command)) {
+      parts.push(
+        '💡 Tip: On Windows, use `Get-Content -Tail` or `Select-Object -Last` instead of `tail`.',
+      )
+    }
+    if (/diff\b/.test(command) || /cmp\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Compare-Object` instead of `diff`/`cmp`.')
+    }
+    if (/curl\b/.test(command) && !/curl\b/.test(command.replace(/".*"/g, ''))) {
+      parts.push(
+        '💡 Tip: On Windows, use `Invoke-WebRequest` or `Invoke-RestMethod` instead of `curl`. curl is available in newer Windows builds.',
+      )
+    }
+    if (/wget\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Invoke-WebRequest` instead of `wget`.')
+    }
+    if (/env\b/.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Get-ChildItem Env:` to list environment variables.')
+    }
+    if (/kill\b/.test(command) && !/stop-process/i.test(command)) {
+      parts.push('💡 Tip: On Windows, use `Stop-Process` or `taskkill` instead of `kill`.')
+    }
+  } else {
+    // Unix-specific tips
+    if (/dir\b/.test(command)) {
+      parts.push('💡 Tip: On Unix, use `ls -la` instead of `dir`.')
+    }
+    if (/findstr\b/.test(command)) {
+      parts.push('💡 Tip: On Unix, use `grep` instead of `findstr`.')
+    }
+    if (/type\b/.test(command) && !/type\b/.test(command.replace(/".*"/g, ''))) {
+      parts.push('💡 Tip: On Unix, use `cat` instead of `type`.')
+    }
+    if (/where\b/.test(command)) {
+      parts.push('💡 Tip: On Unix, use `which` instead of `where` to find executable locations.')
+    }
+    if (/copy\b/.test(command)) {
+      parts.push('💡 Tip: On Unix, use `cp` instead of `copy`.')
+    }
+    if (/move\b/.test(command) || /ren\b/.test(command)) {
+      parts.push('💡 Tip: On Unix, use `mv` instead of `move`/`ren`.')
+    }
+    if (/del\b/.test(command)) {
+      parts.push('💡 Tip: On Unix, use `rm` instead of `del`.')
+    }
+  }
+
+  if (cwd) {
+    parts.push(`Working directory: ${cwd}`)
+  }
+
+  return parts.join('\n')
+}
+
+export {
+  buildErrorMsg,
+  checkCommandNotFound,
+  checkPowerShellError,
+  extractPowerShellNativeOutput,
+  truncateOutput,
+}

package/src/tools/execute/bash/execution.ts

@@ -0,0 +1,211 @@
+import type { ChildProcess } from 'node:child_process'
+import { execSync, spawn } from 'node:child_process'
+import * as os from 'node:os'
+
+import { fmtErr } from '../../errors.js'
+import { MAX_ERROR_LENGTH, MAX_OUTPUT_LENGTH } from './constants.js'
+import { ENCODING } from './platform.js'
+
+interface ExecResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+  timedOut: boolean
+}
+
+/**
+ * Kill a child process tree reliably across platforms.
+ * - On Windows: uses `taskkill /F /T` for force-kill of the process tree when possible.
+ * - On Unix: sends SIGTERM first, then SIGKILL after a grace period.
+ * - Handles missing pid and protects against thrown errors.
+ */
+function killProcess(child: ChildProcess): NodeJS.Timeout | undefined {
+  try {
+    if (!child || typeof (child as any).pid !== 'number' || Number.isNaN((child as any).pid)) {
+      // Best-effort kill if pid is not available
+      try {
+        child.kill()
+      } catch {
+        /* ignore */
+      }
+      return undefined
+    }
+
+    if (os.platform() === 'win32') {
+      try {
+        // Use taskkill to terminate the whole process tree. If it fails, fall back to child.kill().
+        execSync(`taskkill /F /T /PID ${child.pid}`, {
+          stdio: 'ignore',
+          timeout: 3000,
+        })
+      } catch {
+        try {
+          child.kill()
+        } catch {
+          /* ignore */
+        }
+      }
+      return undefined
+    } else {
+      try {
+        child.kill('SIGTERM')
+      } catch {
+        /* ignore */
+      }
+      // Track timer so we can force-KILL after a grace period
+      const killTimer = setTimeout(() => {
+        try {
+          child.kill('SIGKILL')
+        } catch {
+          /* already exited or cannot kill */
+        }
+      }, 5000)
+      // Ensure we clean up the timer and the listener when the child exits
+      const onExit = () => {
+        try {
+          clearTimeout(killTimer)
+        } catch {
+          /* ignore */
+        }
+        try {
+          child.removeListener('exit', onExit)
+        } catch {
+          /* ignore */
+        }
+      }
+      child.on('exit', onExit)
+      return killTimer
+    }
+  } catch {
+    return undefined
+  }
+}
+
+function execCommand(command: string, timeout: number, cwd?: string): Promise<ExecResult> {
+  return new Promise(resolve => {
+    const isWindows = os.platform() === 'win32'
+    const shellExe = isWindows ? 'powershell.exe' : process.env.SHELL || '/bin/sh'
+    const shellArgs = isWindows
+      ? ['-NoProfile', '-NonInteractive', '-Command', command]
+      : ['-c', command]
+
+    // Protect against spawn throwing synchronously (e.g. missing shell)
+    let child: ChildProcess | undefined
+    try {
+      child = spawn(shellExe, shellArgs, {
+        cwd: cwd || process.cwd(),
+        env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+        windowsHide: true,
+      })
+    } catch (err) {
+      // Return a normalized error result rather than throwing
+      resolve({ stdout: '', stderr: fmtErr(err), exitCode: 1, timedOut: false })
+      return
+    }
+
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+
+    // Keep memory bounded by limiting how much we accumulate for each stream
+    const MAX_STDOUT_BUFFER = Math.max(MAX_OUTPUT_LENGTH * 2, 20000)
+    const MAX_STDERR_BUFFER = Math.max(MAX_ERROR_LENGTH * 2, 4000)
+    let stdoutTruncated = false
+    let stderrTruncated = false
+
+    // Track which encodings work for each stream (per-chunk fallback).
+    let stdoutEncoding: string | undefined
+    let stderrEncoding: string | undefined
+
+    let treeKillTimer: NodeJS.Timeout | undefined
+    const timer = setTimeout(() => {
+      timedOut = true
+      // Attempt to kill the process tree; capture any returned timer so we can clear it on close
+      treeKillTimer = killProcess(child!)
+    }, timeout)
+
+    child!.stdout?.on('data', (data: Buffer) => {
+      if (stdout.length >= MAX_STDOUT_BUFFER) {
+        stdoutTruncated = true
+        return
+      }
+      try {
+        const enc = stdoutEncoding || ENCODING
+        stdout += data.toString(enc as BufferEncoding)
+        stdoutEncoding = enc
+      } catch {
+        // Detected encoding failed; fall back to utf-8
+        try {
+          stdout += data.toString('utf-8')
+          stdoutEncoding = 'utf-8'
+        } catch {
+          // Give up on this chunk
+        }
+      }
+    })
+
+    child!.stderr?.on('data', (data: Buffer) => {
+      if (stderr.length >= MAX_STDERR_BUFFER) {
+        stderrTruncated = true
+        return
+      }
+      try {
+        const enc = stderrEncoding || ENCODING
+        stderr += data.toString(enc as BufferEncoding)
+        stderrEncoding = enc
+      } catch {
+        try {
+          stderr += data.toString('utf-8')
+          stderrEncoding = 'utf-8'
+        } catch {
+          // ignore
+        }
+      }
+    })
+
+    const finish = (code: number | null) => {
+      try {
+        clearTimeout(timer)
+      } catch {
+        /* ignore */
+      }
+      if (treeKillTimer) {
+        try {
+          clearTimeout(treeKillTimer)
+        } catch {
+          /* ignore */
+        }
+      }
+
+      // If we truncated during streaming, append a short notice so final output can indicate truncation
+      if (stdoutTruncated) stdout += '\n... [stdout truncated due to size limit]'
+      if (stderrTruncated) stderr += '\n... [stderr truncated due to size limit]'
+
+      resolve({ stdout, stderr, exitCode: code ?? 0, timedOut })
+    }
+
+    child!.on('close', code => finish(code))
+
+    child!.on('error', err => {
+      try {
+        clearTimeout(timer)
+      } catch {
+        /* ignore */
+      }
+      if (treeKillTimer) {
+        try {
+          clearTimeout(treeKillTimer)
+        } catch {
+          /* ignore */
+        }
+      }
+      // Include the spawn error message in stderr so callers can surface it
+      const errMsg = fmtErr(err)
+      if (errMsg) stderr += (stderr ? '\n' : '') + errMsg
+      resolve({ stdout, stderr, exitCode: 1, timedOut })
+    })
+  })
+}
+
+export type { ExecResult }
+export { execCommand, killProcess }