Codewalkers/docs/dispatch-events.md

Dispatch & Events

apps/server/dispatch/ — Task and phase dispatch queues. apps/server/events/ — Typed event bus.

Event Bus

apps/server/events/ — Typed pub/sub system for inter-module communication.

Architecture

• Port: EventBus interface with emit(event) and on(type, handler)
• Adapter: TypedEventBus using Node.js EventEmitter
• All events implement BaseEvent { type, timestamp, payload }

Event Types (52)

Category	Events	Count
Agent	agent:spawned, agent:stopped, agent:crashed, agent:resumed, agent:account_switched, agent:deleted, agent:waiting, agent:output	8
Task	task:queued, task:dispatched, task:completed, task:blocked, task:pending_approval	5
Phase	phase:queued, phase:started, phase:completed, phase:blocked	4
Merge	merge:queued, merge:started, merge:completed, merge:conflicted	4
Page	page:created, page:updated, page:deleted	3
Process	process:spawned, process:stopped, process:crashed	3
Server	server:started, server:stopped	2
Worktree	worktree:created, worktree:removed, worktree:merged, worktree:conflict	4
Account	account:credentials_refreshed, account:credentials_expired, account:credentials_validated	3
Preview	preview:building, preview:ready, preview:stopped, preview:failed	4
Conversation	conversation:created, conversation:answered	2
Log	log:entry	1

Key Event Payloads

AgentSpawnedEvent    { agentId, name, taskId, worktreeId, provider }
AgentStoppedEvent    { agentId, name, taskId, reason }
  // reason: 'user_requested'|'task_complete'|'error'|'waiting_for_input'|
  //         'context_complete'|'plan_complete'|'detail_complete'|'refine_complete'
AgentWaitingEvent    { agentId, name, taskId, sessionId, questions[] }
AgentOutputEvent     { agentId, stream, data }
TaskCompletedEvent   { taskId, agentId, success, message }
TaskQueuedEvent      { taskId, priority, dependsOn[] }
PhaseStartedEvent    { phaseId, initiativeId }
MergeConflictedEvent { taskId, agentId, worktreeId, targetBranch, conflictingFiles[] }
AccountCredentialsRefreshedEvent { accountId, expiresAt, previousExpiresAt? }

Task Dispatch

apps/server/dispatch/ — In-memory queue with dependency-ordered dispatch.

Architecture

• Port: DispatchManager interface
• Adapter: DefaultDispatchManager

How Task Dispatch Works

1. Queue — queue(taskId) fetches task dependencies, adds to internal Map
2. Dispatch — dispatchNext() finds highest-priority task with all deps complete
3. Priority order: high > medium > low, then oldest first (FIFO within priority)
4. Checkpoint skip — Tasks with type starting with checkpoint: skip auto-dispatch
5. Planning skip — Planning-category tasks (research, discuss, plan, detail, refine) skip auto-dispatch — they use the architect flow
6. Approval check — completeTask() checks requiresApproval (task-level, then initiative-level)
7. Approval flow — If approval required: status → pending_approval, emit task:pending_approval

DispatchManager Methods

Method	Purpose
queue(taskId)	Add task to dispatch queue
dispatchNext()	Find and dispatch next ready task
getNextDispatchable()	Get next task without dispatching
completeTask(taskId, agentId?)	Complete with approval check
approveTask(taskId)	Approve pending task
blockTask(taskId, reason)	Block task with reason
getQueueState()	Return queued, ready, blocked tasks

Phase Dispatch

DefaultPhaseDispatchManager — Same pattern for phases:

1. Queue — queuePhase(phaseId) validates phase is approved, gets dependencies
2. Dispatch — dispatchNextPhase() finds phase with all deps complete
3. Auto-queue tasks — When phase starts, pending execution tasks are queued (planning-category tasks excluded)
4. Events — phase:queued, phase:started, phase:completed, phase:blocked

PhaseDispatchManager Methods

Method	Purpose
queuePhase(phaseId)	Queue approved phase
dispatchNextPhase()	Start next ready phase, auto-queue its tasks
getNextDispatchablePhase()	Get next phase without dispatching
completePhase(phaseId)	Mark phase complete
blockPhase(phaseId, reason)	Block phase
getPhaseQueueState()	Return queued, ready, blocked phases