fix(queue): add --format=json and --limit flags to queue list

- kugetsu: show only parent commands, not all subcommands inline
- kugetsu <command> help: show help for specific command
- kugetsu queue: show queue subcommands (list, stats, clear, enqueue)
- kugetsu queue-daemon: show daemon subcommands (start, stop, restart, status, logs)
- kugetsu env: show env subcommands (list, get, set, rm)
- kugetsu server: show server subcommands (list, add, remove, default, get)

Closes #244

skills/kugetsu/SKILL.md

@@ -364,14 +364,10 @@ kugetsu queue-daemon logs       # Show recent daemon logs
 
 **Daemon Behavior:**
 1. Runs at configurable interval (default: 5 minutes)
-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)
+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`
 
 **Queue Directory:**
 ```
@@ -530,13 +526,6 @@ 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

@@ -17,77 +17,129 @@ usage() {
 kugetsu - OpenCode Session Manager (Issue-Driven)
 
 Usage:
-    kugetsu init [--force]                            Initialize base + pm-agent sessions (requires TTY)
-    kugetsu start <issue-ref> <message> [--debug]    Start task for issue (forks base session)
-    kugetsu continue <issue-ref> [message] [--debug] Continue existing task for issue
-    kugetsu delegate <message>                        Send message to PM agent (fire-and-forget)
-    kugetsu logs [n]                                  Show recent delegation logs (default: 10)
-    kugetsu status                                    Check kugetsu initialization status
-    kugetsu doctor [--fix]                            Diagnose and fix kugetsu issues
-    kugetsu notify [list|clear]                        Show or clear notifications
-    kugetsu list                                     List all tracked sessions
-    kugetsu prune [--force]                          Remove orphaned sessions (keeps base + pm-agent)
-    kugetsu destroy <issue-ref> [-y]                  Delete session for issue
-    kugetsu destroy --pm-agent [-y]                   Delete pm-agent session (not recommended)
-    kugetsu destroy --base [-y]                      Delete base session
-    kugetsu set-pr <issue-ref> <pr-url>            Set PR URL for session (for PR tracking)
-    kugetsu context <issue-ref>                        Show context for issue
-    kugetsu queue [list|stats|clear]                  Show queue status or statistics
-    kugetsu queue enqueue <issue-ref> <message>       Enqueue a task (normally via delegate)
-    kugetsu queue-daemon [start|stop|restart|status|logs]  Manage queue daemon
-    kugetsu env [get|set|list]                        Manage agent environment variables
-    kugetsu server [list|add|remove|default|get]     Manage git server configurations
-    kugetsu help                                     Show this help
+    kugetsu <command> [subcommand] [options]
+
+Commands:
+    init [--force]                                    Initialize base + pm-agent sessions (requires TTY)
+    start <issue-ref> <message> [--debug]            Start task for issue (forks base session)
+    continue <issue-ref> [message] [--debug]          Continue existing task for issue
+    delegate <message>                                Send message to PM agent (fire-and-forget)
+    logs [n]                                          Show recent delegation logs (default: 10)
+    status                                            Check kugetsu initialization status
+    doctor [--fix]                                    Diagnose and fix kugetsu issues
+    notify [list|clear]                               Show or clear notifications
+    list                                              List all tracked sessions
+    prune [--force]                                  Remove orphaned sessions
+    destroy <target> [-y]                             Delete session (issue, pm-agent, or base)
+    set-pr <issue-ref> <pr-url>                       Set PR URL for session
+    context <issue-ref>                               Show context for issue
+    queue [subcommand]                                Queue management
+    queue-daemon [subcommand]                         Queue daemon management
+    env [subcommand]                                  Environment variable management
+    server [subcommand]                                Git server configuration
+    help [command]                                   Show help for a command
+
+Use 'kugetsu <command> help' for subcommand help.
+Example: kugetsu queue help, kugetsu queue-daemon help
 
 Issue Ref Format:
     instance/user/repo#number
     Example: github.com/shoko/kugetsu#14
+EOF
+}
 
-Commands:
-    init        Create base + pm-agent sessions via TUI. Requires terminal access.
-                Use --force to reinitialize if sessions exist.
-    start       Fork new session from base for specific issue.
-                Requires pm-agent to be running (created by init).
-    continue    Continue work on existing issue session.
-    delegate    Send message to PM agent for task coordination.
-                Fire-and-forget: returns immediately, runs in background.
-                Use 'kugetsu logs' to check output.
-    logs        Show recent delegation logs.
-                Default: 10 most recent. Use 'kugetsu logs 20' for more.
-    status      Check if kugetsu is initialized and PM agent is active.
-    doctor      Diagnose kugetsu issues. Use --fix to attempt repairs.
-    notify      Show or clear notifications from PM agent.
-                Use 'kugetsu notify list' to see unread notifications.
-    list        Show all sessions (base + pm-agent + forked issues).
-    prune       Remove sessions not in index (orphaned from opencode).
-                Use --force to skip confirmation.
-    destroy     Delete specific issue, pm-agent, or base session.
+usage_queue() {
+    cat << 'EOF'
+kugetsu queue - Queue management
 
-Options:
-    --debug   Show real-time debug output and capture to debug.log
+Usage:
+    kugetsu queue [subcommand]
 
-PM Context:
-    kugetsu reads ~/.kugetsu/pm-agent.md (if exists) and injects it
-    into the PM agent session at init time. This allows customizing PM
-    behavior without recreating the session.
+Subcommands:
+    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
 
-Notifications:
-    PM Agent writes task completion notifications to ~/.kugetsu/notifications.json
-    Use 'kugetsu notify list' to see unread notifications.
+Options for list:
+    --limit=N         Number of items to return (default: 10)
+    --format=json     Output in JSON format with stats
 
 Examples:
-    kugetsu init
-    kugetsu status
-    kugetsu delegate "work on issue #5"
-    kugetsu logs
-    kugetsu logs 20
-    kugetsu doctor
-    kugetsu doctor --fix
-    kugetsu notify list
-    kugetsu notify clear
-    kugetsu start github.com/shoko/kugetsu#14 "fix bug"
-    kugetsu continue github.com/shoko/kugetsu#14 "add tests"
-    kugetsu list
+    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"
+EOF
+}
+
+usage_queue_daemon() {
+    cat << 'EOF'
+kugetsu queue-daemon - Queue daemon management
+
+Usage:
+    kugetsu queue-daemon [subcommand]
+
+Subcommands:
+    start                                              Start the queue daemon
+    stop                                               Stop the queue daemon
+    restart                                            Restart the queue daemon
+    status                                             Check daemon status
+    logs                                               Show recent daemon logs
+    help                                               Show this help
+
+Examples:
+    kugetsu queue-daemon start
+    kugetsu queue-daemon status
+    kugetsu queue-daemon logs
+EOF
+}
+
+usage_env() {
+    cat << 'EOF'
+kugetsu env - Environment variable management
+
+Usage:
+    kugetsu env [subcommand]
+
+Subcommands:
+    list                                               List all environment variables
+    get <key>                                          Get a specific variable
+    set <key> <value>                                  Set a variable
+    rm <key>                                           Remove a variable
+    help                                               Show this help
+
+Examples:
+    kugetsu env list
+    kugetsu env get GITEA_TOKEN
+    kugetsu env set CUSTOM_VAR "value"
+    kugetsu env rm CUSTOM_VAR
+EOF
+}
+
+usage_server() {
+    cat << 'EOF'
+kugetsu server - Git server configuration
+
+Usage:
+    kugetsu server [subcommand]
+
+Subcommands:
+    list                                               List all configured servers (default)
+    add <name> <url>                                   Add a new server
+    remove <name>                                      Remove a server
+    default [<name>]                                   Get or set default server
+    get [<name>]                                       Get server URL
+    help                                               Show this help
+
+Examples:
+    kugetsu server list
+    kugetsu server add github.com https://github.com
+    kugetsu server default github.com
 EOF
 }
 
@@ -310,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):
@@ -334,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() {
@@ -865,18 +937,34 @@ find_sessions_by_issue_number() {
 }
 
 cmd_queue() {
-    local action="${1:-list}"
-    shift
+    local action="${1:-}"
     
     case "$action" in
+        ""|help|--help|-h)
+            usage_queue
+            ;;
+        help|--help|-h)
+            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)
@@ -898,8 +986,8 @@ cmd_queue() {
             echo "Queue cleared."
             ;;
         enqueue)
-            local issue_ref="${1:-}"
-            local message="${2:-}"
+            local issue_ref="${2:-}"
+            local message="${3:-}"
             if [ -z "$issue_ref" ] || [ -z "$message" ]; then
                 echo "Usage: kugetsu queue enqueue <issue-ref> <message>" >&2
                 exit 1
@@ -910,16 +998,20 @@ cmd_queue() {
             check_task_timeouts
             ;;
         *)
-            echo "Usage: kugetsu queue [list|stats|clear|enqueue]" >&2
+            echo "Unknown queue subcommand: $action" >&2
+            usage_queue
             exit 1
             ;;
     esac
 }
 
 cmd_queue_daemon() {
-    local action="${1:-status}"
+    local action="${1:-}"
     
     case "$action" in
+        ""|help|--help|-h)
+            usage_queue_daemon
+            ;;
         start)
             if [ -f "$QUEUE_DAEMON_PID_FILE" ]; then
                 local old_pid=$(cat "$QUEUE_DAEMON_PID_FILE")
@@ -978,7 +1070,8 @@ cmd_queue_daemon() {
             fi
             ;;
         *)
-            echo "Usage: kugetsu queue-daemon [start|stop|restart|status|logs]" >&2
+            echo "Unknown queue-daemon subcommand: $action" >&2
+            usage_queue_daemon
             exit 1
             ;;
     esac
@@ -1059,10 +1152,12 @@ set_debug_mode() {
 }
 
 cmd_env() {
-    local action="${1:-list}"
-    shift
+    local action="${1:-}"
     
     case "$action" in
+        ""|help|--help|-h)
+            usage_env
+            ;;
         list)
             echo "Agent environment variables:"
             if [ -d "$ENV_DIR" ]; then
@@ -1080,7 +1175,7 @@ cmd_env() {
             fi
             ;;
         get)
-            local key="${1:-}"
+            local key="${2:-}"
             if [ -z "$key" ]; then
                 echo "Usage: kugetsu env get <key>" >&2
                 exit 1
@@ -1095,8 +1190,8 @@ cmd_env() {
             fi
             ;;
         set)
-            local key="${1:-}"
-            local value="${2:-}"
+            local key="${2:-}"
+            local value="${3:-}"
             if [ -z "$key" ] || [ -z "$value" ]; then
                 echo "Usage: kugetsu env set <key> <value>" >&2
                 exit 1
@@ -1105,8 +1200,8 @@ cmd_env() {
             echo "${key}=${value}" >> "$ENV_DIR/default.env"
             echo "Set $key in $ENV_DIR/default.env"
             ;;
-        rm)
-            local key="${1:-}"
+        rm|remove)
+            local key="${2:-}"
             if [ -z "$key" ]; then
                 echo "Usage: kugetsu env rm <key>" >&2
                 exit 1
@@ -1117,7 +1212,8 @@ cmd_env() {
             fi
             ;;
         *)
-            echo "Usage: kugetsu env [list|get|set|rm]" >&2
+            echo "Unknown env subcommand: $action" >&2
+            usage_env
             exit 1
             ;;
     esac
@@ -1127,7 +1223,10 @@ cmd_server() {
     local action="${1:-}"
     
     case "$action" in
-        ""|"list")
+        ""|help|--help|-h)
+            usage_server
+            ;;
+        "list")
             if [ -z "${GIT_SERVERS+x}" ]; then
                 echo "No git servers configured"
                 return
@@ -1204,14 +1303,8 @@ cmd_server() {
             fi
             ;;
         *)
-            echo "Usage: kugetsu server <list|add|remove|default|get>" >&2
-            echo "" >&2
-            echo "Commands:" >&2
-            echo "  list              List all configured git servers" >&2
-            echo "  add <name> <url>  Add a new git server" >&2
-            echo "  remove <name>     Remove a git server" >&2
-            echo "  default [<name>]  Get or set default server" >&2
-            echo "  get [<name>]      Get URL for a server (default: current default)" >&2
+            echo "Unknown server subcommand: $action" >&2
+            usage_server
             exit 1
             ;;
     esac
@@ -1321,8 +1414,30 @@ main() {
     
     case "$command" in
         help|--help|-h)
+            local subcommand="${1:-}"
+            case "$subcommand" in
+                queue|"")
+                    usage_queue
+                    ;;
+                queue-daemon)
+                    usage_queue_daemon
+                    ;;
+                env)
+                    usage_env
+                    ;;
+                server)
+                    usage_server
+                    ;;
+                "")
                     usage
                     ;;
+                *)
+                    echo "Help not available for '$subcommand'" >&2
+                    usage
+                    exit 1
+                    ;;
+            esac
+            ;;
         init)
             cmd_init "$@"
             ;;