Merge pull request 'docs: update SKILL.md to reflect v0.2.3 daemon changes' (#256) from fix/issue-158 into main

- Update Daemon Behavior section to describe cmd_continue usage
- Document that daemon forks dev agents from base session (not pm_agent)
- Add v0.2.3 changelog entry documenting issue #156 fix
- Describe daemon locking and timeout handling features

Fixes #158

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,21 +56,14 @@ Usage:
     kugetsu queue [subcommand]
 
 Subcommands:
-    list [--limit=N] [--format=json]                 Show pending tasks (default: 10 items, text format)
+    list                                               Show pending tasks (default)
     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"
@@ -362,25 +355,19 @@ PYEOF
 
 get_pending_tasks() {
     local limit="${1:-10}"
-    local format="${2:-text}"
     
     if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
-        if [ "$format" = "json" ]; then
-            echo '{"items": [], "total": 0, "pending": 0}'
-        else
-            echo "No pending tasks in queue."
-        fi
+        echo "[]"
         return
     fi
     
-    python3 << PYEOF
+    python3 -c "
 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):
@@ -392,27 +379,13 @@ 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
 
-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
+print(json.dumps(items))
+" "$limit"
 }
 
 get_queue_stats() {
@@ -947,24 +920,13 @@ cmd_queue() {
             usage_queue
             ;;
         list)
-            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"
+            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
             ;;
         stats)
             local stats=$(get_queue_stats)