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 (e.g., a subagent crashed or cleaned up before wu:done).	relaunch_wu.
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:

1. recover_wu — contamination or stall.
2. finish_wu — ready work that can complete immediately.
3. relaunch_wu — dead worktrees that need a new agent.
4. launch_wu — fresh eligible work.
5. 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 ADR-010 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.

Related

• 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.