From 611c0df3f7c69ec8e37e2926f055078866aa70c1 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Wed, 8 Apr 2026 06:28:59 +0000 Subject: [PATCH] fix(session): return proper exit codes for cmd_continue and fork_agent - 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 --- EXITCODES.md | 61 +++++++++++++++++++++++ skills/kugetsu/scripts/kugetsu-session.sh | 30 ++++++----- 2 files changed, 75 insertions(+), 16 deletions(-) create mode 100644 EXITCODES.md diff --git a/EXITCODES.md b/EXITCODES.md new file mode 100644 index 0000000..d50541c --- /dev/null +++ b/EXITCODES.md @@ -0,0 +1,61 @@ +# 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 +``` \ No newline at end of file diff --git a/skills/kugetsu/scripts/kugetsu-session.sh b/skills/kugetsu/scripts/kugetsu-session.sh index f81a3a3..b6ffaf5 100755 --- a/skills/kugetsu/scripts/kugetsu-session.sh +++ b/skills/kugetsu/scripts/kugetsu-session.sh @@ -380,8 +380,8 @@ ensure_worktree() { local active_count=$(count_active_dev_sessions) if [ "$active_count" -ge "${MAX_CONCURRENT_AGENTS:-3}" ]; then log "error" "ensure_worktree" "Max concurrent agents reached for $issue_ref" - echo "error" - return 1 + echo "max_agents" + return 2 fi if create_worktree "$issue_ref" "$WORKTREES_DIR" 2>&1 | tee >(cat >&2); then @@ -467,7 +467,6 @@ fork_agent() { if [ -z "$worktree_path" ] || [ ! -d "$worktree_path" ]; then log "error" "fork_agent" "Invalid worktree path: $worktree_path" - echo "error" return 1 fi @@ -476,7 +475,7 @@ fork_agent() { cd "$worktree_path" local sanitized_id=$(echo "$session_id" | sed 's/[^a-zA-Z0-9_-]/_/g') mkdir -p "$worktree_path/.kugetsu" - if [ ! -f "$worktree_path/.gitignore" ] || ! grep -q "^.kugetsu/" "$worktree_path/.gitignore"; then + if [ ! -f "$worktree_path/.gitignore" ] || ! grep -q "^.kugetsu/" "$worktree_path/.gitignore" ]; then echo ".kugetsu/" >> "$worktree_path/.gitignore" 2>/dev/null || true fi local msg_file="$worktree_path/.kugetsu/msg.txt" @@ -484,7 +483,6 @@ fork_agent() { nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$session_id'" >> "$LOGS_DIR/dev-$sanitized_id.log" 2>&1 & log "info" "fork_agent" "Forked agent for session $session_id in $worktree_path" - echo "forked" return 0 } @@ -499,10 +497,10 @@ cmd_continue() { if [ -z "$issue_ref" ]; then echo "Error: issue ref is required" >&2 echo "Usage: kugetsu continue [message]" >&2 - exit 1 + return 1 fi - validate_issue_ref "$issue_ref" + validate_issue_ref "$issue_ref" || return 1 if [ -z "$message" ]; then message=$(build_dev_agent_message "$issue_ref" "") @@ -511,15 +509,19 @@ cmd_continue() { fi local worktree_status=$(ensure_worktree "$issue_ref") + if [ "$worktree_status" = "max_agents" ]; then + echo "Error: Max concurrent agents reached for '$issue_ref'" >&2 + return 2 + fi if [ "$worktree_status" = "error" ]; then echo "Error: Failed to ensure worktree for '$issue_ref'" >&2 - exit 1 + return 1 fi local session_status=$(ensure_session "$issue_ref") if [ "$session_status" = "error" ]; then echo "Error: Failed to ensure session for '$issue_ref'" >&2 - exit 1 + return 1 fi kugetsu_context_dump "$issue_ref" "$message" "$(issue_ref_to_branch_name "$issue_ref")" @@ -529,17 +531,13 @@ cmd_continue() { local opencode_session_id=$(python3 -c "import json; print(json.load(open('$session_path')).get('opencode_session_id', ''))" 2>/dev/null || echo "") local worktree_path=$(python3 -c "import json; print(json.load(open('$session_path')).get('worktree_path', ''))" 2>/dev/null || echo "") - local fork_status=$(fork_agent "$opencode_session_id" "$worktree_path" "$message") - if [ "$fork_status" = "error" ]; then - echo "Error: Failed to fork agent for '$issue_ref'" >&2 - exit 1 - fi + fork_agent "$opencode_session_id" "$worktree_path" "$message" || return 1 - log "info" "cmd_continue" "Result for $issue_ref: worktree=$worktree_status session=$session_status fork=$fork_status" + log "info" "cmd_continue" "Result for $issue_ref: worktree=$worktree_status session=$session_status fork=forked" echo "Session continued for '$issue_ref': $opencode_session_id" echo "Worktree: $worktree_path" - echo "${worktree_status}-${session_status}-${fork_status}" + echo "${worktree_status}-${session_status}-forked" } cmd_list() { -- 2.49.1