feat(kugetsu): add lock mechanism for worktree coordination

Add lock mechanism to prevent concurrent access to worktrees: - Add LOCKS_DIR constant (~/.kugetsu/locks) - Add acquire_lock() - acquires lock file with PID, session_id, timestamp - Add release_lock() - releases lock if held by current process - Add release_all_locks() - releases all locks for a session - Add check_lock() - check if issue is locked - Modify cmd_start to acquire lock before creating worktree - Modify cmd_destroy to release lock when destroying session - Add trap for cleanup on EXIT/INT/TERM Lock files named after issue ref. Stale lock detection: if PID no longer exists, lock is considered stale. Fixes #71
Merge pull request 'feat(kugetsu): add queue infrastructure for autonomous PM' (#97 ) from feat/issue-49-queue-v2 into main
2026-04-02 02:52:16 +00:00 · 2026-04-02 04:37:41 +02:00 · 2026-04-02 01:04:10 +00:00
20 changed files with 1629 additions and 3663 deletions
--- a/.github/ISSUES/fix-queue-daemon-excess-agents.md
+++ b/.github/ISSUES/fix-queue-daemon-excess-agents.md
@@ -1,67 +0,0 @@
 # Fix: Queue daemon spawning excess agents due to race condition
 ## Problem
 When enqueueing multiple tasks (e.g., 6 tasks), the queue daemon was spawning many more subagents than expected, eventually exhausting container memory.
 **Root Cause:** The combination of:
 1. `process_queue()` calling `opencode run` directly instead of `kugetsu start`, bypassing all concurrency logic
 2. `count_active_dev_sessions()` counting `pm-agent.json` toward `MAX_CONCURRENT_AGENTS`, reducing effective dev agent slots
 3. No atomic locking around session count check + session file creation (TOCTOU race condition)
 4. Background spawning of multiple concurrent processes in `process_queue()`
 **Expected behavior:** With `MAX_CONCURRENT_AGENTS=3` and 6 tasks:
 - Tasks should be processed sequentially via `kugetsu start`
 - Only 3 dev agents should run at a time
 - Tasks should queue and wait for slots to free up
 ## Solution
 ### 1. `count_active_dev_sessions()` - Exclude pm-agent
 Only count actual dev agent session files (exclude `pm-agent.json`).
 ### 2. `process_queue()` - Call `kugetsu start` directly + retry logic
 - Call `kugetsu start` directly (foreground, sequential) instead of spawning `opencode run` background process
 - Dynamic batch size = available slots (removes need for `QUEUE_DAEMON_BATCH_SIZE`)
 - Retry logic (max 3 attempts) on failure
 - On failure: cleanup worktree/session and revert to `pending` state
 - Save `fork_pid` to queue item for timeout handling
 ### 3. `cmd_start()` - Add flock
 - Add flock around critical section (count check + fork)
 - Track `fork_pid` for queue item timeout handling
 ### 4. Notification System
 New notification types:
 | Event | Type |
 |-------|------|
 | Task enqueued | `task_queued` |
 | Task dequeued | `task_dequeued` |
 | Task started | `task_started` |
 | Task completed | `task_completed` |
 | Task error | `task_error` |
 ### 5. Config
 - Remove `QUEUE_DAEMON_BATCH_SIZE` (no longer needed - batch size is now dynamic)
 ## Notification Flow
 | Event | Location | Type |
 |-------|----------|------|
 | Task enqueued | `enqueue_task()` | `task_queued` |
 | Task dequeued | `process_queue()` after state change to `notified` | `task_dequeued` |
 | Task started | `cmd_start()` after session file created | `task_started` |
 | Task completed | `update_queue_item_state()` | `task_completed` |
 | Task error | `update_queue_item_state()` | `task_error` |
 ## Out of Scope
 - Re-check loop in cmd_start (checking if session DB is reliable) - deferred to separate research issue
 - Buffer mechanism for excess forking (safety failsafe only)
 ## Status
 - [x] Issue created
 - [x] Implementation
 - [x] PR created (#147)
 - [ ] Merged
--- a/.gitignore
+++ b/.gitignore
@@ -4,4 +4,3 @@ results/
 */results/
 *.pyc
 .kugetsu/
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,18 +0,0 @@
 repos:
  - repo: https://github.com/shellcheck-py/shellcheck-py
    rev: v0.9.0.6
    hooks:
      - id: shellcheck
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.8
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/commitizen-tools/commitizen
    rev: v3.2.0
    hooks:
      - id: commitizen
        stages: [commit-msg]
--- 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 feat/issue-N-feature-name`
+1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b docs/topic-name`
 2. Make changes and commit with clear messages
 3. Open a Pull Request for review
-4. Do not merge directly to `main` or `develop` for reviewable changes
+4. Do not merge directly to `master` for reviewable changes
 5. After approval, squash and merge
 ## Guidelines
@@ -14,85 +14,10 @@
 - Keep PRs focused and reasonably sized
 - Document any non-obvious decisions
 - Test changes before submitting
 - See [VERSIONING.md](VERSIONING.md) for backport compatibility rules
 ## Pre-commit Hooks
 This repository uses [pre-commit](https://pre-commit.com/) for linting and commit message enforcement.
 ### Setup
 ```bash
 pip install pre-commit
 pre-commit install
 ```
 ### Hooks
 - **shellcheck** — Lints bash scripts
 - **ruff** — Lints and formats Python
 - **commitizen** — Enforces [Conventional Commits](https://www.conventionalcommits.org/) format
 ### Commit Message Format
 Use Conventional Commits format:
 ```
 type(scope): message
 # Examples
 fix(session): handle missing session gracefully
 feat(pm): add queue daemon for task delegation
 docs: update contributing guide
 ```
 Types: `fix`, `feat`, `docs`, `refactor`, `chore`, `test`
 ## Branches
-### Primary Branches
+- `master` — stable, reviewed content only
 - `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
- `refactor/*` — code refactoring (no behavior change)
+- `research/*` — new research notes
 ## 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
@@ -1,71 +0,0 @@
 # 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
@@ -1,130 +0,0 @@
 # 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/docs/kugetsu-architecture.md
+++ b/docs/kugetsu-architecture.md
@@ -326,7 +326,7 @@ When a Coding Agent starts, it:
 | Phase 1 | ✅ Complete | SSH + Tailscale remote access |
 | Phase 1b | ✅ Complete | Tailscale VPN setup |
 | Phase 2 | 📋 Planned | API Interface |
-| Phase 3 | ✅ Implemented | Chat Integration (Telegram) |
+| Phase 3 | 🔄 In Progress | Chat Integration (Telegram) |
 | Phase 4 | 📋 Planned | Web Dashboard |
 ### 6.2 Current Implementation
--- a/skills/kugetsu/SKILL.md
+++ b/skills/kugetsu/SKILL.md
@@ -48,9 +48,6 @@ A default config file is created during `kugetsu init` with commented examples:
 |----------|---------|-------------|
 | `MAX_CONCURRENT_AGENTS` | 3 | Maximum number of concurrent dev agents |
 | `KUGETSU_TEMP_DIR` | `~/.local/share/opencode/tool-output` | Temp directory for subagent tool output (useful in headless environments where /tmp is restricted) |
 | `KUGETSU_VERBOSITY` | `default` | PM agent verbosity level: `verbose`, `default`, or `quiet` |
 | `QUEUE_DAEMON_INTERVAL_MINUTES` | 5 | How often daemon polls queue (in minutes) |
 | `QUEUE_CLEANUP_AGE_DAYS` | 7 | Auto-cleanup completed/error items older than N days |
 ### Environment Variables for Agents
@@ -113,10 +110,6 @@ Each issue session gets its own git worktree to prevent conflicts:
 ├── worktrees/
 │   ├── github.com-shoko-kugetsu-14/     # Isolated workdir for issue #14
 │   └── github.com-shoko-kugetsu-15/     # Isolated workdir for issue #15
 ├── queue/
 │   ├── items/                      # Queue item JSON files
 │   ├── daemon.pid                   # Daemon process ID
 │   └── daemon.log                  # Daemon log output
 └── index.json                       # Maps session IDs and issue refs to session files
 ```
@@ -262,152 +255,23 @@ kugetsu destroy --base -y
 **Note**: Destroying base also destroys PM agent since PM depends on base.
 ### kugetsu delegate `<message>`
 Send a message to the PM agent for task coordination via queue:
 ```bash
 kugetsu delegate "work on issue #14"
 kugetsu delegate "review PR #92"
 ```
 - **Always enqueues** (fire-and-forget): returns immediately
 - Queue daemon polls queue and invokes PM when slots available
 - Tasks are processed FIFO (first-in-first-out)
 - Use `kugetsu queue list` to see pending tasks
 - Use `kugetsu queue-daemon logs` to debug queue processing
 ### kugetsu logs [n]
 Show recent delegation logs:
 ```bash
 kugetsu logs           # Show last 10 logs
 kugetsu logs 20       # Show last 20 logs
 ```
 - Logs are stored in `~/.kugetsu/logs/`
 - Automatically deletes logs older than 7 days
 ### kugetsu status
 Check if kugetsu is properly initialized:
 ```bash
 kugetsu status
 ```
 Output:
 - `kugetsu_not_initialized` - No index file
 - `base_session_missing` - Base session not found
 - `pm_agent_missing` - PM agent not found
 - `ok` - Everything is initialized
 ### kugetsu doctor [--fix]
 Diagnose and fix kugetsu issues:
 ```bash
 kugetsu doctor              # Show diagnostic info
 kugetsu doctor --fix        # Attempt automatic repairs
 ```
 - Checks index file existence
 - Validates base and PM agent sessions
 - With `--fix`: recreates PM agent if missing
 - With `--fix-permissions`: fixes session permissions in opencode database
 ### kugetsu notify [list|clear]
 Show or clear notifications from PM agent:
 ```bash
 kugetsu notify list         # Show unread notifications (default)
 kugetsu notify clear       # Mark all as read
 ```
 - PM agent writes task completion notifications to `~/.kugetsu/notifications.json`
 - Shows timestamp, type, message, and issue ref for each notification
 ### kugetsu server <list|add|remove|default|get>
 Manage git server configurations:
 ```bash
 kugetsu server list              # List all configured servers
 kugetsu server add github https://github.com    # Add a server
 kugetsu server remove gitlab    # Remove a server
 kugetsu server default github   # Set default server
 kugetsu server get github       # Get server URL
 ```
 ### kugetsu queue <list|stats|clear>
 Manage task queue for autonomous PM operation:
 ```bash
 kugetsu queue list              # Show queued tasks with status
 kugetsu queue stats            # Show queue statistics (total, pending, notified, completed, error)
 kugetsu queue clear            # Clean up old completed/error items
 kugetsu queue enqueue <issue-ref> <message>  # Manually enqueue a task
 ```
 **Queue Item States:**
 - `pending` - Waiting in queue, daemon can pick up
 - `notified` - PM agent has picked up the task
 - `completed` - Dev agent finished, PR created
 - `error` - Timeout or failure
 ### kugetsu queue-daemon <start|stop|restart|status|logs>
 Manage the queue daemon background process:
 ```bash
 kugetsu queue-daemon start     # Start daemon in background
 kugetsu queue-daemon stop      # Stop daemon
 kugetsu queue-daemon restart    # Restart daemon
 kugetsu queue-daemon status    # Check if daemon is running
 kugetsu queue-daemon logs       # Show recent daemon logs
 ```
 **Daemon Behavior:**
 1. Runs at configurable interval (default: 5 minutes)
 2. Checks if active agents < MAX_CONCURRENT_AGENTS
 3. Picks 1-N pending items (configurable batch size)
 4. Forks PM session for each picked item
 5. PM decides whether to use `start` or `continue`
 **Queue Directory:**
 ```
 ~/.kugetsu/queue/
 ├── items/                     # Queue item JSON files
 │   ├── q_1234567890.json    # One file per queued task
 │   └── q_1234567891.json
 ├── daemon.pid                # Daemon process ID
 ├── daemon.lock               # Daemon lock file
 └── daemon.log                # Daemon log output
 ```
 ## Workflow Example
 ### First-time Setup
 ```bash
-# Initialize kugetsu (requires TTY)
+# First-time setup (requires TTY)
 kugetsu init
 # Creates: base session + pm-agent session
-# Start the queue daemon (for autonomous operation)
+# Start work on issue
-kugetsu queue-daemon start
+kugetsu start github.com/shoko/kugetsu#14 "implement feature X"
-```
+# Creates: worktree at ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14/
-### Normal Workflow
+# Continue later
 ```bash
 # Enqueue tasks via delegate - agents will process them automatically
 kugetsu delegate "work on issue #14"
 kugetsu delegate "review PR #92"
 # Check queue status
 kugetsu queue list           # See pending tasks
 kugetsu queue stats         # See statistics
 # Debug queue daemon
 kugetsu queue-daemon status  # Is daemon running?
 kugetsu queue-daemon logs    # See daemon logs
 # Continue work on existing issue
 kugetsu continue github.com/shoko/kugetsu#14 "add tests"
 # Continue again
 kugetsu continue github.com/shoko/kugetsu#14 "fix failing test"
 # List all sessions
 kugetsu list
@@ -418,21 +282,6 @@ kugetsu prune --force
 kugetsu destroy github.com/shoko/kugetsu#14
 ```
 ### Queue Daemon Management
 ```bash
 # Check if daemon is running
 kugetsu queue-daemon status
 # View daemon logs for debugging
 kugetsu queue-daemon logs
 # Restart daemon if needed
 kugetsu queue-daemon restart
 # Stop daemon
 kugetsu queue-daemon stop
 ```
 ## Headless Operation
 This design solves the headless CLI limitation discovered in Issue #14:
--- a/skills/kugetsu/pm/SKILL.md
+++ b/skills/kugetsu/pm/SKILL.md
@@ -2,33 +2,6 @@ You are a PM (Project Manager) for software development.
 Your role is COORDINATOR. You break down requests, delegate work, monitor progress, and report results. You NEVER write code. Not even small fixes. Not even one-liners. Not even documentation. If asked to write code: delegate it using `kugetsu start`.
 ## Response Modes
 You have TWO response modes. Choose based on the user's request:
 ### Mode 1: Task Mode (Delegate)
 When the user asks for something that requires coding, implementation, or file changes:
 - "work on issue #81"
 - "close PR #42"
 - "create a PR for issue #91"
 - "fix the bug in login.js"
 - "add tests for the API"
 - Any request that modifies code or creates commits
 **Action:** Delegate using `kugetsu start` or `kugetsu continue`.
 ### Mode 2: Conversation Mode (Answer Directly)
 When the user asks a question that doesn't require code changes:
 - "show open issues"
 - "what is the current state of repo"
 - "hi"
 - "show me recent commits"
 - "what issues are being worked on"
 - "what branches exist"
 - Any informational query
 **Action:** Answer directly from available context or API calls.
 ## Write Permissions: Strict Boundary
 PM has EXPLICIT write boundaries. You can ONLY write to two specific locations.
@@ -45,116 +18,75 @@ PM has EXPLICIT write boundaries. You can ONLY write to two specific locations.
 - Any `.md` files, config files, scripts, or code
 ### If Asked to Write Outside ~/.kugetsu/:
-You MUST delegate to a dev agent using Task Mode.
+You MUST delegate to a dev agent:
 ```
 kugetsu start <domain>/<user>/<repo>#<issue> <task description>
 ```
 Where:
 - `<domain>` = git server (e.g., `github.com`, `gitlab.com`, `git.fbrns.co`)
 - `<user>` = git username (from `git config user.name`)
 - `<repo>` = repository name (from `git remote -v`)
 - `<issue>` = issue number to address
-## Tools for Delegation
+### New Kugetsu Scripts:
 Do NOT write new kugetsu scripts yourself (even for internal use). Delegate to a dev agent via the normal workflow:
 1. Create an issue describing the needed script
 2. Delegate: `kugetsu start <domain>/<user>/<repo>#<issue> Create new kugetsu script`
 3. After PR is merged, you may test the new script
-### kugetsu start
+**Example violations (DO NOT DO THESE):**
-Create a NEW dev agent session for an issue that has no existing session/worktree.
+- "Update SKILL.md" → DELEGATE, don't edit it yourself
 - "Fix the bug in login.js" → DELEGATE, don't write to repositories/
 - "Add a new script for queue management" → DELEGATE via issue/PR workflow
 ## Critical: How to Delegate
 Use `kugetsu start` to create dev agent sessions:
 ```
-kugetsu start <issue-ref> <task description>
+kugetsu start <domain>/<user>/<repo>#<issue> <task description>
 ```
-**Params:**
+**Domain/User/Repo**: Pull from `git remote -v` and `git config user.name` to make this agnostic to any git server.
 - `issue-ref`: Format `instance/user/repo#number`
  - Example: `github.com/shoko/kugetsu#81`
  - Example: `git.fbrns.co/shoko/kugetsu#118`
 - `task description`: What the agent should do (be specific)
-**Returns:** Creates new worktree and dev session, returns session ID
+**NOT `kugetsu delegate`** - that routes back to the PM (you). Use `kugetsu start` to create a NEW dev agent.
 **When to use:** When there is NO existing session or worktree for this issue.
 ---
 ### kugetsu continue
 Continue an EXISTING dev agent session that already has a worktree/session.
 ```
 kugetsu continue <issue-ref> [additional instructions]
 ```
 **Params:**
 - `issue-ref`: Format `instance/user/repo#number`
 - `additional instructions`: (optional) Extra context or changed instructions
 **Returns:** Continues existing session, returns session ID
 **When to use:** When a worktree/session already exists for this issue (check with `kugetsu list`).
 ---
 ### How to Choose: start vs continue
 | Scenario | Tool |
 |----------|------|
 | First time working on issue | `kugetsu start` |
 | Issue already has worktree/session | `kugetsu continue` |
 | Session exists but needs new task | `kugetsu continue <issue-ref> <new task>` |
 | Not sure if session exists | Check `kugetsu list` first, or use `kugetsu continue` (it will error if no session) |
 **NOT `kugetsu delegate`** - that routes back to the PM (you). Use `kugetsu start` or `kugetsu continue` to create a NEW dev agent.
 ## Your Identity
 You are the PM. Your job is to coordinate, not to code.
- You delegate ALL implementation tasks to dev agents using Task Mode
+- You delegate ALL implementation tasks to dev agents using `kugetsu start`
 - You answer informational queries directly in Conversation Mode
 - You review PRs but do not edit code yourself
 - You break down complex requests into delegate-able tasks
 - You monitor progress and keep stakeholders informed
-## Delegation is Your Default Behavior for Tasks
+## Delegation is Your Default Behavior
 When a request comes in:
-1. **Identify Mode** - Is this a task (code change needed) or a conversation (info request)?
+1. **Understand** - What needs to be built? What's the repo and issue?
-2. **For Tasks:**
+2. **Delegate** - Use `kugetsu start <issue-ref> <task>` to create a dev agent task
-   - **Understand** - What needs to be built? What's the repo and issue?
+3. **Monitor** - Watch for PR creation and review
-   - **Choose Tool** - Use `kugetsu start` (new) or `kugetsu continue` (existing)?
+4. **Report** - Post final results to the issue
   - **Delegate** - Call the appropriate tool with issue-ref and task
   - **Monitor** - Watch for PR creation and review
   - **Report** - Post final results to the issue
 3. **For Conversations:**
   - Answer directly using available context
 ## Few-Shot Examples
 **User:** "Fix the bug in login.js"
 **Mode:** Task
 **You:** `kugetsu start <domain>/<user>/<repo>#123 Investigate and fix the login bug in login.js`
 **User:** "Add tests for the API"
 **Mode:** Task
 **You:** `kugetsu start <domain>/<user>/<repo>#124 Write tests for the API module`
 **User:** "Can you write a quick script to parse this JSON?"
 **Mode:** Task
 **You:** `kugetsu start <domain>/<user>/<repo>#125 Create a script to parse the JSON file`
 **User:** "Update the README with installation instructions"
 **Mode:** Task
 **You:** `kugetsu start <domain>/<user>/<repo>#126 Update README with installation instructions`
 **User:** "Create a file at /tmp/test.txt"
 **Mode:** Task
 **You:** `kugetsu start <domain>/<user>/<repo>#127 Create a file at /tmp/test.txt`
-**User:** "What open issues do we have?"
+Notice: In every example, the correct response is to DELEGATE using `kugetsu start`, not to do it yourself.
 **Mode:** Conversation
 **You:** (Answer directly about open issues from the repository)
 **User:** "Show me recent commits"
 **Mode:** Conversation
 **You:** (Answer directly about recent commits)
 **User:** "Hi, how are you?"
 **Mode:** Conversation
 **You:** (Answer greeting directly)
 ---
 ## You Are the PM. You Coordinate. You Do Not Write Code.
@@ -162,4 +94,4 @@ This is not just a rule - it is your identity. The code you coordinate is built
 ---
-*PM Agent v5 - Coordinators coordinate. Delegation is for tasks, conversation is for questions. Strict write boundary: ONLY ~/.kugetsu/.*
+*PM Agent v4 - Coordinators coordinate, we do not code. Strict write boundary: ONLY ~/.kugetsu/.*
--- a/skills/kugetsu/scripts/kugetsu
+++ b/skills/kugetsu/scripts/kugetsu
--- a/skills/kugetsu/scripts/kugetsu-config.sh
+++ b/skills/kugetsu/scripts/kugetsu-config.sh
@@ -1,89 +0,0 @@
 #!/bin/bash
 set -euo pipefail
 KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
 SESSIONS_DIR="$KUGETSU_DIR/sessions"
 WORKTREES_DIR="$KUGETSU_DIR/worktrees"
 REPOS_CONFIG="$KUGETSU_DIR/repos.json"
 INDEX_FILE="$KUGETSU_DIR/index.json"
 NOTIFICATIONS_FILE="$KUGETSU_DIR/notifications.json"
 LOGS_DIR="$KUGETSU_DIR/logs"
 ENV_DIR="${ENV_DIR:-$KUGETSU_DIR/env}"
 VERBOSITY_DIR="$KUGETSU_DIR/verbosity"
 MAX_CONCURRENT_AGENTS="${MAX_CONCURRENT_AGENTS:-3}"
 KUGETSU_VERBOSITY="${KUGETSU_VERBOSITY:-default}"
 CONTEXT_DIR="${CONTEXT_DIR:-$KUGETSU_DIR/context}"
 ENABLE_CONTEXT_DUMP="${ENABLE_CONTEXT_DUMP:-true}"
 WORKTREE_CHECK_PR_STATUS="${WORKTREE_CHECK_PR_STATUS:-true}"
 QUEUE_DIR="${QUEUE_DIR:-$KUGETSU_DIR/queue}"
 QUEUE_ITEMS_DIR="${QUEUE_ITEMS_DIR:-$QUEUE_DIR/items}"
 QUEUE_DAEMON_PID_FILE="${QUEUE_DAEMON_PID_FILE:-$QUEUE_DIR/daemon.pid}"
 QUEUE_DAEMON_LOCK_FILE="${QUEUE_DAEMON_LOCK_FILE:-$QUEUE_DIR/daemon.lock}"
 QUEUE_DAEMON_LOG_FILE="${QUEUE_DAEMON_LOG_FILE:-$QUEUE_DIR/daemon.log}"
 QUEUE_DAEMON_INTERVAL_MINUTES="${QUEUE_DAEMON_INTERVAL_MINUTES:-5}"
 QUEUE_CLEANUP_AGE_DAYS="${QUEUE_CLEANUP_AGE_DAYS:-7}"
 TASK_TIMEOUT_HOURS="${TASK_TIMEOUT_HOURS:-1}"
 # Load user config overrides (~/.kugetsu/config)
 if [ -f "$KUGETSU_DIR/config" ]; then
    source "$KUGETSU_DIR/config"
 fi
 mask_sensitive_vars() {
    local line="${1:-}"
    for var in GITEA_TOKEN GITHUB_TOKEN GITLAB_TOKEN API_KEY PASSWORD TOKEN SECRET; do
        if [[ "$line" =~ $var ]]; then
            line=$(echo "$line" | sed -E "s/=.*/=***MASKED***/")
        fi
    done
    echo "$line"
 }
 strip_ansi_codes() {
    local line="${1:-}"
    echo "$line" | sed 's/\x1b\[[0-9;]*m//g' | sed 's/\x1b\[[0-9;]*[a-zA-Z]//g'
 }
 load_agent_env() {
    local agent_type="${1:-base}"
    local env_file="$ENV_DIR/${agent_type}.env"
    if [ -f "$env_file" ]; then
        set -a
        source "$env_file"
        set +a
    elif [ -f "$ENV_DIR/default.env" ]; then
        set -a
        source "$ENV_DIR/default.env"
        set +a
    elif [ -f "$ENV_DIR/pm-agent.env" ]; then
        set -a
        source "$ENV_DIR/pm-agent.env"
        set +a
    fi
 }
 set_debug_mode() {
    local filtered_args=()
    local debug_mode=false
    for arg in "$@"; do
        case "$arg" in
            --debug)
                debug_mode=true
                ;;
            *)
                filtered_args+=("$arg")
                ;;
        esac
    done
    if [ "$debug_mode" = true ]; then
        export KUGETSU_VERBOSITY="debug"
        echo "[DEBUG] Debug mode enabled" >&2
    fi
    echo "${filtered_args[@]}"
 }
--- a/skills/kugetsu/scripts/kugetsu-index.sh
+++ b/skills/kugetsu/scripts/kugetsu-index.sh
@@ -1,282 +0,0 @@
 #!/bin/bash
 set -euo pipefail
 read_index() {
    if [ -f "$INDEX_FILE" ]; then
        cat "$INDEX_FILE"
    else
        echo '{"base": null, "pm_agent": null, "issues": {}}'
    fi
 }
 write_index() {
    local base="$1"
    local pm_agent="$2"
    local issues_json="$3"
    local temp_file="$INDEX_FILE.tmp.$$"
    printf '{"base": %s, "pm_agent": %s, "issues": %s}\n' "$base" "$pm_agent" "$issues_json" > "$temp_file"
    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"
 }
 get_base_session_id() {
    local index=$(read_index)
    echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or '')"
 }
 get_pm_agent_session_id() {
    local index=$(read_index)
    echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or '')"
 }
 get_session_for_issue() {
    local issue_ref="$1"
    local index=$(read_index)
    echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('issues', {}).get('$issue_ref') or 'null')"
 }
 set_base_in_index() {
    local session_id="$1"
    local index=$(read_index)
    local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
    if [ "$session_id" = "null" ]; then
        write_index "null" "$pm_agent" "$issues"
    else
        if [ "$pm_agent" = "null" ]; then
            write_index "\"$session_id\"" "null" "$issues"
        else
            write_index "\"$session_id\"" "\"$pm_agent\"" "$issues"
        fi
    fi
 }
 set_pm_agent_in_index() {
    local session_id="$1"
    local index=$(read_index)
    local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
    if [ "$session_id" = "null" ]; then
        write_index "$base" "null" "$issues"
    else
        if [ "$base" = "null" ]; then
            write_index "null" "\"$session_id\"" "$issues"
        else
            write_index "\"$base\"" "\"$session_id\"" "$issues"
        fi
    fi
 }
 add_issue_to_index() {
    local issue_ref="$1"
    local session_file="$2"
    local index=$(read_index)
    local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
    local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
    issues=$(python3 -c "import sys, json; d=json.load(sys.stdin); d['$issue_ref']='$session_file'; print(json.dumps(d))" <<< "$issues")
    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() {
    local issue_ref="$1"
    local index=$(read_index)
    local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
    local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
    local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
    issues=$(python3 -c "import sys, json; d=json.load(sys.stdin); d.pop('$issue_ref', None); print(json.dumps(d))" <<< "$issues")
    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() {
    local issue_ref="$1"
    if [[ ! "$issue_ref" =~ ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+#[0-9]+$ ]]; then
        echo "Error: Invalid issue ref format: '$issue_ref'" >&2
        echo "Expected format: instance/user/repo#number" >&2
        echo "Example: github.com/shoko/kugetsu#14" >&2
        exit 1
    fi
 }
 update_session_pr_url() {
    local issue_ref="$1"
    local pr_url="$2"
    local session_file=$(get_session_for_issue "$issue_ref")
    if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
        echo "Error: No session found for '$issue_ref'" >&2
        return 1
    fi
    local session_path="$SESSIONS_DIR/$session_file"
    if [ ! -f "$session_path" ]; then
        echo "Error: Session file not found: $session_path" >&2
        return 1
    fi
    python3 << PYEOF
 import json
 session_path = "$session_path"
 pr_url = "$pr_url"
 with open(session_path, 'r') as f:
    session = json.load(f)
 session['pr_url'] = pr_url
 with open(session_path, 'w') as f:
    json.dump(session, f, indent=2)
    print(f"Updated PR URL for $issue_ref: $pr_url")
 PYEOF
 }
 # Convert issue ref to session filename
 issue_ref_to_filename() {
    local issue_ref="$1"
    echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
 }
 # Convert session filename back to issue ref
 filename_to_issue_ref() {
    local filename="$1"
    local name="${filename%.json}"
    echo "$name" | sed 's-\([0-9]*\)$-#\1-' | sed 's/-/\//g'
 }
 # Add notification to notifications file
 kugetsu_add_notification() {
    local type="$1"
    local message="$2"
    local issue_ref="${3:-}"
    local gitea_url="${4:-}"
    mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
    python3 << PYEOF
 import json
 import os
 from datetime import datetime
 notification = {
    "type": "$type",
    "message": "$message",
    "issue_ref": "$issue_ref" if "$issue_ref" else None,
    "gitea_url": "$gitea_url" if "$gitea_url" else None,
    "timestamp": datetime.now().isoformat(),
    "read": False
 }
 file_path = os.path.expanduser("$NOTIFICATIONS_FILE")
 notifications = []
 if os.path.exists(file_path):
    try:
        with open(file_path, 'r') as f:
            notifications = json.load(f)
    except:
        notifications = []
 notifications.append(notification)
 with open(file_path, 'w') as f:
    json.dump(notifications, f, indent=2)
 print("Notification added")
 PYEOF
 }
 # Update queue item state
 update_queue_item_state() {
    local queue_id="$1"
    local new_state="$2"
    local session_id="${3:-}"
    local pid="${4:-}"
    local item_file="$QUEUE_ITEMS_DIR/${queue_id}.json"
    if [ ! -f "$item_file" ]; then
        echo "Error: Queue item not found: $queue_id" >&2
        return 1
    fi
    local issue_ref=$(python3 -c "import json; print(json.load(open('$item_file')).get('issue_ref', ''))" 2>/dev/null || echo "")
    python3 << PYEOF
 import json
 from datetime import datetime
 item_file = "$item_file"
 new_state = "$new_state"
 session_id = "$session_id"
 pid = "$pid"
 with open(item_file, 'r') as f:
    item = json.load(f)
 item['state'] = new_state
 if new_state == "notified":
    item['notified_at'] = datetime.now().isoformat() + "Z"
    if session_id:
        item['opencode_session_id'] = session_id
    if pid:
        item['pid'] = int(pid) if pid.isdigit() else None
 elif new_state == "completed":
    item['completed_at'] = datetime.now().isoformat() + "Z"
 elif new_state == "error":
    item['error'] = datetime.now().isoformat() + "Z"
 with open(item_file, 'w') as f:
    json.dump(item, f, indent=2)
 print(f"Updated $queue_id to state: $new_state")
 PYEOF
    if [ "$new_state" = "completed" ]; then
        kugetsu_add_notification "task_completed" "Task completed: $issue_ref" "$issue_ref"
    elif [ "$new_state" = "error" ]; then
        kugetsu_add_notification "task_error" "Task error: $issue_ref" "$issue_ref"
    fi
 }
--- a/skills/kugetsu/scripts/kugetsu-log.sh
+++ b/skills/kugetsu/scripts/kugetsu-log.sh
@@ -1,136 +0,0 @@
 #!/bin/bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/kugetsu-config.sh"
 log() {
    local level="${1:-}"
    local component="${2:-}"
    local message="${3:-}"
    local timestamp
    timestamp=$(date -Iseconds)
    case "$level" in
        info|warn|error|debug) ;;
        *)
            echo "Error: log level must be info|warn|error|debug" >&2
            return 1
            ;;
    esac
    if [ -z "$message" ]; then
        message="$component"
        component="${level}"
        level="info"
    fi
    local masked
    masked=$(mask_sensitive_vars "$message")
    echo "[$timestamp] $level $component $masked"
 }
 log_debug() { log "debug" "$1" "${2:-}"; }
 log_info()  { log "info"  "$1" "${2:-}"; }
 log_warn()  { log "warn"  "$1" "${2:-}"; }
 log_error() { log "error" "$1" "${2:-}"; }
 cmd_logs() {
    local count="${1:-10}"
    if [ ! -d "$LOGS_DIR" ]; then
        echo "No logs found."
        return
    fi
    find "$LOGS_DIR" -type f -mtime +7 -delete 2>/dev/null
    ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | while read line; do
        echo "$line"
    done
    echo ""
    echo "Recent log contents:"
    echo "===================="
    for log in $(ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | awk '{print $NF}'); do
        if [ -f "$LOGS_DIR/$log" ]; then
            echo ""
            echo "--- $log ---"
            tail -20 "$LOGS_DIR/$log" | while read line; do
                line=$(strip_ansi_codes "$line")
                line=$(mask_sensitive_vars "$line")
                echo "  $line"
            done
        fi
    done
 }
 kugetsu_add_notification() {
    local notification_type="$1"
    local message="$2"
    local issue_ref="${3:-}"
    local timestamp=$(date -Iseconds)
    mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
    local notifications="[]"
    if [ -f "$NOTIFICATIONS_FILE" ]; then
        notifications=$(cat "$NOTIFICATIONS_FILE")
    fi
    notifications=$(echo "$notifications" | python3 -c "
 import json
 import sys
 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"
 }
 cmd_notify() {
    local action="${1:-list}"
    case "$action" in
        list)
            if [ ! -f "$NOTIFICATIONS_FILE" ]; then
                echo "No notifications."
                return
            fi
            local notifications=$(cat "$NOTIFICATIONS_FILE")
            local count=$(echo "$notifications" | python3 -c "import sys, json; n=json.load(sys.stdin); print(sum(1 for x in n if not x.get('read', False)))")
            if [ "$count" -eq 0 ]; then
                echo "No unread notifications."
                return
            fi
            echo "Unread notifications ($count):"
            echo "$notifications" | python3 -c "import sys, json; [print(f\"  [{x.get('timestamp', '')}] {x.get('type', '')}: {x.get('message', '')}\") for x in json.load(sys.stdin) if not x.get('read', False)]"
            ;;
        clear)
            if [ -f "$NOTIFICATIONS_FILE" ]; then
                python3 -c "import json; print(json.dumps([x for x in json.load(open('$NOTIFICATIONS_FILE')) if x.get('read', False)], indent=2))" > "$NOTIFICATIONS_FILE"
                echo "Cleared unread notifications."
            fi
            ;;
        *)
            echo "Usage: kugetsu notify [list|clear]" >&2
            exit 1
            ;;
    esac
 }
--- a/skills/kugetsu/scripts/kugetsu-queue-daemon.sh
+++ b/skills/kugetsu/scripts/kugetsu-queue-daemon.sh
@@ -1,142 +0,0 @@
 #!/bin/bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/kugetsu-config.sh"
 source "$SCRIPT_DIR/kugetsu-index.sh"
 source "$SCRIPT_DIR/kugetsu-worktree.sh"
 source "$SCRIPT_DIR/kugetsu-log.sh"
 load_agent_env "pm-agent"
 acquire_lock() {
    local issue_ref="$1"
    local lock_file="$QUEUE_DIR/locks/$(echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/').lock"
    mkdir -p "$(dirname "$lock_file")"
    if [ -f "$lock_file" ]; then
        local pid=$(cat "$lock_file" 2>/dev/null || echo "")
        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
            return 1
        fi
        rm -f "$lock_file"
    fi
    echo $$ > "$lock_file"
    return 0
 }
 release_lock() {
    local issue_ref="$1"
    local lock_file="$QUEUE_DIR/locks/$(echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/').lock"
    rm -f "$lock_file"
 }
 check_task_completion() {
    local item="$1"
    local queue_id=$(basename "$item" .json)
    local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
    [ "$state" = "notified" ] || return 0
    local session_id=$(python3 -c "import json; print(json.load(open('$item')).get('opencode_session_id', ''))" 2>/dev/null)
    local issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
    local pid=$(python3 -c "import json; print(json.load(open('$item')).get('pid', ''))" 2>/dev/null)
    if [ -n "$pid" ] && [ "$pid" != "None" ]; then
        if ! kill -0 "$pid" 2>/dev/null; then
            local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$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"
    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
    release_lock "$issue_ref"
 }
 while true; do
    if [ -d "$QUEUE_ITEMS_DIR" ]; then
        for item in "$QUEUE_ITEMS_DIR"/*.json; do
            [ -f "$item" ] || continue
            check_task_completion "$item"
        done
        for item in "$QUEUE_ITEMS_DIR"/*.json; do
            [ -f "$item" ] || continue
            state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
            if [ "$state" = "pending" ]; then
                process_task "$item"
            fi
        done
    fi
    sleep "${QUEUE_DAEMON_INTERVAL_MINUTES:-5}m"
 done
--- a/skills/kugetsu/scripts/kugetsu-session.sh
+++ b/skills/kugetsu/scripts/kugetsu-session.sh
@@ -1,784 +0,0 @@
 #!/bin/bash
 set -euo pipefail
 # Source required modules for session management functions
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/kugetsu-config.sh"
 source "$SCRIPT_DIR/kugetsu-index.sh"
 source "$SCRIPT_DIR/kugetsu-worktree.sh"
 source "$SCRIPT_DIR/kugetsu-log.sh"
 count_active_dev_sessions() {
    local count=0
    if [ -d "$SESSIONS_DIR" ]; then
        for session_file in "$SESSIONS_DIR"/*.json; do
            if [ -f "$session_file" ]; then
                local filename=$(basename "$session_file")
                if [ "$filename" != "base.json" ] && [ "$filename" != "pm-agent.json" ]; then
                    count=$((count + 1))
                fi
            fi
        done
    fi
    echo "$count"
 }
 cmd_init() {
    local force=false
    while [ $# -gt 0 ]; do
        case "$1" in
            --force)
                force=true
                ;;
            *)
                ;;
        esac
        shift
    done
    ensure_dirs
    if [ ! -f "$KUGETSU_DIR/config" ]; then
        cat > "$KUGETSU_DIR/config" << 'EOF'
 # User configuration overrides
 # Values set here take precedence over defaults
 # Changes take effect immediately (no re-init needed)
 # Max concurrent dev agents (default: 3)
 # MAX_CONCURRENT_AGENTS=5
 # Git server configurations
 # Format: GIT_SERVERS["hostname"]="https://hostname"
 declare -A GIT_SERVERS
 GIT_SERVERS["github.com"]="https://github.com"
 GIT_SERVERS["git.fbrns.co"]="https://git.fbrns.co"
 DEFAULT_GIT_SERVER="github.com"
 EOF
        echo "Created config file: $KUGETSU_DIR/config"
    fi
    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
            exit 1
        fi
    fi
    if ! test -t 0; then
        echo "Error: init requires a terminal (TTY)" >&2
        echo "Please run this command in an interactive shell" >&2
        exit 1
    fi
    echo "Starting TUI to create base session..."
    echo "Press Ctrl+C to cancel or wait for session to be created"
    sleep 2
    local before_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
    opencode
    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
    fi
    echo "$session_ids" > "$SESSIONS_DIR/base.json"
    set_base_in_index "$session_ids"
    echo "Base session created: $session_ids"
    echo "Starting PM agent..."
    before_sessions="$after_sessions"
    opencode
    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"
    fi
    echo "$pm_session_ids" > "$SESSIONS_DIR/pm-agent.json"
    set_pm_agent_in_index "$pm_session_ids"
    load_agent_env "pm-agent"
    local pm_system_prompt=""
    if [ -f "$KUGETSU_DIR/pm-agent.md" ]; then
        pm_system_prompt=$(cat "$KUGETSU_DIR/pm-agent.md")
        echo "Injecting PM agent system prompt from $KUGETSU_DIR/pm-agent.md"
    fi
    echo "PM agent session created: $pm_session_ids"
    echo ""
    echo "kugetsu initialized successfully!"
    echo "  Base session: $session_ids"
    echo "  PM agent: $pm_session_ids"
 }
 extract_issue_ref_from_message() {
    local message="$1"
    if [ -z "$message" ]; then
        echo ""
        return
    fi
    if [[ "$message" =~ ^([a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+#[0-9]+) ]]; then
        echo "${BASH_REMATCH[1]}"
        return
    fi
    if [[ "$message" =~ (https?://)?([a-zA-Z0-9.-]+)/([a-zA-Z0-9._-]+)/([a-zA-Z0-9._-]+)/(issues|pull)/([0-9]+) ]]; then
        local 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
    echo ""
 }
 cmd_delegate() {
    local message="${1:-}"
    if [ -z "$message" ]; then
        echo "Error: message is required" >&2
        echo "Usage: kugetsu delegate <message>" >&2
        exit 1
    fi
    local issue_ref=$(extract_issue_ref_from_message "$message")
    if [ -n "$issue_ref" ] && [[ "$issue_ref" =~ \#[0-9]+$ ]]; then
        # Enqueue for daemon to process via cmd_start/cmd_continue
        enqueue_task "$issue_ref" "$message"
        return
    fi
    # No issue ref detected — 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"
    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 &
    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_set=$(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" >/dev/null 2>&1
    sleep 1
    local after_json=$(opencode session list --format=json 2>/dev/null)
    local after_sessions=$(echo "$after_json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); [print(s['id']) for s in sessions]" 2>/dev/null || true)
    local new_session_id=""
    while IFS= read -r sess; do
        if [[ -n "$sess" ]] && [[ ! "$before_set" =~ \|${sess}\| ]]; then
            new_session_id="$sess"
            break
        fi
    done <<< "$after_sessions"
    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")
    if [ -n "$user_message" ]; then
        cat <<EOF
 You are assigned to work on $issue_ref.
 IMPORTANT: Follow the workflow below as your guideline, but prioritize the delegator's message.
 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 using: tea pr create --repo $owner/$repo --title "Your PR title" --body "PR description"
   - Make sure you are logged in with: tea login add --name gitea --token \$GITEA_TOKEN --url https://$instance
   - If tea is not available, use: curl -X POST "https://$instance/api/v1/repos/$owner/$repo/pulls" -H "Authorization: Bearer \$GITEA_TOKEN" -H "Content-Type: application/json" -d '{"title":"PR Title","head":"branch-name","base":"main","body":"PR description"}'
 Tools for PR interaction:
 - Post issue/PR comment: curl -X POST "https://$instance/api/v1/repos/$owner/$repo/issues/$number/comments" -H "Authorization: Bearer \$GITEA_TOKEN" -H "Content-Type: application/json" -d '{"body":"Your comment"}'
 - List PR comments: curl -s "https://$instance/api/v1/repos/$owner/$repo/issues/$number/comments" -H "Authorization: Bearer \$GITEA_TOKEN"
 - List PR reviews: curl -s "https://$instance/api/v1/repos/$owner/$repo/pulls/$number/reviews" -H "Authorization: Bearer \$GITEA_TOKEN"
 - Merge PR (only with approval): tea pr merge --repo $owner/$repo $number --style merge
  - MERGING requires approval first! Check for: approval in reviews, OR "lgtm"/"approved" in comments
  - If no approval, ask reviewer to approve first before merging
 Delegator's message:
 $user_message
 Work directory: $worktree_path
 EOF
    else
        cat <<EOF
 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 using: tea pr create --repo $owner/$repo --title "Your PR title" --body "PR description"
   - Make sure you are logged in with: tea login add --name gitea --token \$GITEA_TOKEN --url https://$instance
   - If tea is not available, use: curl -X POST "https://$instance/api/v1/repos/$owner/$repo/pulls" -H "Authorization: Bearer \$GITEA_TOKEN" -H "Content-Type: application/json" -d '{"title":"PR Title","head":"branch-name","base":"main","body":"PR description"}'
 Tools for PR interaction:
 - Post issue/PR comment: curl -X POST "https://$instance/api/v1/repos/$owner/$repo/issues/$number/comments" -H "Authorization: Bearer \$GITEA_TOKEN" -H "Content-Type: application/json" -d '{"body":"Your comment"}'
 - List PR comments: curl -s "https://$instance/api/v1/repos/$owner/$repo/issues/$number/comments" -H "Authorization: Bearer \$GITEA_TOKEN"
 - List PR reviews: curl -s "https://$instance/api/v1/repos/$owner/$repo/pulls/$number/reviews" -H "Authorization: Bearer \$GITEA_TOKEN"
 - Merge PR (only with approval): tea pr merge --repo $owner/$repo $number --style merge
  - MERGING requires approval first! Check for: approval in reviews, OR "lgtm"/"approved" in comments
  - If no approval, ask reviewer to approve first before merging
 Work directory: $worktree_path
 EOF
    fi
 }
 ensure_worktree() {
    local issue_ref="$1"
    if worktree_exists "$issue_ref" "$WORKTREES_DIR"; then
        log "info" "ensure_worktree" "Worktree already exists for $issue_ref"
        echo "existed"
        return 0
    fi
    local base_session_id=$(get_base_session_id)
    if [ -z "$base_session_id" ] || [ "$base_session_id" = "null" ]; then
        log "error" "ensure_worktree" "Base session not found for $issue_ref"
        echo "error"
        return 1
    fi
    local active_count=$(count_active_dev_sessions)
    if [ "$active_count" -ge "${MAX_CONCURRENT_AGENTS:-3}" ]; then
        log "error" "ensure_worktree" "Max concurrent agents reached for $issue_ref"
        echo "error"
        return 1
    fi
    if create_worktree "$issue_ref" "$WORKTREES_DIR" 2>&1 | tee >(cat >&2); then
        log "info" "ensure_worktree" "Created worktree for $issue_ref"
        echo "created"
        return 0
    else
        log "error" "ensure_worktree" "Failed to create worktree for $issue_ref"
        echo "error"
        return 1
    fi
 }
 ensure_session() {
    local issue_ref="$1"
    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" "$WORKTREES_DIR"; then
        worktree_exists=true
    fi
    local session_exists=false
    if [ -f "$session_path" ]; then
        session_exists=true
    fi
    if $worktree_exists && $session_exists; then
        log "info" "ensure_session" "Session already exists for $issue_ref"
        echo "continued"
        return 0
    fi
    if ! $worktree_exists && $session_exists; then
        log "warn" "ensure_session" "Session exists but worktree is missing. Removing stale session..."
        rm -f "$session_path"
        remove_issue_from_index "$issue_ref"
        session_exists=false
    fi
    if ! $worktree_exists; then
        local wt_status=$(ensure_worktree "$issue_ref")
        if [ "$wt_status" != "created" ] && [ "$wt_status" != "existed" ]; then
            log "error" "ensure_session" "Failed to ensure worktree for $issue_ref"
            echo "error"
            return 1
        fi
    fi
    local base_session_id=$(get_base_session_id)
    if [ -z "$base_session_id" ] || [ "$base_session_id" = "null" ]; then
        log "error" "ensure_session" "Base session not found for $issue_ref"
        echo "error"
        return 1
    fi
    local new_session_id=$(create_session "$base_session_id")
    if [ -z "$new_session_id" ]; then
        log "error" "ensure_session" "Could not create session for $issue_ref"
        echo "error"
        return 1
    fi
    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref")
    printf '{"type": "forked", "issue_ref": "%s", "opencode_session_id": "%s", "worktree_path": "%s", "created_at": "%s", "state": "idle"}\n' \
        "$issue_ref" "$new_session_id" "$worktree_path" "$(date -Iseconds)" > "$SESSIONS_DIR/$session_file"
    add_issue_to_index "$issue_ref" "$session_file"
    log "info" "ensure_session" "Created session for $issue_ref: $new_session_id"
    echo "created"
    return 0
 }
 fork_agent() {
    local session_id="$1"
    local worktree_path="$2"
    local message="$3"
    if [ -z "$worktree_path" ] || [ ! -d "$worktree_path" ]; then
        log "error" "fork_agent" "Invalid worktree path: $worktree_path"
        echo "error"
        return 1
    fi
    load_agent_env "dev"
    cd "$worktree_path"
    local sanitized_id=$(echo "$session_id" | sed 's/[^a-zA-Z0-9_-]/_/g')
    mkdir -p "$worktree_path/.kugetsu"
    if [ ! -f "$worktree_path/.gitignore" ] || ! grep -q "^.kugetsu/" "$worktree_path/.gitignore"; then
        echo ".kugetsu/" >> "$worktree_path/.gitignore" 2>/dev/null || true
    fi
    local msg_file="$worktree_path/.kugetsu/msg.txt"
    printf '%s' "$message" > "$msg_file"
    nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$session_id'" >> "$LOGS_DIR/dev-$sanitized_id.log" 2>&1 &
    log "info" "fork_agent" "Forked agent for session $session_id in $worktree_path"
    echo "forked"
    return 0
 }
 cmd_start() {
    cmd_continue "$@"
 }
 cmd_continue() {
    local issue_ref="${1:-}"
    local message="${2:-}"
    if [ -z "$issue_ref" ]; then
        echo "Error: issue ref is required" >&2
        echo "Usage: kugetsu continue <issue-ref> [message]" >&2
        exit 1
    fi
    validate_issue_ref "$issue_ref"
    if [ -z "$message" ]; then
        message=$(build_dev_agent_message "$issue_ref" "")
    else
        message=$(build_dev_agent_message "$issue_ref" "$message")
    fi
    local worktree_status=$(ensure_worktree "$issue_ref")
    if [ "$worktree_status" = "error" ]; then
        echo "Error: Failed to ensure worktree for '$issue_ref'" >&2
        exit 1
    fi
    local session_status=$(ensure_session "$issue_ref")
    if [ "$session_status" = "error" ]; then
        echo "Error: Failed to ensure session for '$issue_ref'" >&2
        exit 1
    fi
    kugetsu_context_dump "$issue_ref" "$message" "$(issue_ref_to_branch_name "$issue_ref")"
    local session_file=$(issue_ref_to_filename "$issue_ref")
    local session_path="$SESSIONS_DIR/$session_file"
    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 fork_status=$(fork_agent "$opencode_session_id" "$worktree_path" "$message")
    if [ "$fork_status" = "error" ]; then
        echo "Error: Failed to fork agent for '$issue_ref'" >&2
        exit 1
    fi
    log "info" "cmd_continue" "Result for $issue_ref: worktree=$worktree_status session=$session_status fork=$fork_status"
    echo "Session continued for '$issue_ref': $opencode_session_id"
    echo "Worktree: $worktree_path"
    echo "${worktree_status}-${session_status}-${fork_status}"
 }
 cmd_list() {
    echo "=== kugetsu sessions ==="
    echo ""
    local base_id=$(get_base_session_id)
    if [ -n "$base_id" ] && [ "$base_id" != "null" ]; then
        echo "Base session: $base_id"
    else
        echo "Base session: not initialized"
    fi
    local pm_id=$(get_pm_agent_session_id)
    if [ -n "$pm_id" ] && [ "$pm_id" != "null" ]; then
        echo "PM agent: $pm_id"
    else
        echo "PM agent: not initialized"
    fi
    echo ""
    echo "Issue sessions:"
    if [ -d "$SESSIONS_DIR" ]; then
        for session_file in "$SESSIONS_DIR"/*.json; do
            if [ -f "$session_file" ]; then
                local filename=$(basename "$session_file")
                if [ "$filename" != "base.json" ] && [ "$filename" != "pm-agent.json" ]; then
                    local issue_ref=$(filename_to_issue_ref "$filename")
                    local opencode_sid=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', 'unknown'))" 2>/dev/null || echo "unknown")
                    local state=$(python3 -c "import json; print(json.load(open('$session_file')).get('state', 'unknown'))" 2>/dev/null || echo "unknown")
                    local worktree_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
                    local worktree_status=""
                    if [ -n "$worktree_path" ]; then
                        if [ -d "$worktree_path" ]; then
                            worktree_status="(worktree exists)"
                        else
                            worktree_status="(worktree MISSING)"
                        fi
                    fi
                    echo "  $filename"
                    echo "    Issue: $issue_ref"
                    echo "    Session: $opencode_sid"
                    echo "    State: $state"
                    echo "    $worktree_status"
                fi
            fi
        done
    fi
    if [ -d "$WORKTREES_DIR" ]; then
        echo ""
        echo "Worktrees without sessions:"
        for worktree in $(find "$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null); do
            local worktree_name=$(basename "$worktree")
            local has_session=false
            for session_file in "$SESSIONS_DIR"/*.json; do
                if [ -f "$session_file" ]; then
                    local wt_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
                    if [ "$wt_path" = "$worktree" ]; then
                        has_session=true
                        break
                    fi
                fi
            done
            if [ "$has_session" = false ]; then
                echo "  $worktree_name (no session)"
            fi
        done
    fi
 }
 cmd_prune() {
    local force=false
    if [ "$1" = "--force" ]; then
        force=true
    fi
    echo "=== kugetsu prune ==="
    echo ""
    local orphaned=()
    if [ -d "$SESSIONS_DIR" ]; then
        for session_file in "$SESSIONS_DIR"/*.json; do
            [ -f "$session_file" ] || continue
            local filename=$(basename "$session_file")
            if [ "$filename" = "base.json" ] || [ "$filename" = "pm-agent.json" ]; then
                continue
            fi
            local opencode_sid=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', ''))" 2>/dev/null || echo "")
            if [ -n "$opencode_sid" ]; then
                local exists=$(opencode session list 2>/dev/null | grep -c "^$opencode_sid" || echo "0")
                if [ "$exists" -eq 0 ]; then
                    orphaned+=("$session_file")
                fi
            else
                orphaned+=("$session_file")
            fi
        done
    fi
    if [ ${#orphaned[@]} -eq 0 ]; then
        echo "No orphaned sessions found."
        return
    fi
    echo "Found ${#orphaned[@]} orphaned session(s):"
    for session in "${orphaned[@]}"; do
        echo "  $session"
    done
    echo ""
    if [ "$force" = false ]; then
        read -p "Remove these sessions? [y/N] " -r answer
        if [[ ! "$answer" =~ ^[Yy]$ ]]; then
            echo "Aborted."
            return
        fi
    fi
    for session in "${orphaned[@]}"; do
        local issue_ref=$(python3 -c "import json; print(json.load(open('$session')).get('issue_ref', ''))" 2>/dev/null || echo "")
        local worktree_path=$(python3 -c "import json; print(json.load(open('$session')).get('worktree_path', ''))" 2>/dev/null || echo "")
        if [ -n "$worktree_path" ] && [ -d "$worktree_path" ]; then
            echo "Removing worktree: $worktree_path"
            git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
        fi
        rm -f "$session"
        if [ -n "$issue_ref" ]; then
            remove_issue_from_index "$issue_ref"
        fi
        echo "Removed: $session"
    done
    echo ""
    echo "Pruned ${#orphaned[@]} orphaned session(s)."
 }
 cmd_destroy() {
    local target="${1:-}"
    local force=false
    if [ "${2:-}" = "-y" ]; then
        force=true
    fi
    if [ -z "$target" ]; then
        echo "Error: target is required" >&2
        echo "Usage: kugetsu destroy <issue-ref> [-y]" >&2
        echo "       kugetsu destroy --pm-agent [-y]" >&2
        echo "       kugetsu destroy --base [-y]" >&2
        exit 1
    fi
    if [ "$target" = "--pm-agent" ]; then
        if [ "$force" = false ]; then
            echo "Warning: Destroying PM agent session is not recommended." >&2
            read -p "Continue? [y/N] " -r answer
            if [[ ! "$answer" =~ ^[Yy]$ ]]; then
                echo "Aborted."
                return
            fi
        fi
        local pm_session=$(get_pm_agent_session_id)
        if [ -n "$pm_session" ] && [ "$pm_session" != "null" ]; then
            echo "Stopping PM agent session: $pm_session"
            opencode session stop "$pm_session" 2>/dev/null || true
        fi
        rm -f "$SESSIONS_DIR/pm-agent.json"
        set_pm_agent_in_index "null"
        echo "PM agent session destroyed"
    elif [ "$target" = "--base" ]; then
        if [ "$force" = false ]; then
            echo "Warning: Destroying base session will remove ALL sessions." >&2
            read -p "Continue? [y/N] " -r answer
            if [[ ! "$answer" =~ ^[Yy]$ ]]; then
                echo "Aborted."
                return
            fi
        fi
        for session_file in "$SESSIONS_DIR"/*.json; do
            [ -f "$session_file" ] || continue
            rm -f "$session_file"
        done
        for worktree in "$WORKTREES_DIR"/.kugetsu-worktrees/*; do
            if [ -d "$worktree" ]; then
                git worktree remove "$worktree" 2>/dev/null || rm -rf "$worktree"
            fi
        done
        write_index "null" "null" "{}"
        echo "Base session and all worktrees destroyed"
    else
        validate_issue_ref "$target"
        local session_file=$(get_session_for_issue "$target")
        if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
            echo "Error: No session found for '$target'" >&2
            exit 1
        fi
        local session_path="$SESSIONS_DIR/$session_file"
        if [ "$force" = true ]; then
            remove_worktree_for_issue "$target"
            rm -f "$session_path"
            remove_issue_from_index "$target"
            echo "Session for '$target' destroyed"
        else
            echo "Warning: This will delete session and worktree for '$target'" >&2
            read -p "Continue? [y/N] " -r answer
            if [[ ! "$answer" =~ ^[Yy]$ ]]; then
                echo "Aborted."
                return
            fi
            remove_worktree_for_issue "$target"
            rm -f "$session_path"
            remove_issue_from_index "$target"
            echo "Session for '$target' destroyed"
        fi
    fi
 }
 cmd_status() {
    echo "=== kugetsu status ==="
    local base_id=$(get_base_session_id)
    local pm_id=$(get_pm_agent_session_id)
    if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
        echo "Status: Not initialized"
        echo "Run 'kugetsu init' to initialize."
        return
    fi
    echo "Base session: $base_id"
    if [ -n "$pm_id" ] && [ "$pm_id" != "null" ]; then
        echo "PM agent: $pm_id"
    else
        echo "PM agent: not running"
    fi
    local active_count=$(count_active_dev_sessions)
    echo "Active issue sessions: $active_count / ${MAX_CONCURRENT_AGENTS:-3}"
    echo ""
    echo "OpenCode sessions:"
    opencode session list 2>/dev/null || echo "  (unable to list sessions)"
 }
--- a/skills/kugetsu/scripts/kugetsu-worktree.sh
+++ b/skills/kugetsu/scripts/kugetsu-worktree.sh
@@ -1,167 +0,0 @@
 #!/bin/bash
 set -euo pipefail
 issue_ref_to_worktree_name() {
    local issue_ref="$1"
    echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
 }
 issue_ref_to_worktree_path() {
    local issue_ref="$1"
    local parent_dir="${2:-$WORKTREES_DIR}"
    local worktree_name=$(issue_ref_to_worktree_name "$issue_ref")
    echo "$parent_dir/$worktree_name"
 }
 issue_ref_to_branch_name() {
    local issue_ref="$1"
    local number_part=$(echo "$issue_ref" | grep -oE '#[0-9]+$' || echo "")
    if [ -n "$number_part" ]; then
        echo "fix/issue-${number_part#\#}"
    else
        local identifier=$(echo "$issue_ref" | grep -oE '#[^-]+$' || echo "")
        if [ -n "$identifier" ]; then
            local clean_id=$(echo "$identifier" | sed 's/^#//' | sed 's/-/_/g')
            echo "fix/${clean_id}"
        else
            echo "fix/issue-temp"
        fi
    fi
 }
 get_repo_url() {
    local issue_ref="$1"
    if [ -f "$REPOS_CONFIG" ]; then
        local url=$(python3 -c "import json, sys; d=json.load(open('$REPOS_CONFIG')); print(d.get('$issue_ref', ''))" 2>/dev/null || echo "")
        if [ -n "$url" ]; then
            echo "$url"
            return
        fi
    fi
    local instance=$(echo "$issue_ref" | cut -d'/' -f1 | cut -d'#' -f1)
    local rest=$(echo "$issue_ref" | sed 's/^[^\/]*\///' | sed 's/#.*//')
    if [ -n "${GIT_SERVERS[$instance]:-}" ]; then
        echo "${GIT_SERVERS[$instance]}/${rest}.git"
        return
    fi
    if [ -n "${GIT_SERVERS[$DEFAULT_GIT_SERVER]:-}" ]; then
        echo "${GIT_SERVERS[$DEFAULT_GIT_SERVER]}/${rest}.git"
        return
    fi
    echo "https://${instance}/${rest}.git"
 }
 worktree_exists() {
    local issue_ref="$1"
    local parent_dir="${2:-$PWD}"
    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
    [ -d "$worktree_path" ]
 }
 create_worktree() {
    local issue_ref="$1"
    local parent_dir="${2:-$PWD}"
    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
    local branch_name=$(issue_ref_to_branch_name "$issue_ref")
    local repo_url=$(get_repo_url "$issue_ref")
    if [ -z "$repo_url" ]; then
        echo "Error: Cannot determine repo URL for '$issue_ref'" >&2
        echo "Please add to $REPOS_CONFIG or ensure worktree exists" >&2
        exit 1
    fi
    local worktree_parent_dir=$(dirname "$worktree_path")
    mkdir -p "$worktree_parent_dir"
    if worktree_exists "$issue_ref" "$parent_dir"; then
        echo "Removing existing worktree at '$worktree_path'..."
        git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
    fi
    echo "Creating worktree at '$worktree_path'..."
    git clone "$repo_url" "$worktree_path" 2>/dev/null || {
        echo "Error: Failed to clone repository" >&2
        exit 1
    }
    echo "Creating branch '$branch_name'..."
    (cd "$worktree_path" && git checkout -b "$branch_name" origin/main 2>/dev/null || git checkout -b "$branch_name" main 2>/dev/null) || {
        echo "Warning: Could not checkout branch (may need to run from within worktree after session)" >&2
    }
    echo "Worktree created at: $worktree_path"
 }
 remove_worktree_for_issue() {
    local issue_ref="$1"
    local parent_dir="${2:-$PWD}"
    local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
    if worktree_exists "$issue_ref" "$parent_dir"; then
        echo "Removing worktree at '$worktree_path'..."
        git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
    fi
 }
 get_worktree_path_for_session() {
    local session_file="$1"
    if [ -f "$session_file" ]; then
        python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo ""
    else
        echo ""
    fi
 }
 check_pr_status() {
    local pr_url="$1"
    if [ -z "$pr_url" ]; then
        echo "no_pr_url"
        return 1
    fi
    local hostname=$(echo "$pr_url" | sed -E 's|https://([^/]+)/.*|\1|')
    local server_base="${GIT_SERVERS[$hostname]:-}"
    if [ -z "$server_base" ]; then
        echo "unknown_server"
        return 1
    fi
    local api_base="${server_base}/api/v1"
    local api_url=$(echo "$pr_url" | sed -E 's|https://[^/]+/([^/]+)/([^/]+)/(pulls|merge_requests)/([0-9]+)|'"${api_base}"'/repos/\1/\2/\3/\4|')
    local token=""
    if [[ "$hostname" == "github.com" ]]; then
        token="${GITHUB_TOKEN:-}"
    else
        token="${GITEA_TOKEN:-}"
    fi
    local response
    if [ -n "$token" ]; then
        response=$(curl -s -H "Authorization: token $token" "$api_url" 2>/dev/null || echo "{}")
    else
        response=$(curl -s "$api_url" 2>/dev/null || echo "{}")
    fi
    local state=$(echo "$response" | python3 -c "import json, sys; d=json.load(sys.stdin); print(d.get('state', 'unknown'))" 2>/dev/null || echo "unknown")
    local merged=$(echo "$response" | python3 -c "import json, sys; d=json.load(sys.stdin); print('true' if d.get('merged', False) else 'false')" 2>/dev/null || echo "false")
    if [ "$merged" = "true" ]; then
        echo "merged"
    elif [ "$state" = "closed" ]; then
        echo "closed"
    elif [ "$state" = "open" ]; then
        echo "open"
    else
        echo "unknown"
    fi
 }
--- a/skills/kugetsu/tests/test-create-session.sh
+++ b/skills/kugetsu/tests/test-create-session.sh
@@ -1,181 +0,0 @@
 #!/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
@@ -1,298 +0,0 @@
 #!/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,8 +7,6 @@
 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"
@@ -20,28 +18,28 @@ PASS=0
 FAIL=0
 cleanup() {
-    rm -rf "$TEST_KUGETSU_DIR" 2>/dev/null || true
+    rm -rf ~/.kugetsu/sessions/* ~/.kugetsu/worktrees/* ~/.kugetsu/index.json 2>/dev/null || true
 }
 setup_mock_base() {
-    mkdir -p "$TEST_KUGETSU_DIR/sessions" "$TEST_KUGETSU_DIR/worktrees"
+    mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
-    cat > "$TEST_KUGETSU_DIR/index.json" << EOF
+    cat > ~/.kugetsu/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": "$TEST_PM_AGENT_SESSION_ID",
  "issues": {}
 }
 EOF
-    cat > "$TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE" << EOF
+    cat > ~/.kugetsu/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 > "$TEST_KUGETSU_DIR/sessions/$TEST_PM_AGENT_SESSION_FILE" << EOF
+    cat > ~/.kugetsu/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 > "$TEST_KUGETSU_DIR/index.json" << EOF
+    cat > ~/.kugetsu/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": "$TEST_PM_AGENT_SESSION_ID",
@@ -50,7 +48,7 @@ setup_mock_forked() {
  }
 }
 EOF
-    cat > "$TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE" << EOF
+    cat > ~/.kugetsu/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
 }
@@ -114,16 +112,16 @@ echo ""
 # Test 3b: start fails without pm-agent
 echo "--- Test: start without pm-agent session ---"
-rm -f $TEST_KUGETSU_DIR/index.json $TEST_KUGETSU_DIR/sessions/*
+rm -f ~/.kugetsu/index.json ~/.kugetsu/sessions/*
-mkdir -p $TEST_KUGETSU_DIR/sessions
+mkdir -p ~/.kugetsu/sessions
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+cat > ~/.kugetsu/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": null,
  "issues": {}
 }
 EOF
-cat > $TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE << EOF
+cat > ~/.kugetsu/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)
@@ -178,7 +176,7 @@ echo ""
 # Test 6c: index.json has pm_agent field
 echo "--- Test: index.json has pm_agent field ---"
-if grep -q '"pm_agent"' $TEST_KUGETSU_DIR/index.json; then
+if grep -q '"pm_agent"' ~/.kugetsu/index.json; then
    pass "index.json has pm_agent field"
 else
    fail "index.json missing pm_agent field"
@@ -229,12 +227,12 @@ echo ""
 echo "--- Test: destroy --pm-agent -y ---"
 setup_mock_base
 OUTPUT=$($KUGETSU destroy --pm-agent -y 2>&1 || true)
-if [ -f $TEST_KUGETSU_DIR/sessions/$TEST_PM_AGENT_SESSION_FILE ]; then
+if [ -f ~/.kugetsu/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' $TEST_KUGETSU_DIR/index.json; then
+if grep -q '"pm_agent": null' ~/.kugetsu/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"
@@ -245,7 +243,7 @@ echo ""
 echo "--- Test: destroy --base -y ---"
 setup_mock_base
 OUTPUT=$($KUGETSU destroy --base -y 2>&1 || true)
-if [ -f $TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE ]; then
+if [ -f ~/.kugetsu/sessions/$TEST_BASE_SESSION_FILE ]; then
    fail "destroy --base -y removes base file"
 else
    pass "destroy --base -y removes base file"
@@ -294,7 +292,7 @@ echo ""
 # Test 15: worktree path in session file
 echo "--- Test: worktree_path in session file ---"
-if grep -q "worktree_path" $TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE; then
+if grep -q "worktree_path" ~/.kugetsu/sessions/$TEST_FORKED_SESSION_FILE; then
    pass "session file contains worktree_path"
 else
    fail "session file missing worktree_path"
@@ -305,7 +303,7 @@ echo ""
 echo "--- Test: prune with orphaned worktree ---"
 cleanup
 setup_mock_base
-mkdir -p $TEST_KUGETSU_DIR/worktrees/orphaned-worktree
+mkdir -p ~/.kugetsu/worktrees/orphaned-worktree
 OUTPUT=$($KUGETSU prune 2>&1 || true)
 if echo "$OUTPUT" | grep -q "orphaned worktree"; then
    pass "prune detects orphaned worktree"
@@ -317,7 +315,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 $TEST_KUGETSU_DIR/worktrees/orphaned-worktree ]; then
+if [ -d ~/.kugetsu/worktrees/orphaned-worktree ]; then
    fail "prune --force should remove orphaned worktree"
 else
    pass "prune --force removes orphaned worktree"
@@ -334,10 +332,10 @@ echo ""
 echo "--- Test: destroy removes worktree ---"
 cleanup
 setup_mock_forked
-# remove_worktree_for_issue derives path from issue ref: $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
+# remove_worktree_for_issue derives path from issue ref: ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14
-mkdir -p $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
+mkdir -p ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14
 OUTPUT=$($KUGETSU destroy github.com/shoko/kugetsu#14 -y 2>&1 || true)
-if [ -d $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14 ]; then
+if [ -d ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14 ]; then
    fail "destroy should remove worktree"
 else
    pass "destroy removes worktree"
@@ -347,7 +345,7 @@ echo ""
 # Test 20: session file properly formatted for v2.2
 echo "--- Test: session file format v2.2 ---"
 setup_mock_forked
-SESSION_CONTENT=$(cat $TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE)
+SESSION_CONTENT=$(cat ~/.kugetsu/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"
@@ -369,8 +367,8 @@ echo ""
 # Test 22: status when base missing
 echo "--- Test: status (base missing) ---"
-mkdir -p $TEST_KUGETSU_DIR/sessions
+mkdir -p ~/.kugetsu/sessions
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+cat > ~/.kugetsu/index.json << EOF
 {
  "base": null,
  "pm_agent": "$TEST_PM_AGENT_SESSION_ID",
@@ -387,7 +385,7 @@ echo ""
 # Test 23: status when pm-agent missing
 echo "--- Test: status (pm-agent missing) ---"
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+cat > ~/.kugetsu/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": null,
@@ -404,7 +402,7 @@ echo ""
 # Test 24: status when pm-agent is "None" (Python None output)
 echo "--- Test: status (pm-agent is Python None) ---"
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+cat > ~/.kugetsu/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": "None",
@@ -447,8 +445,8 @@ echo ""
 # Test 27: delegate when pm-agent missing
 echo "--- Test: delegate (pm-agent missing) ---"
 cleanup
-mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
+mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+cat > ~/.kugetsu/index.json << EOF
 {
  "base": "$TEST_BASE_SESSION_ID",
  "pm_agent": null,
@@ -510,7 +508,7 @@ echo ""
 # Test 32: delegate is fire-and-forget (returns immediately)
 echo "--- Test: delegate is fire-and-forget ---"
 setup_mock_base
-mkdir -p $TEST_KUGETSU_DIR/logs
+mkdir -p ~/.kugetsu/logs
 START=$(date +%s)
 OUTPUT=$($KUGETSU delegate "test fire-and-forget" 2>&1 || true)
 END=$(date +%s)
@@ -529,10 +527,10 @@ echo ""
 # Test 33: delegate creates log file
 echo "--- Test: delegate creates log file ---"
 setup_mock_base
-LOG_COUNT_BEFORE=$(ls $TEST_KUGETSU_DIR/logs/*.log 2>/dev/null | wc -l)
+LOG_COUNT_BEFORE=$(ls ~/.kugetsu/logs/*.log 2>/dev/null | wc -l)
 $KUGETSU delegate "test log file" 2>&1 || true
 sleep 1
-LOG_COUNT_AFTER=$(ls $TEST_KUGETSU_DIR/logs/*.log 2>/dev/null | wc -l)
+LOG_COUNT_AFTER=$(ls ~/.kugetsu/logs/*.log 2>/dev/null | wc -l)
 if [ $LOG_COUNT_AFTER -gt $LOG_COUNT_BEFORE ]; then
    pass "delegate creates log file"
 else
@@ -560,10 +558,10 @@ echo ""
 # Test E2: env set creates file
 echo "--- Test: env set creates env file ---"
-mkdir -p $TEST_KUGETSU_DIR/env
+mkdir -p ~/.kugetsu/env
-rm -f $TEST_KUGETSU_DIR/env/pm-agent.env
+rm -f ~/.kugetsu/env/pm-agent.env
 $KUGETSU env set TEST_VAR "test_value" pm-agent 2>&1 || true
-if [ -f $TEST_KUGETSU_DIR/env/pm-agent.env ]; then
+if [ -f ~/.kugetsu/env/pm-agent.env ]; then
    pass "env set creates pm-agent.env file"
 else
    fail "env set did not create pm-agent.env"
@@ -572,7 +570,7 @@ echo ""
 # Test E3: env show masks sensitive values
 echo "--- Test: env show masks sensitive values ---"
-cat > $TEST_KUGETSU_DIR/env/pm-agent.env << 'ENVEOF'
+cat > ~/.kugetsu/env/pm-agent.env << 'ENVEOF'
 export GITEA_TOKEN="secret_token_123"
 export MY_VAR="visible_value"
 ENVEOF
@@ -586,14 +584,14 @@ echo ""
 # Test E4: Variables exported to child processes via set -a
 echo "--- Test: set -a exports variables to children ---"
-mkdir -p $TEST_KUGETSU_DIR/env
+mkdir -p ~/.kugetsu/env
-cat > $TEST_KUGETSU_DIR/env/test.env << 'ENVEOF'
+cat > ~/.kugetsu/env/test.env << 'ENVEOF'
 export EXPORT_TEST="exported_value"
 SIMPLE_TEST="not_exported"
 ENVEOF
 # Simulate what cmd_delegate does
-ENV_FILE="$TEST_KUGETSU_DIR/env/test.env"
+ENV_FILE="~/.kugetsu/env/test.env"
 env_sh="set -a; source '$ENV_FILE'; set +a; "
 result=$(bash -c "${env_sh}bash -c 'echo \$EXPORT_TEST'")
@@ -606,11 +604,11 @@ echo ""
 # Test E5: pm-agent.env takes precedence
 echo "--- Test: pm-agent.env takes precedence over default ---"
-mkdir -p $TEST_KUGETSU_DIR/env
+mkdir -p ~/.kugetsu/env
-cat > $TEST_KUGETSU_DIR/env/default.env << 'ENVEOF'
+cat > ~/.kugetsu/env/default.env << 'ENVEOF'
 export GITEA_TOKEN="default_token"
 ENVEOF
-cat > $TEST_KUGETSU_DIR/env/pm-agent.env << 'ENVEOF'
+cat > ~/.kugetsu/env/pm-agent.env << 'ENVEOF'
 export GITEA_TOKEN="pm_agent_token"
 ENVEOF
@@ -646,7 +644,7 @@ fi
 echo ""
 # Cleanup env files
-rm -rf $TEST_KUGETSU_DIR/env 2>/dev/null || true
+rm -rf ~/.kugetsu/env 2>/dev/null || true
 # Test E7: fix_session_permissions function exists
 echo "--- Test: fix_session_permissions function exists ---"
@@ -738,7 +736,7 @@ PASS=0
 FAIL=0
 test_cleanup() {
-    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
+    rm -rf ~/.kugetsu/sessions/* ~/.kugetsu/worktrees/* ~/.kugetsu/index.json ~/.kugetsu/logs/* ~/.kugetsu/.agent_count ~/.kugetsu/.agent_lock 2>/dev/null || true
 }
 pass() {
@@ -752,25 +750,25 @@ fail() {
 }
 setup_mock_sessions() {
-    mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees $TEST_KUGETSU_DIR/logs
+    mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees ~/.kugetsu/logs
-    cat > $TEST_KUGETSU_DIR/index.json << INDEX
+    cat > ~/.kugetsu/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"}' > $TEST_KUGETSU_DIR/sessions/base.json
+    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"}' > $TEST_KUGETSU_DIR/sessions/pm-agent.json
+    echo '{"type": "pm_agent", "opencode_session_id": "ses_test_pm_456", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > ~/.kugetsu/sessions/pm-agent.json
 }
 # Test C1: Agent count file is initialized to 0
 echo "--- Test: agent count file initialized ---"
 test_cleanup
-mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
+mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
 $KUGETSU list > /dev/null 2>&1 || true
-if [ -f $TEST_KUGETSU_DIR/.agent_count ]; then
+if [ -f ~/.kugetsu/.agent_count ]; then
-    COUNT=$(cat $TEST_KUGETSU_DIR/.agent_count)
+    COUNT=$(cat ~/.kugetsu/.agent_count)
    if [ "$COUNT" = "0" ]; then
        pass "agent count file initialized to 0"
    else
@@ -797,10 +795,10 @@ test_cleanup
 setup_mock_sessions
 # Initialize count to 0
-echo 0 > $TEST_KUGETSU_DIR/.agent_count
+echo 0 > ~/.kugetsu/.agent_count
 # Verify initial state
-INITIAL=$(cat $TEST_KUGETSU_DIR/.agent_count)
+INITIAL=$(cat ~/.kugetsu/.agent_count)
 if [ "$INITIAL" = "0" ]; then
    pass "agent count starts at 0"
 else
@@ -811,7 +809,7 @@ fi
 $KUGETSU list > /dev/null 2>&1
 # Verify count is still 0 (no slot leak)
-AFTER=$(cat $TEST_KUGETSU_DIR/.agent_count)
+AFTER=$(cat ~/.kugetsu/.agent_count)
 if [ "$AFTER" = "0" ]; then
    pass "agent count stays 0 after list (no leak)"
 else
--- a/skills/kugetsu/tests/test-kugetsu.sh
+++ b/skills/kugetsu/tests/test-kugetsu.sh
@@ -0,0 +1,277 @@
 #!/bin/bash
 # kugetsu test suite
 # Run with: bash skills/kugetsu/tests/test-kugetsu.sh
 #
 # Memory management approach:
 # - Sequential test execution (no parallel)
 # - Cleanup between tests that spawn opencode
 # - No hard memory cap (ulimit -v breaks Bun/opencode)
 # - If OOM occurs, it is a known failure mode
 set -euo pipefail
 KUGETSU="./skills/kugetsu/scripts/kugetsu"
 TEST_SESSION_PREFIX="kugetsu-test-"
 PASS=0
 FAIL=0
 cleanup_sessions() {
    for dir in ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}*; do
        [ -d "$dir" ] && rm -rf "$dir" 2>/dev/null || true
    done
 }
 cleanup_opencode() {
    pkill -f "opencode.*${TEST_SESSION_PREFIX}" 2>/dev/null || true
    pkill -f "kugetsu.*${TEST_SESSION_PREFIX}" 2>/dev/null || true
    sleep 0.5
 }
 cleanup() {
    cleanup_sessions
    cleanup_opencode
 }
 pass() {
    echo "✅ PASS: $1"
    PASS=$((PASS + 1))
 }
 fail() {
    echo "❌ FAIL: $1"
    FAIL=$((FAIL + 1))
 }
 cleanup
 echo "=== kugetsu Test Suite ==="
 echo ""
 # Test 1: Help
 echo "--- Test: help ---"
 if $KUGETSU help 2>&1 | grep -q "kugetsu - OpenCode Session Manager"; then
    pass "help displays usage"
 else
    fail "help displays usage"
 fi
 echo ""
 # Test 2: List empty
 echo "--- Test: list (empty) ---"
 if $KUGETSU list 2>&1 | grep -q "SESSION_ID"; then
    pass "list shows header even when empty"
 else
    fail "list shows header even when empty"
 fi
 echo ""
 # Test 3: List --all empty
 echo "--- Test: list --all (empty) ---"
 if $KUGETSU list --all 2>&1 | grep -q "SESSION_ID"; then
    pass "list --all shows header even when empty"
 else
    fail "list --all shows header even when empty"
 fi
 echo ""
 # Test 4: Start session (quick exit)
 echo "--- Test: start session ---"
 if timeout 15 bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}start-test 'echo hello'" 2>&1; then
    if [ -d ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}start-test ]; then
        pass "start creates session directory"
    else
        fail "start creates session directory"
    fi
 else
    fail "start runs successfully"
 fi
 echo ""
 # Test 5: List shows only left by default
 echo "--- Test: list default filters non-left ---"
 if ! $KUGETSU list 2>&1 | grep -q "${TEST_SESSION_PREFIX}start-test"; then
    pass "list default hides idle sessions"
 else
    fail "list default hides idle sessions"
 fi
 echo ""
 # Test 6: List --all shows all
 echo "--- Test: list --all shows all states ---"
 if $KUGETSU list --all 2>&1 | grep -q "${TEST_SESSION_PREFIX}start-test"; then
    pass "list --all shows all sessions"
 else
    fail "list --all shows all sessions"
 fi
 echo ""
 # Test 7: Resume with auto-fill
 echo "--- Test: resume auto-fill ---"
 mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-test
 echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-test/state
 echo "continue this task" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-test/message
 OUTPUT=$(timeout 10 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}resume-test" 2>&1 || true)
 if echo "$OUTPUT" | grep -q "Auto-filled message: continue this task"; then
    pass "resume auto-fills stored message"
 else
    fail "resume auto-fills stored message"
 fi
 cleanup
 echo ""
 # Test 8: Resume with provided message overrides
 echo "--- Test: resume with message overrides ---"
 mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-override
 echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-override/state
 echo "original message" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-override/message
 OUTPUT=$(timeout 30 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}resume-override 'new message'" 2>&1 || true)
 if echo "$OUTPUT" | grep -q "new message" && ! echo "$OUTPUT" | grep -q "Auto-filled message"; then
    pass "resume uses provided message over auto-fill"
 else
    fail "resume uses provided message over auto-fill: $OUTPUT"
 fi
 cleanup
 echo ""
 # Test 9: Resume idle session fails
 echo "--- Test: resume idle session fails ---"
 rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}idle-test 2>/dev/null
 mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}idle-test
 echo "idle" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}idle-test/state
 OUTPUT=$(timeout 5 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}idle-test" 2>&1 || true)
 if echo "$OUTPUT" | grep -q "cannot be resumed"; then
    pass "resume idle session fails with message"
 else
    echo "DEBUG: $OUTPUT"
    fail "resume idle session fails with message"
 fi
 echo ""
 # Test 10: Resume non-existent session fails
 echo "--- Test: resume non-existent session fails ---"
 rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}nonexistent 2>/dev/null
 OUTPUT=$(timeout 5 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}nonexistent" 2>&1 || true)
 if echo "$OUTPUT" | grep -q "not found"; then
    pass "resume non-existent session fails"
 else
    echo "DEBUG: $OUTPUT"
    fail "resume non-existent session fails"
 fi
 echo ""
 # Test 11: Stop non-used session fails
 echo "--- Test: stop non-used session fails ---"
 rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}notused 2>/dev/null
 mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}notused
 echo "idle" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}notused/state
 OUTPUT=$(timeout 5 bash -c "$KUGETSU stop ${TEST_SESSION_PREFIX}notused" 2>&1 || true)
 if echo "$OUTPUT" | grep -q "not in use"; then
    pass "stop non-used session fails"
 else
    echo "DEBUG: $OUTPUT"
    fail "stop non-used session fails"
 fi
 echo ""
 # Test 12: Start existing left session resumes instead
 echo "--- Test: start on left session resumes ---"
 mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}left-start
 echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}left-start/state
 echo "original task" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}left-start/message
 OUTPUT=$(timeout 10 bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}left-start 'new task'" 2>&1 || true)
 if echo "$OUTPUT" | grep -q "Resuming instead"; then
    pass "start on left session resumes"
 else
    fail "start on left session resumes"
 fi
 cleanup
 echo ""
 # ============================================================================
 # FLAKY TESTS - Commented out due to timing/process behavior issues
 # ============================================================================
 # Test: Stop active session (FLAKY - timing dependent)
 # echo "--- Test: stop active session (FLAKY) ---"
 # (
 #     timeout 20 bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}stop-test 'sleep 30'" 2>&1 &
 #     KUGETSU_PID=$!
 #     sleep 3
 #     
 #     # Check session is in use
 #     if ! $KUGETSU list --all 2>&1 | grep -q "${TEST_SESSION_PREFIX}stop-test.*used"; then
 #         echo "⚠️  SKIP (FLAKY): Could not verify session was used"
 #     elif timeout 5 bash -c "$KUGETSU stop ${TEST_SESSION_PREFIX}stop-test" 2>&1; then
 #         if [ "$(cat ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}stop-test/state 2>/dev/null)" = "idle" ]; then
 #             echo "✅ PASS (FLAKY): stop transitions to idle"
 #         else
 #             echo "❌ FAIL (FLAKY): stop does not transition to idle"
 #         fi
 #     else
 #         echo "❌ FAIL (FLAKY): stop command failed"
 #     fi
 #     
 #     wait $KUGETSU_PID 2>/dev/null || true
 # ) 2>&1 || true
 # Test: Interrupt session leaves state as left (FLAKY - opencode signal handling)
 # echo "--- Test: interrupt session leaves left (FLAKY) ---"
 # (
 #     bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}interrupt-test 'sleep 30'" 2>&1 &
 #     KUGETSU_PID=$!
 #     sleep 3
 #     
 #     # Find and kill opencode process
 #     OPENCODE_PID=$(pgrep -f "opencode.*${TEST_SESSION_PREFIX}interrupt-test" | head -1 || true)
 #     if [ -n "$OPENCODE_PID" ]; then
 #         kill -9 $OPENCODE_PID 2>/dev/null || true
 #     fi
 #     
 #     wait $KUGETSU_PID 2>/dev/null || true
 #     sleep 1
 #     
 #     STATE=$(cat ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}interrupt-test/state 2>/dev/null || echo "unknown")
 #     if [ "$STATE" = "left" ]; then
 #         echo "✅ PASS (FLAKY): interrupt leaves state as left"
 #     else
 #         echo "❌ FAIL (FLAKY): interrupt left state=$STATE (expected left)"
 #     fi
 # ) 2>&1 || true
 # Test: Concurrent resume attempts (FLAKY - race condition)
 # echo "--- Test: concurrent resume (FLAKY) ---"
 # mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent
 # echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent/state
 # echo "test task" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent/message
 # 
 # (
 #     timeout 10 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}concurrent" 2>&1 &
 #     timeout 10 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}concurrent" 2>&1
 # ) 2>&1 || true
 # 
 # echo "⚠️  NOTE (FLAKY): This test is informational only - no assertion"
 # rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent
 # ============================================================================
 # Cleanup
 # ============================================================================
 cleanup
 echo ""
 echo "=== Test Summary ==="
 echo "Passed: $PASS"
 echo "Failed: $FAIL"
 echo ""
 if [ $FAIL -eq 0 ]; then
    echo "All tests passed!"
    exit 0
 else
    echo "Some tests failed."
    exit 1
 fi