fix CONTRIBUTING.md: branch naming should include issue number

Address han's review feedback: - Changed feat/feature-name to feat/issue-N-feature-name - Consistent with fix/issue-N-name format
docs: add versioning policy, changelog, and update contributing guide
2026-04-05 10:26:59 +00:00 · 2026-04-05 09:38:25 +00:00 · 2026-04-05 10:49:24 +02:00 · 2026-04-05 08:44:45 +00:00 · 2026-04-05 08:56:59 +02:00 · 2026-04-05 06:51:57 +00:00
6 changed files with 920 additions and 169 deletions
--- a/.github/ISSUES/fix-queue-daemon-excess-agents.md
+++ b/.github/ISSUES/fix-queue-daemon-excess-agents.md
@@ -0,0 +1,67 @@
+# Fix: Queue daemon spawning excess agents due to race condition
+
+## Problem
+
+When enqueueing multiple tasks (e.g., 6 tasks), the queue daemon was spawning many more subagents than expected, eventually exhausting container memory.
+
+**Root Cause:** The combination of:
+1. `process_queue()` calling `opencode run` directly instead of `kugetsu start`, bypassing all concurrency logic
+2. `count_active_dev_sessions()` counting `pm-agent.json` toward `MAX_CONCURRENT_AGENTS`, reducing effective dev agent slots
+3. No atomic locking around session count check + session file creation (TOCTOU race condition)
+4. Background spawning of multiple concurrent processes in `process_queue()`
+
+**Expected behavior:** With `MAX_CONCURRENT_AGENTS=3` and 6 tasks:
+- Tasks should be processed sequentially via `kugetsu start`
+- Only 3 dev agents should run at a time
+- Tasks should queue and wait for slots to free up
+
+## Solution
+
+### 1. `count_active_dev_sessions()` - Exclude pm-agent
+Only count actual dev agent session files (exclude `pm-agent.json`).
+
+### 2. `process_queue()` - Call `kugetsu start` directly + retry logic
+- Call `kugetsu start` directly (foreground, sequential) instead of spawning `opencode run` background process
+- Dynamic batch size = available slots (removes need for `QUEUE_DAEMON_BATCH_SIZE`)
+- Retry logic (max 3 attempts) on failure
+- On failure: cleanup worktree/session and revert to `pending` state
+- Save `fork_pid` to queue item for timeout handling
+
+### 3. `cmd_start()` - Add flock
+- Add flock around critical section (count check + fork)
+- Track `fork_pid` for queue item timeout handling
+
+### 4. Notification System
+New notification types:
+| Event | Type |
+|-------|------|
+| Task enqueued | `task_queued` |
+| Task dequeued | `task_dequeued` |
+| Task started | `task_started` |
+| Task completed | `task_completed` |
+| Task error | `task_error` |
+
+### 5. Config
+- Remove `QUEUE_DAEMON_BATCH_SIZE` (no longer needed - batch size is now dynamic)
+
+## Notification Flow
+
+| Event | Location | Type |
+|-------|----------|------|
+| Task enqueued | `enqueue_task()` | `task_queued` |
+| Task dequeued | `process_queue()` after state change to `notified` | `task_dequeued` |
+| Task started | `cmd_start()` after session file created | `task_started` |
+| Task completed | `update_queue_item_state()` | `task_completed` |
+| Task error | `update_queue_item_state()` | `task_error` |
+
+## Out of Scope
+
+- Re-check loop in cmd_start (checking if session DB is reliable) - deferred to separate research issue
+- Buffer mechanism for excess forking (safety failsafe only)
+
+## Status
+
+- [x] Issue created
+- [x] Implementation
+- [x] PR created (#147)
+- [ ] Merged
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,10 +2,10 @@

 ## Workflow

-1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b docs/topic-name`
+1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b feat/issue-N-feature-name`
 2. Make changes and commit with clear messages
 3. Open a Pull Request for review
-4. Do not merge directly to `master` for reviewable changes
+4. Do not merge directly to `main` or `develop` for reviewable changes
 5. After approval, squash and merge

 ## Guidelines
@@ -14,10 +14,53 @@
 - Keep PRs focused and reasonably sized
 - Document any non-obvious decisions
 - Test changes before submitting
+- See [VERSIONING.md](VERSIONING.md) for backport compatibility rules

 ## Branches

- `master` — stable, reviewed content only
+### Primary Branches
+
+- `main` — stable 0.1.x releases, production-ready code
+- `develop` — experimental 0.2.x work, next major version
+
+### Feature Branches
+
 - `fix/*` — bug fixes
+- `feat/*` — new features
 - `docs/*` — documentation updates
- `research/*` — new research notes
+- `refactor/*` — code refactoring (no behavior change)
+
+## Branch Model
+
+```
+main (0.1.x stable)
+  └── v0.1.0, v0.1.1, v0.1.2, ...
+
+develop (0.2.x experimental)
+  └── (next major version work)
+```
+
+### Which Branch to Target?
+
+| Change Type | Target Branch | Backport? |
+|-------------|---------------|-----------|
+| Bug fix | `main` | N/A |
+| Documentation | `main` | N/A |
+| New feature (backport-compatible) | `main` | Can cherry-pick to `develop` |
+| Experimental feature | `develop` | No |
+| Breaking change | `develop` | No |
+
+## Backport Compatibility
+
+Before merging, consider if your change is backport-compatible:
+
+- **YES**: Bug fixes, docs, adding new optional inputs
+- **NO**: Changing behavior, changing defaults, removing features
+
+See [VERSIONING.md](VERSIONING.md) for full policy.
+
+## Release Process
+
+1. Bug fixes and docs → directly to `main`
+2. New features → `develop` or feature branches → `develop`
+3. When `develop` is stable enough → merge to `main` for release
--- a/VERSIONING.md
+++ b/VERSIONING.md
@@ -0,0 +1,71 @@
+# Versioning Policy
+
+## Branch Strategy
+
+Kugetsu uses a dual-branch model:
+
+| Branch | Purpose | Version | Stability |
+|--------|---------|---------|-----------|
+| `main` | Stable releases | 0.1.x | Production-ready |
+| `develop` | Experimental work | 0.2.x | Active development |
+
+### Branch Definitions
+
+- **`main`**: Contains the latest stable 0.1.x releases. All changes here should be production-ready and backport-compatible when possible.
+
+- **`develop`**: Contains work for the next major version (0.2.x). This branch may contain experimental features that could change or be removed.
+
+## Version Format
+
+Versions follow [Semantic Versioning](https://semver.org/):
+```
+MAJOR.MINOR.PATCH
+```
+
+- **MAJOR**: Incompatible API/behavior changes
+- **MINOR**: New functionality (backward-compatible)
+- **PATCH**: Bug fixes (backward-compatible)
+
+## Backport Compatibility
+
+### Backport-Compatible Changes (0.1.x)
+- Bug fixes
+- Documentation updates
+- Performance improvements
+- Adding new inputs/options (must have sensible defaults)
+- Changes that only affect 0.2.x-specific features
+
+### NOT Backport-Compatible
+- Removing or renaming existing options
+- Changing default values of existing options
+- Changing behavior of existing commands
+- Introducing breaking changes to the API/shell interface
+
+## Deprecation Policy
+
+When introducing breaking changes:
+
+1. **Deprecate in minor X**: Add warning messages, document the change
+2. **Remove in major X+1**: The breaking change is removed in the next major version
+
+Example:
+- Option `--old-flag` deprecated in v0.1.5
+- Option `--old-flag` removed in v1.0.0 (not v0.2.0)
+
+## What Constitutes a Version Bump
+
+| Change Type | Version Bump |
+|-------------|--------------|
+| Add new command/option | MINOR |
+| Bug fix | PATCH |
+| Change default value | MINOR (may warrant PATCH) |
+| Add new required input | MAJOR |
+| Remove deprecated feature | MAJOR |
+| Change behavior of existing command | MINOR (needs deprecation first) |
+
+## Release Process
+
+1. Changes are developed on feature branches
+2. PRs are opened against `main` for 0.1.x changes, or `develop` for 0.2.x
+3. After review and approval, changes are squash-merged
+4. Releases are tagged from `main` after significant changes
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to kugetsu are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [v0.2.1] - 2026-04-03
+
+### Fixed
+- Prevent excess agent spawning with flock + sequential processing
+
+## [v0.2.0] - 2026-03-30
+
+### Added
+- Queue system with background daemon
+- Agent timeout handling
+- Context dump/load for session isolation
+- PR tracking and safe destroy
+
+## [v0.1.13] - 2026-03-29
+
+### Fixed
+- Add missing closing parenthesis in process_queue Python extraction
+
+## [v0.1.12] - 2026-03-25
+
+### Added
+- Post-comment helper for PM agent
+
+## [v0.1.11] - 2026-03-20
+
+### Fixed
+- Wrap cmd_continue in subshell with cd for correct worktree dir
+
+## [v0.1.10] - 2026-03-15
+
+### Fixed
+- destroy --base now also deletes PM agent session
+
+## [v0.1.9] - 2026-03-10
+
+### Added
+- init creates base session in ~/.kugetsu-worktrees
+- Adds context to forked sessions
+- Clears logs on init
+
+## [v0.1.8] - 2026-03-05
+
+### Fixed
+- destroy --base and --pm-agent actually delete opencode sessions
+
+## [v0.1.7] - 2026-02-28
+
+### Fixed
+- Warn if init run from non-empty directory
+
+## [v0.1.6] - 2026-02-20
+
+### Fixed
+- Detect session via DB query instead of opencode session list
+
+## [v0.1.5] - 2026-02-15
+
+### Fixed
+- Update forked session permissions after detection
+
+## [v0.1.4] - 2026-02-10
+
+### Fixed
+- Call fix_session_permissions before forking
+
+## [v0.1.3] - 2026-02-05
+
+### Fixed
+- Session detection ordering bug and debugging
+
+## [v0.1.2] - 2026-01-28
+
+### Fixed
+- Improve session detection in cmd_start with retry logic and logging
+
+## [v0.1.1] - 2026-01-20
+
+### Fixed
+- Use cd + worktree inside parent dir instead of --dir flag
+
+## [v0.1.0] - 2026-01-15
+
+### Added
+- KUGETSU_VERBOSITY for PM agent output control
+- Initial documented release
+
+[Unreleased]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.1...HEAD
+[v0.2.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.0...v0.2.1
+[v0.2.0]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.13...v0.2.0
+[v0.1.13]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.12...v0.1.13
+[v0.1.12]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.11...v0.1.12
+[v0.1.11]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.10...v0.1.11
+[v0.1.10]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.9...v0.1.10
+[v0.1.9]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.8...v0.1.9
+[v0.1.8]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.7...v0.1.8
+[v0.1.7]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.6...v0.1.7
+[v0.1.6]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.5...v0.1.6
+[v0.1.5]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.4...v0.1.5
+[v0.1.4]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.3...v0.1.4
+[v0.1.3]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.2...v0.1.3
+[v0.1.2]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.1...v0.1.2
+[v0.1.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.0...v0.1.1
+[v0.1.0]: https://git.fbrns.co/shoko/kugetsu/releases/tag/v0.1.0
--- a/skills/kugetsu/SKILL.md
+++ b/skills/kugetsu/SKILL.md
@@ -49,6 +49,8 @@ A default config file is created during `kugetsu init` with commented examples:
 | `MAX_CONCURRENT_AGENTS` | 3 | Maximum number of concurrent dev agents |
 | `KUGETSU_TEMP_DIR` | `~/.local/share/opencode/tool-output` | Temp directory for subagent tool output (useful in headless environments where /tmp is restricted) |
 | `KUGETSU_VERBOSITY` | `default` | PM agent verbosity level: `verbose`, `default`, or `quiet` |
+| `QUEUE_DAEMON_INTERVAL_MINUTES` | 5 | How often daemon polls queue (in minutes) |
+| `QUEUE_CLEANUP_AGE_DAYS` | 7 | Auto-cleanup completed/error items older than N days |

 ### Environment Variables for Agents

@@ -111,6 +113,10 @@ Each issue session gets its own git worktree to prevent conflicts:
 ├── worktrees/
 │   ├── github.com-shoko-kugetsu-14/     # Isolated workdir for issue #14
 │   └── github.com-shoko-kugetsu-15/     # Isolated workdir for issue #15
+├── queue/
+│   ├── items/                      # Queue item JSON files
+│   ├── daemon.pid                   # Daemon process ID
+│   └── daemon.log                  # Daemon log output
 └── index.json                       # Maps session IDs and issue refs to session files
 ```

@@ -258,16 +264,17 @@ kugetsu destroy --base -y

 ### kugetsu delegate `<message>`

-Send a message to the PM agent for task coordination (fire-and-forget):
+Send a message to the PM agent for task coordination via queue:
 ```bash
 kugetsu delegate "work on issue #14"
 kugetsu delegate "review PR #92"
 ```

- Non-blocking: returns immediately, runs in background
- PM agent processes the message asynchronously
- Uses `KUGETSU_VERBOSITY` env var to control PM agent output verbosity
- Log output stored in `~/.kugetsu/logs/delegate-<timestamp>.log`
+- **Always enqueues** (fire-and-forget): returns immediately
+- Queue daemon polls queue and invokes PM when slots available
+- Tasks are processed FIFO (first-in-first-out)
+- Use `kugetsu queue list` to see pending tasks
+- Use `kugetsu queue-daemon logs` to debug queue processing

 ### kugetsu logs [n]

@@ -328,35 +335,79 @@ kugetsu server default github   # Set default server
 kugetsu server get github       # Get server URL
 ```

-### kugetsu queue <list|enqueue|dequeue|clear>
+### kugetsu queue <list|stats|clear>

 Manage task queue for autonomous PM operation:
 ```bash
-kugetsu queue list              # Show queued tasks
-kugetsu queue enqueue "task"   # Add task to queue
-kugetsu queue dequeue          # Remove next task from queue
-kugetsu queue clear            # Clear all queued tasks
+kugetsu queue list              # Show queued tasks with status
+kugetsu queue stats            # Show queue statistics (total, pending, notified, completed, error)
+kugetsu queue clear            # Clean up old completed/error items
+kugetsu queue enqueue <issue-ref> <message>  # Manually enqueue a task
 ```

- Queue stored in `~/.kugetsu/queue.json`
+**Queue Item States:**
+- `pending` - Waiting in queue, daemon can pick up
+- `notified` - PM agent has picked up the task
+- `completed` - Dev agent finished, PR created
+- `error` - Timeout or failure
+
+### kugetsu queue-daemon <start|stop|restart|status|logs>
+
+Manage the queue daemon background process:
+```bash
+kugetsu queue-daemon start     # Start daemon in background
+kugetsu queue-daemon stop      # Stop daemon
+kugetsu queue-daemon restart    # Restart daemon
+kugetsu queue-daemon status    # Check if daemon is running
+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`
+
+**Queue Directory:**
+```
+~/.kugetsu/queue/
+├── items/                     # Queue item JSON files
+│   ├── q_1234567890.json    # One file per queued task
+│   └── q_1234567891.json
+├── daemon.pid                # Daemon process ID
+├── daemon.lock               # Daemon lock file
+└── daemon.log                # Daemon log output
+```

 ## Workflow Example

+### First-time Setup
 ```bash
-# First-time setup (requires TTY)
+# Initialize kugetsu (requires TTY)
 kugetsu init
-# Creates: base session + pm-agent session

-# Start work on issue
-kugetsu start github.com/shoko/kugetsu#14 "implement feature X"
-# Creates: worktree at ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14/
+# Start the queue daemon (for autonomous operation)
+kugetsu queue-daemon start
+```

-# Continue later
+### Normal Workflow
+```bash
+# Enqueue tasks via delegate - agents will process them automatically
+kugetsu delegate "work on issue #14"
+kugetsu delegate "review PR #92"
+
+# Check queue status
+kugetsu queue list           # See pending tasks
+kugetsu queue stats         # See statistics
+
+# Debug queue daemon
+kugetsu queue-daemon status  # Is daemon running?
+kugetsu queue-daemon logs    # See daemon logs
+
+# Continue work on existing issue
 kugetsu continue github.com/shoko/kugetsu#14 "add tests"

-# Continue again
-kugetsu continue github.com/shoko/kugetsu#14 "fix failing test"
-
 # List all sessions
 kugetsu list

@@ -367,6 +418,21 @@ kugetsu prune --force
 kugetsu destroy github.com/shoko/kugetsu#14
 ```

+### Queue Daemon Management
+```bash
+# Check if daemon is running
+kugetsu queue-daemon status
+
+# View daemon logs for debugging
+kugetsu queue-daemon logs
+
+# Restart daemon if needed
+kugetsu queue-daemon restart
+
+# Stop daemon
+kugetsu queue-daemon stop
+```
+
 ## Headless Operation

 This design solves the headless CLI limitation discovered in Issue #14:
--- a/skills/kugetsu/scripts/kugetsu
+++ b/skills/kugetsu/scripts/kugetsu
@@ -17,6 +17,15 @@ CONTEXT_DIR="${CONTEXT_DIR:-$KUGETSU_DIR/context}"
 ENABLE_CONTEXT_DUMP="${ENABLE_CONTEXT_DUMP:-true}"
 WORKTREE_CHECK_PR_STATUS="${WORKTREE_CHECK_PR_STATUS:-true}"

+QUEUE_DIR="${QUEUE_DIR:-$KUGETSU_DIR/queue}"
+QUEUE_ITEMS_DIR="${QUEUE_ITEMS_DIR:-$QUEUE_DIR/items}"
+QUEUE_DAEMON_PID_FILE="${QUEUE_DAEMON_PID_FILE:-$QUEUE_DIR/daemon.pid}"
+QUEUE_DAEMON_LOCK_FILE="${QUEUE_DAEMON_LOCK_FILE:-$QUEUE_DIR/daemon.lock}"
+QUEUE_DAEMON_LOG_FILE="${QUEUE_DAEMON_LOG_FILE:-$QUEUE_DIR/daemon.log}"
+QUEUE_DAEMON_INTERVAL_MINUTES="${QUEUE_DAEMON_INTERVAL_MINUTES:-5}"
+QUEUE_CLEANUP_AGE_DAYS="${QUEUE_CLEANUP_AGE_DAYS:-7}"
+TASK_TIMEOUT_HOURS="${TASK_TIMEOUT_HOURS:-1}"
+
 # Load user config overrides (~/.kugetsu/config)
 if [ -f "$KUGETSU_DIR/config" ]; then
    source "$KUGETSU_DIR/config"
@@ -53,7 +62,7 @@ count_active_dev_sessions() {
        for session_file in "$SESSIONS_DIR"/*.json; do
            if [ -f "$session_file" ]; then
                local filename=$(basename "$session_file")
-                if [ "$filename" != "base.json" ]; then
+                if [ "$filename" != "base.json" ] && [ "$filename" != "pm-agent.json" ]; then
                    count=$((count + 1))
                fi
            fi
@@ -82,6 +91,9 @@ Usage:
    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 help                                     Show this help

 Issue Ref Format:
@@ -477,6 +489,234 @@ except Exception as e:
 PYEOF
 }

+ensure_queue_dirs() {
+    mkdir -p "$QUEUE_ITEMS_DIR"
+}
+
+generate_queue_id() {
+    echo "q_$(date +%s)_$$_$RANDOM"
+}
+
+enqueue_task() {
+    local issue_ref="$1"
+    local message="$2"
+    
+    if [ -z "$issue_ref" ] || [ -z "$message" ]; then
+        echo "Error: enqueue_task requires <issue-ref> and <message>" >&2
+        return 1
+    fi
+    
+    validate_issue_ref "$issue_ref"
+    ensure_queue_dirs
+    
+    local queue_id=$(generate_queue_id)
+    local pending_since=$(date -Iseconds)
+    
+    python3 << PYEOF
+import json
+
+queue_item = {
+    "id": "$queue_id",
+    "issue_ref": "$issue_ref",
+    "message": """$message""",
+    "state": "pending",
+    "pending_since": "$pending_since",
+    "notified_at": None,
+    "completed_at": None,
+    "error": None
+}
+
+with open("$QUEUE_ITEMS_DIR/${queue_id}.json", "w") as f:
+    json.dump(queue_item, f, indent=2)
+
+print(f"Enqueued: $queue_id")
+PYEOF
+
+    kugetsu_add_notification "task_queued" "Task queued: $issue_ref" "$issue_ref"
+}
+
+get_pending_tasks() {
+    local limit="${1:-10}"
+    
+    if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
+        echo "[]"
+        return
+    fi
+    
+    find "$QUEUE_ITEMS_DIR" -name "*.json" -type f 2>/dev/null | while read -r file; do
+        local state=$(python3 -c "import json; print(json.load(open('$file')).get('state', ''))" 2>/dev/null || echo "")
+        if [ "$state" = "pending" ]; then
+            cat "$file"
+        fi
+    done | head -"$limit"
+}
+
+get_queue_stats() {
+    local total=0
+    local pending=0
+    local notified=0
+    local completed=0
+    local error=0
+    
+    if [ -d "$QUEUE_ITEMS_DIR" ]; then
+        for file in "$QUEUE_ITEMS_DIR"/*.json; do
+            [ -f "$file" ] || continue
+            total=$((total + 1))
+            local state=$(python3 -c "import json; print(json.load(open('$file')).get('state', ''))" 2>/dev/null || echo "")
+            case "$state" in
+                pending) pending=$((pending + 1)) ;;
+                notified) notified=$((notified + 1)) ;;
+                completed) completed=$((completed + 1)) ;;
+                error) error=$((error + 1)) ;;
+            esac
+        done
+    fi
+    
+    echo "{\"total\": $total, \"pending\": $pending, \"notified\": $notified, \"completed\": $completed, \"error\": $error}"
+}
+
+update_queue_item_state() {
+    local queue_id="$1"
+    local new_state="$2"
+    local session_id="${3:-}"
+    local pid="${4:-}"
+    
+    local item_file="$QUEUE_ITEMS_DIR/${queue_id}.json"
+    if [ ! -f "$item_file" ]; then
+        echo "Error: Queue item not found: $queue_id" >&2
+        return 1
+    fi
+    
+    python3 << PYEOF
+import json
+import os
+from datetime import datetime
+
+item_file = "$item_file"
+new_state = "$new_state"
+session_id = "$session_id"
+pid = "$pid"
+
+with open(item_file, 'r') as f:
+    item = json.load(f)
+
+issue_ref = item.get('issue_ref', '')
+
+item['state'] = new_state
+
+if new_state == "notified":
+    item['notified_at'] = datetime.now().isoformat() + "Z"
+    if session_id:
+        item['opencode_session_id'] = session_id
+    if pid:
+        item['pid'] = int(pid) if pid.isdigit() else None
+elif new_state == "completed":
+    item['completed_at'] = datetime.now().isoformat() + "Z"
+    os.system(f"kugetsu_add_notification 'task_completed' 'Task completed: {issue_ref}' '{issue_ref}'")
+elif new_state == "error":
+    item['error'] = datetime.now().isoformat() + "Z"
+    os.system(f"kugetsu_add_notification 'task_error' 'Task error: {issue_ref}' '{issue_ref}'")
+
+with open(item_file, 'w') as f:
+    json.dump(item, f, indent=2)
+
+print(f"Updated $queue_id to state: $new_state")
+PYEOF
+}
+
+check_task_timeouts() {
+    if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
+        return
+    fi
+    
+    local timeout_hours="${TASK_TIMEOUT_HOURS:-1}"
+    
+    for item in "$QUEUE_ITEMS_DIR"/*.json; do
+        [ -f "$item" ] || continue
+        
+        local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
+        if [ "$state" != "notified" ]; then
+            continue
+        fi
+        
+        local notified_at=$(python3 -c "import json; print(json.load(open('$item')).get('notified_at', ''))" 2>/dev/null)
+        if [ -z "$notified_at" ]; then
+            continue
+        fi
+        
+        local queue_id=$(basename "$item" .json)
+        local pid=$(python3 -c "import json; print(json.load(open('$item')).get('pid', ''))" 2>/dev/null)
+        local session_id=$(python3 -c "import json; print(json.load(open('$item')).get('opencode_session_id', ''))" 2>/dev/null)
+        
+        local notified_epoch=$(date -d "$notified_at" +%s 2>/dev/null || echo "0")
+        local now_epoch=$(date +%s)
+        local hours_elapsed=$(( (now_epoch - notified_epoch) / 3600 ))
+        
+        if [ "$hours_elapsed" -ge "$timeout_hours" ]; then
+            echo "Task $queue_id timed out after ${hours_elapsed}h (limit: ${timeout_hours}h)"
+            
+            if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+                echo "Killing process $pid"
+                kill "$pid" 2>/dev/null || true
+            fi
+            
+            if [ -n "$session_id" ]; then
+                local worktree_path=""
+                for session_file in "$SESSIONS_DIR"/*.json; do
+                    [ -f "$session_file" ] || continue
+                    local sess_id=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', ''))" 2>/dev/null)
+                    if [ "$sess_id" = "$session_id" ]; then
+                        worktree_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null)
+                        break
+                    fi
+                done
+                
+                if [ -n "$worktree_path" ]; then
+                    pkill -f "opencode.*$worktree_path" 2>/dev/null || true
+                fi
+            fi
+            
+            update_queue_item_state "$queue_id" "error"
+            
+            local issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
+            if [ -n "$issue_ref" ]; then
+                local session_file=$(get_session_for_issue "$issue_ref")
+                if [ -n "$session_file" ] && [ "$session_file" != "null" ]; then
+                    python3 << PYEOF
+import json
+session_path = "$SESSIONS_DIR/$session_file"
+try:
+    with open(session_path, 'r') as f:
+        session = json.load(f)
+    session['state'] = 'timeout'
+    with open(session_path, 'w') as f:
+        json.dump(session, f, indent=2)
+    print(f"Marked session for $issue_ref as timeout")
+except Exception as e:
+    print(f"Error marking session: {e}")
+PYEOF
+                fi
+            fi
+        fi
+    done
+}
+
+cleanup_old_queue_items() {
+    local days="${QUEUE_CLEANUP_AGE_DAYS:-7}"
+    
+    if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
+        return
+    fi
+    
+    find "$QUEUE_ITEMS_DIR" -name "*.json" -type f -mtime "+$days" 2>/dev/null | while read -r file; do
+        local state=$(python3 -c "import json; print(json.load(open('$file')).get('state', ''))" 2>/dev/null || echo "")
+        if [ "$state" = "completed" ] || [ "$state" = "error" ]; then
+            rm -f "$file"
+            echo "Cleaned up: $(basename "$file")"
+        fi
+    done
+}
+
 update_session_pr_url() {
    local issue_ref="$1"
    local pr_url="$2"
@@ -984,9 +1224,218 @@ find_sessions_by_issue_number() {
    echo "$results"
 }

+cmd_queue() {
+    local action="${1:-list}"
+    shift
+    
+    case "$action" in
+        list)
+            ensure_queue_dirs
+            local stats=$(get_queue_stats)
+            echo "Queue Statistics:"
+            echo "$stats" | python3 -c "import json, sys; d=json.load(sys.stdin); print(f\"  Total: {d['total']}\n  Pending: {d['pending']}\n  Notified: {d['notified']}\n  Completed: {d['completed']}\n  Error: {d['error']}\")"
+            echo ""
+            echo "Pending tasks:"
+            local count=0
+            for item in "$QUEUE_ITEMS_DIR"/*.json; do
+                [ -f "$item" ] || continue
+                local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', '')" 2>/dev/null)
+                if [ "$state" = "pending" ]; then
+                    count=$((count + 1))
+                    python3 -c "import json; d=json.load(open('$item')); print(f\"  [{d['id']}] {d['issue_ref']}: {d['message'][:50]}...\n    pending since: {d['pending_since']}\")" 2>/dev/null
+                fi
+            done
+            if [ $count -eq 0 ]; then
+                echo "  (none)"
+            fi
+            ;;
+        stats)
+            local stats=$(get_queue_stats)
+            echo "$stats" | python3 -c "import json, sys; d=json.load(sys.stdin); print(json.dumps(d, indent=2))"
+            ;;
+        clear)
+            echo "Cleaning up old queue items..."
+            cleanup_old_queue_items
+            ;;
+        enqueue)
+            local issue_ref="${1:-}"
+            local message="${2:-}"
+            if [ -z "$issue_ref" ] || [ -z "$message" ]; then
+                echo "Usage: kugetsu queue enqueue <issue-ref> <message>" >&2
+                exit 1
+            fi
+            enqueue_task "$issue_ref" "$message"
+            ;;
+        *)
+            echo "Usage: kugetsu queue [list|stats|clear|enqueue <issue-ref> <message>]" >&2
+            exit 1
+            ;;
+    esac
+}
+
+cmd_queue_daemon() {
+    local action="${1:-status}"
+    shift
+    
+    case "$action" in
+        start)
+            if [ -f "$QUEUE_DAEMON_PID_FILE" ]; then
+                local old_pid=$(cat "$QUEUE_DAEMON_PID_FILE" 2>/dev/null)
+                if [ -n "$old_pid" ] && kill -0 "$old_pid" 2>/dev/null; then
+                    echo "Daemon is already running with PID $old_pid"
+                    exit 1
+                fi
+                rm -f "$QUEUE_DAEMON_PID_FILE"
+            fi
+            
+            mkdir -p "$(dirname "$QUEUE_DAEMON_LOG_FILE")"
+            nohup bash "$0" queue-daemon run >> "$QUEUE_DAEMON_LOG_FILE" 2>&1 &
+            local daemon_pid=$!
+            echo "$daemon_pid" > "$QUEUE_DAEMON_PID_FILE"
+            echo "Queue daemon started with PID $daemon_pid"
+            echo "Log file: $QUEUE_DAEMON_LOG_FILE"
+            ;;
+        stop)
+            if [ ! -f "$QUEUE_DAEMON_PID_FILE" ]; then
+                echo "Daemon PID file not found. Is the daemon running?"
+                exit 1
+            fi
+            local pid=$(cat "$QUEUE_DAEMON_PID_FILE")
+            if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+                kill "$pid"
+                rm -f "$QUEUE_DAEMON_PID_FILE"
+                echo "Daemon stopped (PID $pid)"
+            else
+                echo "Daemon not running (stale PID file)"
+                rm -f "$QUEUE_DAEMON_PID_FILE"
+            fi
+            ;;
+        restart)
+            cmd_queue_daemon stop
+            sleep 1
+            cmd_queue_daemon start
+            ;;
+        status)
+            if [ -f "$QUEUE_DAEMON_PID_FILE" ]; then
+                local pid=$(cat "$QUEUE_DAEMON_PID_FILE")
+                if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+                    echo "Queue daemon is running (PID $pid)"
+                else
+                    echo "Daemon not running (stale PID file)"
+                    rm -f "$QUEUE_DAEMON_PID_FILE"
+                fi
+            else
+                echo "Queue daemon is not running"
+            fi
+            ;;
+        logs)
+            local lines="${1:-50}"
+            if [ -f "$QUEUE_DAEMON_LOG_FILE" ]; then
+                tail -"$lines" "$QUEUE_DAEMON_LOG_FILE"
+            else
+                echo "No daemon log file found"
+            fi
+            ;;
+        run)
+            queue_daemon_loop
+            ;;
+        *)
+            echo "Usage: kugetsu queue-daemon [start|stop|restart|status|logs]" >&2
+            exit 1
+            ;;
+    esac
+}
+
+queue_daemon_loop() {
+    local pid=$$
+    echo "$pid" > "$QUEUE_DAEMON_PID_FILE"
+    echo "Queue daemon started (PID $pid) at $(date)"
+    
+    while true; do
+        sleep $((QUEUE_DAEMON_INTERVAL_MINUTES * 60))
+        
+        if [ ! -f "$QUEUE_DAEMON_PID_FILE" ] || [ "$(cat "$QUEUE_DAEMON_PID_FILE")" != "$pid" ]; then
+            echo "PID file changed, stopping daemon"
+            exit 0
+        fi
+        
+        check_task_timeouts
+        process_queue
+    done
+}
+
+process_queue() {
+    local active_count=$(count_active_dev_sessions)
+    
+    if [ "$active_count" -ge "$MAX_CONCURRENT_AGENTS" ]; then
+        return
+    fi
+    
+    local available_slots=$((MAX_CONCURRENT_AGENTS - active_count))
+    
+    if [ "$available_slots" -le 0 ]; then
+        return
+    fi
+    
+    local count=0
+    for item in $(ls -t "$QUEUE_ITEMS_DIR"/*.json 2>/dev/null | head -20); do
+        [ $count -ge "$available_slots" ] && break
+        [ -f "$item" ] || continue
+        
+        local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
+        if [ "$state" != "pending" ]; then
+            continue
+        fi
+        
+        local queue_id=$(basename "$item" .json)
+        local issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
+        local message=$(python3 -c "import json; print(json.load(open('$item')).get('message', ''))" 2>/dev/null)
+        
+        if [ -z "$issue_ref" ] || [ -z "$message" ]; then
+            continue
+        fi
+        
+        update_queue_item_state "$queue_id" "notified"
+        kugetsu_add_notification "task_dequeued" "Task dequeued: $issue_ref" "$issue_ref"
+        
+        local log_file="$LOGS_DIR/delegate-${queue_id}.log"
+        mkdir -p "$LOGS_DIR"
+        
+        local max_retries=3
+        local attempt=1
+        local success=false
+        local fork_pid=""
+        
+        while [ $attempt -le $max_retries ]; do
+            if kugetsu start "$issue_ref" "$message" >> "$log_file" 2>&1; then
+                success=true
+                break
+            fi
+            
+            echo "Attempt $attempt failed for $queue_id, cleaning up..." >> "$log_file"
+            
+            local session_file="$(issue_ref_to_filename "$issue_ref").json"
+            local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$PWD")
+            
+            [ -f "$SESSIONS_DIR/$session_file" ] && rm -f "$SESSIONS_DIR/$session_file"
+            worktree_exists "$issue_ref" "$PWD" && remove_worktree_for_issue "$issue_ref" "$PWD"
+            remove_issue_from_index "$issue_ref" 2>/dev/null || true
+            
+            attempt=$((attempt + 1))
+        done
+        
+        if [ "$success" = true ]; then
+            echo "Started task $queue_id: $issue_ref"
+            count=$((count + 1))
+        else
+            echo "Failed to start task $queue_id after $max_retries attempts"
+            update_queue_item_state "$queue_id" "pending"
+        fi
+    done
+}
+
 cmd_delegate() {
    local message="${1:-}"
-    local verbosity="${KUGETSU_VERBOSITY:-default}"
    
    if [ -z "$message" ]; then
        echo "Error: message is required" >&2
@@ -994,94 +1443,22 @@ cmd_delegate() {
        exit 1
    fi
    
-    local pm_session=$(get_pm_agent_session_id)
-    if [ -z "$pm_session" ] || [ "$pm_session" = "null" ] || [ "$pm_session" = "None" ]; then
-        echo "Error: PM agent session not found. Run 'kugetsu init' first." >&2
-        exit 1
-    fi
-    
-    mkdir -p "$LOGS_DIR"
-    local log_file="$LOGS_DIR/delegate-$(date +%s).log"
-    
    local parsed=$(parse_issue_ref_from_message "$message")
    local gitserver=$(echo "$parsed" | cut -d'|' -f1)
    local owner=$(echo "$parsed" | cut -d'|' -f2)
    local repo=$(echo "$parsed" | cut -d'|' -f3)
    local issue_number=$(echo "$parsed" | cut -d'|' -f4)
    
-    local missing_info=$(get_missing_info "$parsed")
-    local context_injection=""
-    if [ -n "$missing_info" ]; then
-        context_injection=$(build_missing_info_context "$missing_info")
-        echo "NOTE: Delegation missing information: ${missing_info}"
+    if [ -z "$issue_number" ] || [ -z "$gitserver" ] || [ -z "$owner" ] || [ -z "$repo" ]; then
+        echo "Error: Could not parse issue reference from message" >&2
+        echo "Message should contain an issue reference like 'github.com/user/repo#123'" >&2
+        exit 1
    fi
    
-    local candidates=""
-    local candidate_count=0
+    local issue_ref="${gitserver}/${owner}/${repo}#${issue_number}"
    
-    if [ -n "$issue_number" ]; then
-        local worktrees=$(find_worktrees_by_issue_number "$issue_number")
-        local sessions=$(find_sessions_by_issue_number "$issue_number")
-        
-        while IFS=: read -r path type; do
-            if [ -n "$path" ]; then
-                candidate_count=$((candidate_count + 1))
-                candidates="${candidates}${candidate_count}) ${path} (${type})
-"
-            fi
-        done <<< "$worktrees"
-        
-        while IFS=: read -r path type; do
-            if [ -n "$path" ]; then
-                candidate_count=$((candidate_count + 1))
-                candidates="${candidates}${candidate_count}) ${path} (${type})
-"
-            fi
-        done <<< "$sessions"
-    fi
-    
-    local use_worktree=""
-    if [ $candidate_count -gt 0 ]; then
-        echo "Found $candidate_count existing worktree(s)/session(s) for issue #${issue_number}:"
-        echo "$candidates"
-        echo "r) Delegate anyway (without routing)"
-        echo "Which one to use? [1-${candidate_count}/r]: "
-        read -r choice
-        
-        if [ "$choice" = "r" ] || [ -z "$choice" ]; then
-            use_worktree=""
-        elif [ "$choice" -ge 1 ] && [ "$choice" -le "$candidate_count" ]; then
-            local selected=$(echo "$candidates" | sed -n "${choice}p")
-            use_worktree=$(echo "$selected" | sed 's/) .*//')
-        fi
-    fi
-    
-    local final_message="${message}${context_injection}"
-    
-    if [ -n "$use_worktree" ]; then
-        if [ -d "$use_worktree" ]; then
-            echo "Using worktree: $use_worktree"
-            final_message="${final_message}
-
-NOTE: Worktree selected: ${use_worktree}"
-        fi
-    fi
-    
-    local temp_dir="${KUGETSU_TEMP_DIR:-$HOME/.local/share/opencode/tool-output}"
-    
-    mkdir -p "$ENV_DIR"
-    local env_sh="set -a; export KUGETSU_TEMP_DIR='$temp_dir'; export KUGETSU_VERBOSITY='$verbosity'; "
-    if [ -f "$ENV_DIR/pm-agent.env" ]; then
-        env_sh="${env_sh}source '$ENV_DIR/pm-agent.env'; "
-    elif [ -f "$ENV_DIR/default.env" ]; then
-        env_sh="${env_sh}source '$ENV_DIR/default.env'; "
-    fi
-    env_sh="${env_sh}set +a; "
-    
-    nohup sh -c "${env_sh}opencode run '${final_message}' --continue --session '$pm_session' >> '$log_file' 2>&1" > /dev/null 2>&1 &
-    disown
-    echo "Delegated to PM agent (logged to $(basename "$log_file"))"
-    echo "Verbosity: $verbosity"
+    enqueue_task "$issue_ref" "$message"
+    echo "Task enqueued. The queue daemon will process it when a slot is available."
 }

 cmd_logs() {
@@ -1699,20 +2076,10 @@ cmd_start() {
    create_worktree "$issue_ref" "$parent_dir"

    local session_file="$(issue_ref_to_filename "$issue_ref").json"
-
-    echo "Forking session for '$issue_ref'..."
-    
-    # Session-counting: count actual dev sessions, reject if at limit
-    local active_count=$(count_active_dev_sessions)
-    if [ "$active_count" -ge "$MAX_CONCURRENT_AGENTS" ]; then
-        echo "Error: Max concurrent agents ($MAX_CONCURRENT_AGENTS) reached" >&2
-        echo "Active sessions: $active_count" >&2
-        remove_worktree_for_issue "$issue_ref" "$parent_dir"
-        exit 1
-    fi
-     
    local fork_log="$SESSIONS_DIR/$session_file.fork.log"
    local opencode_db="${OPENCODE_DB:-$HOME/.local/share/opencode/opencode.db}"
+    local lock_file="$KUGETSU_DIR/.session_lock"
+    local lock_fd=200
    
    > "$fork_log"
    
@@ -1725,25 +2092,38 @@ ${previous_context}
 ## YOUR TASK
 $message"
    
-    fix_session_permissions
-    
-    if [ "$DEBUG_MODE" = true ]; then
-        (cd "$worktree_path" && opencode run "$full_message" --fork --session "$base_session_id" --dir "$worktree_path" 2>&1) | tee "$fork_log" &
-    else
-        (cd "$worktree_path" && opencode run "$full_message" --fork --session "$base_session_id" --dir "$worktree_path" 2>&1) >> "$fork_log" &
-    fi
-
-    local fork_pid=$!
-    
-    local max_attempts=10
-    local attempt=1
-    local new_session_id=""
-    local fork_log_output=""
-    
-    while [ $attempt -le $max_attempts ]; do
-        sleep 1
+    (
+        flock -x $lock_fd
        
-        new_session_id=$(python3 -c "
+        local active_count=$(count_active_dev_sessions)
+        if [ "$active_count" -ge "$MAX_CONCURRENT_AGENTS" ]; then
+            echo "Error: Max concurrent agents ($MAX_CONCURRENT_AGENTS) reached" >&2
+            echo "Active sessions: $active_count" >&2
+            remove_worktree_for_issue "$issue_ref" "$parent_dir"
+            exit 1
+        fi
+        
+        echo "Forking session for '$issue_ref'..."
+        
+        fix_session_permissions
+        
+        if [ "$DEBUG_MODE" = true ]; then
+            (cd "$worktree_path" && opencode run "$full_message" --fork --session "$base_session_id" --dir "$worktree_path" 2>&1) | tee "$fork_log" &
+        else
+            (cd "$worktree_path" && opencode run "$full_message" --fork --session "$base_session_id" --dir "$worktree_path" 2>&1) >> "$fork_log" &
+        fi
+
+        local fork_pid=$!
+        
+        local max_attempts=10
+        local attempt=1
+        local new_session_id=""
+        local fork_log_output=""
+        
+        while [ $attempt -le $max_attempts ]; do
+            sleep 1
+            
+            new_session_id=$(python3 -c "
 import sqlite3
 conn = sqlite3.connect('$opencode_db')
 cursor = conn.cursor()
@@ -1752,31 +2132,31 @@ result = cursor.fetchone()
 if result:
    print(result[0])
 " 2>/dev/null || echo "")
-        
-        if [ -n "$new_session_id" ] && [ "$new_session_id" != "$base_session_id" ] && [ "$new_session_id" != "$pm_agent_session_id" ]; then
-            break
-        fi
-        
-        if ! kill -0 $fork_pid 2>/dev/null; then
-            fork_log_output=$(tail -20 "$fork_log" 2>/dev/null || echo "(log empty or unavailable)")
-            break
-        fi
-        
-        attempt=$((attempt + 1))
-    done
+            
+            if [ -n "$new_session_id" ] && [ "$new_session_id" != "$base_session_id" ] && [ "$new_session_id" != "$pm_agent_session_id" ]; then
+                break
+            fi
+            
+            if ! kill -0 $fork_pid 2>/dev/null; then
+                fork_log_output=$(tail -20 "$fork_log" 2>/dev/null || echo "(log empty or unavailable)")
+                break
+            fi
+            
+            attempt=$((attempt + 1))
+        done

-    if [ -z "$new_session_id" ]; then
-        echo "Error: Could not find newly created session after ${max_attempts}s" >&2
-        if [ -n "$fork_log_output" ]; then
-            echo "Fork log output:" >&2
-            echo "$fork_log_output" >&2
+        if [ -z "$new_session_id" ]; then
+            echo "Error: Could not find newly created session after ${max_attempts}s" >&2
+            if [ -n "$fork_log_output" ]; then
+                echo "Fork log output:" >&2
+                echo "$fork_log_output" >&2
+            fi
+            remove_worktree_for_issue "$issue_ref"
+            exit 1
        fi
-        remove_worktree_for_issue "$issue_ref"
-        exit 1
-    fi

-    echo "Updating permissions for new session: $new_session_id"
-    python3 -c "
+        echo "Updating permissions for new session: $new_session_id"
+        python3 -c "
 import sqlite3
 conn = sqlite3.connect('$opencode_db')
 cursor = conn.cursor()
@@ -1786,9 +2166,9 @@ conn.commit()
 print('[OK] Session permissions updated')
 "

-    if [ "$DEBUG_MODE" = true ]; then
-        echo "[DEBUG] Forked session permissions check:"
-        python3 -c "
+        if [ "$DEBUG_MODE" = true ]; then
+            echo "[DEBUG] Forked session permissions check:"
+            python3 -c "
 import sqlite3
 conn = sqlite3.connect('$opencode_db')
 cursor = conn.cursor()
@@ -1798,11 +2178,11 @@ for row in cursor.fetchall():
    print('  Directory:', row[1])
    print('  Permission:', row[2])
 " 2>/dev/null || echo "  (failed to query DB)"
-    fi
+        fi

-    local branch_name=$(issue_ref_to_branch_name "$issue_ref")
-    
-    python3 << PYEOF > "$SESSIONS_DIR/$session_file"
+        local branch_name=$(issue_ref_to_branch_name "$issue_ref")
+        
+        python3 << PYEOF > "$SESSIONS_DIR/$session_file"
 import json

 session = {
@@ -1820,12 +2200,15 @@ with open("$SESSIONS_DIR/$session_file", "w") as f:
    json.dump(session, f, indent=2)
 PYEOF

-    add_issue_to_index "$issue_ref" "$session_file"
-    
-    kugetsu_context_dump "$issue_ref" "$message" "$branch_name"
+        add_issue_to_index "$issue_ref" "$session_file"
+        
+        kugetsu_context_dump "$issue_ref" "$message" "$branch_name"
+        
+        kugetsu_add_notification "task_started" "Task started: $issue_ref" "$issue_ref"

-    echo "Session started for '$issue_ref': $new_session_id"
-    echo "Worktree: $worktree_path"
+        echo "Session started for '$issue_ref': $new_session_id"
+        echo "Worktree: $worktree_path"
+    ) 200>"$lock_file"
 }

 cmd_continue() {
@@ -2218,6 +2601,16 @@ main() {
                exit 1
            fi
            ;;
+        queue)
+            local action="${1:-list}"
+            shift
+            cmd_queue "$action" "$@"
+            ;;
+        queue-daemon)
+            local action="${1:-status}"
+            shift
+            cmd_queue_daemon "$action" "$@"
+            ;;
        *)
            echo "Error: unknown command '$command'" >&2
            usage
Author	SHA1	Message	Date
shokollm	92f8369d6f	fix CONTRIBUTING.md: branch naming should include issue number Address han's review feedback: - Changed feat/feature-name to feat/issue-N-feature-name - Consistent with fix/issue-N-name format	2026-04-05 10:26:59 +00:00
shokollm	16e417c88e	docs: add versioning policy, changelog, and update contributing guide - Add VERSIONING.md documenting 0.1.x/0.2.x branch strategy - Add docs/CHANGELOG.md with release notes for v0.1.0-v0.2.1 - Update CONTRIBUTING.md: fix master->main, add develop branch - Closes #120	2026-04-05 09:38:25 +00:00
shoko	da0fa302de	Merge pull request 'fix(kugetsu): prevent excess agent spawning with flock + sequential processing' (#147 ) from fix/issue-queue-daemon-excess-agents into main	2026-04-05 10:49:24 +02:00
shokollm	54aa6419eb	fix(kugetsu): prevent excess agent spawning with flock + sequential processing - count_active_dev_sessions() now excludes pm-agent.json from count - process_queue() now calls kugetsu start directly (not opencode run) - process_queue() uses dynamic batch size = available_slots - process_queue() has retry logic (max 3 attempts) on failure - cmd_start() now uses flock around critical section - Added notification types: task_queued, task_dequeued, task_started, task_completed, task_error - Removed QUEUE_DAEMON_BATCH_SIZE config (no longer needed) Fixes issue #146	2026-04-05 08:44:45 +00:00
shoko	98a31070a7	Merge pull request '[FIX] process_queue: add missing closing parentheses' (#143 ) from fix/issue-142-process-queue-missing-parens into main	2026-04-05 08:56:59 +02:00
shoko	26346235c9	fix: add missing closing parenthesis in process_queue Python extraction Fixes #142 - process_queue silently skips all queue items because issue_ref and message Python extraction commands were missing a closing parenthesis. The error was silently swallowed by 2>/dev/null causing both variables to be empty, so every queue item was skipped.	2026-04-05 06:51:57 +00:00
shoko	2212fabf22	Merge pull request 'feat(timeout): add agent timeout handling' (#141 ) from feat/agent-timeout into main	2026-04-05 06:59:05 +02:00
shokollm	0fa778353b	feat(timeout): add agent timeout handling Implements #137 - Agent timeout handling. Changes: - Add TASK_TIMEOUT_HOURS config (default: 1 hour) - Update queue item to track opencode_session_id and pid - Add check_task_timeouts() function that: - Checks notified tasks against timeout threshold - Kills process if exceeded - Marks session as 'timeout' state - Integrate timeout check into queue daemon loop Timeout behavior: - Task is marked 'notified' when PM receives it - If not completed within TASK_TIMEOUT_HOURS, task is killed - Queue item marked 'error', session marked 'timeout'	2026-04-05 04:53:27 +00:00
shoko	151efadca3	Merge pull request 'feat(queue): add queue system with background daemon' (#140 ) from feat/queue-daemon into main	2026-04-05 06:49:13 +02:00
shokollm	379d53cedc	docs: update SKILL.md with queue system documentation - Update kugetsu delegate section to explain queue-based processing - Add queue-daemon command documentation - Update queue command with proper list/stats/clear/enqueue - Add queue-related config options - Update directory structure to include queue/ - Update workflow example with queue daemon setup	2026-04-05 04:45:56 +00:00
shokollm	043542344a	feat(queue): add queue system with background daemon Implements #134 - Queue system with background daemon. ## Changes ### Configuration - QUEUE_DIR, QUEUE_ITEMS_DIR for queue storage - QUEUE_DAEMON_PID_FILE, LOCK_FILE, LOG_FILE for daemon management - QUEUE_DAEMON_INTERVAL_MINUTES (default: 5) - QUEUE_DAEMON_BATCH_SIZE (default: 2) - QUEUE_CLEANUP_AGE_DAYS (default: 7) ### Queue System - File-based queue at ~/.kugetsu/queue/items/ - One JSON file per queue item - States: pending, notified, completed, error ### New Commands - kugetsu queue [list\|stats\|clear] - View queue status - kugetsu queue enqueue <issue-ref> <message> - Manually enqueue - kugetsu queue-daemon [start\|stop\|restart\|status\|logs] - Daemon management ### Behavior Change - kugetsu delegate now always enqueues (fire-and-forget) - Queue daemon polls queue and invokes PM when slots available ### Queue Item Format ```json { "id": "q_xxx", "issue_ref": "github.com/user/repo#123", "message": "task description", "state": "pending", "pending_since": "...", "notified_at": null, "completed_at": null, "error": null } ``` Closes #134	2026-04-05 04:28:41 +00:00
shoko	e763ceb0ad	Merge pull request 'feat(context): add context dump/load for session isolation' (#139 ) from feat/context-dump-load into main	2026-04-05 06:23:40 +02:00