Lifecycle

LumenFlow separates initiative orchestration into six distinct concerns. Keeping them separate is what lets humans, local agents, and compatible remote orchestration surfaces drive the same initiative without re-deriving the rules.

1. Plan

Compute the logical-wave dependency graph. A WU’s logical wave is its shortest-path distance from any root, and it does not change unless the graph changes.

Inputs: initiative YAML, WU YAMLs, lane WIP limits.
Output: plan.json in the attempt bundle (see Artifact bundle).
Run it with pnpm orchestrate:initiative -i INIT-XXX --dry-run (no handoff files written).

2. Handoff

Record the intent to launch a WU. This is the step where the orchestrator produces one universal handoff artifact and writes a launch receipt tying that artifact to (initiative, logical_wave, launch_attempt, handoff_format). Capability-declared adapters may project that artifact for a compatible host, but do not create a separate lifecycle authority.

Prompt emission is not launch. The receipt in launch.json is the durable record; the prompt is adapter output.
wu:brief remains the canonical full handoff surface for a single WU. For an explicit cross-session continuation, its durable lifecycle receipt is carried unchanged as --handoff-receipt to wu:prep, wu:done, or wu:recover. The verifier binds the receipt to the WU, lane, owner, policy, protected WU payload, canonical repository/worktree, expected head and phase, operation, expiry, and one-use-per-operation audit sequence. It rejects changed, stale, replayed, or cross-context receipts; claim-auto does not issue one. Launch modes in orchestrate:initiative write the same client-shaped handoff artifacts into the bundle and print the artifact paths by default. When the WU carries an unresolved trajectory:* signal (see below), wu:brief renders a Trajectory redirect block above the acceptance criteria so a worker resuming from a brief sees the evidence before its first tool call.
--print-handoffs replays the stored handoff artifacts inline when a human needs manual copy/paste output.
Clients that can spawn workers directly do so here; clients that cannot leave the handoff as a pending payload the human copies into their agent.

3. Execution

The worker claims the WU (wu:claim), runs wu:brief, implements the change, runs wu:prep, and completes via wu:done. The orchestrator does not participate in this phase — it is pure lifecycle evidence, the same evidence any LumenFlow WU produces whether it came from an initiative or not.

Every generated handoff — wu:brief, wu:delegate, and the launch artifacts this orchestration writes — renders that same two-step contract from one shared renderer and states it as the worker’s only completion authority: run wu:prep, then execute only the exact command it prints, from main. No generated handoff offers a competing path (raw gates plus a standalone verification command, a status poll with a hand-typed wu:done, or worker return) alongside it.

For local worktree and worktree-pr claims, claimed_branch is a durable binding rather than a branch-name hint. Remote-backed claims persist it in both canonical and worktree WU documents only after WU/lane/status/claim-time, owner, active session, configured-root realpath, current branch, exactly one Git worktree registration, and both active state ledgers agree. Local worktree claims using --no-push or git.requireRemote=false are refused before mutation because they cannot establish that dual-document authority; use branch-only mode for offline work. Branch-PR/cloud behavior remains unchanged.

Every wu:rebase path—including --dry-run, --continue, and --abort—and the first local-worktree wu:done preflight consume that binding. An explicit WU id cannot authorize an arbitrary custom branch. If the binding is absent, first run pnpm wu:repair --claim --id WU-XXX --check; remove --check only after reviewing the evidence. Repair fills absent fields only, rechecks both readbacks, remains retry-safe after a partial write, and refuses conflicts or inactive lifecycle state.

Independent review (worker execution contract)

Every WU resolves to one worker execution contract: an effective independent-review mode, its source, its risk reasons and a digest over those resolved fields. The contract is computed, not written in prose, and the same resolution runs at three points: the worker’s final wu:prep, the pre-merge boundary inside wu:done, and the publication seam on whatever commit actually lands — re-checked after each auto-rebase and contention retry, on every landing route including branch-only, branch-PR and --already-merged recovery, where the merged lane commit is judged under the record as it stood before finalization. The generated brief shows it in a Worker Execution Contract block whose heading names the rollout stage — enforced for authored and legacy-floored requirements, observed (reported, not refused) for requirements the risk policy derived — deliberately distinct from the advisory Suggested Routing block above it.

The worker owns the whole lifecycle either way. A reviewer, when the contract asks for one, is read-only: they assess a candidate the worker froze, and they never complete the WU.

Solo ad-hoc WU — no reviewer. The ordinary case. No P0, no api exposure, no safety-critical path, so auto resolves to none:

pnpm wu:review --id WU-XXXX --contract
# Independent review: none (authored auto, source auto-default)
# Contract digest: <sha256>

pnpm wu:review --id WU-XXXX --review-status
# State: ready
# Next action: proceed

pnpm wu:prep --id WU-XXXX   # normal gates, no reviewer step
pnpm wu:done --id WU-XXXX   # exactly the command wu:prep printed

Nothing extra runs: no reviewer, no supervisor process, and no host attestation that was never requested.

Required review — request, record, then land. Either authored (--set-independent-review required), floored by a legacy requires_review: true, or derived by the risk policy:

# Author the policy (recorded through the governed edit path; the effective
# mode is still resolved, so an explicit none cannot weaken an active floor)
pnpm wu:review --id WU-XXXX --set-independent-review required

pnpm wu:review --id WU-XXXX --review-status
# State: awaiting-review
# Next action: request-independent-review

# The reviewer — a different principal, holding an externally signed,
# single-use grant — assesses the frozen candidate read-only and records:
pnpm wu:review --id WU-XXXX --record --verdict approved \
  --reviewer-session <id> --scope-key <key> --grant <token>

pnpm wu:review --id WU-XXXX --review-status
# State: complete
# Next action: proceed

pnpm wu:prep --id WU-XXXX
pnpm wu:done --id WU-XXXX

A changes-required verdict returns state changes-required and next action address-findings. The verdict binds to the exact candidate SHA and the contract digest: a material edit after the review asks for re-review-current-candidate, and a policy change that moves the digest invalidates the old evidence rather than carrying the approval forward. Missing, stale, wrong-WU, self-issued, negative and unsupported authority evidence all fail closed — advisory signals and prose certify nothing.

Enforcement is staged at launch. A requirement that was authored, carried over from a legacy requires_review: true floor, or produced by an unsupported policy value refuses the boundary. A requirement the risk policy derived on its own is reported in full — effective mode, refusal code, digest and next action — and refuses nothing, until reviewer grants are provisioned. Nothing is skipped or weakened in that stage: the effective mode stays required, no evidence is fabricated, and no per-run flag moves a WU between stages.

4. Reconciliation

Read the durable evidence and classify every WU into an orchestration state:

WU YAML status + .done stamps
Worktree presence on disk
Launch receipt from launch.json
Delegation registry pickup timestamp
Checkpoint + signal activity in shared memory
WU lease/session evidence and lane branch presence
Main-checkout contamination (from git status)
Stalled worktrees (no activity past the configured threshold)

Reconciliation is the heart of the control plane. The canonical @hellmai/lumenflow-packs-software-delivery/initiatives owner ships a single classifier that the CLI and MCP tools share, so the answer is the same no matter which surface you look at. The historical @hellmai/lumenflow-initiatives package is a deprecated compatibility shell that forwards its published entrypoints to that owner.

orchestrate:monitor uses this same evidence before calling a delegation stuck. Stale rows for WUs that are already done or otherwise settled become reconciled stale results, while contradictory rows are surfaced as conflicts requiring recovery. A vendor/client/model label is never the lifecycle key.

Trajectory supervision

Reconciliation answers “is the agent alive?”. A separate, ledger-backed classifier answers a harder question: “is the agent getting anywhere?” orchestrate:monitor reads the per-gate gate_attempt ledger, lane-branch commits, and checkpoint/signal evidence for every active WU and classifies it as productive, slow, stagnating, thrashing, awaiting-wake, or unknown — with no wall-clock term: a WU can be classified stagnating minutes after claim if the ledger shows the same gate failing repeatedly with no diff change.

stagnating, thrashing, and awaiting-wake each emit one A2A signal (trajectory:stagnating, trajectory:thrashing, trajectory:awaiting-wake); two or more active WUs sharing one root cause emit a single trajectory:shared-failure signal instead of one per WU. orchestrate:monitor --recover lists a redirect suggestion for each — a copyable mem:signal --to <worker> --intent PROPOSE command and a wu:block alternative — beside the existing stuck-delegation suggestions. These are suggestions only: the classifier and --recover never call wu:block, delegation recovery, session termination, or re-dispatch on their own authority. See Trajectory Supervision for the full design.

5. Finish

Drive WUs that are ready_for_finish through wu:prep + wu:done. Completion semantics differ by claimed mode:

Worktree mode — wu:done succeeds, the .done stamp exists, the worktree is cleaned up. Binding evidence is re-attested immediately before completion and again before cleanup.
Branch-PR / cloud mode — wu:done creates a PR and the WU enters awaiting_merge; it becomes done only after the merge and wu:cleanup produce the terminal stamp.

Worker return is not completion. A subagent stopping, a delegation completing, or a prep-ready worktree showing up only mean the classifier now has stronger evidence.

Host guarantees the lifecycle depends on

Every phase above writes state and scaffolding, and those writes carry the same contract on Windows, macOS and Linux — satisfied by each host’s own native primitive rather than by exporting one host’s model to the others (WU-3877, ADR-033 §4/§5/§13):

Safety and launch wrappers are native. scripts/safe-git ships with a scripts/safe-git.cmd companion enforcing the identical guards, and wu:brief --launch-script / wu:delegate emit both a .sh and a .cmd launch wrapper, advertising only the one this host can run. Needing Git Bash is not an acceptable native result.
Protected local state is owner-isolated. Gate-comparison artifacts and lifecycle mutation evidence are readable by the owning OS principal and no other, through a POSIX mode off Windows and a native owner-only DACL on it. If the boundary cannot be applied the operation refuses; it never silently succeeds having restricted nothing.
State writes replace atomically. Publishing a rewritten event log, a lifecycle receipt or an installed pack goes through one shared helper that retries a Windows open-handle failure within a bounded budget and, if that budget is exhausted, leaves the previous valid copy untouched.
Remediation text is pasteable where you are. An out-of-memory retry hint prints the POSIX environment-prefix form on Linux and macOS, and both the cmd.exe and PowerShell forms on Windows.

The Windows halves of these guarantees are unverified by construction on a POSIX developer machine and in CI today: they are asserted through injected platform seams, not executed against a Win32 kernel. Real-OS proof arrives with the blocking windows-latest CI leg (WU-3879). See docs/05-building-block-view/native-filesystem-guarantees.md for the mechanism table and the exact verification status of each row.

6. Status

Project the reconciled truth to humans, agents, and remote surfaces:

Stdout — concise human summary + next-step commands.
Launch stdout — wave summary, artifact bundle paths, and per-WU handoff file paths by default; --print-handoffs replays stored handoffs inline.
--json — authoritative machine-readable state for agents and remote launchers.
Artifact bundle — durable files for resume, audit, and adapter generation.
Capability-declared adapter projections — optional host-specific views on top of the control-plane contract; they do not alter lifecycle authority.

Every surface answers the same question: what is the next safe action for this initiative?

State machine — the vocabulary this lifecycle produces.
Artifact bundle — the durable files each phase writes.
Capacity + integrity — how reconciliation refuses to advance unsafely.
Trajectory Supervision — the productivity classifier behind orchestrate:monitor --recover’s redirect suggestions and wu:brief’s Trajectory redirect block.