Architecture

Bosun is now organized around a monitor runtime, workflow/task ownership layers, and operator-facing surfaces. Older references to root-level files like monitor.mjs, config.mjs, or legacy orchestrator filenames are no longer accurate for the current repo.

Top-level layout

Module	Role
`cli.mjs`	Main CLI entrypoint and runtime command router.
`setup.mjs`	Setup flow entrypoint.
`infra/`	Monitor loop, restart logic, maintenance, presence, sessions, runtime plumbing.
`workflow/`	Workflow engine, node implementations, adapters, and execution helpers.
`workflow-templates/`	Template library for lifecycle, review, maintenance, recovery, and orchestration flows.
`task/`	Task lifecycle, task CLI, execution ownership, claims, and archive behavior.
`server/`	Mini App backend, setup server, and related HTTP endpoints.
`ui/`	Mini App frontend and shared browser assets.
`telegram/`	Bot, sentinel, chat integration, and notification surfaces.
`workspace/`	Workspace registry, context indexing, worktree and shared-state support.
`agent/` and `shell/`	Executor integrations, prompts, hooks, transport layers, and fleet coordination.
`github/` and `kanban/`	GitHub auth/webhooks and board-adapter logic.

Runtime flow

cli.mjs
  ├─ setup and validation commands
  ├─ daemon / sentinel / desktop entrypoints
  └─ monitor startup

infra/monitor.mjs
  ├─ loads resolved config
  ├─ coordinates task and workflow execution
  ├─ talks to task backends and integrations
  ├─ updates operator-facing surfaces
  └─ manages recovery, retries, and lifecycle state

At a high level, Bosun now operates as:

Configuration resolution from CLI, env, `.env`, and JSON config.
Task and workflow intake from internal, GitHub, Jira, or other configured backends.
Executor selection through agent and shell layers.
Validation and lifecycle ownership through workflows, review, and merge gates.
Observation and recovery through telemetry, sentinel, and maintenance loops.

Workflow-first ownership

Current Bosun development emphasizes workflow-first lifecycle ownership. That means task execution, review, PR management, and repair paths increasingly live in reusable workflow templates rather than ad hoc legacy runtime branches.

workflow/ contains execution primitives and nodes.
workflow-templates/ contains high-level lifecycle templates.
task/ and infra/ remain the runtime owners for persistence and orchestration around those flows.

Operator surfaces

Surface	Current backing modules
CLI	`cli.mjs`, `task/task-cli.mjs`, related companion binaries
Mini App	`server/ui-server.mjs` + `ui/`
Setup portal	`server/setup-web-server.mjs` + setup flow
Telegram	`telegram/telegram-bot.mjs`, `telegram/telegram-sentinel.mjs`
Desktop portal	`desktop/` plus CLI desktop entry flags
Voice	`voice/` and UI voice modules

Persistence and coordination

Bosun persists and coordinates multiple classes of runtime state:

task state for internal task management and lifecycle transitions
workflow run state for resumable workflow execution
workspace and shared-workspace metadata for multi-repo operation
session state for agent and operator history
presence and shared coordination data for multi-instance runtime ownership

Recovery model

Modern Bosun recovery is layered rather than handled by one restart loop:

monitor/runtime safeguards in infra/
workflow retries and escalation paths in templates and nodes
task-state and shared-state repair behavior in task/workspace layers
sentinel watchdog behavior in the Telegram companion process