Merge pull request 'fix: remove doubled .kugetsu-worktrees path segment in issue_ref_to_worktree_path' (#180) from fix/issue-179-worktree-path-doubled into main

Fixes #179 - cmd_start fails due to incorrect worktree path being created
with .kugetsu-worktrees/.kugetsu-worktrees/ instead of just the worktree name.

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

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

docs/CHANGELOG.md

@@ -0,0 +1,130 @@
+# 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.4] - 2026-04-06
+
+### Fixed
+- Queue daemon: Locking to prevent daemon vs manual conflicts
+- Queue daemon: Proper error handling for failed tasks
+- Queue daemon: Fix GITEA_TOKEN loading from pm-agent.env
+- cmd_delegate: Enqueue tasks instead of bypassing queue
+- Notifications: Call kugetsu_add_notification from bash instead of os.system()
+- kugetsu: Remove duplicate update_queue_item_state that overwrote fixed version
+
+### Added
+- Queue functions moved to kugetsu-index.sh for daemon access
+- kugetsu-session.sh sources required modules for daemon use
+
+## [v0.2.3] - 2026-04-06
+
+### Fixed
+- get_pending_tasks() returns proper JSON array instead of concatenated JSON objects
+
+## [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

skills/kugetsu/scripts/kugetsu

@@ -93,23 +93,16 @@ EOF
 
 ensure_dirs() {
     mkdir -p "$SESSIONS_DIR"
+    mkdir -p "$LOGS_DIR"
+    mkdir -p "$WORKTREES_DIR"
+    mkdir -p "$QUEUE_DIR"
+    mkdir -p "$QUEUE_ITEMS_DIR"
 }
 
 ensure_worktree_dir() {
     mkdir -p "$WORKTREES_DIR"
 }
 
-issue_ref_to_filename() {
-    local issue_ref="$1"
-    echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
-}
-
-filename_to_issue_ref() {
-    local filename="$1"
-    local name="${filename%.json}"
-    echo "$name" | sed 's/-\([0-9]*\)$/#\1/' | sed 's/-/\//g'
-}
-
 issue_ref_to_context_file() {
     local issue_ref="$1"
     local context_filename=$(issue_ref_to_filename "$issue_ref")
@@ -268,7 +261,9 @@ PYEOF
 }
 
 ensure_queue_dirs() {
+    mkdir -p "$QUEUE_DIR"
     mkdir -p "$QUEUE_ITEMS_DIR"
+    mkdir -p "$LOGS_DIR"
 }
 
 generate_queue_id() {
@@ -321,12 +316,31 @@ get_pending_tasks() {
         return
     fi
     
-    find "$QUEUE_ITEMS_DIR" -name "*.json" -type f 2>/dev/null | while read -r file; do
-        local state=$(python3 -c "import json; print(json.load(open('$file')).get('state', ''))" 2>/dev/null || echo "")
-        if [ "$state" = "pending" ]; then
-            cat "$file"
-        fi
-    done | head -"$limit"
+    python3 -c "
+import json
+import os
+import sys
+
+queue_dir = os.environ.get('QUEUE_ITEMS_DIR', '')
+limit = int(sys.argv[1]) if len(sys.argv) > 1 else 10
+
+items = []
+if os.path.isdir(queue_dir):
+    for filename in os.listdir(queue_dir):
+        if filename.endswith('.json'):
+            filepath = os.path.join(queue_dir, filename)
+            try:
+                with open(filepath) as f:
+                    data = json.load(f)
+                    if data.get('state') == 'pending':
+                        items.append(data)
+                        if len(items) >= limit:
+                            break
+            except:
+                pass
+
+print(json.dumps(items))
+" "$limit"
 }
 
 get_queue_stats() {
@@ -353,55 +367,6 @@ get_queue_stats() {
     echo "{\"total\": $total, \"pending\": $pending, \"notified\": $notified, \"completed\": $completed, \"error\": $error}"
 }
 
-update_queue_item_state() {
-    local queue_id="$1"
-    local new_state="$2"
-    local session_id="${3:-}"
-    local pid="${4:-}"
-    
-    local item_file="$QUEUE_ITEMS_DIR/${queue_id}.json"
-    if [ ! -f "$item_file" ]; then
-        echo "Error: Queue item not found: $queue_id" >&2
-        return 1
-    fi
-    
-    python3 << PYEOF
-import json
-import os
-from datetime import datetime
-
-item_file = "$item_file"
-new_state = "$new_state"
-session_id = "$session_id"
-pid = "$pid"
-
-with open(item_file, 'r') as f:
-    item = json.load(f)
-
-issue_ref = item.get('issue_ref', '')
-
-item['state'] = new_state
-
-if new_state == "notified":
-    item['notified_at'] = datetime.now().isoformat() + "Z"
-    if session_id:
-        item['opencode_session_id'] = session_id
-    if pid:
-        item['pid'] = int(pid) if pid.isdigit() else None
-elif new_state == "completed":
-    item['completed_at'] = datetime.now().isoformat() + "Z"
-    os.system(f"kugetsu_add_notification 'task_completed' 'Task completed: {issue_ref}' '{issue_ref}'")
-elif new_state == "error":
-    item['error'] = datetime.now().isoformat() + "Z"
-    os.system(f"kugetsu_add_notification 'task_error' 'Task error: {issue_ref}' '{issue_ref}'")
-
-with open(item_file, 'w') as f:
-    json.dump(item, f, indent=2)
-
-print(f"Updated $queue_id to state: $new_state")
-PYEOF
-}
-
 check_task_timeouts() {
     if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
         return
@@ -447,6 +412,549 @@ check_task_timeouts() {
     done
 }
 
+cleanup_old_queue_items() {
+    local days="${QUEUE_CLEANUP_AGE_DAYS:-7}"
+    
+    if [ ! -d "$QUEUE_ITEMS_DIR" ]; then
+        return
+    fi
+    
+    find "$QUEUE_ITEMS_DIR" -name "*.json" -type f -mtime "+$days" 2>/dev/null | while read -r file; do
+        local state=$(python3 -c "import json; print(json.load(open('$file')).get('state', ''))" 2>/dev/null || echo "")
+        if [ "$state" = "completed" ] || [ "$state" = "error" ]; then
+            rm -f "$file"
+            echo "Cleaned up: $(basename "$file")"
+        fi
+    done
+}
+update_session_pr_url() {
+    local issue_ref="$1"
+    local pr_url="$2"
+    
+    if [ -z "$issue_ref" ] || [ -z "$pr_url" ]; then
+        echo "Error: update_session_pr_url requires <issue-ref> and <pr-url>" >&2
+        return 1
+    fi
+    
+    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 to: {pr_url}")
+PYEOF
+}
+
+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['issues'].get('$issue_ref') or '')"
+}
+
+set_base_in_index() {
+    local base_session_id="$1"
+    local pm_agent=$(get_pm_agent_session_id)
+    local issues_json=$(read_index | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d['issues']))")
+    if [ -z "$pm_agent" ] || [ "$pm_agent" = "null" ]; then
+        write_index "\"$base_session_id\"" "null" "$issues_json"
+    else
+        write_index "\"$base_session_id\"" "\"$pm_agent\"" "$issues_json"
+    fi
+}
+
+set_pm_agent_in_index() {
+    local pm_agent_session_id="$1"
+    local base=$(get_base_session_id)
+    local issues_json=$(read_index | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d['issues']))")
+    if [ -z "$base" ] || [ "$base" = "null" ]; then
+        write_index "null" "\"$pm_agent_session_id\"" "$issues_json"
+    else
+        write_index "\"$base\"" "\"$pm_agent_session_id\"" "$issues_json"
+    fi
+}
+
+add_issue_to_index() {
+    local issue_ref="$1"
+    local session_file="$2"
+    local index=$(read_index)
+    local base=$(get_base_session_id)
+    local pm_agent=$(get_pm_agent_session_id)
+    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d['issues']))")
+    local new_issues=$(echo "$issues" | python3 -c "import sys, json; d=json.load(sys.stdin); d['$issue_ref']='$session_file'; print(json.dumps(d))")
+    if [ -z "$base" ] || [ "$base" = "null" ]; then
+        if [ -z "$pm_agent" ] || [ "$pm_agent" = "null" ]; then
+            write_index "null" "null" "$new_issues"
+        else
+            write_index "null" "\"$pm_agent\"" "$new_issues"
+        fi
+    else
+        if [ -z "$pm_agent" ] || [ "$pm_agent" = "null" ]; then
+            write_index "\"$base\"" "null" "$new_issues"
+        else
+            write_index "\"$base\"" "\"$pm_agent\"" "$new_issues"
+        fi
+    fi
+}
+
+remove_issue_from_index() {
+    local issue_ref="$1"
+    local index=$(read_index)
+    local base=$(get_base_session_id)
+    local pm_agent=$(get_pm_agent_session_id)
+    local new_issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); d['issues'].pop('$issue_ref', None); print(json.dumps(d['issues']))")
+    if [ -z "$base" ] || [ "$base" = "null" ]; then
+        if [ -z "$pm_agent" ] || [ "$pm_agent" = "null" ]; then
+            write_index "null" "null" "$new_issues"
+        else
+            write_index "null" "\"$pm_agent\"" "$new_issues"
+        fi
+    else
+        if [ -z "$pm_agent" ] || [ "$pm_agent" = "null" ]; then
+            write_index "\"$base\"" "null" "$new_issues"
+        else
+            write_index "\"$base\"" "\"$pm_agent\"" "$new_issues"
+        fi
+    fi
+}
+
+validate_issue_ref() {
+    local issue_ref="$1"
+    if [[ ! "$issue_ref" =~ ^[^/]+/[^/]+/[^#]+#[0-9]+$ ]]; then
+        echo "Error: invalid issue ref format" >&2
+        echo "Expected: instance/user/repo#number" >&2
+        echo "Example: github.com/shoko/kugetsu#14" >&2
+        exit 1
+    fi
+}
+
+check_opencode_session_exists() {
+    local session_id="$1"
+    opencode session list --format json 2>/dev/null | grep -q "\"$session_id\""
+}
+
+kugetsu_get_pm_context() {
+    local user_pm_context="${KUGETSU_DIR}/pm-agent.md"
+    local skill_pm_context="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../pm/SKILL.md"
+    
+    if [ -f "$user_pm_context" ]; then
+        cat "$user_pm_context"
+    elif [ -f "$skill_pm_context" ]; then
+        cat "$skill_pm_context"
+    else
+        echo ""
+    fi
+}
+
+kugetsu_get_fork_context() {
+    local issue_ref="$1"
+    local context=""
+    
+    context="## IMPORTANT WORKING RULES
+
+1. You are working on issue: $issue_ref
+2. If you encounter ANY error, blocker, or cannot complete the task:
+   - STOP immediately
+   - Log what happened and why you cannot proceed
+   - Do NOT switch to other work or try alternative approaches
+3. Do NOT work on other issues or PRs unless explicitly asked
+4. Environment variables are available in ~/.kugetsu/env/
+
+"
+    
+    if [ -f "$REPOS_CONFIG" ]; then
+        context="${context}
+## REPOSITORIES CONFIG
+$(cat "$REPOS_CONFIG")
+
+"
+    fi
+    
+    if [ -f "$ENV_DIR/default.env" ]; then
+        context="${context}
+## ENVIRONMENT (available at ~/.kugetsu/env/)
+Environment file exists at: $ENV_DIR/default.env
+Source it with: source ~/.kugetsu/env/default.env
+"
+    fi
+    
+    echo "$context"
+}
+
+kugetsu_add_notification() {
+    local type="$1"
+    local message="$2"
+    local issue_ref="${3:-}"
+    local gitea_url="${4:-}"
+    
+    mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
+    
+    local notification=$(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
+)
+    echo "$notification"
+}
+
+kugetsu_get_notifications() {
+    local limit="${1:-10}"
+    
+    if [ ! -f "$NOTIFICATIONS_FILE" ]; then
+        echo "[]"
+        return
+    fi
+    
+    python3 << PYEOF
+import json
+import os
+from datetime import datetime
+
+file_path = os.path.expanduser("$NOTIFICATIONS_FILE")
+
+if not os.path.exists(file_path):
+    print("[]")
+    exit(0)
+
+try:
+    with open(file_path, 'r') as f:
+        notifications = json.load(f)
+    
+    unread = [n for n in notifications if not n.get("read", False)]
+    unread.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+    
+    for n in unread[:$limit]:
+        ts = n.get("timestamp", "unknown")
+        ntype = n.get("type", "info")
+        msg = n.get("message", "")
+        issue = n.get("issue_ref", "")
+        gitea = n.get("gitea_url", "")
+        
+        print(f"[{ts}] {ntype}: {msg}")
+        if issue:
+            print(f"  Issue: {issue}")
+        if gitea:
+            print(f"  Link: {gitea}")
+        print()
+    
+    if not unread:
+        print("No unread notifications.")
+    
+except Exception as e:
+    print(f"Error reading notifications: {e}")
+PYEOF
+}
+
+kugetsu_clear_notifications() {
+    if [ ! -f "$NOTIFICATIONS_FILE" ]; then
+        return
+    fi
+    
+    python3 << PYEOF
+import json
+import os
+
+file_path = os.path.expanduser("$NOTIFICATIONS_FILE")
+
+if not os.path.exists(file_path):
+    exit(0)
+
+try:
+    with open(file_path, 'r') as f:
+        notifications = json.load(f)
+    
+    for n in notifications:
+        n["read"] = True
+    
+    with open(file_path, 'w') as f:
+        json.dump(notifications, f, indent=2)
+    
+    print("Notifications marked as read")
+except Exception as e:
+    print(f"Error: {e}")
+PYEOF
+}
+
+cmd_notify() {
+    local action="${1:-}"
+    
+    case "$action" in
+        ""|"list"|"show")
+            kugetsu_get_notifications 10
+            ;;
+        "clear")
+            kugetsu_clear_notifications
+            ;;
+        *)
+            echo "Usage: kugetsu notify [list|clear]"
+            ;;
+    esac
+}
+
+cmd_status() {
+    if [ ! -f "$INDEX_FILE" ]; then
+        echo "kugetsu_not_initialized"
+        return
+    fi
+    
+    local base=$(get_base_session_id)
+    local pm_agent=$(get_pm_agent_session_id)
+    
+    if [ -z "$base" ] || [ "$base" = "null" ]; then
+        echo "base_session_missing"
+        return
+    fi
+    
+    if [ -z "$pm_agent" ] || [ "$pm_agent" = "null" ] || [ "$pm_agent" = "None" ]; then
+        echo "pm_agent_missing"
+        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"
+}
+
+get_verbosity_context() {
+    local verbosity="${KUGETSU_VERBOSITY:-default}"
+    local verbosity_file="$VERBOSITY_DIR/${verbosity}.md"
+    
+    if [ -f "$verbosity_file" ]; then
+        cat "$verbosity_file"
+    else
+        echo "## Verbosity: $verbosity"
+    fi
+}
+
+init_verbosity_templates() {
+    mkdir -p "$VERBOSITY_DIR"
+    
+    if [ ! -f "$VERBOSITY_DIR/verbose.md" ]; then
+        cat > "$VERBOSITY_DIR/verbose.md" << 'EOF'
+## Verbosity: Verbose
+
+You are operating in HIGH verbosity mode. Include ALL available context:
+- Full command outputs and their results
+- Detailed reasoning and thinking process
+- All file changes with diffs when relevant
+- Complete log excerpts
+- Comprehensive status updates
+- Ask clarifying questions when uncertain
+EOF
+    fi
+    
+    if [ ! -f "$VERBOSITY_DIR/default.md" ]; then
+        cat > "$VERBOSITY_DIR/default.md" << 'EOF'
+## Verbosity: Default
+
+You are operating in NORMAL verbosity mode. Provide balanced output:
+- Standard command outputs and key results
+- Moderate reasoning detail
+- Important file changes summarized
+- Regular status updates
+EOF
+    fi
+    
+    if [ ! -f "$VERBOSITY_DIR/quiet.md" ]; then
+        cat > "$VERBOSITY_DIR/quiet.md" << 'EOF'
+## Verbosity: Quiet
+
+You are operating in QUIET verbosity mode. Keep output minimal:
+- Only essential information
+- Brief status updates (1-2 sentences)
+- Final decisions only
+- Yes/No answers when appropriate
+EOF
+    fi
+}
+
+parse_issue_ref_from_message() {
+    # DEPRECATED: This function is not called anywhere.
+    # The active implementation is extract_issue_ref_from_message()
+    # in kugetsu-session.sh which is used by cmd_delegate.
+    # This function is kept for backwards compatibility and will
+    # be removed in a future release.
+    local message="$1"
+    
+    local gitserver=""
+    local owner=""
+    local repo=""
+    local issue_number=""
+    
+    if [[ "$message" =~ (https?://)?([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/([a-zA-Z0-9._-]+)/([a-zA-Z0-9._-]+)/(issues|pull)/([0-9]+) ]]; then
+        gitserver="${BASH_REMATCH[2]}"
+        owner="${BASH_REMATCH[3]}"
+        repo="${BASH_REMATCH[4]}"
+        issue_number="${BASH_REMATCH[6]}"
+    elif [[ "$message" =~ (https?://)?([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/([a-zA-Z0-9._-]+)/([a-zA-Z0-9._-]+)#([0-9]+) ]]; then
+        gitserver="${BASH_REMATCH[2]}"
+        owner="${BASH_REMATCH[3]}"
+        repo="${BASH_REMATCH[4]}"
+        issue_number="${BASH_REMATCH[5]}"
+    elif [[ "$message" =~ ([a-zA-Z0-9._-]+)/([a-zA-Z0-9._-]+)#([0-9]+) ]]; then
+        owner="${BASH_REMATCH[1]}"
+        repo="${BASH_REMATCH[2]}"
+        issue_number="${BASH_REMATCH[3]}"
+    fi
+    
+    echo "${gitserver}|${owner}|${repo}|${issue_number}"
+}
+
+get_missing_info() {
+    local parsed="$1"
+    local gitserver=$(echo "$parsed" | cut -d'|' -f1)
+    local owner=$(echo "$parsed" | cut -d'|' -f2)
+    local repo=$(echo "$parsed" | cut -d'|' -f3)
+    local issue_number=$(echo "$parsed" | cut -d'|' -f4)
+    
+    local missing=""
+    [ -z "$gitserver" ] && missing="${missing}git server, "
+    [ -z "$owner" ] && missing="${missing}owner, "
+    [ -z "$repo" ] && missing="${missing}repository, "
+    [ -z "$issue_number" ] && missing="${missing}issue number, "
+    
+    echo "$missing" | sed 's/, $//'
+}
+
+build_missing_info_context() {
+    local missing="$1"
+    if [ -n "$missing" ]; then
+        echo ""
+        echo "NOTE: This task delegation has no information about: ${missing}."
+        echo "We need them if user wants to work on a specific issue. Otherwise we don't need it."
+    fi
+}
+
+find_worktrees_by_issue_number() {
+    local issue_number="$1"
+    local results=""
+    
+    if [ ! -d "$WORKTREES_DIR/.kugetsu-worktrees" ]; then
+        echo ""
+        return
+    fi
+    
+    for wt in "$WORKTREES_DIR/.kugetsu-worktrees"/*; do
+        if [ -d "$wt" ]; then
+            local wt_issue_number=$(echo "$wt" | grep -oE '#?[0-9]+$' | grep -oE '[0-9]+' | head -1)
+            if [ "$wt_issue_number" = "$issue_number" ]; then
+                results="${results}${wt}:worktree
+"
+            fi
+        fi
+    done
+    
+    echo "$results"
+}
+
+find_sessions_by_issue_number() {
+    local issue_number="$1"
+    local results=""
+    
+    if [ ! -d "$SESSIONS_DIR" ]; then
+        echo ""
+        return
+    fi
+    
+    for session_file in "$SESSIONS_DIR"/*.json; do
+        if [ -f "$session_file" ]; then
+            local session_issue_ref=$(basename "$session_file" .json | sed 's/_/\//g')
+            local session_issue_number=$(echo "$session_issue_ref" | grep -oE '#?[0-9]+$' | grep -oE '[0-9]+' | head -1)
+            if [ "$session_issue_number" = "$issue_number" ]; then
+                results="${results}${session_file}:session
+"
+            fi
+        fi
+    done
+    
+    echo "$results"
+}
+
 cmd_queue() {
     local action="${1:-list}"
     shift

skills/kugetsu/scripts/kugetsu-index.sh

@@ -133,3 +133,111 @@ with open(session_path, 'w') as f:
     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
+}

skills/kugetsu/scripts/kugetsu-log.sh

@@ -43,15 +43,24 @@ kugetsu_add_notification() {
         notifications=$(cat "$NOTIFICATIONS_FILE")
     fi
     
-    local new_notification=$(python3 -c "import json; print(json.dumps({
+    notifications=$(echo "$notifications" | python3 -c "
+import json
+import sys
+
+notifications = json.load(sys.stdin)
+new_notification = {
     'type': '$notification_type',
-        'message': '$message',
-        'issue_ref': '$issue_ref',
+    'message': '''$message'''.replace('\"', '\"'),
+    'issue_ref': '$issue_ref' if '$issue_ref' else None,
     '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))")
+notifications.append(new_notification)
+notifications = notifications[-50:] if len(notifications) > 50 else notifications
+
+print(json.dumps(notifications, indent=2))
+")
     
     echo "$notifications" > "$NOTIFICATIONS_FILE"
 }

skills/kugetsu/scripts/kugetsu-queue-daemon.sh

@@ -8,23 +8,146 @@ 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
-                queue_id=$(basename "$item" .json)
-                issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
-                message=$(python3 -c "import json; print(json.load(open('$item')).get('message', ''))" 2>/dev/null)
-                
-                pm_session=$(get_pm_agent_session_id)
-                if [ -n "$pm_session" ] && [ "$pm_session" != "null" ]; then
-                    log_file="$LOGS_DIR/delegate-$(date +%s).log"
-                    GITEA_TOKEN="${GITEA_TOKEN:-}" nohup sh -c "opencode run '$message' --continue --session '$pm_session' >> '$log_file' 2>&1" > /dev/null 2>&1 &
-                    pid=$!
-                    update_queue_item_state "$queue_id" "notified" "$pm_session" "$pid"
-                fi
+                process_task "$item"
             fi
         done
     fi

skills/kugetsu/scripts/kugetsu-session.sh

@@ -1,6 +1,13 @@
 #!/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
@@ -74,9 +81,20 @@ EOF
     echo "Press Ctrl+C to cancel or wait for session to be created"
     sleep 2
 
+    local before_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
+
     opencode
 
-    local session_ids=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' | tail -1)
+    local after_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
+    local session_ids=""
+    while IFS= read -r line; do
+        local sid=$(echo "$line" | awk '{print $1}')
+        if [ -n "$sid" ] && ! echo "$before_sessions" | grep -q "^${sid}$"; then
+            session_ids="$sid"
+            break
+        fi
+    done <<< "$after_sessions"
+
     if [ -z "$session_ids" ]; then
         echo "Error: Could not find newly created session" >&2
         exit 1
@@ -88,9 +106,20 @@ EOF
     echo "Base session created: $session_ids"
     echo "Starting PM agent..."
 
+    before_sessions="$after_sessions"
+
     opencode
 
-    local pm_session_ids=$(opencode session list 2>/dev/null | grep -E '^ses_' | grep -v "$session_ids" | tail -1)
+    after_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
+    local pm_session_ids=""
+    while IFS= read -r line; do
+        local sid=$(echo "$line" | awk '{print $1}')
+        if [ -n "$sid" ] && ! echo "$before_sessions" | grep -q "^${sid}$"; then
+            pm_session_ids="$sid"
+            break
+        fi
+    done <<< "$after_sessions"
+
     if [ -z "$pm_session_ids" ]; then
         echo "Warning: Could not find separate PM agent session" >&2
         pm_session_ids="$session_ids"
@@ -127,13 +156,11 @@ extract_issue_ref_from_message() {
         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]+$')
+    if [[ "$message" =~ (https?://)?([a-zA-Z0-9.-]+)/([a-zA-Z0-9._-]+)/([a-zA-Z0-9._-]+)/(issues|pull)/([0-9]+) ]]; then
+        local instance="${BASH_REMATCH[2]}"
+        local owner="${BASH_REMATCH[3]}"
+        local repo="${BASH_REMATCH[4]}"
+        local num="${BASH_REMATCH[6]}"
         echo "${instance}/${owner}/${repo}#${num}"
         return
     fi
@@ -153,10 +180,12 @@ cmd_delegate() {
     local issue_ref=$(extract_issue_ref_from_message "$message")
     
     if [ -n "$issue_ref" ] && [[ "$issue_ref" =~ \#[0-9]+$ ]]; then
-        cmd_start "$issue_ref" "$message"
+        # 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
@@ -165,7 +194,7 @@ cmd_delegate() {
     
     mkdir -p "$LOGS_DIR"
     local log_file="$LOGS_DIR/delegate-$(date +%s).log"
-    nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '$message' --continue --session '$pm_session' >> '$log_file' 2>&1" > /dev/null 2>&1 &
+    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"))"
 }

skills/kugetsu/scripts/kugetsu-worktree.sh

@@ -10,7 +10,7 @@ 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"
+    echo "$parent_dir/$worktree_name"
 }
 
 issue_ref_to_branch_name() {

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