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

.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

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` for reviewable changes
 5. After approval, squash and merge
 
 ## Guidelines
@@ -17,7 +17,10 @@
 
 ## Branches
 
-- `master` — stable, reviewed content only
+- `main` — stable, reviewed content only
+- `develop` — experimental work for 0.2.x
 - `fix/*` — bug fixes
+- `feat/*` — new features
 - `docs/*` — documentation updates
+- `refactor/*` — refactoring
 - `research/*` — new research notes

skills/kugetsu/SKILL.md

@@ -50,7 +50,6 @@ A default config file is created during `kugetsu init` with commented examples:
 | `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_DAEMON_BATCH_SIZE` | 2 | How many tasks daemon picks per poll |
 | `QUEUE_CLEANUP_AGE_DAYS` | 7 | Auto-cleanup completed/error items older than N days |
 
 ### Environment Variables for Agents

skills/kugetsu/scripts/kugetsu

@@ -23,7 +23,6 @@ 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_DAEMON_BATCH_SIZE="${QUEUE_DAEMON_BATCH_SIZE:-2}"
 QUEUE_CLEANUP_AGE_DAYS="${QUEUE_CLEANUP_AGE_DAYS:-7}"
 TASK_TIMEOUT_HOURS="${TASK_TIMEOUT_HOURS:-1}"
 
@@ -63,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
@@ -532,6 +531,8 @@ with open("$QUEUE_ITEMS_DIR/${queue_id}.json", "w") as f:
 
 print(f"Enqueued: $queue_id")
 PYEOF
+
+    kugetsu_add_notification "task_queued" "Task queued: $issue_ref" "$issue_ref"
 }
 
 get_pending_tasks() {
@@ -588,6 +589,7 @@ update_queue_item_state() {
     
     python3 << PYEOF
 import json
+import os
 from datetime import datetime
 
 item_file = "$item_file"
@@ -598,6 +600,8 @@ 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":
@@ -608,8 +612,10 @@ if new_state == "notified":
         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)
@@ -1069,6 +1075,18 @@ cmd_status() {
         return
     fi
     
+    local opencode_sessions=$(opencode session list 2>/dev/null | grep -oP '^ses_\w+' || true)
+    
+    if ! echo "$opencode_sessions" | grep -q "^${base}$"; then
+        echo "error: base session '$base' not found in opencode"
+        return
+    fi
+    
+    if ! echo "$opencode_sessions" | grep -q "^${pm_agent}$"; then
+        echo "error: pm_agent session '$pm_agent' not found in opencode"
+        return
+    fi
+    
     echo "ok"
 }
 
@@ -1139,6 +1157,11 @@ parse_issue_ref_from_message() {
         owner=$(echo "$full_path" | cut -d'/' -f2)
         repo=$(echo "$full_path" | cut -d'/' -f3)
         issue_number=$(echo "$full_path" | grep -oE '[0-9]+$' | head -1)
+    elif echo "$message" | grep -qE '[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#[0-9]+'; then
+        gitserver=$(echo "$message" | grep -oE '[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+' | head -1)
+        owner=$(echo "$gitserver" | cut -d'/' -f2)
+        repo=$(echo "$gitserver" | cut -d'/' -f3)
+        issue_number=$(echo "$message" | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | head -1)
     elif echo "$message" | grep -qE '[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#([0-9]+)'; then
         owner=$(echo "$message" | grep -oE '[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#' | sed 's/#$//' | cut -d'/' -f1)
         repo=$(echo "$message" | grep -oE '[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#' | sed 's/#$//' | cut -d'/' -f2)
@@ -1366,22 +1389,15 @@ process_queue() {
     fi
     
     local available_slots=$((MAX_CONCURRENT_AGENTS - active_count))
-    local batch_size=$QUEUE_DAEMON_BATCH_SIZE
-    [ "$batch_size" -gt "$available_slots" ] && batch_size=$available_slots
     
-    if [ "$batch_size" -le 0 ]; then
+    if [ "$available_slots" -le 0 ]; then
-        return
-    fi
-    
-    local pm_session=$(get_pm_agent_session_id)
-    if [ -z "$pm_session" ] || [ "$pm_session" = "null" ]; 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
-        [ $count -ge "$batch_size" ] && break
         
         local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
         if [ "$state" != "pending" ]; then
@@ -1389,33 +1405,49 @@ process_queue() {
         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 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)
+        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 env_sh="set -a; "
+        local max_retries=3
-        if [ -f "$ENV_DIR/pm-agent.env" ]; then
+        local attempt=1
-            env_sh="${env_sh}source '$ENV_DIR/pm-agent.env'; "
+        local success=false
-        elif [ -f "$ENV_DIR/default.env" ]; then
+        local fork_pid=""
-            env_sh="${env_sh}source '$ENV_DIR/default.env'; "
+        
+        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
-        env_sh="${env_sh}set +a; "
-        
-        nohup sh -c "${env_sh}opencode run 'Delegate task: ${message}' --continue --session '$pm_session'" >> "$log_file" 2>&1 &
-        local fork_pid=$!
-        
-        update_queue_item_state "$queue_id" "notified" "" "$fork_pid"
-        
-        echo "Queued task $queue_id for PM agent (PID: $fork_pid)"
-        count=$((count + 1))
     done
 }
 
@@ -2061,20 +2093,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"
     
@@ -2087,25 +2109,38 @@ ${previous_context}
 ## YOUR TASK
 $message"
     
-    fix_session_permissions
+    (
-    
+        flock -x $lock_fd
-    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 "
+        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()
@@ -2114,31 +2149,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
+            if [ -n "$new_session_id" ] && [ "$new_session_id" != "$base_session_id" ] && [ "$new_session_id" != "$pm_agent_session_id" ]; then
-            break
+                break
-        fi
+            fi
-        
+            
-        if ! kill -0 $fork_pid 2>/dev/null; then
+            if ! kill -0 $fork_pid 2>/dev/null; then
-            fork_log_output=$(tail -20 "$fork_log" 2>/dev/null || echo "(log empty or unavailable)")
+                fork_log_output=$(tail -20 "$fork_log" 2>/dev/null || echo "(log empty or unavailable)")
-            break
+                break
-        fi
+            fi
-        
+            
-        attempt=$((attempt + 1))
+            attempt=$((attempt + 1))
-    done
+        done
 
-    if [ -z "$new_session_id" ]; then
+        if [ -z "$new_session_id" ]; then
-        echo "Error: Could not find newly created session after ${max_attempts}s" >&2
+            echo "Error: Could not find newly created session after ${max_attempts}s" >&2
-        if [ -n "$fork_log_output" ]; then
+            if [ -n "$fork_log_output" ]; then
-            echo "Fork log output:" >&2
+                echo "Fork log output:" >&2
-            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"
+        echo "Updating permissions for new session: $new_session_id"
-    python3 -c "
+        python3 -c "
 import sqlite3
 conn = sqlite3.connect('$opencode_db')
 cursor = conn.cursor()
@@ -2148,9 +2183,9 @@ conn.commit()
 print('[OK] Session permissions updated')
 "
 
-    if [ "$DEBUG_MODE" = true ]; then
+        if [ "$DEBUG_MODE" = true ]; then
-        echo "[DEBUG] Forked session permissions check:"
+            echo "[DEBUG] Forked session permissions check:"
-        python3 -c "
+            python3 -c "
 import sqlite3
 conn = sqlite3.connect('$opencode_db')
 cursor = conn.cursor()
@@ -2160,11 +2195,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")
+        local branch_name=$(issue_ref_to_branch_name "$issue_ref")
-    
+        
-    python3 << PYEOF > "$SESSIONS_DIR/$session_file"
+        python3 << PYEOF > "$SESSIONS_DIR/$session_file"
 import json
 
 session = {
@@ -2182,12 +2217,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"
+        add_issue_to_index "$issue_ref" "$session_file"
-    
+        
-    kugetsu_context_dump "$issue_ref" "$message" "$branch_name"
+        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 "Session started for '$issue_ref': $new_session_id"
-    echo "Worktree: $worktree_path"
+        echo "Worktree: $worktree_path"
+    ) 200>"$lock_file"
 }
 
 cmd_continue() {

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
+    mkdir -p "$TEST_KUGETSU_DIR/sessions" "$TEST_KUGETSU_DIR/worktrees"
-    cat > ~/.kugetsu/index.json << EOF
+    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/*
+rm -f $TEST_KUGETSU_DIR/index.json $TEST_KUGETSU_DIR/sessions/*
-mkdir -p ~/.kugetsu/sessions
+mkdir -p $TEST_KUGETSU_DIR/sessions
-cat > ~/.kugetsu/index.json << EOF
+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
+# remove_worktree_for_issue derives path from issue ref: $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
-mkdir -p ~/.kugetsu/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
+mkdir -p $TEST_KUGETSU_DIR/sessions
-cat > ~/.kugetsu/index.json << EOF
+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
+mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
-cat > ~/.kugetsu/index.json << EOF
+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
+mkdir -p $TEST_KUGETSU_DIR/env
-rm -f ~/.kugetsu/env/pm-agent.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
+mkdir -p $TEST_KUGETSU_DIR/env
-cat > ~/.kugetsu/env/test.env << 'ENVEOF'
+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
+mkdir -p $TEST_KUGETSU_DIR/env
-cat > ~/.kugetsu/env/default.env << 'ENVEOF'
+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
+    mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees $TEST_KUGETSU_DIR/logs
-    cat > ~/.kugetsu/index.json << INDEX
+    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": "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"}' > ~/.kugetsu/sessions/pm-agent.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
+if [ -f $TEST_KUGETSU_DIR/.agent_count ]; then
-    COUNT=$(cat ~/.kugetsu/.agent_count)
+    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