feat(kugetsu): implement worktree isolation + lock mechanism for delegation coordination #71

New Issue

shoko · 2026-04-01T10:47:17+02:00

shoko commented

2026-04-01 10:47:17 +02:00

Problem

Current delegation system has no coordination:

cmd_delegate is fire-and-forget - spawns new opencode process each time
Multiple delegations sent quickly result in concurrent processes
Concurrent processes modify same worktrees, causing conflicts
PM gets stuck on TTY-dependent operations (vim for git rebase)

Desired Behavior

Hybrid approach: worktree isolation + lock mechanism

Worktree Isolation (existing)

Each issue gets its own worktree
Filesystem-level separation

Lock Mechanism (new)

Before working on issue, acquire lock file: ~/.kugetsu/locks/<issue-ref>.lock
Lock contains: PID, session_id, timestamp
Check lock before starting work
If locked, either:
- Wait and retry (with timeout)
- Fail with "issue already being worked on"
Release lock when done (or on crash, stale lock detection)

Delegation Coordination

Option A - Serialized delegation:

# cmd_delegate checks PM is idle before sending
if pm_busy; then
    queue_delegation
else
    send_to_pm
fi

Option B - PM session mutex:

# PM session has a lock
# Only one delegation process can send to PM at a time
acquire_mutex(pm_session)
send_to_pm
release_mutex(pm_session)

Option C - Delegation queue:

# All delegations go to a queue file
# PM reads queue and processes one by one

Tasks

Create lock directory: ~/.kugetsu/locks/
Implement lock acquisition/release in kugetsu script
Modify cmd_start to check lock before creating worktree
Modify cmd_delegate to either queue or check PM busy status
Add stale lock detection (if PID no longer exists)
Document locking protocol
Test concurrent delegation scenarios

Tradeoffs

Approach	Pros	Cons
Worktree only	Simple, existing	No coordination, conflicts
Lock only	Coordinates access	Still need isolation
Hybrid (proposed)	Best of both	More complexity

## Problem Current delegation system has no coordination: - cmd_delegate is fire-and-forget - spawns new opencode process each time - Multiple delegations sent quickly result in concurrent processes - Concurrent processes modify same worktrees, causing conflicts - PM gets stuck on TTY-dependent operations (vim for git rebase) ## Desired Behavior Hybrid approach: worktree isolation + lock mechanism ### Worktree Isolation (existing) - Each issue gets its own worktree - Filesystem-level separation ### Lock Mechanism (new) - Before working on issue, acquire lock file: `~/.kugetsu/locks/<issue-ref>.lock` - Lock contains: PID, session_id, timestamp - Check lock before starting work - If locked, either: - Wait and retry (with timeout) - Fail with "issue already being worked on" - Release lock when done (or on crash, stale lock detection) ### Delegation Coordination Option A - Serialized delegation: ```bash # cmd_delegate checks PM is idle before sending if pm_busy; then queue_delegation else send_to_pm fi ``` Option B - PM session mutex: ```bash # PM session has a lock # Only one delegation process can send to PM at a time acquire_mutex(pm_session) send_to_pm release_mutex(pm_session) ``` Option C - Delegation queue: ```bash # All delegations go to a queue file # PM reads queue and processes one by one ``` ## Tasks 1. Create lock directory: `~/.kugetsu/locks/` 2. Implement lock acquisition/release in kugetsu script 3. Modify cmd_start to check lock before creating worktree 4. Modify cmd_delegate to either queue or check PM busy status 5. Add stale lock detection (if PID no longer exists) 6. Document locking protocol 7. Test concurrent delegation scenarios ## Tradeoffs | Approach | Pros | Cons | |----------|------|------| | Worktree only | Simple, existing | No coordination, conflicts | | Lock only | Coordinates access | Still need isolation | | Hybrid (proposed) | Best of both | More complexity |

shoko referenced this issue

2026-04-01 11:18:15 +02:00

feat(kugetsu): cmd_delegate should call cmd_start directly for parallelization #74

shoko referenced this issue

2026-04-01 11:53:52 +02:00

PM Agent Cannot Post Gitea Comments - Needs GITEA_TOKEN Access #76

shoko added the parallelization label 2026-04-02 00:30:43 +02:00

shoko referenced this issue from a commit

2026-04-02 01:26:25 +02:00

feat(kugetsu): add lock mechanism for worktree coordination

shoko referenced a pull request that will close this issue

2026-04-02 01:26:37 +02:00