feat(cli): clean exit 130 on Ctrl+C outside a run (#241, PR 2 of 2)

[pbean]

Closes #241 (PR 2 of 2 — the ExitCode enum + docs landed in #255).

What

A KeyboardInterrupt that escapes main() outside engine.run() — during config load, engine construction, or a handler with no run loop — was uncaught. A KeyboardInterrupt is a BaseException, so the broad except Exception backstop never caught it.

This catches it at the dispatch boundary, prints a one-line interrupted to stderr, and returns the new ExitCode.INTERRUPTED = 130 (128 + SIGINT).

The exit code was already 130 — this makes it clean

The issue text (and the original F-5 assessment) said this path exited rc 1. That is wrong, and PR #255's review already corrected the record: uncaught, CPython re-raises SIGINT and the process already ended at 130 — verified again here:

$ python -c 'raise KeyboardInterrupt'; echo $?
Traceback (most recent call last):
  ...
KeyboardInterrupt
130

So the exit code is unchanged. What changes:

	before (uncaught)	after (this PR)
shell $?	130	130
subprocess.returncode	-2 (signal death)	130 (clean exit)
stderr	bare traceback	one-line interrupted
stdout	whatever a --json command had already written	empty

The clean, empty stdout matters most for --json consumers, which otherwise had a half-written document followed by a traceback.

Deliberately unchanged

The in-run interrupt path is engine.run()'s own clean RunStopped (engine.py:333-348) and never reaches this handler — a Ctrl+C during a run still finalizes as a resumable stopped run at rc 0. Per finding F-5 that path's rc must not move, so engine.py is untouched.

Tests

• New characterization test: raising KeyboardInterrupt from a monkeypatched handler → rc 130, stderr interrupted, empty stdout (--json-safe), no traceback.
• ExitCode enum tests updated for the new member ({0, 1, 2, 130}).
• CHANGELOG under Changed documents the clean-message change and the -2 → 130 subprocess.returncode shift; the README exit-code table gains the INTERRUPTED row (the feat(cli): ExitCode enum + exit-code docs (#241, PR 1 of 2) #255 note that forward-referenced this PR is replaced).
• Full suite green (2723 passed). The 2 test_module_skills_sync failures are pre-existing local .agents/.claude module.yaml drift (untracked install artifacts), not from this diff. trunk check clean.

Summary by CodeRabbit

• Bug Fixes

  • Pressing Ctrl+C outside an active run now exits cleanly with code 130.
  • Displays a concise interrupted message instead of a traceback.
  • Ensures no partial output is written to standard output when interrupted.

• Documentation

  • Clarified exit-code behavior, including the distinction between interruptions during and outside active runs.

[coderabbitai]

Warning

Review limit reached

@pbean, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0505feb1-6b2d-443c-84ce-8b997088d2f3

📥 Commits

Reviewing files that changed from the base of the PR and between 9415520 and c1b6d53.

📒 Files selected for processing (2)

• src/bmad_loop/cli.py
• tests/test_entry_point.py

Walkthrough

The CLI now returns exit code 130 for KeyboardInterrupt outside engine.run(), prints interrupted to stderr, and avoids traceback output. Interrupts during a run remain resumable with exit code 0. Tests and documentation cover the updated exit-code contract.

Changes

Interrupt exit contract

Layer / File(s)	Summary
CLI interrupt handling src/bmad_loop/cli.py	Adds ExitCode.INTERRUPTED = 130 and handles KeyboardInterrupt at the main() boundary with clean stderr output.
Interrupt validation and documentation tests/test_entry_point.py, README.md, CHANGELOG.md	Tests verify code 130, empty stdout, and no traceback; documentation records the distinction between interrupts inside and outside a run.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• bmad-code-org/bmad-loop#249: Adds related CLI exit-code characterization tests.
• bmad-code-org/bmad-loop#255: Introduces the ExitCode contract extended by this change.

Suggested reviewers: dracic

Poem

I pressed Ctrl+C with a twitch of my nose,
Now 130 is the way the wind blows.
“interrupted,” I whisper, no traceback in sight,
While running loops stop and resume just right.
— A tidy-tailed rabbit 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is specific, concise, and accurately summarizes the main change: cleanly exiting with code 130 on Ctrl+C outside a run.
Linked Issues check	✅ Passed	The changes match #241 by catching outside-run KeyboardInterrupt, returning 130, preserving in-run behavior, and updating tests and docs.
Out of Scope Changes check	✅ Passed	The diff stays within the exit-code fix scope; the README, changelog, code, and tests all support the same behavior change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/exit-code-interrupted

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pbean]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[pbean]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/bmad_loop/cli.py`:
- Line 92: Replace the en dash in the numeric range `3–129` with a hyphen in the
docstrings at src/bmad_loop/cli.py lines 92-92 and tests/test_entry_point.py
lines 153-153; no other changes are needed.

In `@tests/test_entry_point.py`:
- Around line 122-137: Update test_exit_keyboard_interrupt_is_130 to invoke
cli.main with the validate --json option, then assert captured.err exactly
equals "interrupted\n" rather than stripping whitespace. Keep the existing
exit-code, empty-stdout, and traceback assertions unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 353ad3ae-91d9-4bbb-91ce-612702624fc4

📥 Commits

Reviewing files that changed from the base of the PR and between dc71927 and 9415520.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• src/bmad_loop/cli.py
• tests/test_entry_point.py