feat: shekel run — non-invasive CLI budget enforcement (v0.2.9)

[arieradle]

Summary

• Adds shekel run agent.py --budget 5 as a zero-code-change budget enforcer for any Python agent script
• New Budget(warn_only=True) parameter suppresses raises and fires warn callback instead
• GitHub Actions composite action (.github/actions/enforce/action.yml) for GHA pipelines
• Docker & container docs (docs/docker.md) with entrypoint patterns, env-var control, JSON logging

Key flags

Flag	Description
--budget N / AGENT_BUDGET_USD=N	USD cap; env var enables Docker/CI operator control
--warn-at F	Warn at fraction of budget (e.g. 0.8)
--max-llm-calls N	Cap on LLM API calls
--max-tool-calls N	Cap on tool invocations
--output json	Machine-readable spend summary
--warn-only	Log warning, never exit 1
--dry-run	Track only, implies --warn-only
--budget-file PATH	Load limits from shekel.toml

Test plan

• 85 new tests (TDD — red before green), all passing
• 100% coverage on _cli.py, _run_utils.py, _run_config.py
• black, isort, ruff, mypy — all clean on changed files
• Performance: shekel run on no-op script < 100 ms (benchmark median ~230 µs)
• Pre-existing failures (litellm Groq + temporal performance flakiness) unchanged

🤖 Generated with Claude Code

In general, to avoid swallowing exceptions with a finally plus an unconditional exit/return, ensure that process termination (or returns) occur inside the try block, and that the finally block is restricted to cleanup that should run regardless of success or failure. If additional reporting or summary output is needed, it should either be done outside the finally after confirming no exception occurred, or wrapped in its own try/except so that unexpected issues don’t silently override earlier errors.

For this specific snippet in shekel/_cli.py, the least disruptive fix is:

• Move sys.exit(script_exit_code) from after the finally into the try block (after the core script execution and any logic that sets script_exit_code).
• Wrap the content of the current finally block in an inner try/except to ensure that any unexpected exception in the reporting code does not mask the original exception from the try. In the except of that inner block, re-raise so that the original behavior (propagating an error) is preserved when something goes wrong in summary generation.
• Keep sys.argv = original_argv as unconditional cleanup in the outer finally so it always runs, even if reporting fails. The rest of the status/JSON/text printing logic should be in the inner try so exceptions there can propagate properly.

Concretely, within the region around lines 270–305:

• Change the finally: block so that it only guarantees restoration of sys.argv, and does the status/output logic inside an inner try/except that re-raises.
• Remove the trailing sys.exit(script_exit_code) outside the try/finally, and add a sys.exit(script_exit_code) at the end of the try block where the script’s main logic finishes. Because the snippet you provided only shows the end of the function, we will adjust just this bottom region: we will move the sys.exit(script_exit_code) into the try by replacing the end of the finally + trailing sys.exit with a finally that sets sys.argv and an explicit inner try/except for the reporting code.

No new imports or helper methods are needed; we only restructure the control flow in the shown section.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!