fix(kugetsu): remove duplicate update_queue_item_state to use fixed version from kugetsu-index.sh

The main kugetsu script had its own update_queue_item_state() definition with broken os.system() calls that overwrote the fixed version in kugetsu-index.sh. Now kugetsu will use the fixed version from kugetsu-index.sh (which sources kugetsu-log.sh) since that module is sourced first. Fixes #170
Merge pull request 'fix(kugetsu-index): call kugetsu_add_notification from bash instead of os.system()' (#169 ) from fix/issue-167-notification-bash into main
2026-04-06 00:40:55 +00:00 · 2026-04-06 02:35:36 +02:00 · 2026-04-06 00:33:35 +00:00 · 2026-04-06 02:06:36 +02:00 · 2026-04-06 00:02:47 +00:00 · 2026-04-06 00:01:41 +00:00
14 changed files with 2442 additions and 1202 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/.kugetsu-worktrees/git.fbrns.co-shoko-jigaido-2
+++ b/.kugetsu-worktrees/git.fbrns.co-shoko-jigaido-2
--- 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
--- a/skills/kugetsu/scripts/kugetsu-config.sh
+++ b/skills/kugetsu/scripts/kugetsu-config.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+set -euo pipefail
+
+KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
+SESSIONS_DIR="$KUGETSU_DIR/sessions"
+WORKTREES_DIR="$KUGETSU_DIR/worktrees"
+REPOS_CONFIG="$KUGETSU_DIR/repos.json"
+INDEX_FILE="$KUGETSU_DIR/index.json"
+NOTIFICATIONS_FILE="$KUGETSU_DIR/notifications.json"
+LOGS_DIR="$KUGETSU_DIR/logs"
+ENV_DIR="${ENV_DIR:-$KUGETSU_DIR/env}"
+VERBOSITY_DIR="$KUGETSU_DIR/verbosity"
+
+MAX_CONCURRENT_AGENTS="${MAX_CONCURRENT_AGENTS:-3}"
+KUGETSU_VERBOSITY="${KUGETSU_VERBOSITY:-default}"
+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"
+fi
+
+mask_sensitive_vars() {
+    local line="$1"
+    for var in GITEA_TOKEN GITHUB_TOKEN GITLAB_TOKEN API_KEY PASSWORD TOKEN SECRET; do
+        if [[ "$line" =~ $var ]]; then
+            line=$(echo "$line" | sed -E "s/=.*/=***MASKED***/")
+        fi
+    done
+    echo "$line"
+}
+
+load_agent_env() {
+    local agent_type="${1:-base}"
+    local env_file="$ENV_DIR/${agent_type}.env"
+    
+    if [ -f "$env_file" ]; then
+        set -a
+        source "$env_file"
+        set +a
+    elif [ -f "$ENV_DIR/default.env" ]; then
+        set -a
+        source "$ENV_DIR/default.env"
+        set +a
+    fi
+}
--- a/skills/kugetsu/scripts/kugetsu-index.sh
+++ b/skills/kugetsu/scripts/kugetsu-index.sh
@@ -0,0 +1,243 @@
+#!/bin/bash
+set -euo pipefail
+
+read_index() {
+    if [ -f "$INDEX_FILE" ]; then
+        cat "$INDEX_FILE"
+    else
+        echo '{"base": null, "pm_agent": null, "issues": {}}'
+    fi
+}
+
+write_index() {
+    local base="$1"
+    local pm_agent="$2"
+    local issues_json="$3"
+    local temp_file="$INDEX_FILE.tmp.$$"
+    printf '{"base": %s, "pm_agent": %s, "issues": %s}\n' "$base" "$pm_agent" "$issues_json" > "$temp_file"
+    mv "$temp_file" "$INDEX_FILE"
+}
+
+get_base_session_id() {
+    local index=$(read_index)
+    echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or '')"
+}
+
+get_pm_agent_session_id() {
+    local index=$(read_index)
+    echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or '')"
+}
+
+get_session_for_issue() {
+    local issue_ref="$1"
+    local index=$(read_index)
+    echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('issues', {}).get('$issue_ref') or 'null')"
+}
+
+set_base_in_index() {
+    local session_id="$1"
+    local index=$(read_index)
+    local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
+    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
+    
+    if [ "$session_id" = "null" ]; then
+        write_index "null" "$pm_agent" "$issues"
+    else
+        write_index "\"$session_id\"" "$pm_agent" "$issues"
+    fi
+}
+
+set_pm_agent_in_index() {
+    local session_id="$1"
+    local index=$(read_index)
+    local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
+    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
+    
+    if [ "$session_id" = "null" ]; then
+        write_index "$base" "null" "$issues"
+    else
+        write_index "$base" "\"$session_id\"" "$issues"
+    fi
+}
+
+add_issue_to_index() {
+    local issue_ref="$1"
+    local session_file="$2"
+    
+    local index=$(read_index)
+    local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
+    local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
+    
+    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
+    
+    issues=$(python3 -c "import sys, json; d=json.load(sys.stdin); d['$issue_ref']='$session_file'; print(json.dumps(d))" <<< "$issues")
+    
+    write_index "$base" "$pm_agent" "$issues"
+}
+
+remove_issue_from_index() {
+    local issue_ref="$1"
+    
+    local index=$(read_index)
+    local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
+    local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
+    
+    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
+    
+    issues=$(python3 -c "import sys, json; d=json.load(sys.stdin); d.pop('$issue_ref', None); print(json.dumps(d))" <<< "$issues")
+    
+    write_index "$base" "$pm_agent" "$issues"
+}
+
+validate_issue_ref() {
+    local issue_ref="$1"
+    
+    if [[ ! "$issue_ref" =~ ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+#[0-9]+$ ]]; then
+        echo "Error: Invalid issue ref format: '$issue_ref'" >&2
+        echo "Expected format: instance/user/repo#number" >&2
+        echo "Example: github.com/shoko/kugetsu#14" >&2
+        exit 1
+    fi
+}
+
+update_session_pr_url() {
+    local issue_ref="$1"
+    local pr_url="$2"
+    
+    local session_file=$(get_session_for_issue "$issue_ref")
+    if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
+        echo "Error: No session found for '$issue_ref'" >&2
+        return 1
+    fi
+    
+    local session_path="$SESSIONS_DIR/$session_file"
+    if [ ! -f "$session_path" ]; then
+        echo "Error: Session file not found: $session_path" >&2
+        return 1
+    fi
+    
+    python3 << PYEOF
+import json
+
+session_path = "$session_path"
+pr_url = "$pr_url"
+
+with open(session_path, 'r') as f:
+    session = json.load(f)
+
+session['pr_url'] = pr_url
+
+with open(session_path, 'w') as f:
+    json.dump(session, f, indent=2)
+
+    print(f"Updated PR URL for $issue_ref: $pr_url")
+PYEOF
+}
+
+# Convert issue ref to session filename
+issue_ref_to_filename() {
+    local issue_ref="$1"
+    echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
+}
+
+# Convert session filename back to issue ref
+filename_to_issue_ref() {
+    local filename="$1"
+    local name="${filename%.json}"
+    echo "$name" | sed 's-\([0-9]*\)$-#\1-' | sed 's/-/\//g'
+}
+
+# Add notification to notifications file
+kugetsu_add_notification() {
+    local type="$1"
+    local message="$2"
+    local issue_ref="${3:-}"
+    local gitea_url="${4:-}"
+    
+    mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
+    
+    python3 << PYEOF
+import json
+import os
+from datetime import datetime
+
+notification = {
+    "type": "$type",
+    "message": "$message",
+    "issue_ref": "$issue_ref" if "$issue_ref" else None,
+    "gitea_url": "$gitea_url" if "$gitea_url" else None,
+    "timestamp": datetime.now().isoformat(),
+    "read": False
+}
+
+file_path = os.path.expanduser("$NOTIFICATIONS_FILE")
+notifications = []
+
+if os.path.exists(file_path):
+    try:
+        with open(file_path, 'r') as f:
+            notifications = json.load(f)
+    except:
+        notifications = []
+
+notifications.append(notification)
+
+with open(file_path, 'w') as f:
+    json.dump(notifications, f, indent=2)
+
+print("Notification added")
+PYEOF
+}
+
+# Update queue item state
+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
+    
+    local issue_ref=$(python3 -c "import json; print(json.load(open('$item_file')).get('issue_ref', ''))" 2>/dev/null || echo "")
+    
+    python3 << PYEOF
+import json
+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)
+
+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"
+elif new_state == "error":
+    item['error'] = datetime.now().isoformat() + "Z"
+
+with open(item_file, 'w') as f:
+    json.dump(item, f, indent=2)
+
+print(f"Updated $queue_id to state: $new_state")
+PYEOF
+    
+    if [ "$new_state" = "completed" ]; then
+        kugetsu_add_notification "task_completed" "Task completed: $issue_ref" "$issue_ref"
+    elif [ "$new_state" = "error" ]; then
+        kugetsu_add_notification "task_error" "Task error: $issue_ref" "$issue_ref"
+    fi
+}
--- a/skills/kugetsu/scripts/kugetsu-log.sh
+++ b/skills/kugetsu/scripts/kugetsu-log.sh
@@ -0,0 +1,91 @@
+#!/bin/bash
+set -euo pipefail
+
+cmd_logs() {
+    local count="${1:-10}"
+    
+    if [ ! -d "$LOGS_DIR" ]; then
+        echo "No logs found."
+        return
+    fi
+    
+    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"
+    done
+    
+    echo ""
+    echo "Recent log contents:"
+    echo "===================="
+    
+    for log in $(ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | awk '{print $NF}'); do
+        if [ -f "$LOGS_DIR/$log" ]; then
+            echo ""
+            echo "--- $log ---"
+            tail -20 "$LOGS_DIR/$log" | while read line; do
+                echo "  $(mask_sensitive_vars "$line")"
+            done
+        fi
+    done
+}
+
+kugetsu_add_notification() {
+    local notification_type="$1"
+    local message="$2"
+    local issue_ref="${3:-}"
+    local timestamp=$(date -Iseconds)
+    
+    mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
+    
+    local notifications="[]"
+    if [ -f "$NOTIFICATIONS_FILE" ]; then
+        notifications=$(cat "$NOTIFICATIONS_FILE")
+    fi
+    
+    local new_notification=$(python3 -c "import json; print(json.dumps({
+        'type': '$notification_type',
+        'message': '$message',
+        'issue_ref': '$issue_ref',
+        'timestamp': '$timestamp',
+        'read': False
+    }))")
+    
+    notifications=$(python3 -c "import json; n=json.loads('$notifications'); n.append(json.loads('$new_notification')); print(json.dumps(n[-50:] if len(n)>50 else n, indent=2))")
+    
+    echo "$notifications" > "$NOTIFICATIONS_FILE"
+}
+
+cmd_notify() {
+    local action="${1:-list}"
+    
+    case "$action" in
+        list)
+            if [ ! -f "$NOTIFICATIONS_FILE" ]; then
+                echo "No notifications."
+                return
+            fi
+            
+            local notifications=$(cat "$NOTIFICATIONS_FILE")
+            local count=$(echo "$notifications" | python3 -c "import sys, json; n=json.load(sys.stdin); print(sum(1 for x in n if not x.get('read', False)))")
+            
+            if [ "$count" -eq 0 ]; then
+                echo "No unread notifications."
+                return
+            fi
+            
+            echo "Unread notifications ($count):"
+            echo "$notifications" | python3 -c "import sys, json; [print(f\"  [{x.get('timestamp', '')}] {x.get('type', '')}: {x.get('message', '')}\") for x in json.load(sys.stdin) if not x.get('read', False)]"
+            ;;
+        clear)
+            if [ -f "$NOTIFICATIONS_FILE" ]; then
+                python3 -c "import json; print(json.dumps([x for x in json.load(open('$NOTIFICATIONS_FILE')) if x.get('read', False)], indent=2))" > "$NOTIFICATIONS_FILE"
+                echo "Cleared unread notifications."
+            fi
+            ;;
+        *)
+            echo "Usage: kugetsu notify [list|clear]" >&2
+            exit 1
+            ;;
+    esac
+}
--- a/skills/kugetsu/scripts/kugetsu-queue-daemon.sh
+++ b/skills/kugetsu/scripts/kugetsu-queue-daemon.sh
@@ -0,0 +1,155 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+source "$SCRIPT_DIR/kugetsu-config.sh"
+source "$SCRIPT_DIR/kugetsu-index.sh"
+source "$SCRIPT_DIR/kugetsu-worktree.sh"
+source "$SCRIPT_DIR/kugetsu-log.sh"
+
+load_agent_env "pm-agent"
+
+acquire_lock() {
+    local issue_ref="$1"
+    local lock_file="$QUEUE_DIR/locks/$(echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/').lock"
+    mkdir -p "$(dirname "$lock_file")"
+    if [ -f "$lock_file" ]; then
+        local pid=$(cat "$lock_file" 2>/dev/null || echo "")
+        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+            return 1
+        fi
+        rm -f "$lock_file"
+    fi
+    echo $$ > "$lock_file"
+    return 0
+}
+
+release_lock() {
+    local issue_ref="$1"
+    local lock_file="$QUEUE_DIR/locks/$(echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/').lock"
+    rm -f "$lock_file"
+}
+
+check_task_completion() {
+    local item="$1"
+    local queue_id=$(basename "$item" .json)
+    local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
+
+    [ "$state" = "notified" ] || return 0
+
+    local session_id=$(python3 -c "import json; print(json.load(open('$item')).get('opencode_session_id', ''))" 2>/dev/null)
+    local issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
+    local pid=$(python3 -c "import json; print(json.load(open('$item')).get('pid', ''))" 2>/dev/null)
+
+    if [ -n "$pid" ] && [ "$pid" != "None" ]; then
+        if ! kill -0 "$pid" 2>/dev/null; then
+            local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$HOME/.kugetsu-worktrees")
+            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
+                    has_commits=true
+                fi
+            fi
+
+            if [ "$has_commits" = true ]; then
+                update_queue_item_state "$queue_id" "completed"
+                echo "Task $queue_id ($issue_ref) completed — new commits found"
+            else
+                update_queue_item_state "$queue_id" "error"
+                echo "Task $queue_id ($issue_ref) marked error — no commits found after session ended"
+            fi
+            release_lock "$issue_ref"
+        fi
+    else
+        if [ -n "$session_id" ] && ! opencode session list 2>/dev/null | grep -q "$session_id"; then
+            local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$HOME/.kugetsu-worktrees")
+            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
+                    has_commits=true
+                fi
+            fi
+
+            if [ "$has_commits" = true ]; then
+                update_queue_item_state "$queue_id" "completed"
+                echo "Task $queue_id ($issue_ref) completed — new commits found"
+            else
+                update_queue_item_state "$queue_id" "error"
+                echo "Task $queue_id ($issue_ref) marked error — no commits found after session ended"
+            fi
+            release_lock "$issue_ref"
+        fi
+    fi
+}
+
+get_session_id_for_issue() {
+    local issue_ref="$1"
+    local session_file=$(issue_ref_to_filename "$issue_ref")
+    local session_path="$SESSIONS_DIR/$session_file"
+    if [ -f "$session_path" ]; then
+        python3 -c "import json; print(json.load(open('$session_path')).get('opencode_session_id', ''))" 2>/dev/null || echo ""
+    else
+        echo ""
+    fi
+}
+
+process_task() {
+    local item="$1"
+    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 ! acquire_lock "$issue_ref"; then
+        echo "Task $queue_id ($issue_ref) skipped — another process is handling it"
+        return
+    fi
+
+    source "$SCRIPT_DIR/kugetsu-session.sh"
+
+    if worktree_exists "$issue_ref" "$HOME/.kugetsu-worktrees" || [ -f "$SESSIONS_DIR/$(issue_ref_to_filename "$issue_ref").json" ]; then
+        log_file="$LOGS_DIR/delegate-$(date +%s).log"
+        if cmd_continue "$issue_ref" "$message" >> "$log_file" 2>&1; then
+            sleep 1
+            local session_id=$(get_session_id_for_issue "$issue_ref")
+            update_queue_item_state "$queue_id" "notified" "$session_id" ""
+            echo "Task $queue_id continued for $issue_ref"
+        else
+            update_queue_item_state "$queue_id" "error"
+            echo "Task $queue_id ($issue_ref) failed to continue"
+        fi
+    else
+        log_file="$LOGS_DIR/delegate-$(date +%s).log"
+        if cmd_start "$issue_ref" "$message" >> "$log_file" 2>&1; then
+            sleep 1
+            local session_id=$(get_session_id_for_issue "$issue_ref")
+            update_queue_item_state "$queue_id" "notified" "$session_id" ""
+            echo "Task $queue_id started for $issue_ref"
+        else
+            update_queue_item_state "$queue_id" "error"
+            echo "Task $queue_id ($issue_ref) failed to start"
+        fi
+    fi
+
+    release_lock "$issue_ref"
+}
+
+while true; do
+    if [ -d "$QUEUE_ITEMS_DIR" ]; then
+        for item in "$QUEUE_ITEMS_DIR"/*.json; do
+            [ -f "$item" ] || continue
+            check_task_completion "$item"
+        done
+
+        for item in "$QUEUE_ITEMS_DIR"/*.json; do
+            [ -f "$item" ] || continue
+            state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
+            if [ "$state" = "pending" ]; then
+                process_task "$item"
+            fi
+        done
+    fi
+    sleep "${QUEUE_DAEMON_INTERVAL_MINUTES:-5}m"
+done
--- a/skills/kugetsu/scripts/kugetsu-session.sh
+++ b/skills/kugetsu/scripts/kugetsu-session.sh
@@ -0,0 +1,578 @@
+#!/bin/bash
+set -euo pipefail
+
+# Source required modules for session management functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/kugetsu-config.sh"
+source "$SCRIPT_DIR/kugetsu-index.sh"
+source "$SCRIPT_DIR/kugetsu-worktree.sh"
+source "$SCRIPT_DIR/kugetsu-log.sh"
+
+count_active_dev_sessions() {
+    local count=0
+    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
+                    count=$((count + 1))
+                fi
+            fi
+        done
+    fi
+    echo "$count"
+}
+
+cmd_init() {
+    local force=false
+
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --force)
+                force=true
+                ;;
+            *)
+                ;;
+        esac
+        shift
+    done
+
+    ensure_dirs
+
+    if [ ! -f "$KUGETSU_DIR/config" ]; then
+        cat > "$KUGETSU_DIR/config" << 'EOF'
+# User configuration overrides
+# Values set here take precedence over defaults
+# Changes take effect immediately (no re-init needed)
+
+# Max concurrent dev agents (default: 3)
+# MAX_CONCURRENT_AGENTS=5
+
+# Git server configurations
+# Format: GIT_SERVERS["hostname"]="https://hostname"
+declare -A GIT_SERVERS
+GIT_SERVERS["github.com"]="https://github.com"
+GIT_SERVERS["git.fbrns.co"]="https://git.fbrns.co"
+DEFAULT_GIT_SERVER="github.com"
+EOF
+        echo "Created config file: $KUGETSU_DIR/config"
+    fi
+
+    local existing_base=$(get_base_session_id)
+    local existing_pm=$(get_pm_agent_session_id)
+    
+    if [ -n "$existing_base" ] && [ "$existing_base" != "null" ]; then
+        if [ "$force" = true ]; then
+            echo "Warning: Reinitializing sessions (force mode)" >&2
+        else
+            echo "Error: Base session already exists: $existing_base" >&2
+            echo "Use --force to reinitialize" >&2
+            exit 1
+        fi
+    fi
+
+    if ! test -t 0; then
+        echo "Error: init requires a terminal (TTY)" >&2
+        echo "Please run this command in an interactive shell" >&2
+        exit 1
+    fi
+
+    echo "Starting TUI to create base session..."
+    echo "Press Ctrl+C to cancel or wait for session to be created"
+    sleep 2
+
+    opencode
+
+    local session_ids=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' | tail -1)
+    if [ -z "$session_ids" ]; then
+        echo "Error: Could not find newly created session" >&2
+        exit 1
+    fi
+
+    echo "$session_ids" > "$SESSIONS_DIR/base.json"
+    set_base_in_index "$session_ids"
+
+    echo "Base session created: $session_ids"
+    echo "Starting PM agent..."
+
+    opencode
+
+    local pm_session_ids=$(opencode session list 2>/dev/null | grep -E '^ses_' | grep -v "$session_ids" | tail -1)
+    if [ -z "$pm_session_ids" ]; then
+        echo "Warning: Could not find separate PM agent session" >&2
+        pm_session_ids="$session_ids"
+    fi
+
+    echo "$pm_session_ids" > "$SESSIONS_DIR/pm-agent.json"
+    set_pm_agent_in_index "$pm_session_ids"
+
+    load_agent_env "pm-agent"
+
+    local pm_system_prompt=""
+    if [ -f "$KUGETSU_DIR/pm-agent.md" ]; then
+        pm_system_prompt=$(cat "$KUGETSU_DIR/pm-agent.md")
+        echo "Injecting PM agent system prompt from $KUGETSU_DIR/pm-agent.md"
+    fi
+
+    echo "PM agent session created: $pm_session_ids"
+    echo ""
+    echo "kugetsu initialized successfully!"
+    echo "  Base session: $session_ids"
+    echo "  PM agent: $pm_session_ids"
+}
+
+extract_issue_ref_from_message() {
+    local message="$1"
+    
+    if [ -z "$message" ]; then
+        echo ""
+        return
+    fi
+    
+    if [[ "$message" =~ ^([a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+#[0-9]+) ]]; then
+        echo "${BASH_REMATCH[1]}"
+        return
+    fi
+    
+    if [[ "$message" =~ (https?://[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+/(issues|pull)/[0-9]+) ]]; then
+        local url="${BASH_REMATCH[1]}"
+        local path=$(echo "$url" | sed 's|https\?://||' | cut -d'/' -f2-)
+        local instance=$(echo "$path" | cut -d'/' -f1)
+        local owner=$(echo "$path" | cut -d'/' -f2)
+        local repo=$(echo "$path" | cut -d'/' -f3)
+        local num=$(echo "$path" | grep -oE '[0-9]+$')
+        echo "${instance}/${owner}/${repo}#${num}"
+        return
+    fi
+    
+    echo ""
+}
+
+cmd_delegate() {
+    local message="${1:-}"
+    
+    if [ -z "$message" ]; then
+        echo "Error: message is required" >&2
+        echo "Usage: kugetsu delegate <message>" >&2
+        exit 1
+    fi
+    
+    local issue_ref=$(extract_issue_ref_from_message "$message")
+    
+    if [ -n "$issue_ref" ] && [[ "$issue_ref" =~ \#[0-9]+$ ]]; then
+        # Enqueue for daemon to process via cmd_start/cmd_continue
+        enqueue_task "$issue_ref" "$message"
+        return
+    fi
+    
+    # No issue ref detected — delegate directly to PM agent (legacy path)
+    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"
+    nohup sh -c "GITEA_TOKEN='***' opencode run '$message' --continue --session '$pm_session' >> '$log_file' 2>&1" > /dev/null 2>&1 &
+    disown
+    echo "Delegated to PM agent (logged to $(basename "$log_file"))"
+}
+
+cmd_start() {
+    local issue_ref="${1:-}"
+    local message="${2:-}"
+    
+    if [ -z "$issue_ref" ]; then
+        echo "Error: issue ref is required" >&2
+        echo "Usage: kugetsu start <issue-ref> [message]" >&2
+        exit 1
+    fi
+    
+    validate_issue_ref "$issue_ref"
+    
+    local base_session_id=$(get_base_session_id)
+    if [ -z "$base_session_id" ] || [ "$base_session_id" = "null" ]; then
+        echo "Error: Base session not found. Run 'kugetsu init' first." >&2
+        exit 1
+    fi
+    
+    local pm_agent_session_id=$(get_pm_agent_session_id)
+    if [ -z "$pm_agent_session_id" ] || [ "$pm_agent_session_id" = "null" ]; then
+        echo "Error: PM agent session not found. Run 'kugetsu init' first." >&2
+        exit 1
+    fi
+    
+    if worktree_exists "$issue_ref"; then
+        echo "Issue '$issue_ref' already has a worktree. Use 'kugetsu continue' instead."
+        exit 1
+    fi
+    
+    local active_count=$(count_active_dev_sessions)
+    if [ "$active_count" -ge "${MAX_CONCURRENT_AGENTS:-3}" ]; then
+        echo "Error: Max concurrent agents (${MAX_CONCURRENT_AGENTS:-3}) reached. Use 'kugetsu continue' or wait for an agent to finish." >&2
+        exit 1
+    fi
+    
+    local session_file=$(issue_ref_to_filename "$issue_ref")
+    local session_path="$SESSIONS_DIR/$session_file"
+    
+    if [ -f "$session_path" ]; then
+        echo "Session file already exists: $session_file"
+        echo "Use 'kugetsu continue $issue_ref' to continue work."
+        exit 1
+    fi
+    
+    local before_sessions=$(opencode session list 2>/dev/null | grep -oP '^ses_\w+' | sort)
+    local before_set="|$before_sessions|"
+    
+    create_worktree "$issue_ref"
+    
+    local after_sessions=$(opencode session list 2>/dev/null | grep -oP '^ses_\w+' | sort)
+    local new_session_id=""
+    while IFS= read -r sess; do
+        if [[ ! "$before_set" =~ \|${sess}\| ]] && [[ "$sess" != "$base_session_id" ]] && [[ "$sess" != "$pm_agent_session_id" ]]; then
+            new_session_id="$sess"
+            break
+        fi
+    done <<< "$after_sessions"
+    
+    if [ -z "$new_session_id" ]; then
+        echo "Error: Could not find newly created session" >&2
+        remove_worktree_for_issue "$issue_ref"
+        exit 1
+    fi
+    
+    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref")
+    
+    printf '{"type": "forked", "issue_ref": "%s", "opencode_session_id": "%s", "worktree_path": "%s", "created_at": "%s", "state": "idle"}\n' \
+        "$issue_ref" "$new_session_id" "$worktree_path" "$(date -Iseconds)" > "$SESSIONS_DIR/$session_file"
+    
+    add_issue_to_index "$issue_ref" "$session_file"
+    
+    echo "Session started for '$issue_ref': $new_session_id"
+    echo "Worktree: $worktree_path"
+}
+
+cmd_continue() {
+    local session_name=""
+    local message=""
+    local args=("$@")
+
+    args=$(set_debug_mode "${args[@]}")
+
+    for arg in $args; do
+        if [ -z "$session_name" ]; then
+            session_name="$arg"
+        else
+            message="$arg"
+        fi
+    done
+    
+    if [ -z "$session_name" ]; then
+        echo "Error: issue ref is required" >&2
+        echo "Usage: kugetsu continue <issue-ref> [message]" >&2
+        exit 1
+    fi
+    
+    validate_issue_ref "$session_name"
+    
+    local session_file=$(get_session_for_issue "$session_name")
+    if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
+        echo "Error: No session found for '$session_name'" >&2
+        echo "Use 'kugetsu start $session_name' to create a new session." >&2
+        exit 1
+    fi
+    
+    local session_path="$SESSIONS_DIR/$session_file"
+    
+    if [ ! -f "$session_path" ]; then
+        echo "Error: Session file not found: $session_path" >&2
+        exit 1
+    fi
+    
+    load_agent_env "dev"
+    
+    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 "")
+    
+    if [ -n "$worktree_path" ] && [ -d "$worktree_path" ]; then
+        if [ -n "$message" ]; then
+            (cd "$worktree_path" && opencode run "$message" --continue --session "$opencode_session_id" "$@")
+        else
+            (cd "$worktree_path" && opencode --continue --session "$opencode_session_id" "$@")
+        fi
+    else
+        if [ -n "$message" ]; then
+            opencode run "$message" --continue --session "$opencode_session_id" "$@"
+        else
+            opencode --continue --session "$opencode_session_id" "$@"
+        fi
+    fi
+}
+
+cmd_list() {
+    echo "=== kugetsu sessions ==="
+    echo ""
+    
+    local base_id=$(get_base_session_id)
+    if [ -n "$base_id" ] && [ "$base_id" != "null" ]; then
+        echo "Base session: $base_id"
+    else
+        echo "Base session: not initialized"
+    fi
+    
+    local pm_id=$(get_pm_agent_session_id)
+    if [ -n "$pm_id" ] && [ "$pm_id" != "null" ]; then
+        echo "PM agent: $pm_id"
+    else
+        echo "PM agent: not initialized"
+    fi
+    
+    echo ""
+    echo "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 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"
+                fi
+            fi
+        done
+    fi
+    
+    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
+                    fi
+                fi
+            done
+            if [ "$has_session" = false ]; then
+                echo "  $worktree_name (no session)"
+            fi
+        done
+    fi
+}
+
+cmd_prune() {
+    local force=false
+    
+    if [ "$1" = "--force" ]; then
+        force=true
+    fi
+    
+    echo "=== kugetsu prune ==="
+    echo ""
+    
+    local orphaned=()
+    
+    if [ -d "$SESSIONS_DIR" ]; then
+        for session_file in "$SESSIONS_DIR"/*.json; do
+            [ -f "$session_file" ] || continue
+            local filename=$(basename "$session_file")
+            if [ "$filename" = "base.json" ] || [ "$filename" = "pm-agent.json" ]; then
+                continue
+            fi
+            
+            local opencode_sid=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', ''))" 2>/dev/null || echo "")
+            
+            if [ -n "$opencode_sid" ]; then
+                local exists=$(opencode session list 2>/dev/null | grep -c "^$opencode_sid" || echo "0")
+                if [ "$exists" -eq 0 ]; then
+                    orphaned+=("$session_file")
+                fi
+            else
+                orphaned+=("$session_file")
+            fi
+        done
+    fi
+    
+    if [ ${#orphaned[@]} -eq 0 ]; then
+        echo "No orphaned sessions found."
+        return
+    fi
+    
+    echo "Found ${#orphaned[@]} orphaned session(s):"
+    for session in "${orphaned[@]}"; do
+        echo "  $session"
+    done
+    echo ""
+    
+    if [ "$force" = false ]; then
+        read -p "Remove these sessions? [y/N] " -r answer
+        if [[ ! "$answer" =~ ^[Yy]$ ]]; then
+            echo "Aborted."
+            return
+        fi
+    fi
+    
+    for session in "${orphaned[@]}"; do
+        local issue_ref=$(python3 -c "import json; print(json.load(open('$session')).get('issue_ref', ''))" 2>/dev/null || echo "")
+        local worktree_path=$(python3 -c "import json; print(json.load(open('$session')).get('worktree_path', ''))" 2>/dev/null || echo "")
+        
+        if [ -n "$worktree_path" ] && [ -d "$worktree_path" ]; then
+            echo "Removing worktree: $worktree_path"
+            git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
+        fi
+        
+        rm -f "$session"
+        
+        if [ -n "$issue_ref" ]; then
+            remove_issue_from_index "$issue_ref"
+        fi
+        
+        echo "Removed: $session"
+    done
+    
+    echo ""
+    echo "Pruned ${#orphaned[@]} orphaned session(s)."
+}
+
+cmd_destroy() {
+    local target="${1:-}"
+    local force=false
+    
+    if [ "$target" = "--base" ]; then
+        target=""
+    fi
+    
+    if [ "$2" = "-y" ]; then
+        force=true
+    fi
+    
+    if [ -z "$target" ]; then
+        echo "Error: target is required" >&2
+        echo "Usage: kugetsu destroy <issue-ref> [-y]" >&2
+        echo "       kugetsu destroy --pm-agent [-y]" >&2
+        echo "       kugetsu destroy --base [-y]" >&2
+        exit 1
+    fi
+    
+    if [ "$target" = "--pm-agent" ]; then
+        if [ "$force" = false ]; then
+            echo "Warning: Destroying PM agent session is not recommended." >&2
+            read -p "Continue? [y/N] " -r answer
+            if [[ ! "$answer" =~ ^[Yy]$ ]]; then
+                echo "Aborted."
+                return
+            fi
+        fi
+        
+        local pm_session=$(get_pm_agent_session_id)
+        if [ -n "$pm_session" ] && [ "$pm_session" != "null" ]; then
+            echo "Stopping PM agent session: $pm_session"
+            opencode session stop "$pm_session" 2>/dev/null || true
+        fi
+        
+        rm -f "$SESSIONS_DIR/pm-agent.json"
+        set_pm_agent_in_index "null"
+        echo "PM agent session destroyed"
+    elif [ "$target" = "--base" ]; then
+        if [ "$force" = false ]; then
+            echo "Warning: Destroying base session will remove ALL sessions." >&2
+            read -p "Continue? [y/N] " -r answer
+            if [[ ! "$answer" =~ ^[Yy]$ ]]; then
+                echo "Aborted."
+                return
+            fi
+        fi
+        
+        for session_file in "$SESSIONS_DIR"/*.json; do
+            [ -f "$session_file" ] || continue
+            rm -f "$session_file"
+        done
+        
+        for worktree in "$WORKTREES_DIR"/.kugetsu-worktrees/*; do
+            if [ -d "$worktree" ]; then
+                git worktree remove "$worktree" 2>/dev/null || rm -rf "$worktree"
+            fi
+        done
+        
+        write_index "null" "null" "{}"
+        echo "Base session and all worktrees destroyed"
+    else
+        validate_issue_ref "$target"
+        
+        local session_file=$(get_session_for_issue "$target")
+        if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
+            echo "Error: No session found for '$target'" >&2
+            exit 1
+        fi
+        
+        local session_path="$SESSIONS_DIR/$session_file"
+        
+        if [ "$force" = true ]; then
+            remove_worktree_for_issue "$target"
+            rm -f "$session_path"
+            remove_issue_from_index "$target"
+            echo "Session for '$target' destroyed"
+        else
+            echo "Warning: This will delete session and worktree for '$target'" >&2
+            read -p "Continue? [y/N] " -r answer
+            if [[ ! "$answer" =~ ^[Yy]$ ]]; then
+                echo "Aborted."
+                return
+            fi
+            
+            remove_worktree_for_issue "$target"
+            rm -f "$session_path"
+            remove_issue_from_index "$target"
+            echo "Session for '$target' destroyed"
+        fi
+    fi
+}
+
+cmd_status() {
+    echo "=== kugetsu status ==="
+    
+    local base_id=$(get_base_session_id)
+    local pm_id=$(get_pm_agent_session_id)
+    
+    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
+        echo "Status: Not initialized"
+        echo "Run 'kugetsu init' to initialize."
+        return
+    fi
+    
+    echo "Base session: $base_id"
+    
+    if [ -n "$pm_id" ] && [ "$pm_id" != "null" ]; then
+        echo "PM agent: $pm_id"
+    else
+        echo "PM agent: not running"
+    fi
+    
+    local active_count=$(count_active_dev_sessions)
+    echo "Active issue sessions: $active_count / ${MAX_CONCURRENT_AGENTS:-3}"
+    
+    echo ""
+    echo "OpenCode sessions:"
+    opencode session list 2>/dev/null || echo "  (unable to list sessions)"
+}
--- a/skills/kugetsu/scripts/kugetsu-worktree.sh
+++ b/skills/kugetsu/scripts/kugetsu-worktree.sh
@@ -0,0 +1,167 @@
+#!/bin/bash
+set -euo pipefail
+
+issue_ref_to_worktree_name() {
+    local issue_ref="$1"
+    echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
+}
+
+issue_ref_to_worktree_path() {
+    local issue_ref="$1"
+    local parent_dir="${2:-$WORKTREES_DIR}"
+    local worktree_name=$(issue_ref_to_worktree_name "$issue_ref")
+    echo "$parent_dir/.kugetsu-worktrees/$worktree_name"
+}
+
+issue_ref_to_branch_name() {
+    local issue_ref="$1"
+    local number_part=$(echo "$issue_ref" | grep -oE '#[0-9]+$' || echo "")
+    if [ -n "$number_part" ]; then
+        echo "fix/issue-${number_part#\#}"
+    else
+        local identifier=$(echo "$issue_ref" | grep -oE '#[^-]+$' || echo "")
+        if [ -n "$identifier" ]; then
+            local clean_id=$(echo "$identifier" | sed 's/^#//' | sed 's/-/_/g')
+            echo "fix/${clean_id}"
+        else
+            echo "fix/issue-temp"
+        fi
+    fi
+}
+
+get_repo_url() {
+    local issue_ref="$1"
+    
+    if [ -f "$REPOS_CONFIG" ]; then
+        local url=$(python3 -c "import json, sys; d=json.load(open('$REPOS_CONFIG')); print(d.get('$issue_ref', ''))" 2>/dev/null || echo "")
+        if [ -n "$url" ]; then
+            echo "$url"
+            return
+        fi
+    fi
+    
+    local instance=$(echo "$issue_ref" | cut -d'/' -f1 | cut -d'#' -f1)
+    local rest=$(echo "$issue_ref" | sed 's/.*\///' | sed 's/#.*//')
+    
+    if [ -n "${GIT_SERVERS[$instance]:-}" ]; then
+        echo "${GIT_SERVERS[$instance]}/${rest}.git"
+        return
+    fi
+    
+    if [ -n "${GIT_SERVERS[$DEFAULT_GIT_SERVER]:-}" ]; then
+        echo "${GIT_SERVERS[$DEFAULT_GIT_SERVER]}/${rest}.git"
+        return
+    fi
+    
+    echo "https://${instance}/${rest}.git"
+}
+
+worktree_exists() {
+    local issue_ref="$1"
+    local parent_dir="${2:-$PWD}"
+    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
+    [ -d "$worktree_path" ]
+}
+
+create_worktree() {
+    local issue_ref="$1"
+    local parent_dir="${2:-$PWD}"
+    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
+    local branch_name=$(issue_ref_to_branch_name "$issue_ref")
+    local repo_url=$(get_repo_url "$issue_ref")
+    
+    if [ -z "$repo_url" ]; then
+        echo "Error: Cannot determine repo URL for '$issue_ref'" >&2
+        echo "Please add to $REPOS_CONFIG or ensure worktree exists" >&2
+        exit 1
+    fi
+    
+    local worktree_parent_dir=$(dirname "$worktree_path")
+    mkdir -p "$worktree_parent_dir"
+    
+    if worktree_exists "$issue_ref" "$parent_dir"; then
+        echo "Removing existing worktree at '$worktree_path'..."
+        git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
+    fi
+    
+    echo "Creating worktree at '$worktree_path'..."
+    git clone "$repo_url" "$worktree_path" 2>/dev/null || {
+        echo "Error: Failed to clone repository" >&2
+        exit 1
+    }
+    
+    echo "Creating branch '$branch_name'..."
+    (cd "$worktree_path" && git checkout -b "$branch_name" origin/main 2>/dev/null || git checkout -b "$branch_name" main 2>/dev/null) || {
+        echo "Warning: Could not checkout branch (may need to run from within worktree after session)" >&2
+    }
+    
+    echo "Worktree created at: $worktree_path"
+}
+
+remove_worktree_for_issue() {
+    local issue_ref="$1"
+    local parent_dir="${2:-$PWD}"
+    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
+    
+    if worktree_exists "$issue_ref" "$parent_dir"; then
+        echo "Removing worktree at '$worktree_path'..."
+        git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
+    fi
+}
+
+get_worktree_path_for_session() {
+    local session_file="$1"
+    if [ -f "$session_file" ]; then
+        python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo ""
+    else
+        echo ""
+    fi
+}
+
+check_pr_status() {
+    local pr_url="$1"
+    
+    if [ -z "$pr_url" ]; then
+        echo "no_pr_url"
+        return 1
+    fi
+    
+    local hostname=$(echo "$pr_url" | sed -E 's|https://([^/]+)/.*|\1|')
+    
+    local server_base="${GIT_SERVERS[$hostname]:-}"
+    if [ -z "$server_base" ]; then
+        echo "unknown_server"
+        return 1
+    fi
+    
+    local api_base="${server_base}/api/v1"
+    
+    local api_url=$(echo "$pr_url" | sed -E 's|https://[^/]+/([^/]+)/([^/]+)/(pulls|merge_requests)/([0-9]+)|'"${api_base}"'/repos/\1/\2/\3/\4|')
+    
+    local token=""
+    if [[ "$hostname" == "github.com" ]]; then
+        token="${GITHUB_TOKEN:-}"
+    else
+        token="${GITEA_TOKEN:-}"
+    fi
+    
+    local response
+    if [ -n "$token" ]; then
+        response=$(curl -s -H "Authorization: token $token" "$api_url" 2>/dev/null || echo "{}")
+    else
+        response=$(curl -s "$api_url" 2>/dev/null || echo "{}")
+    fi
+    
+    local state=$(echo "$response" | python3 -c "import json, sys; d=json.load(sys.stdin); print(d.get('state', 'unknown'))" 2>/dev/null || echo "unknown")
+    local merged=$(echo "$response" | python3 -c "import json, sys; d=json.load(sys.stdin); print('true' if d.get('merged', False) else 'false')" 2>/dev/null || echo "false")
+    
+    if [ "$merged" = "true" ]; then
+        echo "merged"
+    elif [ "$state" = "closed" ]; then
+        echo "closed"
+    elif [ "$state" = "open" ]; then
+        echo "open"
+    else
+        echo "unknown"
+    fi
+}
--- a/skills/kugetsu/tests/test-kugetsu-v2.sh
+++ b/skills/kugetsu/tests/test-kugetsu-v2.sh
@@ -7,6 +7,8 @@
 set -euo pipefail

 KUGETSU="./skills/kugetsu/scripts/kugetsu"
+TEST_KUGETSU_DIR="/tmp/test-kugetsu-$$"
+export KUGETSU_DIR="$TEST_KUGETSU_DIR"
 TEST_ISSUE_REF="github.com/shoko/kugetsu#14"
 TEST_DISCUSS_REF="github.com/shoko/kugetsu#-discuss"
 TEST_BASE_SESSION_ID="ses_test_base_123"
@@ -18,28 +20,28 @@ PASS=0
 FAIL=0

 cleanup() {
-    rm -rf ~/.kugetsu/sessions/* ~/.kugetsu/worktrees/* ~/.kugetsu/index.json 2>/dev/null || true
+    rm -rf "$TEST_KUGETSU_DIR" 2>/dev/null || true
 }

 setup_mock_base() {
-    mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
-    cat > ~/.kugetsu/index.json << EOF
+    mkdir -p "$TEST_KUGETSU_DIR/sessions" "$TEST_KUGETSU_DIR/worktrees"
+    cat > "$TEST_KUGETSU_DIR/index.json" << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": "$TEST_PM_AGENT_SESSION_ID",
  "issues": {}
 }
 EOF
-    cat > ~/.kugetsu/sessions/$TEST_BASE_SESSION_FILE << EOF
+    cat > "$TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE" << EOF
 {"type": "base", "opencode_session_id": "$TEST_BASE_SESSION_ID", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
 EOF
-    cat > ~/.kugetsu/sessions/$TEST_PM_AGENT_SESSION_FILE << EOF
+    cat > "$TEST_KUGETSU_DIR/sessions/$TEST_PM_AGENT_SESSION_FILE" << EOF
 {"type": "pm_agent", "opencode_session_id": "$TEST_PM_AGENT_SESSION_ID", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
 EOF
 }

 setup_mock_forked() {
-    cat > ~/.kugetsu/index.json << EOF
+    cat > "$TEST_KUGETSU_DIR/index.json" << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": "$TEST_PM_AGENT_SESSION_ID",
@@ -48,7 +50,7 @@ setup_mock_forked() {
  }
 }
 EOF
-    cat > ~/.kugetsu/sessions/$TEST_FORKED_SESSION_FILE << EOF
+    cat > "$TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE" << EOF
 {"type": "forked", "issue_ref": "$TEST_ISSUE_REF", "opencode_session_id": "ses_forked_789", "worktree_path": "/tmp/test-worktree", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
 EOF
 }
@@ -112,16 +114,16 @@ echo ""

 # Test 3b: start fails without pm-agent
 echo "--- Test: start without pm-agent session ---"
-rm -f ~/.kugetsu/index.json ~/.kugetsu/sessions/*
-mkdir -p ~/.kugetsu/sessions
-cat > ~/.kugetsu/index.json << EOF
+rm -f $TEST_KUGETSU_DIR/index.json $TEST_KUGETSU_DIR/sessions/*
+mkdir -p $TEST_KUGETSU_DIR/sessions
+cat > $TEST_KUGETSU_DIR/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": null,
  "issues": {}
 }
 EOF
-cat > ~/.kugetsu/sessions/$TEST_BASE_SESSION_FILE << EOF
+cat > $TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE << EOF
 {"type": "base", "opencode_session_id": "$TEST_BASE_SESSION_ID", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
 EOF
 OUTPUT=$($KUGETSU start github.com/shoko/kugetsu#14 "test" 2>&1 || true)
@@ -176,7 +178,7 @@ echo ""

 # Test 6c: index.json has pm_agent field
 echo "--- Test: index.json has pm_agent field ---"
-if grep -q '"pm_agent"' ~/.kugetsu/index.json; then
+if grep -q '"pm_agent"' $TEST_KUGETSU_DIR/index.json; then
    pass "index.json has pm_agent field"
 else
    fail "index.json missing pm_agent field"
@@ -227,12 +229,12 @@ echo ""
 echo "--- Test: destroy --pm-agent -y ---"
 setup_mock_base
 OUTPUT=$($KUGETSU destroy --pm-agent -y 2>&1 || true)
-if [ -f ~/.kugetsu/sessions/$TEST_PM_AGENT_SESSION_FILE ]; then
+if [ -f $TEST_KUGETSU_DIR/sessions/$TEST_PM_AGENT_SESSION_FILE ]; then
    fail "destroy --pm-agent -y removes pm-agent file"
 else
    pass "destroy --pm-agent -y removes pm-agent file"
 fi
-if grep -q '"pm_agent": null' ~/.kugetsu/index.json; then
+if grep -q '"pm_agent": null' $TEST_KUGETSU_DIR/index.json; then
    pass "destroy --pm-agent -y sets pm_agent to null in index"
 else
    fail "destroy --pm-agent -y should set pm_agent to null"
@@ -243,7 +245,7 @@ echo ""
 echo "--- Test: destroy --base -y ---"
 setup_mock_base
 OUTPUT=$($KUGETSU destroy --base -y 2>&1 || true)
-if [ -f ~/.kugetsu/sessions/$TEST_BASE_SESSION_FILE ]; then
+if [ -f $TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE ]; then
    fail "destroy --base -y removes base file"
 else
    pass "destroy --base -y removes base file"
@@ -292,7 +294,7 @@ echo ""

 # Test 15: worktree path in session file
 echo "--- Test: worktree_path in session file ---"
-if grep -q "worktree_path" ~/.kugetsu/sessions/$TEST_FORKED_SESSION_FILE; then
+if grep -q "worktree_path" $TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE; then
    pass "session file contains worktree_path"
 else
    fail "session file missing worktree_path"
@@ -303,7 +305,7 @@ echo ""
 echo "--- Test: prune with orphaned worktree ---"
 cleanup
 setup_mock_base
-mkdir -p ~/.kugetsu/worktrees/orphaned-worktree
+mkdir -p $TEST_KUGETSU_DIR/worktrees/orphaned-worktree
 OUTPUT=$($KUGETSU prune 2>&1 || true)
 if echo "$OUTPUT" | grep -q "orphaned worktree"; then
    pass "prune detects orphaned worktree"
@@ -315,7 +317,7 @@ echo ""
 # Test 17: prune --force removes orphaned worktrees
 echo "--- Test: prune --force removes orphaned worktrees ---"
 OUTPUT=$($KUGETSU prune --force 2>&1 || true)
-if [ -d ~/.kugetsu/worktrees/orphaned-worktree ]; then
+if [ -d $TEST_KUGETSU_DIR/worktrees/orphaned-worktree ]; then
    fail "prune --force should remove orphaned worktree"
 else
    pass "prune --force removes orphaned worktree"
@@ -332,10 +334,10 @@ echo ""
 echo "--- Test: destroy removes worktree ---"
 cleanup
 setup_mock_forked
-# remove_worktree_for_issue derives path from issue ref: ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14
-mkdir -p ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14
+# remove_worktree_for_issue derives path from issue ref: $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
+mkdir -p $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
 OUTPUT=$($KUGETSU destroy github.com/shoko/kugetsu#14 -y 2>&1 || true)
-if [ -d ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14 ]; then
+if [ -d $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14 ]; then
    fail "destroy should remove worktree"
 else
    pass "destroy removes worktree"
@@ -345,7 +347,7 @@ echo ""
 # Test 20: session file properly formatted for v2.2
 echo "--- Test: session file format v2.2 ---"
 setup_mock_forked
-SESSION_CONTENT=$(cat ~/.kugetsu/sessions/$TEST_FORKED_SESSION_FILE)
+SESSION_CONTENT=$(cat $TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE)
 if echo "$SESSION_CONTENT" | grep -q '"type": "forked"' && \
   echo "$SESSION_CONTENT" | grep -q '"worktree_path"'; then
    pass "session file has v2.2 format"
@@ -367,8 +369,8 @@ echo ""

 # Test 22: status when base missing
 echo "--- Test: status (base missing) ---"
-mkdir -p ~/.kugetsu/sessions
-cat > ~/.kugetsu/index.json << EOF
+mkdir -p $TEST_KUGETSU_DIR/sessions
+cat > $TEST_KUGETSU_DIR/index.json << EOF
 {
  "base": null,
  "pm_agent": "$TEST_PM_AGENT_SESSION_ID",
@@ -385,7 +387,7 @@ echo ""

 # Test 23: status when pm-agent missing
 echo "--- Test: status (pm-agent missing) ---"
-cat > ~/.kugetsu/index.json << EOF
+cat > $TEST_KUGETSU_DIR/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": null,
@@ -402,7 +404,7 @@ echo ""

 # Test 24: status when pm-agent is "None" (Python None output)
 echo "--- Test: status (pm-agent is Python None) ---"
-cat > ~/.kugetsu/index.json << EOF
+cat > $TEST_KUGETSU_DIR/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": "None",
@@ -445,8 +447,8 @@ echo ""
 # Test 27: delegate when pm-agent missing
 echo "--- Test: delegate (pm-agent missing) ---"
 cleanup
-mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
-cat > ~/.kugetsu/index.json << EOF
+mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
+cat > $TEST_KUGETSU_DIR/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": null,
@@ -508,7 +510,7 @@ echo ""
 # Test 32: delegate is fire-and-forget (returns immediately)
 echo "--- Test: delegate is fire-and-forget ---"
 setup_mock_base
-mkdir -p ~/.kugetsu/logs
+mkdir -p $TEST_KUGETSU_DIR/logs
 START=$(date +%s)
 OUTPUT=$($KUGETSU delegate "test fire-and-forget" 2>&1 || true)
 END=$(date +%s)
@@ -527,10 +529,10 @@ echo ""
 # Test 33: delegate creates log file
 echo "--- Test: delegate creates log file ---"
 setup_mock_base
-LOG_COUNT_BEFORE=$(ls ~/.kugetsu/logs/*.log 2>/dev/null | wc -l)
+LOG_COUNT_BEFORE=$(ls $TEST_KUGETSU_DIR/logs/*.log 2>/dev/null | wc -l)
 $KUGETSU delegate "test log file" 2>&1 || true
 sleep 1
-LOG_COUNT_AFTER=$(ls ~/.kugetsu/logs/*.log 2>/dev/null | wc -l)
+LOG_COUNT_AFTER=$(ls $TEST_KUGETSU_DIR/logs/*.log 2>/dev/null | wc -l)
 if [ $LOG_COUNT_AFTER -gt $LOG_COUNT_BEFORE ]; then
    pass "delegate creates log file"
 else
@@ -558,10 +560,10 @@ echo ""

 # Test E2: env set creates file
 echo "--- Test: env set creates env file ---"
-mkdir -p ~/.kugetsu/env
-rm -f ~/.kugetsu/env/pm-agent.env
+mkdir -p $TEST_KUGETSU_DIR/env
+rm -f $TEST_KUGETSU_DIR/env/pm-agent.env
 $KUGETSU env set TEST_VAR "test_value" pm-agent 2>&1 || true
-if [ -f ~/.kugetsu/env/pm-agent.env ]; then
+if [ -f $TEST_KUGETSU_DIR/env/pm-agent.env ]; then
    pass "env set creates pm-agent.env file"
 else
    fail "env set did not create pm-agent.env"
@@ -570,7 +572,7 @@ echo ""

 # Test E3: env show masks sensitive values
 echo "--- Test: env show masks sensitive values ---"
-cat > ~/.kugetsu/env/pm-agent.env << 'ENVEOF'
+cat > $TEST_KUGETSU_DIR/env/pm-agent.env << 'ENVEOF'
 export GITEA_TOKEN="secret_token_123"
 export MY_VAR="visible_value"
 ENVEOF
@@ -584,14 +586,14 @@ echo ""

 # Test E4: Variables exported to child processes via set -a
 echo "--- Test: set -a exports variables to children ---"
-mkdir -p ~/.kugetsu/env
-cat > ~/.kugetsu/env/test.env << 'ENVEOF'
+mkdir -p $TEST_KUGETSU_DIR/env
+cat > $TEST_KUGETSU_DIR/env/test.env << 'ENVEOF'
 export EXPORT_TEST="exported_value"
 SIMPLE_TEST="not_exported"
 ENVEOF

 # Simulate what cmd_delegate does
-ENV_FILE="~/.kugetsu/env/test.env"
+ENV_FILE="$TEST_KUGETSU_DIR/env/test.env"
 env_sh="set -a; source '$ENV_FILE'; set +a; "
 result=$(bash -c "${env_sh}bash -c 'echo \$EXPORT_TEST'")

@@ -604,11 +606,11 @@ echo ""

 # Test E5: pm-agent.env takes precedence
 echo "--- Test: pm-agent.env takes precedence over default ---"
-mkdir -p ~/.kugetsu/env
-cat > ~/.kugetsu/env/default.env << 'ENVEOF'
+mkdir -p $TEST_KUGETSU_DIR/env
+cat > $TEST_KUGETSU_DIR/env/default.env << 'ENVEOF'
 export GITEA_TOKEN="default_token"
 ENVEOF
-cat > ~/.kugetsu/env/pm-agent.env << 'ENVEOF'
+cat > $TEST_KUGETSU_DIR/env/pm-agent.env << 'ENVEOF'
 export GITEA_TOKEN="pm_agent_token"
 ENVEOF

@@ -644,7 +646,7 @@ fi
 echo ""

 # Cleanup env files
-rm -rf ~/.kugetsu/env 2>/dev/null || true
+rm -rf $TEST_KUGETSU_DIR/env 2>/dev/null || true

 # Test E7: fix_session_permissions function exists
 echo "--- Test: fix_session_permissions function exists ---"
@@ -736,7 +738,7 @@ PASS=0
 FAIL=0

 test_cleanup() {
-    rm -rf ~/.kugetsu/sessions/* ~/.kugetsu/worktrees/* ~/.kugetsu/index.json ~/.kugetsu/logs/* ~/.kugetsu/.agent_count ~/.kugetsu/.agent_lock 2>/dev/null || true
+    rm -rf $TEST_KUGETSU_DIR/sessions/* $TEST_KUGETSU_DIR/worktrees/* $TEST_KUGETSU_DIR/index.json $TEST_KUGETSU_DIR/logs/* $TEST_KUGETSU_DIR/.agent_count $TEST_KUGETSU_DIR/.agent_lock 2>/dev/null || true
 }

 pass() {
@@ -750,25 +752,25 @@ fail() {
 }

 setup_mock_sessions() {
-    mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees ~/.kugetsu/logs
-    cat > ~/.kugetsu/index.json << INDEX
+    mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees $TEST_KUGETSU_DIR/logs
+    cat > $TEST_KUGETSU_DIR/index.json << INDEX
 {
  "base": "ses_test_base_123",
  "pm_agent": "ses_test_pm_456",
  "issues": {}
 }
 INDEX
-    echo '{"type": "base", "opencode_session_id": "ses_test_base_123", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > ~/.kugetsu/sessions/base.json
-    echo '{"type": "pm_agent", "opencode_session_id": "ses_test_pm_456", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > ~/.kugetsu/sessions/pm-agent.json
+    echo '{"type": "base", "opencode_session_id": "ses_test_base_123", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > $TEST_KUGETSU_DIR/sessions/base.json
+    echo '{"type": "pm_agent", "opencode_session_id": "ses_test_pm_456", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > $TEST_KUGETSU_DIR/sessions/pm-agent.json
 }

 # Test C1: Agent count file is initialized to 0
 echo "--- Test: agent count file initialized ---"
 test_cleanup
-mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
+mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
 $KUGETSU list > /dev/null 2>&1 || true
-if [ -f ~/.kugetsu/.agent_count ]; then
-    COUNT=$(cat ~/.kugetsu/.agent_count)
+if [ -f $TEST_KUGETSU_DIR/.agent_count ]; then
+    COUNT=$(cat $TEST_KUGETSU_DIR/.agent_count)
    if [ "$COUNT" = "0" ]; then
        pass "agent count file initialized to 0"
    else
@@ -795,10 +797,10 @@ test_cleanup
 setup_mock_sessions

 # Initialize count to 0
-echo 0 > ~/.kugetsu/.agent_count
+echo 0 > $TEST_KUGETSU_DIR/.agent_count

 # Verify initial state
-INITIAL=$(cat ~/.kugetsu/.agent_count)
+INITIAL=$(cat $TEST_KUGETSU_DIR/.agent_count)
 if [ "$INITIAL" = "0" ]; then
    pass "agent count starts at 0"
 else
@@ -809,7 +811,7 @@ fi
 $KUGETSU list > /dev/null 2>&1

 # Verify count is still 0 (no slot leak)
-AFTER=$(cat ~/.kugetsu/.agent_count)
+AFTER=$(cat $TEST_KUGETSU_DIR/.agent_count)
 if [ "$AFTER" = "0" ]; then
    pass "agent count stays 0 after list (no leak)"
 else
Author	SHA1	Message	Date
shokollm	59f6a4883e	fix(kugetsu): remove duplicate update_queue_item_state to use fixed version from kugetsu-index.sh The main kugetsu script had its own update_queue_item_state() definition with broken os.system() calls that overwrote the fixed version in kugetsu-index.sh. Now kugetsu will use the fixed version from kugetsu-index.sh (which sources kugetsu-log.sh) since that module is sourced first. Fixes #170	2026-04-06 00:40:55 +00:00
shoko	9667c3e800	Merge pull request 'fix(kugetsu-index): call kugetsu_add_notification from bash instead of os.system()' (#169 ) from fix/issue-167-notification-bash into main	2026-04-06 02:35:36 +02:00
shokollm	796e1fe454	fix(kugetsu-index): call kugetsu_add_notification from bash instead of os.system() os.system() spawns a new subprocess that cannot access bash functions. Now calling kugetsu_add_notification directly from bash after Python updates JSON. Fixes #167	2026-04-06 00:33:35 +00:00
shoko	84c59a3b64	Merge pull request 'fix(kugetsu): queue daemon improvements - locking, error handling, cmd_delegate enqueue' (#164 ) from fix/issue-156-queue-fixes into main	2026-04-06 02:06:36 +02:00
shokollm	dc9d4d7327	Merge origin/main into fix/issue-156-queue-fixes	2026-04-06 00:02:47 +00:00
shokollm	bdcb7a476c	fix(queue-daemon): add locking, proper state updates, and error handling - Add acquire_lock/release_lock to prevent daemon vs manual conflicts - Check cmd_start/cmd_continue success before updating state to 'notified' - Set state to 'error' if command fails - Track actual session_id from session file after cmd_start completes - Release lock when task completes (success or error) - Use load_agent_env 'pm-agent' for GITEA_TOKEN Fixes critical race conditions and failure handling in queue processing	2026-04-06 00:01:41 +00:00
shoko	77cf817568	Merge pull request 'fix(kugetsu): return proper JSON array from get_pending_tasks()' (#163 ) from fix/issue-155-queue-list-json into main	2026-04-06 01:45:09 +02:00
shokollm	0f6a30f01c	fix(kugetsu): return proper JSON array from get_pending_tasks()	2026-04-05 23:43:52 +00:00
shoko	77b0963fa4	Merge pull request 'fix(queue-daemon): source pm-agent.env for GITEA_TOKEN instead of default.env' (#162 ) from fix/issue-160-gitea-token-from-pm-agent into main	2026-04-06 01:42:04 +02:00
shokollm	f39e39156a	fix(queue-daemon): source pm-agent.env for GITEA_TOKEN instead of default.env	2026-04-05 23:38:07 +00:00
shokollm	5a0a54898b	fix(kugetsu): kugetsu-session.sh needs to source required modules When daemon sources kugetsu-session.sh to call cmd_start/cmd_continue, it needs access to functions from kugetsu-config.sh, kugetsu-index.sh, kugetsu-worktree.sh, and kugetsu-log.sh. Add sourcing at top of kugetsu-session.sh.	2026-04-05 22:20:49 +00:00
shokollm	b1028a6556	fix(kugetsu): move queue functions to kugetsu-index.sh for daemon access The daemon (kugetsu-queue-daemon.sh) sources kugetsu-index.sh but not the main kugetsu script. Move update_queue_item_state and kugetsu_add_notification to kugetsu-index.sh so the daemon can use these functions when processing tasks.	2026-04-05 22:17:59 +00:00
shokollm	270219873f	fix(kugetsu): cmd_delegate should enqueue instead of calling cmd_start When cmd_delegate detects an issue ref with number (e.g. git.fbrns.co/shoko/kugetsu#158), it was calling cmd_start directly which tries to create worktree and clone. This breaks the queue-based workflow where daemon should handle task execution. Now cmd_delegate calls enqueue_task to add to queue, and daemon processes tasks by calling cmd_start/cmd_continue as appropriate.	2026-04-05 22:05:18 +00:00
shoko	deb18f1e32	Merge pull request 'fix(kugetsu): queue daemon runs PM agent in correct worktree with proper token' (#157 ) from fix/issue-156 into main	2026-04-05 23:39:35 +02:00
shokollm	cbfc8a0646	refactor(kugetsu): daemon uses cmd_start/cmd_continue instead of direct opencode calls - Move issue_ref_to_filename and filename_to_issue_ref to kugetsu-index.sh (where they logically belong, instead of in main kugetsu script) - Refactor queue daemon to use cmd_start/cmd_continue for session management - Daemon now checks if worktree/session exists → cmd_continue, else → cmd_start - Removes ~40 lines of direct opencode session forking logic from daemon - cmd_start/cmd_continue handle worktree creation, session forking, and tracking This simplifies the daemon significantly and centralizes session management in kugetsu-session.sh where it belongs.	2026-04-05 21:29:34 +00:00
shokollm	7fa669b4c3	fix(kugetsu): queue daemon runs PM agent in correct worktree with proper token - Load GITEA_TOKEN from ~/.kugetsu/env/default.env at daemon startup - Use --fork --session --dir instead of --continue to run in correct directory - Create worktree if it doesn't exist for the issue - Track forked session ID (not parent pm_session) for completion detection - Forked session ends when task completes, parent pm_session continues Fixes #156	2026-04-05 20:57:51 +00:00
shoko	acb503471d	Merge pull request 'fix(kugetsu): detect task completion and queue state updates' (#154 ) from fix/issue-150 into main	2026-04-05 15:10:48 +02:00
shokollm	1d4f190d97	fix(kugetsu): pass GITEA_TOKEN via env to subprocess instead of hardcoded value	2026-04-05 13:09:08 +00:00
shokollm	ab0c4e1448	fix: detect task completion by checking if session ended and has commits	2026-04-05 12:45:59 +00:00
shokollm	9bb8afe8c5	Merge origin/main into fix/issue-148-test-suite-index-corruption (fix CONTRIBUTING.md conflict)	2026-04-05 12:24:02 +00:00
shokollm	fd7a98b263	fix: validate sessions in cmd_status + use isolated test environment 1. cmd_status now validates session IDs against opencode session list - Reports 'error: base session X not found in opencode' if missing - Reports 'error: pm_agent session X not found in opencode' if missing 2. Test suite now uses isolated KUGETSU_DIR=/tmp/test-kugetsu-$$ - All tests use separate test directory instead of ~/.kugetsu - Prevents test suite from corrupting real user data - Cleanup removes test directory entirely Fixes #148	2026-04-05 12:10:55 +00:00
shoko	3942a915ff	Merge pull request 'refactor: modularize kugetsu shell script' (#151 ) from fix/issue-116-modularize-script into main	2026-04-05 12:58:48 +02:00
shokollm	1886c4a9c5	Merge origin/main into fix/issue-116-modularize-script (fix leftover conflict markers)	2026-04-05 10:57:46 +00:00
shoko	5052e4ae36	Merge pull request 'fix: add support for gitserver/owner/repo#number issue ref format' (#152 ) from fix/issue-144-parse-issue-ref-format-v2 into main	2026-04-05 12:45:18 +02:00
shoko	fb9cc72f44	Merge pull request 'docs: add versioning policy, changelog, and update contributing guide' (#149 ) from fix/issue-120 into main	2026-04-05 12:44:43 +02:00
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	d0b100fca8	fix: add support for gitserver/owner/repo#number issue ref format Add third pattern to parse_issue_ref_from_message() to support the mixed format 'gitserver/owner/repo#number' (e.g., git.fbrns.co/shoko/kugetsu#116). Previously only two formats were supported: 1. Full URL: #116 2. Short format: shoko/kugetsu#116 Now supports: 3. Mixed format: git.fbrns.co/shoko/kugetsu#116 Fixes #144	2026-04-05 10:22:31 +00:00
shokollm	f61fbd6dd5	refactor: modularize kugetsu shell script Split the monolithic kugetsu script into modular components: Modules created: - kugetsu-config.sh - Config/env loading and global variables - kugetsu-index.sh - Index.json read/write via JSON - kugetsu-worktree.sh - Git worktree operations - kugetsu-log.sh - Structured logging and notifications - kugetsu-session.sh - Session create/fork/destroy logic - kugetsu-queue-daemon.sh - Queue daemon subprocess Main script (kugetsu) is now a thin dispatcher that sources all modules. Acceptance Criteria: - All existing commands work exactly as before - Main script sources modules - Each module is independently testable Fixes #116	2026-04-05 10:17:25 +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
shokollm	61f06f825f	Add context dump/load feature Adds session context management to prevent session poisoning: - CONTEXT_DIR and ENABLE_CONTEXT_DUMP config options - issue_ref_to_context_file() - derive context file path - kugetsu_context_load() - load previous context - kugetsu_context_dump() - save context on session start - kugetsu_context_update_message() - append to conversation history - Integration in cmd_start and cmd_continue - New 'kugetsu context' command	2026-04-05 04:23:26 +00:00
shoko	b76a9b883a	Merge pull request 'feat(worktree-lifecycle): add PR tracking and safe destroy' (#138 ) from feat/worktree-lifecycle into main	2026-04-05 06:00:15 +02:00
shokollm	ac850869fd	fix(worktree-lifecycle): use github.com as example in set-pr help - Remove accidentally committed worktree directory	2026-04-05 03:56:48 +00:00
shokollm	3107dbf1e5	fix(worktree-lifecycle): use GIT_SERVERS config for check_pr_status - Extract hostname from pr_url instead of hardcoding domains - Look up server base URL from GIT_SERVERS config - Append /api/v1 to derive API URL (configurable per server) - Works with any server configured in GIT_SERVERS	2026-04-05 03:41:41 +00:00
shokollm	b8b97e3c09	fix(worktree-lifecycle): address PR review feedback - Rename update-pr to set-pr for clarity (it's setting the PR URL, not updating PR) - Add optional pr-url argument to kugetsu start command Usage: kugetsu start <issue-ref> <message> [pr-url] - If pr-url is provided at start, it's stored directly in session file	2026-04-05 03:16:05 +00:00
shokollm	d8af560e6d	feat(worktree-lifecycle): add PR tracking and safe destroy - Add WORKTREE_CHECK_PR_STATUS config (default: true) - Add pr_url and branch_name fields to session files - Add check_pr_status() to query PR status via API (Gitea/GitHub) - Add update_session_pr_url() to update PR URL in session - Add kugetsu update-pr command to set PR URL - Modify cmd_destroy to check PR status before destroying worktree Closes #135	2026-04-05 02:50:09 +00:00
shoko	5d12f6ca42	Merge pull request 'feat(kugetsu): smart delegate with worktree awareness' (#130 ) from feature/smart-delegate-worktree-awareness into main	2026-04-03 16:31:30 +02:00