feat(grid-agent): supervise grid sessions (#121)

docs/grid-agent-architecture.md

@@ -10,18 +10,21 @@ platform-specific core path.
 
 ## Ownership and bounds
 
-`AgentService::start` is the sole task-creation point. It validates the complete
-configuration before allocating channels, calling a backend, or permitting
-network access. `ServiceHandle` then exclusively owns cancellation, both join
-handles, the control sender, and observable receiver.
+`AgentService::start` owns offline task creation, while
+`SessionSupervisor::start` owns the live lifecycle task. Configuration is
+validated before either allocates channels, calls a backend, or permits network
+access. Their handles exclusively own cancellation, join handles, controls, and
+observable receivers.
 
 | Resource | Owner | Hard/configured bound | Backpressure/termination |
 | --- | --- | --- | --- |
 | Grid-event queue | coordinator receives; backend sends | 8,192 / `grid_event_queue` | async send or cancellation |
 | Control queue | coordinator receives; handle sends | 256 / `control_queue` | async send; closed after stop |
 | Observable queue | handle receives; coordinator/backend send | 8,192 / `observable_queue` | async send or cancellation |
-| Backend task | `ServiceHandle.tasks[0]` | exactly one | shared cancellation token, joined first |
+| Backend task | `ServiceHandle.tasks[0]` | exactly one in offline mode | shared cancellation token, joined first |
 | Coordinator task | `ServiceHandle.tasks[1]` | exactly one | shared cancellation token, joined second |
+| Live session supervisor | `SessionSupervisorHandle` | one owner; one active generation/session | generation cancellation, exact-once logout, bounded join |
+| Offline session work | live supervisor | 1,024 hard / `reconnect.offline_work_capacity` | read-only queue; mutations rejected while not ready |
 | Body / message | typed boundary owners | 8 MiB / 64 KiB hard ceilings, with lower configured limits | rejected before enqueue |
 | Conversation / tool calls | request owner | 256 messages / 64 calls, with lower configured limits | rejected before request |
 | LLM request slots | shared `LlmClient` semaphore | 256 hard / configured concurrent requests | async acquire or cancellation |
@@ -36,7 +39,7 @@ type. Dynamic configuration can lower these absolute ceilings but cannot raise
 them. Backend error text is not forwarded; observations publish a fixed bounded
 diagnostic.
 
-## State machine and shutdown
+## State machines and shutdown
 
 The explicit service states are `starting -> running <-> paused -> stopping ->
 stopped`, with `failed` reserved for task failure. The offline backend publishes
@@ -54,6 +57,13 @@ feature-enabled live adapter drops its
 `LibremetaverseClientOwner` last, invoking the existing client ownership
 shutdown.
 
+Live modes use `stopped`, `connecting`, `degraded` (transport connected but not
+fully ready), `online`, `backoff`, `authentication-blocked`, `paused`, and
+`shutting-down`. Every attempt rotates a generation cancellation token.
+Disconnect, pause, logout, force reconnect, or shutdown invalidates it before
+cleanup, fencing old events and late LLM/tool results. See
+[`grid-agent-session.md`](grid-agent-session.md).
+
 ## Trust boundaries
 
 - JSON configuration and environment text are untrusted. Unknown fields,
@@ -83,7 +93,7 @@ shutdown.
 metacrate-grid-agent binary (portable Ctrl-C + config path)
                     |
                     v
-AgentService -> bounded Tokio channels/tasks -> injected GridBackend
+offline AgentService -> bounded Tokio channels/tasks -> injected GridBackend
      |                                           |
      v                                           v
 typed config/events/policy boundaries    live-grid feature boundary
@@ -104,3 +114,5 @@ The precise LLM compatibility and cancellation contract is documented in
 [`grid-agent-llm.md`](grid-agent-llm.md).
 The origin/capability matrix and opaque mutation boundary are documented in
 [`grid-agent-policy.md`](grid-agent-policy.md).
+The live lifecycle and generation contract is documented in
+[`grid-agent-session.md`](grid-agent-session.md).