docs(protocol): define the v2 session lifecycle (#2579)

* docs(protocol): define the v2 session lifecycle

* docs(protocol): leave session retention to the Agent

Author: benbrandt

docs/protocol/v2/draft/error.mdx

@@ -49,7 +49,7 @@ Malformed parameters and unsupported values get `-32602`. For example, an invali
 
 ### Unknown Sessions
 
-If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **MUST** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created or resumed on the connection, until it is closed.
+If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **MUST** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created or resumed on the connection, until it is closed or the connection ends. See [Session Lifecycle](/protocol/v2/draft/session-setup#session-lifecycle).
 
 This applies to `session/prompt` and `session/set_config_option`, and to `session/resume` of a session that does not exist or was deleted. Closing or deleting a session that does not exist still succeeds; see [Closing Active Sessions](/protocol/v2/draft/session-setup#closing-active-sessions) and [Deleting Sessions](/protocol/v2/draft/session-delete).
 

docs/protocol/v2/draft/session-setup.mdx

@@ -42,6 +42,17 @@ sequenceDiagram
 
 <br />
 
+## Session Lifecycle
+
+A session exists from `session/new` until the Agent discards it. Agents choose how long to keep sessions: for example, they may not store a session that was never prompted, may expire old sessions, or may remove one through [`session/delete`](/protocol/v2/draft/session-delete). `session/list` and `session/resume` only see sessions the Agent still has, and resuming one it no longer has fails with `-32002`.
+
+On a connection, a session is **active** from a successful `session/new` or `session/resume` until `session/close` or the end of the connection. Agents **SHOULD NOT** discard a session while it is active.
+
+- Session-scoped requests such as `session/prompt` and `session/set_config_option` require an active session. Otherwise the Agent responds with `-32002`; see [Unknown Sessions](/protocol/v2/draft/error#unknown-sessions). Agents ignore `session/cancel` for a session that isn't active.
+- Closing a session ends it on the connection but doesn't discard it. Whether a closed session stays listed and resumable depends on how long the Agent keeps it.
+- Resuming a session that is already active on the connection synchronizes it again, like any resume. Ongoing work continues, and the request's MCP servers and workspace roots replace the previous ones.
+- When the connection ends, its sessions stop being active. The Agent **MAY** continue or cancel their foreground work. A later `session/resume` reports the outcome in its [current-state snapshot](#current-state-synchronization).
+
 ## Creating a Session
 
 Clients create a new session by calling the `session/new` method with:

docs/protocol/v2/error.mdx

@@ -49,7 +49,7 @@ Malformed parameters and unsupported values get `-32602`. For example, an invali
 
 ### Unknown Sessions
 
-If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **MUST** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created or resumed on the connection, until it is closed.
+If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **MUST** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created or resumed on the connection, until it is closed or the connection ends. See [Session Lifecycle](/protocol/v2/session-setup#session-lifecycle).
 
 This applies to `session/prompt` and `session/set_config_option`, and to `session/resume` of a session that does not exist or was deleted. Closing or deleting a session that does not exist still succeeds; see [Closing Active Sessions](/protocol/v2/session-setup#closing-active-sessions) and [Deleting Sessions](/protocol/v2/session-delete).
 

docs/protocol/v2/session-setup.mdx

@@ -42,6 +42,17 @@ sequenceDiagram
 
 <br />
 
+## Session Lifecycle
+
+A session exists from `session/new` until the Agent discards it. Agents choose how long to keep sessions: for example, they may not store a session that was never prompted, may expire old sessions, or may remove one through [`session/delete`](/protocol/v2/session-delete). `session/list` and `session/resume` only see sessions the Agent still has, and resuming one it no longer has fails with `-32002`.
+
+On a connection, a session is **active** from a successful `session/new` or `session/resume` until `session/close` or the end of the connection. Agents **SHOULD NOT** discard a session while it is active.
+
+- Session-scoped requests such as `session/prompt` and `session/set_config_option` require an active session. Otherwise the Agent responds with `-32002`; see [Unknown Sessions](/protocol/v2/error#unknown-sessions). Agents ignore `session/cancel` for a session that isn't active.
+- Closing a session ends it on the connection but doesn't discard it. Whether a closed session stays listed and resumable depends on how long the Agent keeps it.
+- Resuming a session that is already active on the connection synchronizes it again, like any resume. Ongoing work continues, and the request's MCP servers and workspace roots replace the previous ones.
+- When the connection ends, its sessions stop being active. The Agent **MAY** continue or cancel their foreground work. A later `session/resume` reports the outcome in its [current-state snapshot](#current-state-synchronization).
+
 ## Creating a Session
 
 Clients create a new session by calling the `session/new` method with: