fix(stall): validate --stall-action at CLI and cleanup (#401)

[frankbria]

Summary

Follow-up polish from code review on #425:

• Validate --stall-action at CLI layer with click.Choice (prevents unhelpful ValueError deep in runtime)
• Remove redundant stall_monitor.stop() in StallDetectedError handler (finally block already handles it)
• Update execute_agent docstring with stall_timeout_s and stall_action parameters

Test plan

• 46 stall-related tests pass
• Ruff lint clean

Summary by CodeRabbit

Release Notes

• New Features

  • Added input validation to stall-action CLI option, restricting choices to: blocker, retry, fail
  • Introduced configurable stall timeout and recovery action parameters for enhanced fault tolerance

• Improvements

  • Refined stall detection and recovery mechanism to improve system stability

[coderabbitai]

Walkthrough

Added Click input validation for stall_action CLI option across two commands, relocated stall monitor cleanup in exception handling, and wired stall_timeout_s and stall_action parameters through the runtime layer to ReactAgent for configurable stall recovery behavior.

Changes

Cohort / File(s)	Summary
CLI Input Validation codeframe/cli/app.py	Added Click import and constrained --stall-action option to accept only ["blocker", "retry", "fail"] (case-insensitive) for both work_start and batch_run commands.
Parameter Threading codeframe/core/runtime.py	Extended execute_agent signature with stall_timeout_s (int, default 300) and stall_action (str, default "blocker") parameters. Imported StallAction and StallDetectedError; wrapped stall_action value and passed both parameters to ReactAgent construction.
Exception Handler Cleanup codeframe/core/react_agent.py	Removed explicit stall monitor stop from StallDetectedError except clause; monitor cleanup now delegated solely to finally block.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(core): wire StallAction dispatch into ReactAgent and runtime (#401) #425: Directly modifies the same stall-action CLI option and execute_agent parameter threading into ReactAgent with exception-driven retry logic.
• feat: Agent stall detection and recovery (#399) #423: Overlaps with ReactAgent, runtime.execute_agent, and CLI stall handling modifications including monitor control flow.

Poem

🐰 A choice for stalls, three paths so fine,
Blocker, retry, fail—pick thine!
Through runtime's veins the config flows,
To ReactAgent, where the magic grows.
Finally cleanup, neat and bright,
Stall detection shines so right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: adding CLI-level validation for --stall-action using click.Choice and removing redundant code. It directly reflects the primary objectives of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/401-stall-action-polish

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@codeframe/core/runtime.py`:
- Around line 617-618: Update the docstring to state that stall_timeout_s and
stall_action apply only to the React engine; specifically mention that
execute_agent() consumes stall_timeout_s and stall_action only when engine ==
"react" (they are not used by the legacy plan engine). Reference the parameters
stall_timeout_s and stall_action and the function execute_agent so readers know
where the restriction applies.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 00e8099a-3041-476b-a951-64b4ad248701

📥 Commits

Reviewing files that changed from the base of the PR and between c3625f5 and 70ead0f.

📒 Files selected for processing (3)

• codeframe/cli/app.py
• codeframe/core/react_agent.py
• codeframe/core/runtime.py

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Clarify that these stall controls are React-only.

execute_agent() only consumes stall_timeout_s and stall_action in the engine == "react" path, so this docstring currently implies support that the legacy plan engine doesn't have.

📝 Suggested wording

-        stall_timeout_s: Seconds without tool activity before stall detection (0 = disabled)
-        stall_action: Recovery action on stall ("blocker", "retry", or "fail")
+        stall_timeout_s: React engine only. Seconds without tool activity before stall detection (0 = disabled)
+        stall_action: React engine only. Recovery action on stall ("blocker", "retry", or "fail")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@codeframe/core/runtime.py` around lines 617 - 618, Update the docstring to
state that stall_timeout_s and stall_action apply only to the React engine;
specifically mention that execute_agent() consumes stall_timeout_s and
stall_action only when engine == "react" (they are not used by the legacy plan
engine). Reference the parameters stall_timeout_s and stall_action and the
function execute_agent so readers know where the restriction applies.