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

# Session Lifecycle

> The core agent primitive — a bounded execution context under delegated authority.

## What a Session Is

An `AgentSession` is the live governance boundary. It binds an Agent (what kind of worker) to a Task (what work) through a Harness (how it runs).

The session is the unit of accountability. "Who did this?" is always answerable with a session UID.

## Lifecycle Phases

```
Pending → Initializing → Active → Completed / Failed / Declined / Revoked / Error
```

| Phase            | Meaning                                             |
| ---------------- | --------------------------------------------------- |
| **Pending**      | Durable session exists; live process not started    |
| **Initializing** | Process spawning, initial artifacts loading         |
| **Active**       | Live work being performed                           |
| **Completed**    | Finished cleanly, outputs produced                  |
| **Failed**       | Attempted the work, didn't achieve the result       |
| **Declined**     | Agent legitimately refused (with structured reason) |
| **Revoked**      | Externally stopped (governance, parent, timeout)    |
| **Error**        | Infrastructure failure prevented execution          |

## Declined is Not Failure

An agent that declines is performing its governance function. Decline reasons flow back to the orchestrator as structured data:

* `insufficient_context` — workflow may route back to research
* `authority_insufficient` — escalation to parent
* `ethical_objection` — escalation to human
* `needs_decomposition` — orchestrator re-plans
* `scope_mismatch` — orchestrator reassigns

## The Reflect Step

After completing (or failing, or declining), the agent assesses:

* What went right and wrong at the task level
* Whether the decomposition was correct
* Whether the orchestration could improve
* What the system should learn from this session

Reflect is mandatory. The session cannot reach a terminal state without producing a reflect artifact.