611c0df3f7
- fork_agent() now returns exit code instead of echoing status - cmd_continue() returns exit code 2 when max agents reached - cmd_continue() returns exit code 1 for general errors (instead of exit 1) - ensure_worktree() returns exit code 2 for max agents condition - Add EXITCODES.md documenting all exit codes Closes #248
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
# Exit Codes
|
|
|
|
This document describes the exit codes used by kugetsu commands.
|
|
|
|
## Exit Codes
|
|
|
|
| Exit Code | Meaning |
|
|
|-----------|---------|
|
|
| 0 | Success - operation completed successfully |
|
|
| 1 | General error - worktree/session/validation failed |
|
|
| 2 | Max concurrent agents reached (MAX_CONCURRENT_AGENTS limit) |
|
|
|
|
## Commands
|
|
|
|
### cmd_continue / cmd_start
|
|
|
|
The `cmd_continue` command (aliased to `cmd_start`) returns exit codes to indicate the result of the operation:
|
|
|
|
- **Exit 0**: Success - agent forked successfully
|
|
- **Exit 1**: General error - worktree/session/validation failed
|
|
- **Exit 2**: Max concurrent agents reached
|
|
|
|
### Internal Functions
|
|
|
|
#### fork_agent()
|
|
|
|
Forks a new agent session for a given worktree.
|
|
|
|
- **Return 0**: Success - agent forked successfully
|
|
- **Return 1**: General error - invalid worktree path or other failure
|
|
|
|
#### ensure_worktree()
|
|
|
|
Ensures a worktree exists for the given issue reference.
|
|
|
|
- **Return 0**: Success - worktree existed or was created
|
|
- **Return 1**: General error - base session not found or worktree creation failed
|
|
- **Return 2**: Max concurrent agents reached
|
|
|
|
## Daemon Integration
|
|
|
|
These exit codes are designed to help the queue daemon distinguish between recoverable and non-recoverable errors:
|
|
|
|
- **Exit 2 (max agents)**: This is a recoverable error - the daemon can retry later when agents become available
|
|
- **Exit 1 (general error)**: Non-recoverable - the task should be marked as failed
|
|
|
|
## MAX_CONCURRENT_AGENTS
|
|
|
|
The maximum number of concurrent development agents is controlled by the `MAX_CONCURRENT_AGENTS` configuration variable (default: 3).
|
|
|
|
Set this in your `config` file:
|
|
|
|
```bash
|
|
MAX_CONCURRENT_AGENTS=5
|
|
```
|
|
|
|
Or via environment variable:
|
|
|
|
```bash
|
|
export MAX_CONCURRENT_AGENTS=5
|
|
``` |