docs/agent-concurrency-benchmark.md

@@ -5,11 +5,19 @@
 
 ## Test Results
 
-| Concurrent Agents | Status | Memory Usage | Notes |
+| Limit (PM+Dev) | Status | Rejection Test | Notes |
-|-------------------|--------|--------------|-------|
+|----------------|--------|---------------|-------|
-| 1 | ✓ Works | ~1.1GB idle | Baseline test |
+| 1 | ✓ Works | 1 dev rejected (PM=1, at limit) | Too strict for normal use |
-| 3 | ✓ Works | ~1.1GB idle | Default limit |
+| 3 | ✓ Works | 4th dev rejected (PM + 3 devs = 4, at limit) | Recommended |
-| 5 | ✓ Works | ~1.1GB idle | Increased limit |
+| 5 | ✓ Works | 6th dev rejected (PM + 5 devs = 6, at limit) | Works, monitor memory |
+
+## Behavior
+
+With MAX_CONCURRENT_AGENTS=N:
+- PM agent counts toward the limit (along with all dev agents)
+- At limit: NEW sessions are REJECTED
+- Existing sessions can ALWAYS be continued (--continue doesn't count toward limit)
+- PM is still accessible when at limit (user can wait or cancel tasks)
 
 ## Configuration
 
@@ -24,20 +32,55 @@ The limit can be overridden via environment variable:
 MAX_CONCURRENT_AGENTS=3 kugetsu start <issue> <message>
 ```
 
+## Implementation
+
+Session counting approach (vs broken slot mechanism):
+
+```bash
+# Count all session files except base.json
+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" ]; then
+                    count=$((count + 1))
+                fi
+            fi
+        done
+    fi
+    echo "$count"
+}
+```
+
 ## Observations
 
 1. **Idle Memory:** ~1.1GB used even with sessions idle (includes system buffers)
 2. **CPU:** 16 cores available - sufficient for multiple agents
 3. **No Active Processes:** When sessions are idle, opencode processes are not actively running
+4. **PM counts:** PM agent session counts toward MAX_CONCURRENT_AGENTS limit
+
+## Session Files
+
+```
+~/.kugetsu/sessions/
+  base.json                    - base session (NOT counted)
+  pm-agent.json                - PM agent (COUNTED)
+  github.com-user-repo#1.json  - dev agent (COUNTED)
+  github.com-user-repo#2.json  - dev agent (COUNTED)
+```
 
 ## Recommendations
 
-- **1-3 agents:** Safe for most workloads on 8GB RAM systems
+- **1 agent:** Too strict - just PM + 0 dev agents
-- **5 agents:** Works but monitor memory if running additional services
+- **3 agents:** Recommended - PM + 2 dev agents, leaves room for PM to coordinate
+- **5 agents:** Works - PM + 4 dev agents, monitor memory
 - **More than 5:** Not tested - may require more RAM
 
-## Notes
+## Session Cleanup
 
-- Each agent session creates a worktree in `~/.kugetsu/worktrees/`
+Sessions persist until explicitly destroyed:
-- Sessions are forked from base session using `opencode run --fork --continue --session`
+- `kugetsu destroy <issue-ref>` - destroy specific session
-- Idle sessions consume minimal resources
+- `kugetsu destroy --pm-agent -y` - destroy PM agent
+- PM should destroy sessions after PR merged (on natural breakpoints)