## Problem
`dispatchTask()` shells out to `openclaw gateway call sessions.patch` which
times out when the gateway is busy, causing:
1. Notifications never fire (they're at the end of dispatchTask)
2. Worker state may not be recorded
3. Workers run silently
## Solution (3 changes)
### 1. Make `ensureSession` fire-and-forget
Session key is deterministic, so we don't need to wait for confirmation.
Health check catches orphaned state later.
### 2. Use runtime API for notifications instead of CLI
Pass `runtime` through opts and use direct API calls:
- `runtime.channel.telegram.sendMessageTelegram()`
- `runtime.channel.whatsapp.sendMessageWhatsApp()`
- etc.
### 3. Move notification before session dispatch
Fire workerStart/workerComplete notifications early (after label transition)
before the session calls that can timeout.
## Files Changed
- lib/dispatch.ts — fire-and-forget ensureSession, early notification, accept runtime
- lib/notify.ts — use runtime API for direct channel sends
- lib/services/pipeline.ts — early notification, accept runtime
- lib/services/tick.ts — pass runtime through to dispatchTask
- lib/tool-helpers.ts — accept runtime in tickAndNotify
- lib/tools/work-start.ts — pass api.runtime to dispatchTask
- lib/tools/work-finish.ts — pass api.runtime to executeCompletion/tickAndNotify
- Updated WorkerState type to use 'level' instead of 'tier'.
- Modified functions related to worker state management, including parseWorkerState, emptyWorkerState, getSessionForLevel, activateWorker, and deactivateWorker to reflect the new terminology.
- Adjusted health check logic to utilize 'level' instead of 'tier'.
- Refactored tick and setup tools to accommodate the change from 'tier' to 'level', including model configuration and workspace scaffolding.
- Updated tests to ensure consistency with the new 'level' terminology.
- Revised documentation and comments to reflect the changes in terminology from 'tier' to 'level'.
- Moved setup logic into dedicated files: agent.ts, config.ts, index.ts, workspace.ts.
- Introduced tool-helpers.ts for shared functions across tools, reducing boilerplate.
- Updated tools (status, task-comment, task-create, task-update, work-finish, work-start) to utilize new helper functions for workspace resolution and provider creation.
- Enhanced error handling and context detection in tools.
- Improved project resolution logic to streamline tool execution.
- Added new functionality for agent creation and configuration management in setup.
- Add issue URL to announcement in dispatch.ts
- Add issueUrl field to workerStart notification event
- Update notification message to include URL
- Both automated notifications and manual announcements now show full ticket URL
Example output:
🔧 Spawning DEV (medior) for #7: Create TODO.md...
🔗https://github.com/laurentenhoor/devclaw/issues/7
Adds notification system for full visibility into the DevClaw pipeline:
Events and targets:
- workerStart: Posted to project group when worker spawns/resumes
- workerComplete: Posted to project group when DEV done/QA pass/fail/refine
- heartbeat: Posted to orchestrator DM with tick summary
Implementation:
- New lib/notify.ts module with buildMessage() and sendMessage()
- Integrated into task_pickup, task_complete, and heartbeat_tick
- Uses OpenClaw gateway to invoke message tool
Configuration (optional):
- orchestratorDm: Chat ID for heartbeat notifications
- notifications.heartbeatDm: Enable/disable heartbeat DM (default: true)
- notifications.workerStart: Enable/disable start notifications (default: true)
- notifications.workerComplete: Enable/disable completion notifications (default: true)
Notifications fail silently (logged but don't break main flow).
