> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DevBox Lifecycle v0

> State model, transition matrix, and execution gating rules for DevBox lifecycle.

# DevBox Lifecycle v0

## Scope

Defines the minimum lifecycle model for AIOS DevBox in v0, including desired-state semantics, observed phases, legal transitions, and execution gating rules used by Gateway, Probe, Scheduler, and self-heal flows.

This page formalizes the lifecycle baseline derived from Sealos-inspired state handling and the accepted AIOS freeze decisions.

## Terminology

* **Desired state**: control-plane target written by Gateway.
* **Observed phase**: execution-side state reported by Probe.
* **Converging transition**: a transition that requires orderly cleanup such as channel close, command cancel, and metadata flush.
* **Recovering**: explicit intermediate phase for bounded local recovery.

## Normative Spec

### State Model

DevBox lifecycle in v0 uses a two-level model:

#### Desired state

* `running`
* `paused`
* `stopped`
* `terminated`

`shutdown` MAY be accepted as an input alias but MUST converge to `stopped` as the normalized state representation in the v0 documentation baseline.

#### Observed phase

* `pending`
* `running`
* `pausing`
* `paused`
* `stopping`
* `stopped`
* `recovering`
* `failed`
* `terminated`
* `unknown`

### Authority Rules

* Gateway MUST own desired-state mutation.
* Probe MUST report observed phase and MUST NOT rewrite desired state.
* Any execution action MUST hold a valid lease before mutating local runtime state.

### Transition Rules

* `running -> paused` is allowed and MUST converge through `pausing -> paused`.
* `paused -> running` is allowed and MUST converge back through `pending` or directly to `running` when immediately ready.
* `running -> stopped` is allowed and MUST follow a converging stop path.
* `paused -> stopped` is allowed and MUST follow a converging stop path.
* `stopped -> running` is allowed and MAY include warm-up through `pending`.
* `running -> terminated` is allowed and MUST follow a converging termination path.
* `paused -> terminated` is allowed and MUST follow a converging termination path.
* `stopped -> terminated` is allowed as final teardown.
* `terminated -> stopped` MUST be rejected.
* `terminated -> running` MUST be rejected in v0.
* `failed -> running` MAY occur only through an explicit recovery path that succeeds.

### Converging Transition Actions

For converging lifecycle actions, the control flow MUST follow:

`observe -> diff -> preflight -> mutate -> health-check -> emit`

The following actions are mandatory during converging stop/terminate flows:

* channel close
* command cancel
* metadata flush

Snapshot creation MAY be applied according to snapshot policy but is not mandatory for every transition.

### Execution Gating

New execution work MUST only be admitted when observed phase is compatible with execution. The v0 recommended execution-admit phases are:

* `pending`
* `running`
* `paused` only when the action is explicitly resume-related

The following phases MUST NOT accept new execution work:

* `pausing`
* `stopping`
* `recovering`
* `failed`
* `terminated`
* `unknown`

### Recovering Phase

* Any non-terminal state MAY enter `recovering` for bounded local repair.
* Exceeding recovery budget MUST escalate and converge to `failed` or a Gateway-directed action.

## Examples

### Transition examples

| Current desired | Target desired | Result   | Notes                         |
| --------------- | -------------- | -------- | ----------------------------- |
| `running`       | `paused`       | allowed  | `pausing -> paused`           |
| `paused`        | `running`      | allowed  | resume to `pending/running`   |
| `running`       | `stopped`      | allowed  | converging stop path required |
| `stopped`       | `terminated`   | allowed  | final teardown                |
| `terminated`    | `running`      | rejected | v0 requires new DevBox        |

### Phase derivation example

```json theme={null}
{
  "desired_state": "running",
  "observed_phase": "recovering",
  "reason": "ssh_remote_attach_failed"
}
```

## Error & Recovery

* Illegal transition requests MUST be rejected and audited.
* Loss of Probe or critical channel readiness MAY push the runtime into `recovering`.
* Recovery beyond budget MUST escalate to Gateway rather than looping indefinitely.

## Security & Audit

* Every transition MUST be traceable through correlation and lifecycle events.
* Desired-state authority remains centralized in Gateway.
* Lifecycle convergence MUST respect approval, lease, and metadata-only audit boundaries.

## Status

Current status: `draft`

Source discussions:

* `docs/maintainers/conversation-records/agent-platform/2026-03-23-devbox-lifecycle-transition-matrix-v0-draft.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-23-sealos-devbox-lifecycle-reference.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md`

## Changelog

* 2026-03-24: Initial formal lifecycle specification created from frozen discussion baseline.

## 相关页面

* [Probe Architecture v0](/agent-platform/architecture/probe-architecture/index)
* [Scheduler v0](/agent-platform/operations/scheduler-v0/index)
* [Self-heal Policy v0](/agent-platform/operations/self-heal-v0/index)