[Phase 2.5] CLI returns exit code 0 for FAILED task executions

[frankbria]

Problem

codeframe work start <id> --execute returns exit code 0 even when the task execution fails. The CLI prints "Task execution failed" to stdout but never calls typer.Exit(1) or raise SystemExit(1).

Impact

• External tools (CI/CD, test runners, scripts) cannot reliably detect task failures
• The e2e test infrastructure had to implement _detect_success() as a workaround that parses stdout for success/failure patterns
• This workaround has its own false-positive bugs ([Phase 2.5] GoldenPathRunner._detect_success() has false positive when agent produces no output #374)

Expected Behavior

Outcome	Exit Code
Task completed successfully	0
Task execution failed	1
Task blocked	1
Invalid task ID / not found	2
Missing API key / config error	2

Files

• codeframe/cli/app.py — The work start command handler needs to check the run result and raise typer.Exit(1) for failure cases

[traycerai]

Plan

Observations

The work start command in file:codeframe/cli/app.py (lines 2054-2073) checks the AgentStatus after execution and prints appropriate messages but never calls raise typer.Exit(code) to set the process exit code. The same issue exists in the work retry command (lines 2519-2528) and potentially in batch execution commands. The codebase consistently uses raise typer.Exit(1) for error cases throughout other CLI commands, establishing a clear pattern to follow.

Approach

Add exit code handling immediately after agent execution status checks in the work start and work retry commands. Map AgentStatus.FAILED and AgentStatus.BLOCKED to exit code 1, and AgentStatus.COMPLETED to exit code 0 (implicit). For batch execution, check the batch results and exit with code 1 if any tasks failed or were blocked. This aligns with the expected behavior table in the issue and follows existing CLI error handling patterns.

Implementation Steps

1. Update work start Command Exit Codes

File: file:codeframe/cli/app.py

In the work_start function (lines 1957-2101), after the agent execution status checks (lines 2060-2073):

• After line 2061 where it prints success message for AgentStatus.COMPLETED, the function should continue normally (exit code 0 is implicit)
• After line 2066 where it prints blocked message for AgentStatus.BLOCKED, add raise typer.Exit(1)
• After line 2072 where it prints failure message for AgentStatus.FAILED, add raise typer.Exit(1)

The logic should be:

if state.status == AgentStatus.COMPLETED:
    console.print("[bold green]Task completed successfully![/bold green]")
    # Exit code 0 (success) - no explicit exit needed
elif state.status == AgentStatus.BLOCKED:
    console.print("[yellow]Task blocked - human input needed[/yellow]")
    if state.blocker:
        console.print(f"  Question: {state.blocker.question}")
    console.print("  Use 'codeframe blocker list' to see blockers")
    raise typer.Exit(1)  # ADD THIS
elif state.status == AgentStatus.FAILED:
    console.print("[red]Task execution failed[/red]")
    if state.step_results:
        last_result = state.step_results[-1]
        if last_result.error:
            console.print(f"  Error: {last_result.error[:200]}")
    raise typer.Exit(1)  # ADD THIS

2. Update work retry Command Exit Codes

File: file:codeframe/cli/app.py

In the work_retry function (lines 2427-2539), after the agent execution status checks (lines 2519-2528):

• After line 2520 where it prints success message for AgentStatus.COMPLETED, continue normally
• After line 2525 where it prints blocked message for AgentStatus.BLOCKED, add raise typer.Exit(1)
• After line 2528 where it prints failure message for AgentStatus.FAILED, add raise typer.Exit(1)

Apply the same pattern as in step 1.

3. Update work batch run Command Exit Codes

File: file:codeframe/cli/app.py

In the batch_run function (lines 2790-2994), after the batch summary is printed (lines 2944-2960):

Add exit code logic based on batch results:

# After line 2960, before the review section
if failed > 0 or blocked > 0:
    # If --review flag is set, still run review but exit with code 1 after
    # Otherwise exit immediately with code 1
    pass  # Will handle after review section

# After the review section (after line 2986), add:
if failed > 0 or blocked > 0:
    raise typer.Exit(1)

The logic should check if any tasks failed or were blocked, and if so, exit with code 1 after showing the summary and optionally running review gates.

4. Handle Edge Cases

Ensure the exit code logic handles these scenarios correctly:

• No execution: When --execute flag is not used in work start, the command should exit with code 0 (current behavior is correct)
• Stub execution: When --stub flag is used (lines 2086-2090), exit with code 0 (current behavior is correct)
• Dry run: When --dry-run is used in batch execution (lines 2919-2925), exit with code 0 (current behavior is correct)
• ValueError exceptions: Already handled correctly with raise typer.Exit(1) (lines 2082-2084, 2098-2100)

5. Verify Consistency with Expected Behavior Table

Cross-reference the implementation with the expected behavior table from the issue:

Outcome	Exit Code	Implementation Location
Task completed successfully	0	AgentStatus.COMPLETED - implicit exit 0
Task execution failed	1	AgentStatus.FAILED - add raise typer.Exit(1)
Task blocked	1	AgentStatus.BLOCKED - add raise typer.Exit(1)
Invalid task ID / not found	2	Already handled at lines 2025-2026, 2029-2032 - change to exit code 2
Missing API key / config error	2	Handled by ValueError exceptions - change to exit code 2

Additional Changes Needed:

• Lines 2025-2026: Change raise typer.Exit(1) to raise typer.Exit(2) for "No task found"
• Lines 2029-2032: Change raise typer.Exit(1) to raise typer.Exit(2) for "Multiple tasks match"
• Lines 2082-2084, 2098-2100: Change raise typer.Exit(1) to raise typer.Exit(2) for ValueError (config/API errors)

Apply the same exit code 2 pattern to work retry and other work commands for consistency.

6. Update Tests

Files: file:tests/cli/test_v2_cli_integration.py, file:tests/cli/test_work_diagnose.py

Update or add test cases to verify:

• work start --execute returns exit code 0 when task completes successfully
• work start --execute returns exit code 1 when task fails
• work start --execute returns exit code 1 when task is blocked
• work start with invalid task ID returns exit code 2
• work retry returns appropriate exit codes
• work batch run returns exit code 1 if any tasks fail or are blocked

Example test structure:

def test_work_start_execute_success_exit_code(workspace, task):
    result = runner.invoke(app, ["work", "start", task.id, "--execute", "-w", str(workspace.repo_path)])
    assert result.exit_code == 0

def test_work_start_execute_failure_exit_code(workspace, task):
    # Mock agent to return FAILED status
    result = runner.invoke(app, ["work", "start", task.id, "--execute", "-w", str(workspace.repo_path)])
    assert result.exit_code == 1

def test_work_start_invalid_task_exit_code(workspace):
    result = runner.invoke(app, ["work", "start", "nonexistent", "-w", str(workspace.repo_path)])
    assert result.exit_code == 2

Execution Flow

sequenceDiagram
    participant CLI as work start --execute
    participant Agent as runtime.execute_agent()
    participant Status as AgentStatus Check
    participant Exit as Process Exit

    CLI->>Agent: Execute task
    Agent-->>CLI: Return AgentState
    CLI->>Status: Check state.status
    
    alt status == COMPLETED
        Status->>Exit: Exit code 0 (implicit)
    else status == FAILED
        Status->>CLI: Print error message
        CLI->>Exit: raise typer.Exit(1)
    else status == BLOCKED
        Status->>CLI: Print blocked message
        CLI->>Exit: raise typer.Exit(1)
    end
    
    Note over Exit: External tools can now<br/>detect failures via exit code

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `work start` command in `file:codeframe/cli/app.py` (lines 2054-2073) checks the `AgentStatus` after execution and prints appropriate messages but never calls `raise typer.Exit(code)` to set the process exit code. The same issue exists in the `work retry` command (lines 2519-2528) and potentially in batch execution commands. The codebase consistently uses `raise typer.Exit(1)` for error cases throughout other CLI commands, establishing a clear pattern to follow.

## Approach

Add exit code handling immediately after agent execution status checks in the `work start` and `work retry` commands. Map `AgentStatus.FAILED` and `AgentStatus.BLOCKED` to exit code 1, and `AgentStatus.COMPLETED` to exit code 0 (implicit). For batch execution, check the batch results and exit with code 1 if any tasks failed or were blocked. This aligns with the expected behavior table in the issue and follows existing CLI error handling patterns.

## Implementation Steps

### 1. Update `work start` Command Exit Codes

**File**: `file:codeframe/cli/app.py`

In the `work_start` function (lines 1957-2101), after the agent execution status checks (lines 2060-2073):

- After line 2061 where it prints success message for `AgentStatus.COMPLETED`, the function should continue normally (exit code 0 is implicit)
- After line 2066 where it prints blocked message for `AgentStatus.BLOCKED`, add `raise typer.Exit(1)` 
- After line 2072 where it prints failure message for `AgentStatus.FAILED`, add `raise typer.Exit(1)`

The logic should be:
```
if state.status == AgentStatus.COMPLETED:
    console.print("[bold green]Task completed successfully![/bold green]")
    # Exit code 0 (success) - no explicit exit needed
elif state.status == AgentStatus.BLOCKED:
    console.print("[yellow]Task blocked - human input needed[/yellow]")
    if state.blocker:
        console.print(f"  Question: {state.blocker.question}")
    console.print("  Use 'codeframe blocker list' to see blockers")
    raise typer.Exit(1)  # ADD THIS
elif state.status == AgentStatus.FAILED:
    console.print("[red]Task execution failed[/red]")
    if state.step_results:
        last_result = state.step_results[-1]
        if last_result.error:
            console.print(f"  Error: {last_result.error[:200]}")
    raise typer.Exit(1)  # ADD THIS
```

### 2. Update `work retry` Command Exit Codes

**File**: `file:codeframe/cli/app.py`

In the `work_retry` function (lines 2427-2539), after the agent execution status checks (lines 2519-2528):

- After line 2520 where it prints success message for `AgentStatus.COMPLETED`, continue normally
- After line 2525 where it prints blocked message for `AgentStatus.BLOCKED`, add `raise typer.Exit(1)`
- After line 2528 where it prints failure message for `AgentStatus.FAILED`, add `raise typer.Exit(1)`

Apply the same pattern as in step 1.

### 3. Update `work batch run` Command Exit Codes

**File**: `file:codeframe/cli/app.py`

In the `batch_run` function (lines 2790-2994), after the batch summary is printed (lines 2944-2960):

Add exit code logic based on batch results:
```
# After line 2960, before the review section
if failed > 0 or blocked > 0:
    # If --review flag is set, still run review but exit with code 1 after
    # Otherwise exit immediately with code 1
    pass  # Will handle after review section

# After the review section (after line 2986), add:
if failed > 0 or blocked > 0:
    raise typer.Exit(1)
```

The logic should check if any tasks failed or were blocked, and if so, exit with code 1 after showing the summary and optionally running review gates.

### 4. Handle Edge Cases

Ensure the exit code logic handles these scenarios correctly:

- **No execution**: When `--execute` flag is not used in `work start`, the command should exit with code 0 (current behavior is correct)
- **Stub execution**: When `--stub` flag is used (lines 2086-2090), exit with code 0 (current behavior is correct)
- **Dry run**: When `--dry-run` is used in batch execution (lines 2919-2925), exit with code 0 (current behavior is correct)
- **ValueError exceptions**: Already handled correctly with `raise typer.Exit(1)` (lines 2082-2084, 2098-2100)

### 5. Verify Consistency with Expected Behavior Table

Cross-reference the implementation with the expected behavior table from the issue:

| Outcome | Exit Code | Implementation Location |
|---------|-----------|------------------------|
| Task completed successfully | 0 | `AgentStatus.COMPLETED` - implicit exit 0 |
| Task execution failed | 1 | `AgentStatus.FAILED` - add `raise typer.Exit(1)` |
| Task blocked | 1 | `AgentStatus.BLOCKED` - add `raise typer.Exit(1)` |
| Invalid task ID / not found | 2 | Already handled at lines 2025-2026, 2029-2032 - **change to exit code 2** |
| Missing API key / config error | 2 | Handled by ValueError exceptions - **change to exit code 2** |

**Additional Changes Needed**:
- Lines 2025-2026: Change `raise typer.Exit(1)` to `raise typer.Exit(2)` for "No task found"
- Lines 2029-2032: Change `raise typer.Exit(1)` to `raise typer.Exit(2)` for "Multiple tasks match"
- Lines 2082-2084, 2098-2100: Change `raise typer.Exit(1)` to `raise typer.Exit(2)` for ValueError (config/API errors)

Apply the same exit code 2 pattern to `work retry` and other work commands for consistency.

### 6. Update Tests

**Files**: `file:tests/cli/test_v2_cli_integration.py`, `file:tests/cli/test_work_diagnose.py`

Update or add test cases to verify:
- `work start --execute` returns exit code 0 when task completes successfully
- `work start --execute` returns exit code 1 when task fails
- `work start --execute` returns exit code 1 when task is blocked
- `work start` with invalid task ID returns exit code 2
- `work retry` returns appropriate exit codes
- `work batch run` returns exit code 1 if any tasks fail or are blocked

Example test structure:
```python
def test_work_start_execute_success_exit_code(workspace, task):
    result = runner.invoke(app, ["work", "start", task.id, "--execute", "-w", str(workspace.repo_path)])
    assert result.exit_code == 0

def test_work_start_execute_failure_exit_code(workspace, task):
    # Mock agent to return FAILED status
    result = runner.invoke(app, ["work", "start", task.id, "--execute", "-w", str(workspace.repo_path)])
    assert result.exit_code == 1

def test_work_start_invalid_task_exit_code(workspace):
    result = runner.invoke(app, ["work", "start", "nonexistent", "-w", str(workspace.repo_path)])
    assert result.exit_code == 2
```

## Execution Flow

```mermaid
sequenceDiagram
    participant CLI as work start --execute
    participant Agent as runtime.execute_agent()
    participant Status as AgentStatus Check
    participant Exit as Process Exit

    CLI->>Agent: Execute task
    Agent-->>CLI: Return AgentState
    CLI->>Status: Check state.status
    
    alt status == COMPLETED
        Status->>Exit: Exit code 0 (implicit)
    else status == FAILED
        Status->>CLI: Print error message
        CLI->>Exit: raise typer.Exit(1)
    else status == BLOCKED
        Status->>CLI: Print blocked message
        CLI->>Exit: raise typer.Exit(1)
    end
    
    Note over Exit: External tools can now<br/>detect failures via exit code
```

---

Execution Information

Branch: main
Commit: e04112c

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.