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

# Status & Lifecycle Reference

> Reference for the lifecycle states used by Starfire AI accounts, runs, FORGE builds, incidents, indexing, and automation.

# Status & lifecycle reference

Starfire uses explicit lifecycle states so users, developers, and operators can distinguish work that is waiting, active, complete, failed, or intentionally stopped.

## Generic run states

| State       | Meaning                                                             | Terminal? |
| ----------- | ------------------------------------------------------------------- | --------: |
| `QUEUED`    | Accepted and waiting for execution capacity or a worker.            |        No |
| `RUNNING`   | Execution is actively in progress.                                  |        No |
| `WAITING`   | Execution is paused for another dependency, condition, or approval. |        No |
| `COMPLETED` | Work finished successfully.                                         |       Yes |
| `FAILED`    | Work stopped because an error could not be recovered.               |       Yes |
| `CANCELLED` | Work was intentionally stopped.                                     |       Yes |

Exact backend enum names can differ by subsystem. The UI should present the same lifecycle meaning even where implementation-specific names vary.

## FORGE build stages

| Stage        | What Starfire is doing                                                                 |
| ------------ | -------------------------------------------------------------------------------------- |
| `QUEUED`     | Waiting for build execution.                                                           |
| `PLANNING`   | Converting requirements into a build plan.                                             |
| `PREPARING`  | Creating or restoring the code workspace.                                              |
| `GENERATING` | Creating or modifying project files.                                                   |
| `VALIDATING` | Running available project checks.                                                      |
| `REPAIRING`  | Applying a targeted correction after validation failure.                               |
| `PACKAGING`  | Creating one or more durable artifacts.                                                |
| `COMPLETED`  | Build and packaging completed successfully.                                            |
| `FAILED`     | Build could not complete within available limits or because of an unrecoverable error. |
| `CANCELLED`  | The build was intentionally stopped.                                                   |

## Knowledge source states

| State        | Meaning                                             |
| ------------ | --------------------------------------------------- |
| `UPLOADED`   | Source exists but has not completed processing.     |
| `PROCESSING` | Content extraction or normalization is in progress. |
| `INDEXING`   | Chunks/embeddings/index entries are being created.  |
| `READY`      | Source is eligible for retrieval.                   |
| `STALE`      | The source or its index is known to need refresh.   |
| `FAILED`     | Processing or indexing did not complete.            |

## Incident states

| State           | Meaning                                                |
| --------------- | ------------------------------------------------------ |
| `INVESTIGATING` | Impact is being confirmed and scoped.                  |
| `IDENTIFIED`    | A cause or failing subsystem has been identified.      |
| `MITIGATING`    | Operators are actively reducing impact.                |
| `MONITORING`    | Recovery is in place and being verified.               |
| `RESOLVED`      | Recovery has been verified and the incident is closed. |

## Account states

Starfire administration supports the idea of multiple account conditions rather than only active/banned.

| State           | Operational meaning                                                        |
| --------------- | -------------------------------------------------------------------------- |
| `ACTIVE`        | Normal account operation.                                                  |
| `RESTRICTED`    | Account remains usable but one or more capabilities are limited.           |
| `SUSPENDED`     | Normal access is blocked by administrative policy.                         |
| `BILLING_HOLD`  | Access is limited because of billing state according to configured policy. |
| `SECURITY_HOLD` | Sensitive access is restricted while a security concern is investigated.   |
| `DEACTIVATED`   | Account is no longer active for normal use.                                |

<Warning>
  Do not infer a user's intent or wrongdoing from a state label. Account states describe platform access, not a judgment about the person.
</Warning>