fix CONTRIBUTING.md: branch naming should include issue number

Address han's review feedback:
- Changed feat/feature-name to feat/issue-N-feature-name
- Consistent with fix/issue-N-name format

CONTRIBUTING.md

@@ -5,7 +5,7 @@
 1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b feat/issue-N-feature-name`
 2. Make changes and commit with clear messages
 3. Open a Pull Request for review
-4. Do not merge directly to `main` for reviewable changes
+4. Do not merge directly to `main` or `develop` for reviewable changes
 5. After approval, squash and merge
 
 ## Guidelines
@@ -14,13 +14,53 @@
 - Keep PRs focused and reasonably sized
 - Document any non-obvious decisions
 - Test changes before submitting
+- See [VERSIONING.md](VERSIONING.md) for backport compatibility rules
 
 ## Branches
 
-- `main` — stable, reviewed content only
-- `develop` — experimental work for 0.2.x
+### Primary Branches
+
+- `main` — stable 0.1.x releases, production-ready code
+- `develop` — experimental 0.2.x work, next major version
+
+### Feature Branches
+
 - `fix/*` — bug fixes
 - `feat/*` — new features
 - `docs/*` — documentation updates
-- `refactor/*` — refactoring
-- `research/*` — new research notes
+- `refactor/*` — code refactoring (no behavior change)
+
+## Branch Model
+
+```
+main (0.1.x stable)
+  └── v0.1.0, v0.1.1, v0.1.2, ...
+
+develop (0.2.x experimental)
+  └── (next major version work)
+```
+
+### Which Branch to Target?
+
+| Change Type | Target Branch | Backport? |
+|-------------|---------------|-----------|
+| Bug fix | `main` | N/A |
+| Documentation | `main` | N/A |
+| New feature (backport-compatible) | `main` | Can cherry-pick to `develop` |
+| Experimental feature | `develop` | No |
+| Breaking change | `develop` | No |
+
+## Backport Compatibility
+
+Before merging, consider if your change is backport-compatible:
+
+- **YES**: Bug fixes, docs, adding new optional inputs
+- **NO**: Changing behavior, changing defaults, removing features
+
+See [VERSIONING.md](VERSIONING.md) for full policy.
+
+## Release Process
+
+1. Bug fixes and docs → directly to `main`
+2. New features → `develop` or feature branches → `develop`
+3. When `develop` is stable enough → merge to `main` for release

VERSIONING.md

@@ -0,0 +1,71 @@
+# Versioning Policy
+
+## Branch Strategy
+
+Kugetsu uses a dual-branch model:
+
+| Branch | Purpose | Version | Stability |
+|--------|---------|---------|-----------|
+| `main` | Stable releases | 0.1.x | Production-ready |
+| `develop` | Experimental work | 0.2.x | Active development |
+
+### Branch Definitions
+
+- **`main`**: Contains the latest stable 0.1.x releases. All changes here should be production-ready and backport-compatible when possible.
+
+- **`develop`**: Contains work for the next major version (0.2.x). This branch may contain experimental features that could change or be removed.
+
+## Version Format
+
+Versions follow [Semantic Versioning](https://semver.org/):
+```
+MAJOR.MINOR.PATCH
+```
+
+- **MAJOR**: Incompatible API/behavior changes
+- **MINOR**: New functionality (backward-compatible)
+- **PATCH**: Bug fixes (backward-compatible)
+
+## Backport Compatibility
+
+### Backport-Compatible Changes (0.1.x)
+- Bug fixes
+- Documentation updates
+- Performance improvements
+- Adding new inputs/options (must have sensible defaults)
+- Changes that only affect 0.2.x-specific features
+
+### NOT Backport-Compatible
+- Removing or renaming existing options
+- Changing default values of existing options
+- Changing behavior of existing commands
+- Introducing breaking changes to the API/shell interface
+
+## Deprecation Policy
+
+When introducing breaking changes:
+
+1. **Deprecate in minor X**: Add warning messages, document the change
+2. **Remove in major X+1**: The breaking change is removed in the next major version
+
+Example:
+- Option `--old-flag` deprecated in v0.1.5
+- Option `--old-flag` removed in v1.0.0 (not v0.2.0)
+
+## What Constitutes a Version Bump
+
+| Change Type | Version Bump |
+|-------------|--------------|
+| Add new command/option | MINOR |
+| Bug fix | PATCH |
+| Change default value | MINOR (may warrant PATCH) |
+| Add new required input | MAJOR |
+| Remove deprecated feature | MAJOR |
+| Change behavior of existing command | MINOR (needs deprecation first) |
+
+## Release Process
+
+1. Changes are developed on feature branches
+2. PRs are opened against `main` for 0.1.x changes, or `develop` for 0.2.x
+3. After review and approval, changes are squash-merged
+4. Releases are tagged from `main` after significant changes

docs/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to kugetsu are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [v0.2.1] - 2026-04-03
+
+### Fixed
+- Prevent excess agent spawning with flock + sequential processing
+
+## [v0.2.0] - 2026-03-30
+
+### Added
+- Queue system with background daemon
+- Agent timeout handling
+- Context dump/load for session isolation
+- PR tracking and safe destroy
+
+## [v0.1.13] - 2026-03-29
+
+### Fixed
+- Add missing closing parenthesis in process_queue Python extraction
+
+## [v0.1.12] - 2026-03-25
+
+### Added
+- Post-comment helper for PM agent
+
+## [v0.1.11] - 2026-03-20
+
+### Fixed
+- Wrap cmd_continue in subshell with cd for correct worktree dir
+
+## [v0.1.10] - 2026-03-15
+
+### Fixed
+- destroy --base now also deletes PM agent session
+
+## [v0.1.9] - 2026-03-10
+
+### Added
+- init creates base session in ~/.kugetsu-worktrees
+- Adds context to forked sessions
+- Clears logs on init
+
+## [v0.1.8] - 2026-03-05
+
+### Fixed
+- destroy --base and --pm-agent actually delete opencode sessions
+
+## [v0.1.7] - 2026-02-28
+
+### Fixed
+- Warn if init run from non-empty directory
+
+## [v0.1.6] - 2026-02-20
+
+### Fixed
+- Detect session via DB query instead of opencode session list
+
+## [v0.1.5] - 2026-02-15
+
+### Fixed
+- Update forked session permissions after detection
+
+## [v0.1.4] - 2026-02-10
+
+### Fixed
+- Call fix_session_permissions before forking
+
+## [v0.1.3] - 2026-02-05
+
+### Fixed
+- Session detection ordering bug and debugging
+
+## [v0.1.2] - 2026-01-28
+
+### Fixed
+- Improve session detection in cmd_start with retry logic and logging
+
+## [v0.1.1] - 2026-01-20
+
+### Fixed
+- Use cd + worktree inside parent dir instead of --dir flag
+
+## [v0.1.0] - 2026-01-15
+
+### Added
+- KUGETSU_VERBOSITY for PM agent output control
+- Initial documented release
+
+[Unreleased]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.1...HEAD
+[v0.2.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.0...v0.2.1
+[v0.2.0]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.13...v0.2.0
+[v0.1.13]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.12...v0.1.13
+[v0.1.12]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.11...v0.1.12
+[v0.1.11]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.10...v0.1.11
+[v0.1.10]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.9...v0.1.10
+[v0.1.9]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.8...v0.1.9
+[v0.1.8]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.7...v0.1.8
+[v0.1.7]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.6...v0.1.7
+[v0.1.6]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.5...v0.1.6
+[v0.1.5]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.4...v0.1.5
+[v0.1.4]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.3...v0.1.4
+[v0.1.3]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.2...v0.1.3
+[v0.1.2]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.1...v0.1.2
+[v0.1.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.0...v0.1.1
+[v0.1.0]: https://git.fbrns.co/shoko/kugetsu/releases/tag/v0.1.0

skills/kugetsu/scripts/kugetsu

@@ -1075,18 +1075,6 @@ cmd_status() {
         return
     fi
     
-    local opencode_sessions=$(opencode session list 2>/dev/null | grep -oP '^ses_\w+' || true)
-    
-    if ! echo "$opencode_sessions" | grep -q "^${base}$"; then
-        echo "error: base session '$base' not found in opencode"
-        return
-    fi
-    
-    if ! echo "$opencode_sessions" | grep -q "^${pm_agent}$"; then
-        echo "error: pm_agent session '$pm_agent' not found in opencode"
-        return
-    fi
-    
     echo "ok"
 }
 
@@ -1157,11 +1145,6 @@ parse_issue_ref_from_message() {
         owner=$(echo "$full_path" | cut -d'/' -f2)
         repo=$(echo "$full_path" | cut -d'/' -f3)
         issue_number=$(echo "$full_path" | grep -oE '[0-9]+$' | head -1)
-    elif echo "$message" | grep -qE '[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#[0-9]+'; then
-        gitserver=$(echo "$message" | grep -oE '[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+' | head -1)
-        owner=$(echo "$gitserver" | cut -d'/' -f2)
-        repo=$(echo "$gitserver" | cut -d'/' -f3)
-        issue_number=$(echo "$message" | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | head -1)
     elif echo "$message" | grep -qE '[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#([0-9]+)'; then
         owner=$(echo "$message" | grep -oE '[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#' | sed 's/#$//' | cut -d'/' -f1)
         repo=$(echo "$message" | grep -oE '[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#' | sed 's/#$//' | cut -d'/' -f2)

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"
-    cat > "$TEST_KUGETSU_DIR/index.json" << EOF
+    mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
+    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/*
-mkdir -p $TEST_KUGETSU_DIR/sessions
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+rm -f ~/.kugetsu/index.json ~/.kugetsu/sessions/*
+mkdir -p ~/.kugetsu/sessions
+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
-mkdir -p $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 ~/.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
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+mkdir -p ~/.kugetsu/sessions
+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
-cat > $TEST_KUGETSU_DIR/index.json << EOF
+mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees
+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
-rm -f $TEST_KUGETSU_DIR/env/pm-agent.env
+mkdir -p ~/.kugetsu/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
-cat > $TEST_KUGETSU_DIR/env/test.env << 'ENVEOF'
+mkdir -p ~/.kugetsu/env
+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
-cat > $TEST_KUGETSU_DIR/env/default.env << 'ENVEOF'
+mkdir -p ~/.kugetsu/env
+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
-    cat > $TEST_KUGETSU_DIR/index.json << INDEX
+    mkdir -p ~/.kugetsu/sessions ~/.kugetsu/worktrees ~/.kugetsu/logs
+    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": "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": "base", "opencode_session_id": "ses_test_base_123", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > ~/.kugetsu/sessions/base.json
+    echo '{"type": "pm_agent", "opencode_session_id": "ses_test_pm_456", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > ~/.kugetsu/sessions/pm-agent.json
 }
 
 # 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
-    COUNT=$(cat $TEST_KUGETSU_DIR/.agent_count)
+if [ -f ~/.kugetsu/.agent_count ]; then
+    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