feat(session): improve session list and log formatting for human readability

- cmd_list: show sessions in table format ordered by last updated time
- cmd_list: display issue_ref, state, last_updated, and session_id columns
- cmd_logs: cleaner timestamp formatting with human-readable dates
- cmd_logs: color-coded log levels (error=red, warn=yellow, info=green, debug=cyan)
- cmd_logs: improved visual separation between log entries

fixes #252

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/SKILL.md

@@ -364,10 +364,14 @@ kugetsu queue-daemon logs       # Show recent daemon logs
 
 **Daemon Behavior:**
 1. Runs at configurable interval (default: 5 minutes)
-2. Checks if active agents < MAX_CONCURRENT_AGENTS
-3. Picks 1-N pending items (configurable batch size)
-4. Forks PM session for each picked item
-5. PM decides whether to use `start` or `continue`
+2. Checks queue for pending items
+3. For each pending item:
+   - Acquires lock to prevent duplicate processing
+   - Sources kugetsu-session.sh and calls `cmd_continue`
+   - `cmd_continue` handles worktree/session creation and forks dev agent from base session
+   - Updates queue item state to "notified"
+4. Uses per-issue locking to prevent race conditions
+5. Implements timeout for tasks that don't complete (marks as "error" after TASK_TIMEOUT_HOURS)
 
 **Queue Directory:**
 ```
@@ -526,6 +530,13 @@ The script will:
 
 See [docs/kugetsu-setup.md](../../docs/kugetsu-setup.md) for full Tailscale setup documentation.
 
+## Version History
+
+### v0.2.3
+- **Queue daemon context drift fix** (issue #156): Daemon now sources kugetsu-session.sh and calls `cmd_continue` directly instead of forking PM session. This fixes context drift where daemon would lose track of task state.
+- **Daemon locking**: Added per-issue locking to prevent race conditions when multiple daemon instances run.
+- **Timeout handling**: Tasks that don't complete within TASK_TIMEOUT_HOURS are marked as "error".
+
 ## Without kugetsu
 
 If kugetsu is not available, use opencode directly:

skills/kugetsu/scripts/kugetsu

@@ -56,14 +56,21 @@ Usage:
     kugetsu queue [subcommand]
 
 Subcommands:
-    list                                               Show pending tasks (default)
+    list [--limit=N] [--format=json]                 Show pending tasks (default: 10 items, text format)
     stats                                              Show queue statistics
     clear                                              Clear all queue items
     enqueue <issue-ref> <message>                      Enqueue a task
     help                                               Show this help
 
+Options for list:
+    --limit=N         Number of items to return (default: 10)
+    --format=json     Output in JSON format with stats
+
 Examples:
     kugetsu queue list
+    kugetsu queue list --limit=50
+    kugetsu queue list --format=json
+    kugetsu queue list --limit=20 --format=json
     kugetsu queue stats
     kugetsu queue clear
     kugetsu queue enqueue github.com/shoko/kugetsu#14 "fix bug"
@@ -355,19 +362,25 @@ PYEOF
 
 get_pending_tasks() {
     local limit="${1:-10}"
+    local format="${2:-text}"
     
     if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
-        echo "[]"
+        if [ "$format" = "json" ]; then
+            echo '{"items": [], "total": 0, "pending": 0}'
+        else
+            echo "No pending tasks in queue."
+        fi
         return
     fi
     
-    python3 -c "
+    python3 << PYEOF
 import json
 import os
 import sys
 
 queue_dir = os.environ.get('QUEUE_ITEMS_DIR', '')
 limit = int(sys.argv[1]) if len(sys.argv) > 1 else 10
+format_type = sys.argv[2] if len(sys.argv) > 2 else 'text'
 
 items = []
 if os.path.isdir(queue_dir):
@@ -379,13 +392,27 @@ if os.path.isdir(queue_dir):
                     data = json.load(f)
                     if data.get('state') == 'pending':
                         items.append(data)
-                        if len(items) >= limit:
-                            break
             except:
                 pass
 
-print(json.dumps(items))
-" "$limit"
+items.sort(key=lambda x: x.get('pending_since', ''))
+
+if format_type == 'json':
+    output = {
+        "items": items[:limit],
+        "total": len(items),
+        "pending": len(items)
+    }
+    print(json.dumps(output))
+else:
+    if not items:
+        print("No pending tasks in queue.")
+    else:
+        print("Pending tasks:")
+        for t in items[:limit]:
+            msg = t.get('message', '')[:50]
+            print(f"  {t.get('id')}: {t.get('issue_ref')} - {msg}...")
+PYEOF
 }
 
 get_queue_stats() {
@@ -920,13 +947,24 @@ cmd_queue() {
             usage_queue
             ;;
         list)
-            local pending_tasks=$(get_pending_tasks 10)
-            if [ "$pending_tasks" = "[]" ]; then
-                echo "No pending tasks in queue."
-            else
-                echo "Pending tasks:"
-                echo "$pending_tasks" | python3 -c "import sys, json; [print(f\"  {t.get('id')}: {t.get('issue_ref')} - {t.get('message', '')[:50]}...\") for t in json.load(sys.stdin)]"
-            fi
+            local limit="10"
+            local format="text"
+            
+            while [ $# -gt 0 ]; do
+                case "$1" in
+                    --limit=*)
+                        limit="${1#*=}"
+                        ;;
+                    --format=json)
+                        format="json"
+                        ;;
+                    *)
+                        ;;
+                esac
+                shift
+            done
+            
+            get_pending_tasks "$limit" "$format"
             ;;
         stats)
             local stats=$(get_queue_stats)

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-log.sh

@@ -45,22 +45,61 @@ cmd_logs() {
     
     find "$LOGS_DIR" -type f -mtime +7 -delete 2>/dev/null
     
-    ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | while read line; do
-        echo "$line"
+    local log_files=()
+    while IFS= read -r line; do
+        log_files+=("$line")
+    done < <(ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | awk '{print $NF}')
+    
+    echo "=== Recent Logs ($count files) ==="
+    echo ""
+    printf "%-30s %8s  %s\n" "FILE" "SIZE" "LAST MODIFIED"
+    echo "----------------------------------------------------------------"
+    
+    for log in "${log_files[@]}"; do
+        if [ -f "$LOGS_DIR/$log" ]; then
+            local size=$(stat -c %s "$LOGS_DIR/$log" 2>/dev/null || echo "0")
+            local mtime=$(stat -c %Y "$LOGS_DIR/$log" 2>/dev/null || echo "0")
+            local date_str=$(date -d "@$mtime" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "unknown")
+            printf "%-30s %8s  %s\n" "$log" "$size" "$date_str"
+        fi
     done
     
     echo ""
-    echo "Recent log contents:"
-    echo "===================="
+    echo "Log Contents:"
+    echo "================================================================"
     
-    for log in $(ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | awk '{print $NF}'); do
+    for log in "${log_files[@]}"; do
         if [ -f "$LOGS_DIR/$log" ]; then
             echo ""
-            echo "--- $log ---"
+            echo ">>> $log <<<"
+            echo "----------------------------------------------------------------"
             tail -20 "$LOGS_DIR/$log" | while read line; do
                 line=$(strip_ansi_codes "$line")
                 line=$(mask_sensitive_vars "$line")
-                echo "  $line"
+                
+                if [[ "$line" =~ \[([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[^\]]*)\]\ ([a-z]+)\ (.+) ]]; then
+                    local ts="${BASH_REMATCH[1]}"
+                    local level="${BASH_REMATCH[2]}"
+                    local msg="${BASH_REMATCH[3]}"
+                    
+                    local color=""
+                    local level_str=""
+                    case "$level" in
+                        error) color="\033[0;31m"; level_str="[ERROR]" ;;
+                        warn)  color="\033[0;33m"; level_str="[WARN ]" ;;
+                        info)  color="\033[0;32m"; level_str="[INFO ]" ;;
+                        debug) color="\033[0;36m"; level_str="[DEBUG]" ;;
+                        *)    color="\033[0;90m"; level_str="[$level]" ;;
+                    esac
+                    
+                    if [ -t 1 ]; then
+                        echo -e "  \033[0;90m$ts\033[0m ${color}${level_str}\033[0m $msg"
+                    else
+                        echo "  $ts ${level_str} $msg"
+                    fi
+                else
+                    echo "  $line"
+                fi
             done
         fi
     done

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() {
@@ -561,53 +559,69 @@ cmd_list() {
     fi
     
     echo ""
-    echo "Issue sessions:"
+    
+    local issue_sessions=()
     
     if [ -d "$SESSIONS_DIR" ]; then
         for session_file in "$SESSIONS_DIR"/*.json; do
             if [ -f "$session_file" ]; then
                 local filename=$(basename "$session_file")
                 if [ "$filename" != "base.json" ] && [ "$filename" != "pm-agent.json" ]; then
+                    local mtime=$(stat -c %Y "$session_file" 2>/dev/null || echo "0")
                     local issue_ref=$(filename_to_issue_ref "$filename")
                     local opencode_sid=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', 'unknown'))" 2>/dev/null || echo "unknown")
                     local state=$(python3 -c "import json; print(json.load(open('$session_file')).get('state', 'unknown'))" 2>/dev/null || echo "unknown")
                     local worktree_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
-                    local worktree_status=""
-                    if [ -n "$worktree_path" ]; then
-                        if [ -d "$worktree_path" ]; then
-                            worktree_status="(worktree exists)"
-                        else
-                            worktree_status="(worktree MISSING)"
-                        fi
-                    fi
-                    echo "  $filename"
-                    echo "    Issue: $issue_ref"
-                    echo "    Session: $opencode_sid"
-                    echo "    State: $state"
-                    echo "    $worktree_status"
+                    issue_sessions+=("$mtime|$filename|$issue_ref|$opencode_sid|$state|$worktree_path")
                 fi
             fi
         done
     fi
     
+    if [ ${#issue_sessions[@]} -gt 0 ]; then
+        printf "%-45s %-10s %-20s %s\n" "ISSUE_REF" "STATE" "LAST_UPDATED" "SESSION_ID"
+        echo "-------------------------------------------------------------------------------------------------------------"
+        
+        while IFS='|' read -r mtime filename issue_ref opencode_sid state worktree_path; do
+            local last_updated=$(date -d "@$mtime" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "unknown")
+            local worktree_status=""
+            if [ -n "$worktree_path" ] && [ ! -d "$worktree_path" ]; then
+                worktree_status=" [worktree MISSING]"
+            fi
+            printf "%-45s %-10s %-20s %s%s\n" "$issue_ref" "$state" "$last_updated" "$opencode_sid" "$worktree_status"
+        done < <(printf '%s\n' "${issue_sessions[@]}" | sort -t'|' -k1 -rn)
+    else
+        echo "No issue sessions found."
+    fi
+    
+    echo ""
+    
+    local orphaned_worktrees=()
     if [ -d "$WORKTREES_DIR" ]; then
-        echo ""
-        echo "Worktrees without sessions:"
         for worktree in $(find "$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null); do
             local worktree_name=$(basename "$worktree")
             local has_session=false
-            for session_file in "$SESSIONS_DIR"/*.json; do
-                if [ -f "$session_file" ]; then
-                    local wt_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
-                    if [ "$wt_path" = "$worktree" ]; then
-                        has_session=true
-                        break
+            if [ -d "$SESSIONS_DIR" ]; then
+                for session_file in "$SESSIONS_DIR"/*.json; do
+                    if [ -f "$session_file" ]; then
+                        local wt_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
+                        if [ "$wt_path" = "$worktree" ]; then
+                            has_session=true
+                            break
+                        fi
                     fi
-                fi
-            done
-            if [ "$has_session" = false ]; then
-                echo "  $worktree_name (no session)"
+                done
             fi
+            if [ "$has_session" = false ]; then
+                orphaned_worktrees+=("$worktree_name")
+            fi
+        done
+    fi
+    
+    if [ ${#orphaned_worktrees[@]} -gt 0 ]; then
+        echo "Worktrees without sessions:"
+        for wt in "${orphaned_worktrees[@]}"; do
+            echo "  $wt"
         done
     fi
 }

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
         :