Skip to content
LumenFlow

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

Section titled “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

Section titled “Priorities”

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

  1. recover_wu — contamination, stall, restorable missing worktrees, or conflicting evidence.
  2. finish_wu — ready work that can complete immediately.
  3. relaunch_wu — dead worktrees that cannot be restored and 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

Section titled “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.

Section titled “Related”