Improve error messaging: Exit code 137 provides no diagnostic info

[EmZod]

Problem

When a command fails with exit code 137, there's zero explanation of what went wrong. Was it memory? Timeout? System kill? User has no path forward.

Perspective: As an AI agent executing speak on behalf of users, when I encounter cryptic errors with no diagnostics, I cannot self-correct or advise the user on next steps. This creates dead ends.

Actual Error Encountered

Exit code 137
[Request interrupted by user for tool use]
speak v0.1.0
Generating audio for 6208 characters...
→ Starting TTS server...
✓ TTS server started
Streaming audio with adaptive buffering...
[K  Buffering: 16.5s / 5s
  Buffer ready, starting playback...
[K  Playing chunk 1 (16.5s) | Buffer: 0.0s

Then: Exit 137. No explanation.

Expected Behavior

Error: Process killed by system (exit code 137)
Possible causes:
  • Out of memory (OOM killer)
  • Process timeout exceeded
  • User/system interrupt (SIGKILL)

Diagnostic info:
  • Memory usage: 8.2GB / 16GB
  • Generation time: 45s
  • TTS server status: Running

Try:
  • Use --model chatterbox-turbo-8bit (lower memory)
  • Use --stream for better memory management
  • Check system resources: Activity Monitor

Exit Code Reference

Common Unix exit codes that should have clear messages:

• 137 = SIGKILL (killed by system/user)
• 130 = SIGINT (Ctrl+C)
• 143 = SIGTERM (graceful termination requested)
• 1 = General error

Proposed Solution

1. Catch common exit codes and provide context-aware messages
2. Show diagnostic info when available (memory, time, model, etc.)
3. Suggest recovery actions based on error type
4. Log to error log (e.g., ~/.chatter/logs/errors.log)

Impact

• High - Critical for debugging and self-service recovery
• Reduces user frustration
• Enables agents to handle errors gracefully
• Improves overall reliability perception