# Worker states

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

The public state is a safe-control projection built from live lifecycle plus
durable assignment/convergence evidence.

It is not a raw Herdr lifecycle string.

| State      | Meaning                                                                                       | New assignment | Steering                                               |
| ---------- | --------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------ |
| `ready`    | Reusable worker is converged and can accept work.                                             | yes            | no                                                     |
| `working`  | Assignment is active.                                                                         | no             | when `steerable: true`                                 |
| `blocked`  | Active assignment waits for owner attention or another condition.                             | no             | no                                                     |
| `settling` | Assignment handoff, completion/result delivery, launch, child gate, or cleanup is converging. | no             | only when list independently reports `steerable: true` |
| `unknown`  | Exact safe control state cannot be proved.                                                    | no             | no                                                     |

## `steerable` is independent

Do not infer steering eligibility from the state name alone.

Always use:

```text
steerable: true
```

A managed parent can be `settling` while direct child work is pending and still
accept steering when all steering predicates are satisfied.

## `blocked` and owner questions

A worker waiting on a valid `ask_owner` reply projects as `blocked` after the
ask turn settles.

Answer through the exact direct owner using `subagent reply`.

## `settling`

Examples:

- task request has not fully converged;
- model completed but final result delivery is still pending;
- parent is gated by direct child work/result delivery;
- one-shot worker cleanup is pending;
- result persistence failed after bounded retries and `result_error` requires recovery;
- startup or integration handoff is incomplete.

Do not assign during `settling`.

## `unknown`

Unknown is intentional fail-closed behavior.

If a current mailbox directory has unreadable, oversized, malformed, or
validation-failing state, `subagent list` reports a bounded `diagnostic` with
`state: "unknown"`. The record has no control identity; do not use it for
assignment, steering, replies, or close operations. Directories that cannot be
current mailbox paths are omitted. These mailbox diagnostics are included only
in a root supervisor's `subagent list`; parent and leaf lists omit diagnostics
outside their ownership scope.

Do not substitute:

- pane idleness;
- elapsed time;
- model metadata;
- missing activity;
- a guessed session;
- an old worker label.

Refresh exact evidence or resolve the underlying recovery condition.

## Inactivity fields do not change state

A qualifying `working` worker may also report:

```text
stale: true
inactive_ms: ...
last_activity_at: ...
```

The control state remains `working`.

This advisory is not proof of a hang.

## See also

- [Lifecycle](../concepts/lifecycle.md)
- [Recovery](../guides/recovery.md)
- [`subagent` API](subagent.md)