Skip to content

State machine

Every WU inside an initiative is in exactly one orchestration state at any time. The state is reconciled from durable evidence on every status call — not from what an agent remembers or what a prompt implies.

States

State	When it fires	Next safe action
`planned`	WU exists in the initiative but has no handoff evidence.	Wait for dependencies, then eligible.
`eligible`	All dependencies complete, no launch recorded yet.	`launch_wu` (emit handoff + receipt).
`handoff_emitted`	`launch.json` records a receipt for this WU but no worktree / pickup evidence yet.	`wait` until pickup or relaunch if it stalls.
`claimed`	Claim recorded (delegation pickup or YAML claim) but no execution evidence yet.	`wait` for execution signal.
`active`	Worktree present, YAML is `in_progress`, or delegation registered a pickup.	`wait` — work is in flight.
`worker_returned`	A subagent-stop checkpoint or delegation-completed event fired but the WU is not done yet.	`wait` and inspect before advancing.
`ready_for_finish`	`worker_returned` and the worktree is still present.	`finish_wu` (run `wu:prep` + `wu:done`).
`awaiting_merge`	Branch-PR mode: worker returned, no worktree, no stamp, PR outstanding.	`wait` for PR merge + `wu:cleanup`.
`blocked`	YAML status is blocked or a blocker signal was received.	`wait` for blocker resolution.
`contaminated`	Delegated WU’s `code_paths` overlap with uncommitted changes in the main checkout.	`recover_wu` before advancing anything else in the wave.
`stalled`	Worktree is present but there has been no checkpoint / signal / claim activity for longer than the configured stall threshold (default 4 h).	`recover_wu` — investigate before relaunching.
`needs_relaunch`	Worker returned but the worktree is gone and restore is not applicable or not possible.	`relaunch_wu`.
`stale-but-reconciled`	Delegation row looks stale, but WU YAML, done stamp, execution evidence, or signals show the WU is settled.	Terminal for that stale row; no relaunch.
`conflicting-evidence`	Delegation, WU, worktree, branch, stamp, or signal evidence disagree in a way that cannot be auto-classified.	`recover_wu` — inspect evidence before advancing.
`done`	Stamp file exists or YAML status is `done`.	Terminal.

Priorities

When multiple WUs have open actions, reconciliation orders them so integrity is surfaced first:

recover_wu — contamination, stall, restorable missing worktrees, or conflicting evidence.
finish_wu — ready work that can complete immediately.
relaunch_wu — dead worktrees that cannot be restored and need a new agent.
launch_wu — fresh eligible work.
wait — everything else.

Humans and agents read this ordering the same way. There is no hidden prompt telling Claude “fix integrity first” — the reconciler makes that the first action in the list.

Legacy value mapping

Earlier versions of LumenFlow used ready where the orchestration model now says eligible. The control-plane SDK parser normalizes 'ready' to 'eligible' on read so older status.json files do not fail validation, but every new emitter uses the eligible spelling.

Lifecycle — which phase each state surfaces in.
Capacity + integrity — what makes contamination and stall fire in practice.
Control-plane SDK — OrchestrationStatusValue as the canonical type.