[fatal-guard] CLI entry point hardening: error messages, exit codes, help text

[Ikalus1988]

Goal

Harden the fatal-guard CLI entry point for production use.

Context

fatal-guard has a CLI at bin/fatal-guard.js but it lacks:

• Consistent exit codes (0=success, 1=error, 2=usage)
• Helpful error messages when things fail
• --help and --version flags
• Graceful handling of missing Node.js
• Timeout for hung processes

Scope

• Add --help flag with usage examples
• Add --version flag
• Define exit codes: 0=normal, 1=error caught, 2=usage error, 3=timeout
• Add --timeout <ms> flag (default: 0 = no timeout)
• Improve error messages for common failures:
  • Missing FATAL_HANDLER
  • Invalid JSON output from handler
  • Process not found
• Test all exit codes and error paths

Deliverable

• fatal-guard --help shows usage
• fatal-guard --version shows version
• Exit codes are consistent and documented
• Error messages are actionable

Labels

ready, agent-friendly, zero-bounty

---

This repo is using Opire - what does it mean? 👇

💵 Everyone can add rewards for this issue commenting /reward 100 (replace 100 with the amount).
🕵️‍♂️ If someone starts working on this issue to earn the rewards, they can comment /try to let everyone know!
🙌 And when they open the PR, they can comment /claim #1010 either in the PR description or in a PR's comment.

🪙 Also, everyone can tip any user commenting /tip 20 @Ikalus1988 (replace 20 with the amount, and @Ikalus1988 with the user to tip).

📖 If you want to learn more, check out our documentation.

[2lll5]

/opire try

[2lll5]

Implemented in PR #1023: #1023

[Ikalus1988]

Status update

This issue is blocked by:

• PR feat(fatal-guard): harden CLI entry point #1023 has merge conflicts (3 conflicts in fatal-guard.js: CLI rewrite + Windows compat)
• PR test(fatal-guard): add cross-platform crash smoke #1027 (smoke test) has been merged with FATAL_HANDLER_ARGS support
• The CLI hardening needs to be rebased on top of the merged smoke test

Before implementing:

1. Rebase PR feat(fatal-guard): harden CLI entry point #1023 on latest main
2. Ensure CLI hardening (exit codes, --help, --version, --timeout) doesn't duplicate FATAL_HANDLER_ARGS from test(fatal-guard): add cross-platform crash smoke #1027
3. Verify buildPayload(reason, error) signature matches index.js

Do not start new implementation until #1023 is rebased.