fix: use temp file for message to avoid shell parsing issues

The message passed to opencode run contains newlines and special characters (parentheses, etc.) which break shell parsing when passed directly in double quotes. Fix by writing message to temp file and using '@msg_file' syntax to pass to opencode run. This handles any characters in the message.
fix: improve worktree/session handling in cmd_start, cmd_continue, and cmd_init
2026-04-07 01:55:34 +00:00 · 2026-04-07 01:40:20 +00:00 · 2026-04-07 00:48:06 +00:00 · 2026-04-07 00:39:45 +00:00 · 2026-04-07 00:24:03 +00:00 · 2026-04-07 00:13:06 +00:00
13 changed files with 1779 additions and 212 deletions
--- 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,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
--- a/skills/kugetsu/scripts/kugetsu
+++ b/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,458 @@ 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
+}
+
+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
--- a/skills/kugetsu/scripts/kugetsu-config.sh
+++ b/skills/kugetsu/scripts/kugetsu-config.sh
@@ -53,5 +53,9 @@ load_agent_env() {
        set -a
        source "$ENV_DIR/default.env"
        set +a
+    elif [ -f "$ENV_DIR/pm-agent.env" ]; then
+        set -a
+        source "$ENV_DIR/pm-agent.env"
+        set +a
    fi
 }
--- a/skills/kugetsu/scripts/kugetsu-index.sh
+++ b/skills/kugetsu/scripts/kugetsu-index.sh
@@ -15,6 +15,13 @@ write_index() {
    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"
+    
+    if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+        echo "Error: write_index would create malformed JSON, aborting. base=$base, pm_agent=$pm_agent, issues_json=$issues_json" >&2
+        rm -f "$temp_file"
+        return 1
+    fi
+    
    mv "$temp_file" "$INDEX_FILE"
 }

@@ -43,7 +50,11 @@ set_base_in_index() {
    if [ "$session_id" = "null" ]; then
        write_index "null" "$pm_agent" "$issues"
    else
-        write_index "\"$session_id\"" "$pm_agent" "$issues"
+        if [ "$pm_agent" = "null" ]; then
+            write_index "\"$session_id\"" "null" "$issues"
+        else
+            write_index "\"$session_id\"" "\"$pm_agent\"" "$issues"
+        fi
    fi
 }

@@ -56,7 +67,11 @@ set_pm_agent_in_index() {
    if [ "$session_id" = "null" ]; then
        write_index "$base" "null" "$issues"
    else
-        write_index "$base" "\"$session_id\"" "$issues"
+        if [ "$base" = "null" ]; then
+            write_index "null" "\"$session_id\"" "$issues"
+        else
+            write_index "\"$base\"" "\"$session_id\"" "$issues"
+        fi
    fi
 }

@@ -72,7 +87,19 @@ add_issue_to_index() {
    
    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"
+    if [ "$base" = "null" ]; then
+        if [ "$pm_agent" = "null" ]; then
+            write_index "null" "null" "$issues"
+        else
+            write_index "null" "\"$pm_agent\"" "$issues"
+        fi
+    else
+        if [ "$pm_agent" = "null" ]; then
+            write_index "\"$base\"" "null" "$issues"
+        else
+            write_index "\"$base\"" "\"$pm_agent\"" "$issues"
+        fi
+    fi
 }

 remove_issue_from_index() {
@@ -86,7 +113,19 @@ remove_issue_from_index() {
    
    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"
+    if [ "$base" = "null" ]; then
+        if [ "$pm_agent" = "null" ]; then
+            write_index "null" "null" "$issues"
+        else
+            write_index "null" "\"$pm_agent\"" "$issues"
+        fi
+    else
+        if [ "$pm_agent" = "null" ]; then
+            write_index "\"$base\"" "null" "$issues"
+        else
+            write_index "\"$base\"" "\"$pm_agent\"" "$issues"
+        fi
+    fi
 }

 validate_issue_ref() {
@@ -130,6 +169,114 @@ 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")
+    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
@@ -43,15 +43,24 @@ kugetsu_add_notification() {
        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=$(echo "$notifications" | python3 -c "
+import json
+import sys

-    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 = json.load(sys.stdin)
+new_notification = {
+    'type': '$notification_type',
+    'message': '''$message'''.replace('\"', '\"'),
+    'issue_ref': '$issue_ref' if '$issue_ref' else None,
+    'timestamp': '$timestamp',
+    'read': False
+}
+
+notifications.append(new_notification)
+notifications = notifications[-50:] if len(notifications) > 50 else notifications
+
+print(json.dumps(notifications, indent=2))
+")
    
    echo "$notifications" > "$NOTIFICATIONS_FILE"
 }
--- a/skills/kugetsu/scripts/kugetsu-queue-daemon.sh
+++ b/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" "$WORKTREES_DIR")
+            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" "$WORKTREES_DIR")
+            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" "$WORKTREES_DIR" || [ -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
--- a/skills/kugetsu/scripts/kugetsu-session.sh
+++ b/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
@@ -51,12 +58,35 @@ EOF
        echo "Created config file: $KUGETSU_DIR/config"
    fi

+    mkdir -p "$ENV_DIR"
+    if [ ! -f "$ENV_DIR/default.env" ]; then
+        cat > "$ENV_DIR/default.env" << 'EOF'
+# Environment variables for agents
+# Copy this file to <agent-type>.env (e.g., pm-agent.env, dev.env)
+# and set your tokens and configuration
+
+# Required: Gitea token for API access
+# GITEA_TOKEN=your_gitea_token_here
+
+# Optional: GitHub token (if using GitHub)
+# GITHUB_TOKEN=your_github_token_here
+
+# Optional: GitLab token (if using GitLab)
+# GITLAB_TOKEN=your_gitlab_token_here
+EOF
+        echo "Created env template: $ENV_DIR/default.env"
+    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
+            echo "Destroying all sessions, worktrees, and logs..." >&2
+            cmd_destroy --base -y 2>/dev/null || true
+            cmd_destroy --pm-agent -y 2>/dev/null || true
+            rm -f "$LOGS_DIR"/*.log 2>/dev/null || true
        else
            echo "Error: Base session already exists: $existing_base" >&2
            echo "Use --force to reinitialize" >&2
@@ -74,9 +104,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 +129,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 +179,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,21 +203,99 @@ 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
    
-    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
+    # No issue ref detected — fork a new session from base session
+    local base_session=$(get_base_session_id)
+    if [ -z "$base_session" ] || [ "$base_session" = "null" ]; then
+        echo "Error: Base 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='${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"))"
+    load_agent_env "pm-agent"
+    
+    local new_session=$(create_session "$base_session")
+    if [ -z "$new_session" ]; then
+        echo "Error: Failed to create session" >&2
+        exit 1
+    fi
+    
+    local msg_file="$LOGS_DIR/msg-$new_session.txt"
+    printf '%s' "$message" > "$msg_file"
+    nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$new_session'" >> "$log_file" 2>&1 &
+    rm -f "$msg_file"
+    echo "Delegated to new session (logged to $(basename "$log_file"))"
+}
+
+create_session() {
+    local base_session="${1:-$base_session_id}"
+    
+    if [ -z "$base_session" ] || [ "$base_session" = "null" ]; then
+        echo "Error: base session not found. Run 'kugetsu init' first." >&2
+        return 1
+    fi
+    
+    local before_json=$(opencode session list --format=json 2>/dev/null)
+    local before_ids=$(echo "$before_json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); print(' '.join(s['id'] for s in sessions))" 2>/dev/null || echo "")
+    
+    opencode run --fork --session "$base_session" "new session" 2>/dev/null
+    
+    local after_json=$(opencode session list --format=json 2>/dev/null)
+    local after_ids=$(echo "$after_json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); print(' '.join(s['id'] for s in sessions))" 2>/dev/null || echo "")
+    
+    local new_session_id=""
+    for sess in $after_ids; do
+        if [[ ! " $before_ids " =~ " $sess " ]] && [[ "$sess" != "$base_session" ]]; then
+            new_session_id="$sess"
+            break
+        fi
+    done
+    
+    echo "$new_session_id"
+}
+
+build_dev_agent_message() {
+    local issue_ref="$1"
+    local user_message="${2:-}"
+    
+    local instance=$(echo "$issue_ref" | cut -d'/' -f1 | cut -d'#' -f1)
+    local owner=$(echo "$issue_ref" | cut -d'/' -f2)
+    local repo=$(echo "$issue_ref" | cut -d'/' -f3 | cut -d'#' -f1)
+    local number=$(echo "$issue_ref" | grep -oE '#[0-9]+$' | tr -d '#')
+    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref")
+    
+    local base_message="You are assigned to work on $issue_ref.
+
+Workflow:
+1. Read the issue at $instance/$owner/$repo/issues/$number AND all comments on that issue
+2. Check if a PR already exists for this issue
+   - If PR exists and is open, review it and learn from it
+   - If PR makes sense to continue, work on it instead
+   - If PR is not worth continuing, create a new branch/PR but explain in PR description why you're creating a new one instead of continuing the existing PR
+3. Read README.md (if exists) to understand the general concept of this repository
+4. Read CONTRIBUTING.md (if exists) to understand how to contribute
+   - If CONTRIBUTING.md doesn't exist, follow steps 5-9 as your guideline
+5. Explore the repository to understand the codebase
+6. If anything is unclear, post a comment on the issue asking for clarification before implementing
+7. Implement the solution
+8. Create a branch named fix/issue-$number and implement the fix
+9. Create a PR when the implementation is complete
+
+Work directory: $worktree_path"
+    
+    if [ -n "$user_message" ]; then
+        echo "$base_message
+
+Additional instructions from delegator:
+$user_message"
+    else
+        echo "$base_message"
+    fi
 }

 cmd_start() {
@@ -188,15 +316,36 @@ cmd_start() {
        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
+    local session_file=$(issue_ref_to_filename "$issue_ref")
+    local session_path="$SESSIONS_DIR/$session_file"
+    local worktree_exists=false
+    
+    if worktree_exists "$issue_ref"; then
+        worktree_exists=true
+    fi
+    
+    local session_exists=false
+    if [ -f "$session_path" ]; then
+        session_exists=true
+    fi
+    
+    if $worktree_exists && $session_exists; then
+        echo "Issue '$issue_ref' already has a worktree and session." >&2
+        echo "Use 'kugetsu continue $issue_ref' to continue work." >&2
        exit 1
    fi
    
-    if worktree_exists "$issue_ref"; then
-        echo "Issue '$issue_ref' already has a worktree. Use 'kugetsu continue' instead."
-        exit 1
+    if $worktree_exists && ! $session_exists; then
+        echo "Warning: Worktree exists but session is missing. Removing worktree to recreate both..." >&2
+        remove_worktree_for_issue "$issue_ref"
+        worktree_exists=false
+    fi
+    
+    if ! $worktree_exists && $session_exists; then
+        echo "Warning: Session exists but worktree is missing. Removing stale session to recreate both..." >&2
+        rm -f "$session_path"
+        remove_issue_from_index "$issue_ref"
+        session_exists=false
    fi
    
    local active_count=$(count_active_dev_sessions)
@@ -205,31 +354,12 @@ cmd_start() {
        exit 1
    fi
    
-    local session_file=$(issue_ref_to_filename "$issue_ref")
-    local session_path="$SESSIONS_DIR/$session_file"
+    create_worktree "$issue_ref" "$WORKTREES_DIR"
    
-    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"
+    local new_session_id=$(create_session "$base_session_id")
    
    if [ -z "$new_session_id" ]; then
-        echo "Error: Could not find newly created session" >&2
+        echo "Error: Could not create session" >&2
        remove_worktree_for_issue "$issue_ref"
        exit 1
    fi
@@ -241,6 +371,16 @@ cmd_start() {
    
    add_issue_to_index "$issue_ref" "$session_file"
    
+    local dev_message=$(build_dev_agent_message "$issue_ref" "$message")
+    
+    load_agent_env "dev"
+    
+    cd "$worktree_path"
+    local msg_file="$LOGS_DIR/msg-$new_session_id.txt"
+    printf '%s' "$dev_message" > "$msg_file"
+    nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$new_session_id'" >> "$LOGS_DIR/dev-$new_session_id.log" 2>&1 &
+    rm -f "$msg_file"
+    
    echo "Session started for '$issue_ref': $new_session_id"
    echo "Worktree: $worktree_path"
 }
@@ -286,20 +426,26 @@ cmd_continue() {
    
    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 "")
+    local issue_ref=$(python3 -c "import json; print(json.load(open('$session_path')).get('issue_ref', ''))" 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
+    if [ -z "$worktree_path" ] || [ ! -d "$worktree_path" ]; then
+        echo "Warning: Worktree is missing for '$session_name'. Recovering..." >&2
+        rm -f "$session_path"
+        remove_issue_from_index "$session_name"
+        echo "Calling cmd_start to create new session and worktree..." >&2
+        cmd_start "$session_name" "$message"
+        return $?
    fi
+    
+    if [ -z "$message" ]; then
+        message=$(build_dev_agent_message "$issue_ref" "")
+    fi
+    
+    cd "$worktree_path"
+    local msg_file="$LOGS_DIR/msg-$opencode_session_id.txt"
+    printf '%s' "$message" > "$msg_file"
+    nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$opencode_session_id'" >> "$LOGS_DIR/dev-$opencode_session_id.log" 2>&1 &
+    rm -f "$msg_file"
 }

 cmd_list() {
@@ -450,11 +596,7 @@ cmd_destroy() {
    local target="${1:-}"
    local force=false
    
-    if [ "$target" = "--base" ]; then
-        target=""
-    fi
-    
-    if [ "$2" = "-y" ]; then
+    if [ "${2:-}" = "-y" ]; then
        force=true
    fi
    
--- a/skills/kugetsu/scripts/kugetsu-worktree.sh
+++ b/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() {
@@ -41,7 +41,7 @@ get_repo_url() {
    fi
    
    local instance=$(echo "$issue_ref" | cut -d'/' -f1 | cut -d'#' -f1)
-    local rest=$(echo "$issue_ref" | sed 's/.*\///' | sed 's/#.*//')
+    local rest=$(echo "$issue_ref" | sed 's/^[^\/]*\///' | sed 's/#.*//')
    
    if [ -n "${GIT_SERVERS[$instance]:-}" ]; then
        echo "${GIT_SERVERS[$instance]}/${rest}.git"
--- a/skills/kugetsu/tests/test-create-session.sh
+++ b/skills/kugetsu/tests/test-create-session.sh
@@ -0,0 +1,181 @@
+#!/bin/bash
+# Tests for create_session function
+#
+# Run with: bash skills/kugetsu/tests/test-create-session.sh
+#
+# NOTE: These tests MUST be run sequentially (not in parallel)
+# to avoid exhausting memory with too many opencode sessions.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../scripts/kugetsu-config.sh"
+source "$SCRIPT_DIR/../scripts/kugetsu-index.sh"
+source "$SCRIPT_DIR/../scripts/kugetsu-session.sh"
+
+PASS=0
+FAIL=0
+RUN=0
+
+pass() {
+    echo "PASS: $1"
+    PASS=$((PASS + 1))
+}
+
+fail() {
+    echo "FAIL: $1"
+    echo "  Expected: $2"
+    echo "  Got: $3"
+    FAIL=$((FAIL + 1))
+}
+
+run_test() {
+    local name="$1"
+    local test_func="$2"
+    RUN=$((RUN + 1))
+    echo ""
+    echo "=== Test $RUN: $name ==="
+    echo "--- $name ---"
+    $test_func
+}
+
+echo "=== create_session Test Suite ==="
+echo "NOTE: Running sequentially to avoid memory exhaustion"
+echo ""
+
+# Test 1: create_session requires base session
+test_create_session_requires_base() {
+    local base_id=$(get_base_session_id)
+    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
+        skip "Base session not initialized - run 'kugetsu init' first"
+        return
+    fi
+    
+    local result=$(create_session "$base_id")
+    if [ -n "$result" ] && [[ "$result" =~ ^ses_ ]]; then
+        pass "create_session returns valid session ID"
+    else
+        fail "create_session returns valid session ID" "ses_xxx" "$result"
+    fi
+}
+
+# Test 2: create_session creates a NEW session (different from base)
+test_create_session_is_new() {
+    local base_id=$(get_base_session_id)
+    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
+        skip "Base session not initialized - run 'kugetsu init' first"
+        return
+    fi
+    
+    local new_id=$(create_session "$base_id")
+    if [ "$new_id" != "$base_id" ]; then
+        pass "create_session returns NEW session (not same as base)"
+    else
+        fail "create_session returns NEW session" "different from base_id" "$new_id"
+    fi
+}
+
+# Test 3: create_session can be called multiple times (creates different sessions)
+test_create_session_multiple_calls() {
+    local base_id=$(get_base_session_id)
+    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
+        skip "Base session not initialized - run 'kugetsu init' first"
+        return
+    fi
+    
+    local id1=$(create_session "$base_id")
+    sleep 1
+    local id2=$(create_session "$base_id")
+    
+    if [ "$id1" != "$id2" ]; then
+        pass "create_session creates different sessions on each call"
+    else
+        fail "create_session creates different sessions" "$id1 != $id2" "both equal: $id1"
+    fi
+}
+
+# Test 4: JSON session list parsing
+test_session_json_parsing() {
+    local json='[{"id": "ses_abc123", "title": "test"}, {"id": "ses_def456", "title": "test2"}]'
+    local ids=$(echo "$json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); print(' '.join(s['id'] for s in sessions))" 2>/dev/null)
+    
+    if [ "$ids" = "ses_abc123 ses_def456" ]; then
+        pass "JSON session list parsing extracts IDs correctly"
+    else
+        fail "JSON session list parsing" "ses_abc123 ses_def456" "$ids"
+    fi
+}
+
+# Test 5: Session ID format validation
+test_session_id_format() {
+    local json='[{"id": "ses_2b4814406ffe3AxcpbrP7FknDr", "title": "test"}]'
+    local ids=$(echo "$json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); print(' '.join(s['id'] for s in sessions))" 2>/dev/null)
+    
+    if [[ "$ids" =~ ^ses_ ]]; then
+        pass "Session ID format is valid (starts with ses_)"
+    else
+        fail "Session ID format" "ses_xxx" "$ids"
+    fi
+}
+
+# Test 6: create_session accepts optional base session parameter
+test_create_session_with_param() {
+    local base_id=$(get_base_session_id)
+    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
+        skip "Base session not initialized - run 'kugetsu init' first"
+        return
+    fi
+    
+    local result=$(create_session "$base_id")
+    if [ -n "$result" ] && [[ "$result" =~ ^ses_ ]]; then
+        pass "create_session accepts base session parameter"
+    else
+        fail "create_session accepts base session parameter" "ses_xxx" "$result"
+    fi
+}
+
+# Test 7: Verify session appears in opencode session list after creation
+test_session_visible_in_list() {
+    local base_id=$(get_base_session_id)
+    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
+        skip "Base session not initialized - run 'kugetsu init' first"
+        return
+    fi
+    
+    local new_id=$(create_session "$base_id")
+    sleep 1
+    
+    local all_sessions=$(opencode session list --format=json 2>/dev/null)
+    if echo "$all_sessions" | grep -q "$new_id"; then
+        pass "Created session appears in opencode session list"
+    else
+        fail "Created session appears in session list" "should contain $new_id" "$all_sessions"
+    fi
+}
+
+skip() {
+    echo "SKIP: $1"
+}
+
+# Run tests sequentially
+run_test "create_session requires base session" test_create_session_requires_base
+run_test "create_session creates NEW session" test_create_session_is_new
+run_test "create_session creates different sessions on multiple calls" test_create_session_multiple_calls
+run_test "JSON session list parsing" test_session_json_parsing
+run_test "Session ID format validation" test_session_id_format
+run_test "create_session accepts optional base session parameter" test_create_session_with_param
+run_test "Created session visible in opencode session list" test_session_visible_in_list
+
+echo ""
+echo "=== Test Results ==="
+echo "Passed: $PASS"
+echo "Failed: $FAIL"
+echo "Total: $RUN"
+
+if [ $FAIL -eq 0 ]; then
+    echo "All tests passed!"
+    exit 0
+else
+    echo "Some tests failed!"
+    exit 1
+fi
--- a/skills/kugetsu/tests/test-git-url-parsing.sh
+++ b/skills/kugetsu/tests/test-git-url-parsing.sh
@@ -0,0 +1,298 @@
+#!/bin/bash
+# Git URL Parsing Tests for kugetsu
+# Tests all functions that parse or construct git URLs and issue refs
+#
+# Run with: bash skills/kugetsu/tests/test-git-url-parsing.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../scripts/kugetsu-config.sh"
+source "$SCRIPT_DIR/../scripts/kugetsu-worktree.sh"
+source "$SCRIPT_DIR/../scripts/kugetsu-session.sh"
+
+PASS=0
+FAIL=0
+
+pass() {
+    echo "PASS: $1"
+    PASS=$((PASS + 1))
+}
+
+fail() {
+    echo "FAIL: $1"
+    echo "  Expected: $2"
+    echo "  Got: $3"
+    FAIL=$((FAIL + 1))
+}
+
+echo "=== Git URL Parsing Test Suite ==="
+echo ""
+
+# Test: get_repo_url with standard GitHub issue ref
+echo "--- Test: get_repo_url with github.com ---"
+result=$(get_repo_url "github.com/shoko/kugetsu#14")
+expected="https://github.com/shoko/kugetsu.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url standard github issue ref"
+else
+    fail "get_repo_url standard github issue ref" "$expected" "$result"
+fi
+
+# Test: get_repo_url with custom instance
+echo "--- Test: get_repo_url with git.fbrns.co ---"
+result=$(get_repo_url "git.fbrns.co/shoko/kugetsu#158")
+expected="https://git.fbrns.co/shoko/kugetsu.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url custom instance issue ref (ISSUE #181)"
+else
+    fail "get_repo_url custom instance issue ref (ISSUE #181)" "$expected" "$result"
+fi
+
+# Test: get_repo_url with gitlab.com (if configured)
+echo "--- Test: get_repo_url with gitlab.com ---"
+if [ -n "${GIT_SERVERS[gitlab.com]:-}" ]; then
+    result=$(get_repo_url "gitlab.com/someuser/somerepo#42")
+    expected="https://gitlab.com/someuser/somerepo.git"
+    if [ "$result" = "$expected" ]; then
+        pass "get_repo_url gitlab.com issue ref"
+    else
+        fail "get_repo_url gitlab.com issue ref" "$expected" "$result"
+    fi
+else
+    echo "SKIP: get_repo_url gitlab.com (not configured in GIT_SERVERS)"
+fi
+
+# Test: get_repo_url with bitbucket.org (if configured)
+echo "--- Test: get_repo_url with bitbucket.org ---"
+if [ -n "${GIT_SERVERS[bitbucket.org]:-}" ]; then
+    result=$(get_repo_url "bitbucket.org/myteam/myproject#7")
+    expected="https://bitbucket.org/myteam/myproject.git"
+    if [ "$result" = "$expected" ]; then
+        pass "get_repo_url bitbucket.org issue ref"
+    else
+        fail "get_repo_url bitbucket.org issue ref" "$expected" "$result"
+    fi
+else
+    echo "SKIP: get_repo_url bitbucket.org (not configured in GIT_SERVERS)"
+fi
+
+# Test: get_repo_url with large issue number
+echo "--- Test: get_repo_url with large issue number ---"
+result=$(get_repo_url "github.com/shoko/kugetsu#999999")
+expected="https://github.com/shoko/kugetsu.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url with large issue number"
+else
+    fail "get_repo_url with large issue number" "$expected" "$result"
+fi
+
+# Test: issue_ref_to_worktree_name standard
+echo "--- Test: issue_ref_to_worktree_name standard ---"
+result=$(issue_ref_to_worktree_name "github.com/shoko/kugetsu#14")
+expected="github.com-shoko-kugetsu-14"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_worktree_name standard"
+else
+    fail "issue_ref_to_worktree_name standard" "$expected" "$result"
+fi
+
+# Test: issue_ref_to_worktree_name with custom instance
+echo "--- Test: issue_ref_to_worktree_name custom instance ---"
+result=$(issue_ref_to_worktree_name "git.fbrns.co/shoko/kugetsu#158")
+expected="git.fbrns.co-shoko-kugetsu-158"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_worktree_name custom instance"
+else
+    fail "issue_ref_to_worktree_name custom instance" "$expected" "$result"
+fi
+
+# Test: issue_ref_to_branch_name with number
+echo "--- Test: issue_ref_to_branch_name with number ---"
+result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#14")
+expected="fix/issue-14"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_branch_name with number"
+else
+    fail "issue_ref_to_branch_name with number" "$expected" "$result"
+fi
+
+# Test: issue_ref_to_branch_name with discuss suffix
+# Note: #-discuss falls through to fix/issue-temp because #[^-]+$ doesn't match #-<text-with-hyphens>
+echo "--- Test: issue_ref_to_branch_name with discuss suffix ---"
+result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#-discuss")
+expected="fix/issue-temp"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_branch_name with discuss suffix"
+else
+    fail "issue_ref_to_branch_name with discuss suffix" "$expected" "$result"
+fi
+
+# Test: issue_ref_to_branch_name with identifier that has no hyphens
+echo "--- Test: issue_ref_to_branch_name with pure identifier ---"
+result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#someid")
+expected="fix/someid"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_branch_name with pure identifier"
+else
+    fail "issue_ref_to_branch_name with pure identifier" "$expected" "$result"
+fi
+
+# Test: issue_ref_to_branch_name without number
+echo "--- Test: issue_ref_to_branch_name without number ---"
+result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#abc")
+expected="fix/abc"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_branch_name without number"
+else
+    fail "issue_ref_to_branch_name without number" "$expected" "$result"
+fi
+
+# Test: extract_issue_ref_from_message with short form
+echo "--- Test: extract_issue_ref_from_message short form ---"
+result=$(extract_issue_ref_from_message "github.com/shoko/kugetsu#14")
+expected="github.com/shoko/kugetsu#14"
+if [ "$result" = "$expected" ]; then
+    pass "extract_issue_ref_from_message short form"
+else
+    fail "extract_issue_ref_from_message short form" "$expected" "$result"
+fi
+
+# Test: extract_issue_ref_from_message with https URL
+echo "--- Test: extract_issue_ref_from_message with https URL ---"
+result=$(extract_issue_ref_from_message "https://github.com/shoko/kugetsu/issues/14")
+expected="github.com/shoko/kugetsu#14"
+if [ "$result" = "$expected" ]; then
+    pass "extract_issue_ref_from_message with https URL"
+else
+    fail "extract_issue_ref_from_message with https URL" "$expected" "$result"
+fi
+
+# Test: extract_issue_ref_from_message with custom instance
+echo "--- Test: extract_issue_ref_from_message custom instance ---"
+result=$(extract_issue_ref_from_message "https://git.fbrns.co/shoko/kugetsu/issues/158")
+expected="git.fbrns.co/shoko/kugetsu#158"
+if [ "$result" = "$expected" ]; then
+    pass "extract_issue_ref_from_message custom instance"
+else
+    fail "extract_issue_ref_from_message custom instance" "$expected" "$result"
+fi
+
+# Test: extract_issue_ref_from_message with empty message
+echo "--- Test: extract_issue_ref_from_message empty message ---"
+result=$(extract_issue_ref_from_message "")
+expected=""
+if [ "$result" = "$expected" ]; then
+    pass "extract_issue_ref_from_message empty message"
+else
+    fail "extract_issue_ref_from_message empty message" "$expected" "$result"
+fi
+
+# Test: extract_issue_ref_from_message with no issue ref
+echo "--- Test: extract_issue_ref_from_message no issue ref ---"
+result=$(extract_issue_ref_from_message "Just a regular message without any issue reference")
+expected=""
+if [ "$result" = "$expected" ]; then
+    pass "extract_issue_ref_from_message no issue ref"
+else
+    fail "extract_issue_ref_from_message no issue ref" "$expected" "$result"
+fi
+
+# Test: extract_issue_ref_from_message with gitlab URL
+echo "--- Test: extract_issue_ref_from_message gitlab URL ---"
+result=$(extract_issue_ref_from_message "https://gitlab.com/someuser/somerepo/issues/42")
+expected="gitlab.com/someuser/somerepo#42"
+if [ "$result" = "$expected" ]; then
+    pass "extract_issue_ref_from_message gitlab URL"
+else
+    fail "extract_issue_ref_from_message gitlab URL" "$expected" "$result"
+fi
+
+# Test: validate_issue_ref valid format
+echo "--- Test: validate_issue_ref valid format ---"
+if validate_issue_ref "github.com/shoko/kugetsu#14" 2>/dev/null; then
+    pass "validate_issue_ref valid format"
+else
+    fail "validate_issue_ref valid format" "exit 0" "exit non-zero"
+fi
+
+# Test: validate_issue_ref invalid format (missing parts)
+echo "--- Test: validate_issue_ref invalid format ---"
+if ! validate_issue_ref "invalid-ref" 2>/dev/null; then
+    pass "validate_issue_ref invalid format"
+else
+    fail "validate_issue_ref invalid format" "exit non-zero" "exit 0"
+fi
+
+# Test: issue_ref_to_filename
+echo "--- Test: issue_ref_to_filename ---"
+result=$(issue_ref_to_filename "github.com/shoko/kugetsu#14")
+expected="github.com-shoko-kugetsu-14.json"
+if [ "$result" = "$expected" ]; then
+    pass "issue_ref_to_filename"
+else
+    fail "issue_ref_to_filename" "$expected" "$result"
+fi
+
+# Test: filename_to_issue_ref
+echo "--- Test: filename_to_issue_ref ---"
+result=$(filename_to_issue_ref "github.com-shoko-kugetsu-14.json")
+expected="github.com/shoko/kugetsu#14"
+if [ "$result" = "$expected" ]; then
+    pass "filename_to_issue_ref"
+else
+    fail "filename_to_issue_ref" "$expected" "$result"
+fi
+
+# Test: get_repo_url with org having hyphen
+echo "--- Test: get_repo_url with hyphenated org ---"
+result=$(get_repo_url "github.com/my-org/my-repo#1")
+expected="https://github.com/my-org/my-repo.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url with hyphenated org"
+else
+    fail "get_repo_url with hyphenated org" "$expected" "$result"
+fi
+
+# Test: get_repo_url with repo having dots
+echo "--- Test: get_repo_url with dotted repo ---"
+result=$(get_repo_url "github.com/shoko/kugetsu.utils#5")
+expected="https://github.com/shoko/kugetsu.utils.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url with dotted repo"
+else
+    fail "get_repo_url with dotted repo" "$expected" "$result"
+fi
+
+# Test: get_repo_url with underscore in username
+echo "--- Test: get_repo_url with underscore in user ---"
+result=$(get_repo_url "github.com/my_user/my_repo#10")
+expected="https://github.com/my_user/my_repo.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url with underscore in user"
+else
+    fail "get_repo_url with underscore in user" "$expected" "$result"
+fi
+
+# Test: get_repo_url with instance not in GIT_SERVERS (fallback)
+echo "--- Test: get_repo_url with unknown instance ---"
+result=$(get_repo_url "unknown.example.com/owner/repo#1")
+expected="https://unknown.example.com/owner/repo.git"
+if [ "$result" = "$expected" ]; then
+    pass "get_repo_url with unknown instance"
+else
+    fail "get_repo_url with unknown instance" "$expected" "$result"
+fi
+
+echo ""
+echo "=== Test Results ==="
+echo "Passed: $PASS"
+echo "Failed: $FAIL"
+
+if [ $FAIL -eq 0 ]; then
+    echo "All tests passed!"
+    exit 0
+else
+    echo "Some tests failed!"
+    exit 1
+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	a130a79bd7	fix: use temp file for message to avoid shell parsing issues The message passed to opencode run contains newlines and special characters (parentheses, etc.) which break shell parsing when passed directly in double quotes. Fix by writing message to temp file and using '@msg_file' syntax to pass to opencode run. This handles any characters in the message.	2026-04-07 01:55:34 +00:00
shokollm	9d0bcef465	fix: improve worktree/session handling in cmd_start, cmd_continue, and cmd_init cmd_continue: - If worktree is missing but session exists, remove stale session and call cmd_start automatically - This allows automatic recovery without user intervention cmd_start: - Check BOTH worktree AND session existence - If only worktree exists (not session): remove worktree, recreate both - If only session exists (not worktree): remove session, recreate both - If both exist: tell user to use continue cmd_init --force: - Now destroys ALL sessions, worktrees, and logs for a clean slate - Destroys base, pm-agent, all forked sessions, all worktrees, all logs Daemon: - Fixed wrong path in check_task_completion ($HOME/.kugetsu-worktrees -> $WORKTREES_DIR)	2026-04-07 01:40:20 +00:00
shokollm	6a8fa563dd	fix: properly quote base and pm_agent in write_index calls When base or pm_agent are not null, they need to be quoted with escaped quotes ("") in write_index calls. This fixes 'write_index would create malformed JSON' error during init.	2026-04-07 00:48:06 +00:00
shokollm	998f7a4f44	refactor: remove duplicate functions from kugetsu, use kugetsu-index.sh exclusively - Remove duplicate write_index, get_base_session_id, get_pm_agent_session_id, get_session_for_issue, set_base_in_index, set_pm_agent_in_index, add_issue_to_index, remove_issue_from_index from kugetsu - These functions are already defined in kugetsu-index.sh which is sourced earlier - The kugetsu versions were shadowing the kugetsu-index.sh ones unnecessarily - This removes code duplication and ensures consistent behavior	2026-04-07 00:39:45 +00:00
shokollm	b595411a07	test: add test suite for create_session function Tests run sequentially to avoid memory exhaustion with too many opencode sessions: - JSON session list parsing - Session ID format validation - create_session returns valid session ID - create_session creates NEW session (different from base) - create_session creates different sessions on multiple calls - create_session accepts optional base session parameter - Created session visible in opencode session list	2026-04-07 00:24:03 +00:00
shokollm	08b633400d	refactor: add create_session() and use --session instead of --continue - Add create_session() function that forks from base session using JSON session detection - cmd_delegate: fork new session from base instead of using pm_agent - cmd_start: use create_session() instead of broken before/after detection - cmd_continue: use --session instead of --continue (no need to continue existing session) - Remove pm_agent check from cmd_start (no longer needed)	2026-04-07 00:13:06 +00:00
shokollm	860bf9295f	fix: use ${GITEA_TOKEN:-} to handle unset token and initialize env during init With set -u, expanding $GITEA_TOKEN fails if not set. Changed to ${GITEA_TOKEN:-} to provide empty default. Also initializes $ENV_DIR/default.env during kugetsu init so users are aware of the env file structure.	2026-04-06 09:45:15 +00:00
shokollm	fd79bfa3ea	fix: cmd_destroy unbound variable $2 With set -u, using $2 without default causes error when called without arguments.	2026-04-06 09:24:47 +00:00
shoko	119c9b8fd9	Merge pull request 'fix: daemon worktree path and agent forking issues' (#191 ) from fix/issue-daemon-worktree-path-fix into main	2026-04-06 11:19:52 +02:00
shokollm	7f7f8b1085	fix: multiple issues with queue daemon and agent forking 1. daemon: use $WORKTREES_DIR instead of $HOME/.kugetsu-worktrees - Worktrees are created in ~/.kugetsu/worktrees but daemon was checking ~/.kugetsu-worktrees - This caused cmd_start to be called when cmd_continue should have been 2. load_agent_env: add fallback to pm-agent.env - When dev.env and default.env don't exist, fallback to pm-agent.env - Ensures GITEA_TOKEN is available 3. Remove '&& disown' pattern that causes 'no such job' errors - nohup already makes process immune to SIGHUP - disown was causing errors because job context was lost	2026-04-06 09:14:37 +00:00
shoko	1a523a805a	Merge pull request 'fix: syntax error in cmd_continue line 372 (issue #189 )' (#190 ) from fix/issue-syntax-error-372 into main	2026-04-06 10:46:09 +02:00
shokollm	6aa84a35b9	fix: syntax error in cmd_continue line 372 (issue #189 ) Wrap nohup command in subshell to fix '&& disown' syntax error	2026-04-06 08:44:29 +00:00
shoko	6e2841bbda	Merge pull request 'fix: cmd_start and cmd_continue now fork dev agent to work on task (issue #187 )' (#188 ) from fix/issue-187-start-forks-agent into main	2026-04-06 10:13:42 +02:00
shokollm	99d09c7dda	fix: cmd_start and cmd_continue now fork dev agent to work on task (issue #187 ) - Added build_dev_agent_message() function to generate default workflow prompt - cmd_start now forks the agent after creating session (fire-and-forget) - cmd_continue now uses default message when empty and forks agent (fire-and-forget) - Both commands log output to $LOGS_DIR/dev-$session_id.log	2026-04-06 08:05:42 +00:00
shoko	383f538438	Merge pull request 'fix: worktree created in wrong directory (issue #185 )' (#186 ) from fix/issue-185-worktree-wrong-directory into main	2026-04-06 07:33:02 +02:00
shokollm	28b343f817	fix: worktree created in wrong directory (issue #185 ) cmd_start was calling create_worktree without passing $WORKTREES_DIR, causing worktrees to be created in $PWD (daemon's working directory) instead of ~/.kugetsu-worktrees/	2026-04-06 05:18:31 +00:00
shoko	3a2095861f	Merge pull request 'fix: destroy --base -y fails with 'target is required' (issue #183 )' (#184 ) from fix/issue-183-destroy-base-requires-target into main	2026-04-06 06:16:30 +02:00
shokollm	836fde07fc	fix: destroy --base -y fails with 'target is required' (issue #183 ) Removed erroneous code that set target="" when target="--base". This caused the early exit at 'if [ -z "$target" ]' to trigger before reaching the actual --base handling at line 517.	2026-04-06 04:14:03 +00:00
shoko	4f2a04e0b4	Merge pull request 'fix: get_repo_url() strips user/org from path (issue #181 )' (#182 ) from fix/issue-181-get-repo-url-strips-user-org into main	2026-04-06 06:07:46 +02:00
shokollm	c8bb0b36f4	fix: get_repo_url() strips user/org from path (issue #181 ) The sed pattern 's/.*\///' on line 44 was removing everything up to the LAST slash, but for issue refs like 'git.fbrns.co/shoko/kugetsu#158' it should remove the instance prefix only (up to the FIRST slash). Before: git.fbrns.co/shoko/kugetsu#158 -> kugetsu (WRONG) After: git.fbrns.co/shoko/kugetsu#158 -> shoko/kugetsu (CORRECT) Also adds comprehensive test suite for git URL parsing functions: - get_repo_url(), issue_ref_to_worktree_name(), issue_ref_to_branch_name() - extract_issue_ref_from_message(), validate_issue_ref() - issue_ref_to_filename(), filename_to_issue_ref()	2026-04-06 04:00:18 +00:00
shoko	937b7c69de	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	2026-04-06 05:27:16 +02:00
shokollm	2051266809	fix: remove doubled .kugetsu-worktrees path segment in issue_ref_to_worktree_path Fixes #179 - cmd_start fails due to incorrect worktree path being created with .kugetsu-worktrees/.kugetsu-worktrees/ instead of just the worktree name.	2026-04-06 03:23:23 +00:00
shoko	80a3228be9	Merge pull request 'fix(kugetsu-session): extract_issue_ref_from_message fix URL parsing' (#178 ) from fix/issue-176-extract-issue-ref into main	2026-04-06 04:54:11 +02:00
shokollm	d68a63af41	fix(kugetsu-session): extract_issue_ref_from_message fix URL parsing Fix issue where full URLs like #158 were incorrectly parsed to 'shoko/kugetsu/issues#158' instead of 'git.fbrns.co/shoko/kugetsu#158'. The regex now correctly extracts instance, owner, repo, and number using bash regex capture groups instead of fragile sed/cut pipeline.	2026-04-06 02:51:51 +00:00
shoko	56310755b8	Merge pull request 'fix: queue daemon crashes on every task (issue #174 )' (#175 ) from fix/issue-174-queue-daemon-crashes into main	2026-04-06 04:16:12 +02:00
shokollm	fb33be3a64	fix: queue daemon crashes on every task - 3 bugs Fix 3 bugs from issue #174 that caused silent failure loop: 1. kugetsu-log.sh: Fix json.loads with newlines - Previously, notifications JSON was embedded in a single-quoted Python string literal, but newlines in the JSON broke the Python parser. - Fix: Pass JSON via stdin to Python instead of embedding in string. 2. kugetsu-queue-daemon.sh: Create logs directory during init - The logs/ directory ($LOGS_DIR) was never created during kugetsu init. - Fix: Add mkdir -p for LOGS_DIR, WORKTREES_DIR, QUEUE_DIR, and QUEUE_ITEMS_DIR to ensure_dirs() and ensure_queue_dirs(). 3. kugetsu: Fix parse_issue_ref_from_message URL parsing - The function used buggy grep/sed to parse URLs like #158 - Fix: Use bash regex (=~) for reliable URL parsing with proper capture groups. Additional improvements: - ensure_dirs() now creates all necessary directories instead of just SESSIONS_DIR - ensure_queue_dirs() now also creates QUEUE_DIR and LOGS_DIR - parse_issue_ref_from_message uses consistent bash regex approach for all URL patterns	2026-04-06 02:14:27 +00:00
shoko	1b19c9a92c	Merge pull request 'fix: init script captures wrong session IDs when old sessions exist' (#173 ) from fix/issue-172-init-script-wrong-session-ids into main	2026-04-06 03:09:30 +02:00
shokollm	85a4239383	fix: init script captures wrong session IDs when old sessions exist The init script used 'tail -1' to find newly created sessions, which fails when old sessions exist because it picks an existing session instead of the newly created one. The fix captures session IDs before and after creating new sessions, then diffs to identify newly created sessions. Fixes #172	2026-04-06 01:08:09 +00:00
shokollm	91b51f62c0	docs: update changelog for v0.2.4	2026-04-06 00:49:00 +00:00
shoko	7234837284	Merge pull request 'fix(kugetsu): remove duplicate update_queue_item_state to use fixed version from kugetsu-index.sh' (#171 ) from fix/issue-170-duplicate-update-queue into main	2026-04-06 02:42:24 +02:00
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	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