fix(kugetsu): prevent excess agent spawning with flock + sequential processing

- count_active_dev_sessions() now excludes pm-agent.json from count
- process_queue() now calls kugetsu start directly (not opencode run)
- process_queue() uses dynamic batch size = available_slots
- process_queue() has retry logic (max 3 attempts) on failure
- cmd_start() now uses flock around critical section
- Added notification types: task_queued, task_dequeued, task_started, task_completed, task_error
- Removed QUEUE_DAEMON_BATCH_SIZE config (no longer needed)

Fixes issue #146

.github/ISSUES/fix-queue-daemon-excess-agents.md

@@ -63,5 +63,5 @@ New notification types:
 
 - [x] Issue created
 - [x] Implementation
-- [x] PR created (#147)
+- [ ] PR created
 - [ ] Merged

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,53 +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
 
 ## 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

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

docs/CHANGELOG.md

@@ -1,111 +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.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