Model-Agnostic Fleet Lifecycle Authority

LumenFlow’s fleet lifecycle authority lets local agents, hosted workers, CLI surfaces, MCP callers, and future control planes cooperate on the same workspace without making any one provider or model the source of truth.

Authority Objects

Lifecycle truth is derived from durable workflow evidence:

WU and lane

The WU id is the durable unit of work. The lane and lane lock define the concurrency boundary.

Session and lease

Session and lease evidence identify the current holder and freshness of active work.

Branch and worktree

The lane branch is the durable Git line of work. The worktree is a filesystem projection, not the only truth.

Stamp and audit

Done stamps, recovery records, quarantine logs, and memory signals prove transitions.

Provider names, model names, client UIs, hosted runners, and plugins are adapter metadata. They may help route work or display ownership, but they do not decide cleanup, recovery, completion, or scheduling authority.

Durable Handoff Receipts

The canonical wu:brief handoff emits a versioned lifecycle receipt when the WU has complete claim metadata. It binds the policy digest, issuing owner and claim transaction, WU and lane, exact protected WU payload hash, canonical repository and worktree, expected baseline head and phase, permitted operation, expiry, and sequence. wu:prep, wu:done, and wu:recover accept it only for an explicit cross-session handoff; an unchanged authenticated claim-holder session remains the normal path.

The issued receipt is recorded durably with the brief evidence. Each permitted operation creates an exclusive, fsync-backed consumption audit record, so a receipt cannot be replayed for that operation. A modified, expired, unrecorded, wrong-WU, wrong-owner, wrong-repository, wrong-phase, or disallowed-operation receipt fails closed. claim-auto records only non-authoritative evidence and never issues a receipt.

This is workflow authority, not a local privilege boundary: two processes that run as the same OS user and can modify the same journal are not sandboxed from one another. Use a protected or shared journal with independent access control when that stronger isolation is required.

Active Leases And Quarantine

Cleanup commands are conservative. wu:prune --execute blocks destructive cleanup for active or recently active WU leases. When it removes tracked stale worktree metadata that may still be useful to inspect, it writes audit evidence under .lumenflow/quarantine/worktrees/cleanup.jsonl.

Raw Git pruning is an implementation detail. The LumenFlow decision is made from WU state, lease/session evidence, lane branch, worktree path, and stamps first.

Restore Before Reset

If an active or recently active WU lost its worktree but the lane branch still exists, restore it:

pnpm wu:recover --id WU-042 --action restore

Restore recreates the worktree from the lane branch and preserves WU status, branch, baseline/main metadata, and completion evidence. Use reset/reclaim only when restore is impossible or intentionally chosen for abandoned work.

Delegation Reconciliation

Delegation records are orchestration evidence, not final lifecycle truth. orchestrate:monitor reconciles delegation rows against WU YAML, done stamps, execution evidence, launch records, memory signals, lease/session evidence, and worktree/branch state before it calls work pending or stuck.

Settled stale rows become reconciled stale results. Contradictory evidence is surfaced as a recovery conflict so an orchestrator can inspect the WU rather than blindly relaunching it.

Flow Diagnostics

Fleet scheduling also needs actionable dependency and capacity signals. flow:bottlenecks and flow:report surface dependency cycles, lane contention, file overlap, and priority pressure so orchestrators can choose safe waves without relying on hidden prompt context.