Files / Config

.claude/commands/worker-reporting.md

# /worker-reporting

Milestone prompt: **Worker Reporting + Queue Visibility**.

## Goal

Workers/agents reliably self-report state into Mission Control, and the board exposes that state as a visible queue. Fakker stays the brain; Mission Control records and surfaces; workers push their own updates.

## Scope

In:
- Stable worker-facing report API surface (CLI + bridge + HTTP) covering: pickup, progress, blocker, finish, fail, heartbeat.
- Server-side validation that every status transition produces an event row.
- Queue visibility: list pending tasks, list in-progress per worker, list blocked, list recently finished, ordered and paginated.
- Worker heartbeat: lightweight `worker-heartbeat` event with timestamp + worker id; surfaces "stale" workers in board summary.
- Documented worker contract in `CLAUDE.md` / `MISSION_CONTROL.md`.
- Unit tests for each report path and queue query.

Out:
- Web UI (next milestone, see `/webui-dispatch`).
- Auto-assignment, retry, scheduling — these are Fakker's job.
- External notifications (Telegram, email).
- Auth/permissions beyond local single-user.

## Worker Contract

Workers MUST call (via CLI, bridge, or API):

| Event | Call |
| --- | --- |
| Pickup | `update-agent-status --status active --mode Building --current-task-id <id>` then `move-task <id> in_progress` |
| Progress | `append-event --type worker-progress --entity-type task --entity-id <id> --message "..."` |
| Heartbeat | `append-event --type worker-heartbeat --entity-type agent --entity-id <agent_id> --message "alive"` |
| Blocker | `move-task <id> blocked --blocker "..."` |
| Finish | `finish-run <run_id> --status finished --result ... --verification-notes ...` then `move-task <id> done` |
| Fail | `finish-run <run_id> --status failed --summary ...` then `move-task <id> blocked --blocker ...` |

Workers MUST NOT decide what to pick up next. Fakker assigns; workers report.

## Queue Visibility

Add or confirm:
- `mission_control.cli bridge board-summary` includes: counts per status, per-worker in-progress list, blocked list with blocker text, recent finished.
- New CLI: `list-tasks --status pending|in_progress|blocked|done` with deterministic ordering (priority then created_at).
- New CLI: `list-workers` shows agent id, status, mode, current_task_id, last heartbeat age.
- Bridge + API parity for each.

## Deliverables

1. Code in `mission_control/service.py`, `mission_control/bridge.py`, `mission_control/cli.py`, `mission_control/api.py`.
2. Tests in `tests/` covering: each report call, transition → event row invariant, queue ordering, stale-worker detection.
3. Doc updates: `CLAUDE.md` worker rules section confirmed accurate; `MISSION_CONTROL.md` updated if user-visible board fields changed.
4. Verify run: `/verify` passes clean.
5. Commit message: `add worker reporting and queue visibility`.

## Constraints

- Python stdlib + existing repo patterns. No new deps without ask.
- No copy from external orchestration code.
- Mission Control records only — no scheduling, no dispatch loop, no autonomous retries.
- Local-only; no public exposure.
- Use existing skills (FastAPI, workflow) for pattern reference only; do not let them restructure the architecture.

## Done When

- All worker report paths covered by CLI + bridge + API with parity.
- Every status transition emits an event row, enforced by test.
- Queue queries return deterministic ordered lists for pending/in-progress/blocked/done.
- Stale workers surface in board summary.
- `/verify` green.
- Committed with the message above.