# Lifecycle

Part of [Build a custom machine](https://www.ownbox.io/sdk/guide).

A machine moves through these stages. Each says who acts, what the Ownbox does, and the build's status after it.

| Stage | Who | What happens | Status after |
|---|---|---|---|
| 1. Write | You | Write and run it on your computer (`ownbox run`). | — |
| 2. Send | Your AI | `core.propose_dev_build` puts the files on the owner's Approvals. Nothing runs yet. | — |
| 3. Start | The owner | Says yes on Approvals. The build starts at the check. | `checking` |
| 4. Check | The Ownbox | Checks the files ([Testing](https://www.ownbox.io/sdk/guide/testing)). A refusal waits for new files. | `dry_running` or `waiting_files` |
| 5. Data run | The Ownbox | Runs it on the owner's real data, reaching nothing. | `waiting_tap`, or `ready` with no hosts |
| 6. Tap | The owner | Taps the hosts it may reach in the test, and how many fetches. | `dry_running` |
| 7. Fetch run | The Ownbox | Runs it against the tapped hosts and the sample business. | `ready` |
| 8. Approve | The owner | Reads the review card and taps **Approve**. | `installing`, or `waiting_ownbox` on a partner's Ownbox |
| 9. Ownbox's yes | Ownbox | On a partner's Ownbox only: reviews that exact code, and says yes or no with the reason. | `installing` or `refused` |
| 10. Install | The Ownbox | Seals the code, checks it again, installs its packages, and puts it in place in one step. | `installed` |
| 11. Run | The Ownbox | Starts it when it has something to do, and stops it after 5 idle minutes. | — |
| 12. Roll back | The owner | Returns to the version before. Its data is never rolled back. | — |
| 13. Remove | The owner | Stops it and takes its code away. Its data is kept. | — |

**One build at a time.** While a build is active, a new one is refused as busy. A build waiting for Ownbox, or
installing, does not hold the next one up.

**A build from a description.** On the owner's Developers page, the Ownbox's own AI can write the machine from a
description of at most 2,000 characters. It drafts every file, reads what the check refused or the dry run did, and
drafts again: at most 12 turns and 4 dry runs. Three failed checks in a row end the build; **More** gives a failed
build 12 turns and 4 dry runs again. A build from your files skips the drafting and starts at the check.

**When the check refuses your files,** the build waits for new files (`waiting_files`). Your AI sends the whole fixed
set again with `core.propose_dev_build`: the owner is asked, and on their yes the files go to that build as its next
turn, its check run again. A build that moved on before the yes (cancelled, or out of turns) takes them as a new build.
A build from the owner's own description is never sent a developer's files.

**Approve holds for the card it was given.** The version, the files' sha256 and the permission lines must equal the
card's, or Approve is refused as changed. Nothing installs from a card that is not `ready` with clean dry runs.

**Installing.** The same code installed twice does nothing. The same version with different code is refused: change
`version`. The Ownbox keeps two versions, the one installed and the one before it.

**Running.** A machine is started when it has a job due, work waiting (a page, a tool, an approval) or a new version,
and stopped after 5 idle minutes. How many run at once is set by the Ownbox's plan. After a crash it waits 30 seconds,
doubling up to an hour.

**Rolling back.** The owner's page offers it after 4 failures in a row. It swaps in the version before, with the
permissions it had, and needs no new yes from Ownbox.

**Removing.** The owner confirms by typing the machine's name. The unit stops, its code goes, and its data is kept
on the Ownbox, set aside with nothing purged on a timer. Its pages, tools, jobs and permissions go with it.

**Updating.** Send the new version the way you sent the first, from your files, with the same slug and a higher
`version`. The build is that machine's update: its data run uses a copy of the live machine's data, its review card
records the version it replaces, and Approve swaps it in, keeping the version before for a rollback. The same version
is refused: raise it. Updates work on an Ownbox that runs off root; on one still run as root, the check refuses the
slug as a name in use. A machine the Ownbox's own AI writes from a description never takes an installed machine's
name.

| Status | Means |
|---|---|
| `drafting` | The Ownbox's AI is writing the files (a build from a description). |
| `checking` | The Ownbox is checking the files. |
| `waiting_files` | The check refused the files; the build waits for new ones. |
| `dry_running` | A dry run is going. |
| `waiting_tap` | The owner taps the hosts for the fetch run. |
| `paused` | The Ownbox's AI allowance for the month ran out mid-build. |
| `ready` | The review card waits for the owner. |
| `waiting_ownbox` | On a partner's Ownbox: the owner approved; Ownbox reviews it. |
| `installing` | It is being put in place. |
| `installed` | It runs on the Ownbox. |
| `failed` | It used its turns or dry runs, or the install failed. The reason is on the build. |
| `cancelled` | The owner cancelled it. |
| `refused` | Ownbox said no, with the reason. |