Architecture

Bosun is organized as a modular Node.js application with clear component boundaries. Each module has a single responsibility and communicates through well-defined interfaces.

High-Level Flow

┌──────────┐     ┌──────────────┐     ┌────────────────────┐
│  cli.mjs │────▶│  monitor.mjs │────▶│  ve-orchestrator   │
│  (entry) │     │  (supervisor)│     │  (task runner)     │
└──────────┘     └──────┬───────┘     └─────────┬──────────┘
                        │                       │
                   ┌────┴────┐            ┌─────┴──────┐
                   │ telegram │            │ ve-kanban  │
                   │ bot.mjs  │            │ .mjs       │
                   └─────────┘            └────────────┘

1. cli.mjs loads config and routes to the appropriate handler (setup, doctor, daemon, or main start)
2. monitor.mjs is the supervisor loop — orchestration, smart PR flow, maintenance, fleet sync
3. ve-orchestrator.mjs handles native task execution with parallel slots, retries, and merge checks
4. ve-kanban.mjs wraps VK CLI operations (list, submit, rebase, archive)

Component Map

Execution Modes

Internal Mode (EXECUTOR_MODE=internal)

Tasks run through the internal agent pool inside the monitor process. The agent pool manages executor selection, weighted distribution, and failover.

Monitor → Agent Pool → [Copilot Shell | Codex Shell | Claude Shell]
                            ↓
                     Task Execution
                            ↓
                     Smart PR Flow → CI Check → Merge

VK Mode (EXECUTOR_MODE=vk)

Task execution is delegated to the Vibe-Kanban orchestrator scripts. The monitor handles supervision and PR lifecycle.

Hybrid Mode (EXECUTOR_MODE=hybrid)

Combines internal and VK modes. Internal handles primary execution; VK picks up overflow or specific task types.

Shared State Model

Distributed task coordination across agents and workstations uses a shared state system:

• Owner heartbeat — Each claim has ownerId (workstation+agent) and ownerHeartbeat timestamp, renewed periodically to prove liveness
• Attempt tokens — Unique UUID per attempt for idempotent operations
• Retry/ignore flags — retryCount tracks attempts, ignoreReason marks tasks agents should skip
• Conflict resolution — Active heartbeat wins over stale claims (first-come-first-served if both active)

Claim Lifecycle

1. claimTaskInSharedState(taskId, ownerId, attemptToken)
2. [work...] renewSharedStateHeartbeat() periodically
3. releaseSharedState(taskId, attemptToken, 'complete'|'failed'|'abandoned')
4. sweepStaleSharedStates() — background cleanup

Smart PR Flow

The smartPRFlow in monitor.mjs handles the full PR lifecycle:

1. Branch creation — from configured target branch
2. PR creation — with conventional commit title and structured body
3. CI monitoring — polls check status
4. Auto-rebase — on merge conflicts with target
5. Merge decision — merge when all checks pass
6. Cleanup — archive task, prune worktree

Error Recovery

Bosun uses multiple layers of error recovery:

• Autofix — Pattern matching on error signatures with guarded fix execution
• Circuit breakers — Prevent infinite retry loops by tracking consecutive failures
• Stale sweeps — Background process that reclaims abandoned tasks
• Daemon restart policy — Configurable crash tracking with cooldown periods
• Sentinel watchdog — Independent process that can restart the monitor on crash

Data Persistence

State is persisted in .cache/bosun/: