Problem: Provider type (github/gitlab) was auto-detected on every
createProvider() call but never persisted, causing loss of
configuration after session restart.
Solution:
- Add 'provider' field to Project type
- Store detected provider type during project registration
- Pass stored provider type to createProvider() calls
Changes:
- lib/projects.ts: Add provider field to Project type
- lib/tools/project-register.ts: Save providerType to projects.json
- lib/tool-helpers.ts: Pass project.provider to createProvider
- lib/services/*.ts: Pass project.provider to createProvider
Impact: Issue tracker source now persists across restarts. Existing
projects will auto-detect on next use and should be re-registered or
manually edited to add provider field.
Fixes#193
Replaces the file-read-network pattern in dispatch.ts with an OpenClaw
agent:bootstrap hook that injects role instructions at agent init time.
Changes:
- Add lib/bootstrap-hook.ts with hook registration, session key parsing,
and role instruction loading (extracted from dispatch.ts)
- Register agent:bootstrap hook in index.ts
- Remove file I/O from dispatch.ts (no more fs/path imports)
- Remove role instructions from task message body (now injected via
system prompt as WORKER_INSTRUCTIONS.md)
- Add 13 tests for session key parsing and instruction loading
- Remove obsolete docs/poc-bootstrap-hook.ts
The bootstrap hook intercepts DevClaw worker session startup, parses
the session key to extract project name and role, loads the appropriate
instructions from workspace, and injects them as a virtual bootstrap
file that OpenClaw automatically includes in the agent's system prompt.
This eliminates the security audit's potential-exfiltration warning
since dispatch.ts no longer performs any file reads.
Comprehensive investigation of OpenClaw-native alternatives to the
file-read-network pattern in dispatch.ts that triggers security audits.
Key Findings:
- Bootstrap hooks are the recommended solution
- Purpose-built for dynamic workspace file injection
- Plugin-only implementation (no core changes needed)
- Eliminates audit false positive
Deliverables:
- Full research document with pros/cons analysis
- PoC code demonstrating implementation approach
- Migration checklist and testing plan
- Decision matrix comparing alternatives
Recommendation: Implement agent:bootstrap hook to inject role
instructions at system prompt construction time instead of appending
to task message payload.
Addresses issue #181
Addresses issue #179. Adds JSDoc comment to loadRoleInstructions() explaining:
- Purpose: Load role-specific instruction files from workspace
- Intent: Intentionally included in task message context for workers
- Safety: Not data exfiltration, just standard task dispatch context
This clarifies the security audit finding and prevents future false positives.
## Problem
lib/services/queue.ts was not updated during workflow refactor (#147) and still
used hardcoded queue labels: QueueLabel type, QUEUE_PRIORITY constant.
## Solution
- Add getQueueLabelsWithPriority() to derive queue labels from workflow config
- Add getQueuePriority() to get priority for any label
- Update getTaskPriority() and getRoleForLabel() to accept workflow config
- Update fetchProjectQueues() to use workflow-derived labels
- Add getTotalQueuedCount() helper
## Files Changed
- lib/services/queue.ts — use workflow config for all queue operations
- lib/tools/status.ts — handle dynamic queue labels, include queueLabels in response
## Backward Compatibility
- QueueLabel type kept as deprecated alias
- QUEUE_PRIORITY kept as deprecated constant
- All functions accept optional workflow parameter, default to DEFAULT_WORKFLOW
## Summary
Introduces a configurable workflow state machine that replaces all hardcoded
state labels. The default workflow matches current behavior exactly, ensuring
backward compatibility.
## Architecture
### lib/workflow.ts — Core workflow engine
XState-style statechart configuration:
```typescript
type StateConfig = {
type: 'queue' | 'active' | 'hold' | 'terminal';
role?: 'dev' | 'qa';
label: string;
color: string;
priority?: number;
on?: Record<string, TransitionTarget>;
};
```
All behavior is derived from the config:
- Queue states: `type: 'queue'`, grouped by role, ordered by priority
- Active states: `type: 'active'` — worker occupied
- Transitions: defined with optional actions (gitPull, detectPr, closeIssue, reopenIssue)
- Labels and colors: derived from state.label and state.color
### Derivation functions
- `getStateLabels()` — all labels for issue tracker sync
- `getLabelColors()` — label → color mapping
- `getQueueLabels(role)` — queue labels for a role, ordered by priority
- `getActiveLabel(role)` — the active/in-progress label for a role
- `getRevertLabel(role)` — queue label to revert to on failure
- `detectRoleFromLabel()` — detect role from a queue label
- `getCompletionRule(role, result)` — derive transition rule from config
## Files Changed
- **lib/workflow.ts** — NEW: workflow engine and default config
- **lib/providers/provider.ts** — deprecate STATE_LABELS, LABEL_COLORS; derive from workflow
- **lib/providers/github.ts** — use workflow config for label operations
- **lib/providers/gitlab.ts** — use workflow config for label operations
- **lib/services/pipeline.ts** — use getCompletionRule() from workflow
- **lib/services/tick.ts** — use workflow for queue/active labels
- **lib/services/health.ts** — use workflow for active/revert labels
- **lib/tools/work-start.ts** — use workflow for target label
## Backward Compatibility
- DEFAULT_WORKFLOW matches current hardcoded behavior exactly
- Deprecated exports kept for any external consumers
- No breaking changes to tool interfaces or project state
## Future Work
- Load per-project workflow overrides from projects.json
- User-facing config in projects/workflow.json
- Tool schema generation from workflow states
## 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
## 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
Change Planning label from #6699cc (blue) to #95a5a6 (grey/slate) to distinguish it from To Do (#428bca).
Note: Only affects newly created labels. Existing repos need manual update.
## Changes
- Remove `activeSessions` parameter from health check (was never populated)
- Add gateway session lookup via `openclaw gateway call status`
- Add issue label lookup via `provider.getIssue(issueId)`
- Implement detection matrix with 6 issue types:
- session_dead: active worker but session missing in gateway
- label_mismatch: active worker but issue not in Doing/Testing
- stale_worker: active for >2h
- stuck_label: inactive but issue has Doing/Testing label
- orphan_issue_id: inactive but issueId set
- issue_gone: active but issue deleted/closed
## Files
- lib/services/health.ts — complete rewrite with three-source triangulation
- lib/tools/health.ts — remove activeSessions param, fetch sessions from gateway
- lib/services/heartbeat.ts — remove empty activeSessions calls, pass sessions map
