Skip to content

Worker Stage Transitions

Workers running inside a dispatched worktree can declare their own stage at key phase boundaries. These explicit declarations give the heartbeat cleaner visibility into what the worker is doing, without changing the heartbeat's authority over the actual lifecycle stage.

How it works

Each declaration is a single CLI call that stores a label on the active dispatch run. The operator surface (just task status <slug>, the tasks server /status page) shows the label alongside elapsed time.

The heartbeat still infers the lifecycle stage from observable state (run rows, PR metadata, exit codes). Worker declarations are visibility refinements — they make intent explicit. If a worker skips a call, the system degrades gracefully to the inferred label.

CLI

just task declare-stage <phase>

Valid phases and when to emit each:

Phase When
setup After reading the task file, before planning
coding Before writing the first implementation line
closeout Code complete, before just pr create
pr_testing After PR is open, CI running

The command resolves the active run from the canonical SQLite runtime DB (by worktree path) or the task/<slug> branch. If there is no active dispatch run (e.g. the worker is running in a plain shell, not from just dispatch), the call noops silently.

Expected sequence for a healthy dispatch

setup → coding → reviewing → closeout → pr_testing

The reviewing label is set by just review automatically; workers do not declare it. A worker that skips some transitions still makes forward progress. The heartbeat infers the missing phases from: - setup/coding: inferred from a live worker run - closeout: inferred from a clean worker exit - pr_testing: inferred from PR existence via PR metadata

  • just task status <slug> — read current stage and subphase for a task
  • task-execute/SKILL.md § Stage Transitions — full transition table for workers
  • libs/tasks/tasks/manager/runtime.py — SUBPHASE_CHOICES, mark_current_subphase
  • tasks/workstreams/tasks-manager/initiatives/task-manager-redesign-linear-stages-and-centralized-transitions/spec.md — authoritative design including the planned stage_transitions log and centralized transition function (future work in the initiative)