# Lifecycle

[Documentation index](../README.md)

The public lifecycle is assignment-centric. It deliberately does not mirror raw
Herdr process states one-for-one.

## Assignment flow

A normal assignment moves conceptually through:

```text
accepted
  ↓
working
  ↓
worker completes
  ↓
settling
  ↓
result delivered
  ├─ reusable → ready
  └─ one-shot → cleanup → gone
```

The authoritative final result is correlated to the accepted assignment request
ID.

## Clarification flow

A worker that requires an owner decision stays on the same assignment:

```text
working
  ↓ ask_owner
blocked
  ↓ owner reply
working
  ↓ completion
settling
  ↓ result delivery
ready or cleanup
```

`reply` is not a new assignment and does not create another final result.

## Public state is a safe-control projection

The public states are:

- `ready`
- `working`
- `blocked`
- `settling`
- `unknown`

See [Worker states](../reference/worker-states.md) for their exact control
meaning.

Raw Herdr lifecycle alone is insufficient. Mailbox handoff, pending result
delivery, pending owner questions, and cleanup may make an otherwise idle
process unsafe to reuse.

## Asynchronous completion

`assign` returns after the task has been durably accepted. It does not wait for
the model to finish.

The owner should not poll. When nothing independent remains, end the turn
normally. Result or attention delivery resumes the owner.

## Exactly-once assignment result

Each accepted task request maps to one final assignment result.

Result publication and cleanup are separate convergence steps. A worker may
therefore appear `settling` after its model has finished.

## Steering is different

`steer` changes the current active assignment. It does not create an independent
result.

Steering is at-least-once at the worker boundary: a worker can apply a steer
before its acknowledgement write becomes durable. If that acknowledgement
write fails, retrying the same request may apply the steer again.

Use `steer` only when `subagent list` reports `steerable: true`.

## Parent completion

Direct child work is a completion gate for a managed parent.

A parent cannot publish its own final result while:

- a direct child has ordinary active work; or
- a completed direct-child result has not yet been delivered to the parent.

This completion gate does not create a separate public parent state. The
parent's own state projection remains authoritative.

## Restart and recovery

Durable mailbox state allows exact managed workers to be reconstructed after a
controller restart. Live metadata can be rebuilt only when exact Herdr and Pi
identity still match.

Unknown evidence remains `unknown`; recovery never rebinds stale metadata to a
different worker generation.

## See also

- [Workers and identity](workers.md)
- [Worker states](../reference/worker-states.md)
- [Recovery](../guides/recovery.md)