feat(events): give a session an event envelope carrying run lifecycle

CLAUDE.md

@@ -134,8 +134,9 @@ aura/
 
 ### Shared Event Types (`aura-events`)
 - Lightweight crate defining `AuraStreamEvent` and `OrchestrationStreamEvent` enums
+- `run::SessionEvent` is a session's own envelope: its `SessionId`, the `RunId` when the event belongs to a run, a `SequenceNumber` dense per session, a `Timestamp`, and either an `agent::AgentEvent` or a `LifecycleEvent` (started, observer attached/detached, claims exhausted, liveness decided, parked, finished, cancelled, failed). `RunId` is a UUID (v7 when minted); there is one per run. No producer emits it yet
 - Both `Serialize + Deserialize` — used by the web server (producer) and CLI (consumer)
-- No agent, MCP, or provider dependencies — only `serde` and `serde_json`
+- No agent, MCP, or provider dependencies — only `serde`, `serde_json`, and `uuid`
 - `ProgressToken` type uses a local wire-compatible definition by default; enables `rmcp-types` feature for direct rmcp interop (used by the `aura` crate)
 
 ## Environment Setup

crates/aura-events/Cargo.toml

@@ -10,6 +10,7 @@ repository.workspace = true
 [dependencies]
 serde = { workspace = true }
 serde_json = { workspace = true }
+uuid = { workspace = true }
 
 # Optional: re-export rmcp's ProgressToken for interop with the aura crate.
 # When rmcp is not available, we define compatible local types.

crates/aura-events/src/lib.rs

@@ -10,13 +10,16 @@
 //!
 //! - [`AuraStreamEvent`] — Base aura events (tool lifecycle, usage, reasoning, progress)
 //! - [`OrchestrationStreamEvent`] — Multi-agent orchestration events
+//! - [`agent::AgentEvent`] — What a running agent emits, before any wire projection
+//! - [`run::SessionEvent`] — One session's ordered stream: its agents' events and its runs' lifecycle
 //!
-//! Both enums derive `Serialize + Deserialize` so they can be used for
+//! All derive `Serialize + Deserialize` so they can be used for
 //! producing SSE (server) and parsing SSE (client) with the same types.
 
 pub mod agent;
 pub mod event_names;
 pub mod orchestration;
+pub mod run;
 
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
@@ -135,6 +138,62 @@ macro_rules! string_newtype {
     };
 }
 
+// Path-based so submodules can invoke it regardless of declaration order.
+pub(crate) use string_newtype;
+
+string_newtype! {
+    /// Identifier for a session: an agent's identity over time, and the key
+    /// its [`SessionEvent`](run::SessionEvent) stream is ordered under.
+    SessionId
+}
+
+/// Identifier for one run: a unit of work within a session, from a prompt to
+/// a terminal state.
+///
+/// This is the epic's "unique agent id for that run". It is not
+/// [`AgentContext::agent_id`], which is [`CONVERSATION_AGENT_ID`] or a worker
+/// name and attributes an event *within* a run.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct RunId(uuid::Uuid);
+
+impl RunId {
+    /// A fresh id. Version 7, so ids order by when they were minted.
+    pub fn mint() -> Self {
+        Self(uuid::Uuid::now_v7())
+    }
+
+    pub fn as_uuid(&self) -> &uuid::Uuid {
+        &self.0
+    }
+}
+
+impl From<uuid::Uuid> for RunId {
+    fn from(uuid: uuid::Uuid) -> Self {
+        Self(uuid)
+    }
+}
+
+impl From<RunId> for uuid::Uuid {
+    fn from(id: RunId) -> Self {
+        id.0
+    }
+}
+
+impl std::str::FromStr for RunId {
+    type Err = uuid::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        uuid::Uuid::from_str(s).map(Self)
+    }
+}
+
+impl std::fmt::Display for RunId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
 string_newtype! {
     /// The id a model assigns to one tool call.
     ToolCallId