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

# Session lifecycle

> Discovery, the normative session state machine, session identity, and recovery scope.

## Discovery

The world's endpoint is deployment configuration ([transport](/spec/transport/overview)). Capability discovery is `initialize`: the agent states the protocol versions it supports and what it can consume, and the world answers with its manifest — embodiments, channels, action types, capabilities, and safety policy — under the selected version (AWP-VER-002). `world.manifest` re-fetches the same document at any time. Everything the agent may later request is visible in that one response.

## State machine

```mermaid theme={null}
stateDiagram-v2
    [*] --> Connecting
    Connecting --> Negotiating: initialize ok
    Negotiating --> Ready: session.open accepted
    Ready --> Active: first obs/action
    Active --> Suspended: connection lost
    Suspended --> Active: session.resume
    Suspended --> Closed: reconnect window expired
    Active --> Closed: session.close / world shutdown
    Ready --> Closed: session.close
```

| From         | Event                                                                 | To                                                                                                                                                                                         | Requirement     |
| ------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| Connecting   | `initialize` succeeds                                                 | Negotiating                                                                                                                                                                                | `[AWP-SES-001]` |
| Negotiating  | `session.open` accepted                                               | Ready                                                                                                                                                                                      | `[AWP-SES-002]` |
| Ready/Active | control connection lost (AWP-SAF-002)                                 | Suspended; the watchdog (AWP-SAF-003) keeps running independently                                                                                                                          | `[AWP-SES-003]` |
| Suspended    | `session.resume` with valid token and `last_status_seq` within window | Active; statuses replayed (AWP-CTL-008); embodiment stays in safe state until a new action executes (AWP-SAF-008)                                                                          | `[AWP-SES-004]` |
| Suspended    | window expires                                                        | Closed; world MUST apply safe state if not already entered, then release embodiments (AWP-EMB-002)                                                                                         | `[AWP-SES-005]` |
| any          | `session.close`                                                       | Closed; pre-execution actions → `cancelled` (`session_closed`), `executing` actions → `cancelling` → `cancelled` (`session_closed`) after safe abort; embodiment released after safe state | `[AWP-SES-006]` |

Worlds MUST emit a `session.state` notification — `{ state, status_seq, ts_mono_ns, reason? }`, [schema](/api-reference/schemas/session-state) — on every transition from `Ready` onward; it shares the `status_seq` sequence with statuses and events (AWP-CTL-008), so the `suspended` transition reaches the agent on replay after `session.resume`. `[AWP-SES-007]`

## Session identity

`session.ready` carries `session_id`, a world-assigned identifier stable for the life of the session and unique within the world process. It names the session in approval requests, `world_resetting` events, and audit records, and MAY be shown to other sessions; it is not a credential and grants nothing. The `session_token` is the credential and is never used as an identifier. `[AWP-SES-009]`

## Recovery scope

Recovery in v0.1 covers loss of the control connection while the world process is alive. If the world has restarted or otherwise no longer holds the session, `session.resume` MUST fail with `AWP_SESSION_UNKNOWN`; the agent MUST treat the session as `Closed`, re-run `initialize` and `session.open`, and MUST NOT assume any prior action or grant survives. Crash-durable sessions are out of scope for v0.1 and MUST NOT be claimed. `[AWP-SES-008]`