# Workers and identity

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

A managed worker is a Pi session whose physical lifecycle is owned by Herdr and
whose assignment lifecycle is coordinated through the extension mailbox.

## The identities are intentionally different

### Agent definition

The **agent definition** selects the worker's model, reasoning policy, tools,
skills, extensions, prompt body, context inheritance, and allowed direct
children.

Example: `reviewer`.

Definitions are configuration, not live worker identity.

### Logical worker label

The **label** is the public identity for a live worker.

Examples:

```text
reviewer
reviewer-2
my-review
```

Use the exact label from `subagent list` for:

- assigning a new task to a `ready` reusable worker;
- steering;
- replying to `ask_owner`;
- closing.

Labels must begin with a lowercase letter, contain only lowercase letters,
digits, `_`, or `-`, and be at most 32 characters.

### Pi session identity

Every managed worker has an exact Pi session. The list may expose the session
ID and path for correlation.

A session path or full UUID can be used with `assign` to restore historical
work, but it is not a live-control identity. When the session is already
represented by a live worker, control continues through that worker's label.

### Herdr identities

Workspace, tab, pane, generated Herdr-agent alias, run ID, and process evidence
exist to prove physical ownership and safe cleanup.

They are not public alternatives to the label.

## Ownership

Each worker has one exact direct owner Pi session.

A root supervisor owns its direct workers.

A managed parent may own direct child workers when its effective definition has
allowed `subagents`.

Public list visibility follows this ownership boundary. Root recovery may expose
a proven orphan descendant only when durable ownership and exact absence of its
former parent are established.

## Authority boundaries

Different systems answer different questions:

| Authority     | Owns                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------- |
| Herdr         | Physical process/pane lifecycle, placement, live agent observations                      |
| Mailbox       | Assignment acknowledgement, active/completed request identity, pending ask, final result |
| Pi            | Session history, turns, messages, model interaction                                      |
| Logical label | Public live control target                                                               |

The mailbox `ResultRecord` is the persisted completion record and carries the
identity needed to match its worker state. The owner-session delivery entry is
a separate, wider record: it also carries delivery metadata such as `cwd` and
the Pi session file. Those records are checked against their respective
identity requirements; `ResultRecord` is not intended to mirror the complete
delivery-entry shape.

If a result cannot be persisted after bounded retries, the worker state carries
a correlated `result_error` recovery condition instead of becoming assignable.

A safe control operation requires these sources to agree. Missing or conflicting
evidence fails closed rather than guessing.

## Reusable versus one-shot workers

A one-shot worker is cleaned up after its result is delivered.

A worker created with `reusable: true` remains alive and becomes `ready` only
after the current assignment and result delivery have fully converged.

The lifetime policy belongs to the live worker generation and cannot be changed
by a later task.

## See also

- [Lifecycle](lifecycle.md)
- [Delegation](delegation.md)
- [Worker states](../reference/worker-states.md)
- [`subagent` API](../reference/subagent.md)