Mission Lifecycle

Missions progress through a defined set of statuses as work moves from planning to completion. Kavi automatically synchronizes mission status based on task state and acceptance results, so the status always reflects the true state of the mission.

Mission Statuses

Status	Description
`planning`	Initial state when the mission is created with a planning task. Codex is decomposing the prompt into an execution plan.
`active`	Tasks are executing. At least one task is pending or running.
`blocked`	A task has failed or is blocked, or acceptance verification has failed. Requires operator attention.
`awaiting_acceptance`	All tasks have completed successfully. The mission is waiting for acceptance verification to run.
`ready_to_land`	Acceptance verification has passed. The mission can be landed into the target branch.
`landed`	The mission's work has been merged into the target branch.
`completed`	Terminal state. The mission is fully done.

State Transitions

The following diagram shows how missions move between statuses:

planning
  |
  v
active <----------+
  |                |
  +---> blocked ---+
  |
  v
awaiting_acceptance
  |
  +---> blocked (acceptance failed) ---> active (retry)
  |
  v
ready_to_land
  |
  v
landed
  |
  v
completed

Transition Rules

planning to active: The planning task completes and produces an execution plan, or a direct root task begins executing.
active to blocked: Any task in the mission enters failed or blocked status.
blocked to active: The operator resolves the blocking issue (e.g., retries a failed task) and tasks resume.
active to awaiting_acceptance: All tasks in the mission reach completed status.
awaiting_acceptance to ready_to_land: All acceptance checks pass or are skipped.
awaiting_acceptance to blocked: An acceptance check fails. The operator must address the failure.
ready_to_land to landed: The operator runs kavi land, merging work into the target branch.
landed to completed: Terminal transition after landing.

Automatic Status Synchronization

Kavi runs syncMissionStates whenever session state changes. This function examines every mission and updates its status based on the current state of its tasks and acceptance pack:

If the mission has been landed (landedAt is set), status is set to landed.
If there are no execution tasks, the planning task is still active, and there is no direct root task, status remains planning.
If any task is failed or blocked, status is set to blocked.
If any task is pending or running, status is set to active (or planning if only the planning task is running and no plan has materialized yet).
If all tasks are completed:
- Acceptance failed: status is blocked
- Acceptance passed: status is ready_to_land
- Acceptance pending: status is awaiting_acceptance
If a plan exists but no tasks remain, status is completed.

The active task list (activeTaskIds) is also refreshed during synchronization, filtering to only tasks with pending, running, or blocked status.

Checkpoints

Checkpoints are immutable progress markers recorded throughout the mission lifecycle. Each checkpoint captures a moment in the mission's execution history.

Checkpoint Kinds

Kind	Trigger	Description
`created`	Mission creation	Recorded when the mission is first created from the operator prompt.
`planning_started`	Planning task dispatched	Codex has been assigned a planning task to decompose the prompt into an execution graph.
`plan_materialized`	Plan attached to mission	The execution plan produced by the planning task has been attached to the mission.
`task_started`	Task begins execution	An agent has started working on a task belonging to this mission.
`task_progress`	Task produces intermediate output	An agent reports progress on a running task (e.g., files changed, intermediate results).
`task_stalled`	Task stops making progress	A running task has not produced output within the expected heartbeat interval.
`task_completed`	Task finishes successfully	An agent has completed a task with a successful result.
`task_failed`	Task fails	An agent task has failed or been marked as blocked.
`acceptance_verified`	Verification runs	Acceptance checks have been executed and the pack status has been updated.
`landed`	Mission lands	The mission's work has been merged into the target branch via `kavi land`.

Checkpoint Fields

Each checkpoint records:

Field	Type	Description
`id`	`string`	Unique identifier (prefixed with `checkpoint-`)
`kind`	`string`	One of the checkpoint kinds listed above
`title`	`string`	Short human-readable title
`detail`	`string`	Extended description of what happened
`taskId`	`string \| null`	ID of the related task, if applicable
`createdAt`	`string`	ISO timestamp of when the checkpoint was recorded

Checkpoints are append-only. They provide a complete audit trail of the mission's execution history and are never modified or deleted after creation.

Example Checkpoint Sequence

A typical mission using guided_autopilot mode produces checkpoints in this order:

created -- Mission created from operator prompt
planning_started -- Codex begins planning
plan_materialized -- Execution plan attached
task_started -- First execution task begins
task_progress -- Agent reports intermediate progress
task_completed -- First task finishes
task_started -- Second task begins (dependency satisfied)
task_completed -- Second task finishes
acceptance_verified -- Verification checks run
landed -- Mission merged into target branch

Mission Lifecycle

On this page