Implement major kugetsu improvements #133

New Issue

shoko · 2026-04-05T04:35:21+02:00

shoko commented

2026-04-05 04:35:21 +02:00

Problem Statement

Kugetsu has accumulated several technical debts that need addressing for more reliable parallel agent orchestration:

Worktree lifecycle - Worktrees are destroyed when sessions end, but should persist until PR is merged/closed
Queue system - No automated queue management; agents must be manually started when slots open
Session poisoning - Sessions occasionally get mixed up between projects (e.g., agents redirected to kugetsu instead of jigaido)
Agent timeout - Hanging/idle agents are not automatically killed

Proposed Solution

1. Worktree Lifecycle Management

Add pr_url and branch_name fields to session files
kugetsu destroy <issue> checks PR status via API before destroying worktree
kugetsu destroy <issue> --force bypasses check

2. Queue System with Background Daemon

~/.kugetsu/queue/items/ - file-based queue (one file per item, no race conditions)
kugetsu queue-daemon start|stop|restart|status|logs - daemon management
kugetsu delegate always enqueues instead of invoking PM directly
Daemon polls queue, forks PM session when slot available

3. Context Dump/Load for Session Isolation

~/.kugetsu/context/<issue-ref>.json - full conversation history
Loaded on kugetsu start/continue, dumped on session end
Context tied to issue-ref, not opencode session ID

4. Agent Timeout Handling

TASK_TIMEOUT_HOURS config (default: 1)
Daemon tracks notified items, kills if exceeded

Tasks

#134 Queue system (daemon + commands)
#135 Worktree lifecycle management
#136 Context dump/load
#137 Agent timeout handling

Related to session management issues experienced when running parallel agents on jigaido.

## Problem Statement Kugetsu has accumulated several technical debts that need addressing for more reliable parallel agent orchestration: 1. **Worktree lifecycle** - Worktrees are destroyed when sessions end, but should persist until PR is merged/closed 2. **Queue system** - No automated queue management; agents must be manually started when slots open 3. **Session poisoning** - Sessions occasionally get mixed up between projects (e.g., agents redirected to kugetsu instead of jigaido) 4. **Agent timeout** - Hanging/idle agents are not automatically killed ## Proposed Solution ### 1. Worktree Lifecycle Management - Add `pr_url` and `branch_name` fields to session files - `kugetsu destroy <issue>` checks PR status via API before destroying worktree - `kugetsu destroy <issue> --force` bypasses check ### 2. Queue System with Background Daemon - `~/.kugetsu/queue/items/` - file-based queue (one file per item, no race conditions) - `kugetsu queue-daemon start|stop|restart|status|logs` - daemon management - `kugetsu delegate` always enqueues instead of invoking PM directly - Daemon polls queue, forks PM session when slot available ### 3. Context Dump/Load for Session Isolation - `~/.kugetsu/context/<issue-ref>.json` - full conversation history - Loaded on `kugetsu start/continue`, dumped on session end - Context tied to issue-ref, not opencode session ID ### 4. Agent Timeout Handling - `TASK_TIMEOUT_HOURS` config (default: 1) - Daemon tracks notified items, kills if exceeded ## Tasks - [ ] #134 Queue system (daemon + commands) - [ ] #135 Worktree lifecycle management - [ ] #136 Context dump/load - [ ] #137 Agent timeout handling ## Related Issues Related to session management issues experienced when running parallel agents on jigaido.

shoko referenced this issue

2026-04-05 04:35:36 +02:00

Queue system with background daemon #134

shoko referenced this issue

2026-04-05 04:35:45 +02:00

Worktree lifecycle management with PR check #135

shoko referenced this issue

2026-04-05 04:36:07 +02:00

Context dump/load for session isolation #136

shoko referenced this issue

2026-04-05 04:36:17 +02:00

Agent timeout handling #137