# KAN-13: Show workflow steps as Queued until a worker starts them

## Ticket

https://danubii.atlassian.net/browse/KAN-13

## Branches

- Source: `ai/KAN-13-show-workflow-steps-as-queued-until-a-worker-sta`
- Target: `main`

## Repositories

- `danubii/openclaw-orchestrator`: `ai/KAN-13-show-workflow-steps-as-queued-until-a-worker-sta` -> `main` (Completed)

## Summary

https://danubii.atlassian.net/browse/KAN-13
When no worker is available, workflow steps should remain visibly queued until a worker actually claims the job. The UI and backend must distinguish queued jobs from running jobs so users can see whether work is waiting for capacity or actively executing.
Scope
- Update workflow/job state handling so newly created worker jobs are represented as Queued until a worker claims them.
- Only mark a step as Running/In Progress after the worker has successfully claimed the job and started execution.
- Expose queued vs running state clearly through workflow APIs, workflow detail, workflow dashboard, and any step timeline/status components.
- Show queued duration or queued timestamp where useful, especially when workers are busy or unavailable.
- Ensure live updates move the step from Queued to Running without requiring a page refresh when the worker picks it up.

## Approved Plan

Show workflow worker-backed steps as `Queued` while a worker job exists but has not been claimed, and show `Running` only after the worker claims/starts the job. Expose the distinction in workflow APIs, dashboard, detail timeline, and live refresh behavior.
- Pending worker jobs render as `Queued`, not `Running` or `Pending`.
- Claimed worker jobs render as `Running` and use worker `StartedAt` for running duration.
- Queued timestamp/duration is visible where useful.
- Workflow detail updates from queued to running through existing live refresh/log flow.
- Dashboard and detail views use the same queued/running interpretation.
- Retries, reruns, and requeued jobs return to `Queued` until claimed.
- Backend tests cover queued, running, completed, failed, retry/requeue, and no-worker cases.

## Test Summary

Running repository test profile `openclaw-local` for `KAN-13`.
danubii/openclaw-orchestrator
- Target: `main`
- Working: `ai/KAN-13-show-workflow-steps-as-queued-until-a-worker-sta`
Required: `True`
Exit code: `0`
Timed out: `False`
Blocked: `False`

## Cross-Repository Integration Summary

Single-repository workflow; cross-repository integration was not required.

## Smoke Test Summary

Running repository smoke profiles for `KAN-13` after implementation, tests, and cross-repository integration.
- `danubii/openclaw-orchestrator` in `repo-10-danubii-openclaw-orchestrator`: `ai/KAN-13-show-workflow-steps-as-queued-until-a-worker-sta` -> `main`
Required: `True`
Exit code: `0`
Timed out: `False`
Blocked: `False`
```bash
GIT_TERMINAL_PROMPT=0 GIT_ASKPASS=/workspace/git-askpass.sh git clone --branch 'main' 'https://github.com/Danubii/openclaw-orchestrator.git' 'repo-10-danubii-openclaw-orchestrator' && git -C 'repo-10-danubii-openclaw-orchestrator' checkout --detach '8bca2a2ab7ff7d59ca6d0845d70bc2026db51f10'

## Review Summary

KAN-13 introduces first-class `Queued` vs `Running` state projection for worker-backed workflow steps. The implementation derives effective step status from live `WorkerJob` timestamps rather than persisting a new `WorkflowStepStatus.Queued`, adds configurable stale-running-job recovery with atomic per-row guards, surfaces the new state through both list and detail APIs, and updates the frontend status badge, dashboard metrics, and timeline copy. A focused Playwright spec validates the queued-before-pickup / running-after-pickup flow against a new mock web server.
All acceptance criteria are addressed. The build is green, 56 backend tests pass, linting passes, the production Next.js build succeeds, and both Playwright specs pass.
---
**APPROVE_WITH_NOTES**
No blocking or high-severity defects were found. The implementation is functionally correct. Four medium issues are flagged for follow-up; none affect correctness in production at current scale.
---
None.
---

## Manual QA

KAN-13: Show workflow steps as Queued until a worker starts them
Automated flow completed through test deploy. Medium review findings accepted for this run; no blocker/high findings remain.

## Guardrails

- OpenClaw created this PR handoff record, but does not merge automatically.
- Human review is required before merge.