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

@@ -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
+```

skills/kugetsu/scripts/kugetsu-config.sh

@@ -28,6 +28,7 @@ TASK_TIMEOUT_HOURS="${TASK_TIMEOUT_HOURS:-1}"
 
 NETWORK_RETRY_ATTEMPTS="${NETWORK_RETRY_ATTEMPTS:-3}"
 NETWORK_RETRY_DELAY_SECONDS="${NETWORK_RETRY_DELAY_SECONDS:-5}"
+KUGETSU_BASE_BRANCH="${KUGETSU_BASE_BRANCH:-origin/main}"
 
 # Load user config overrides (~/.kugetsu/config)
 if [ -f "$KUGETSU_DIR/config" ]; then

skills/kugetsu/scripts/kugetsu-queue-daemon.sh

@@ -75,7 +75,7 @@ check_task_completion() {
             local has_commits=false
 
             if [ -d "$worktree_path" ] && [ -d "$worktree_path/.git" ]; then
-                if [ -n "$(git -C "$worktree_path" log --oneline origin/main..HEAD 2>/dev/null)" ]; then
+                if [ -n "$(git -C "$worktree_path" log --oneline "$KUGETSU_BASE_BRANCH..HEAD" 2>/dev/null)" ]; then
                     has_commits=true
                 fi
             fi
@@ -95,7 +95,7 @@ check_task_completion() {
             local has_commits=false
 
             if [ -d "$worktree_path" ] && [ -d "$worktree_path/.git" ]; then
-                if [ -n "$(git -C "$worktree_path" log --oneline origin/main..HEAD 2>/dev/null)" ]; then
+                if [ -n "$(git -C "$worktree_path" log --oneline "$KUGETSU_BASE_BRANCH..HEAD" 2>/dev/null)" ]; then
                     has_commits=true
                 fi
             fi

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 <issue-ref> [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() {

skills/kugetsu/scripts/kugetsu-worktree.sh

@@ -109,7 +109,7 @@ create_worktree() {
     fi
     
     echo "Creating branch '$branch_name'..."
-    if git -C "$worktree_path" checkout -b "$branch_name" origin/main 2>/dev/null; then
+    if git -C "$worktree_path" checkout -b "$branch_name" "$KUGETSU_BASE_BRANCH" 2>/dev/null; then
         :
     elif git -C "$worktree_path" checkout -b "$branch_name" main 2>/dev/null; then
         :