Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

92.6 KB
Raw Blame
//! Persistence and active lifecycle management for agent sessions.
//!
//! Inbound adapters depend on [`AgentSessionService`] rather than repository
//! ports. Protocol decisions live in [`super::session`]'s pure machine, and
//! each connection's effects are executed by its actor shell.
//!
//! A session's log is the source of truth. The writer projects its current
//! turn state onto the session row for lists; conversation readers fold the
//! frames themselves.
//!
//! A live session's log is written by its actor, which is handed a
//! [`LiveSessionLogWriter`] rather than the bare repository. Anyone writing a
//! run of frames in order has somewhere to keep state, so that writer holds an
//! `agent_fold` machine and pushes each frame into it - which is what keeps a
//! reconnecting session's [`TurnId`](agent_fold::domain::model::TurnId)s
//! counting from where the session actually is, rather than from zero. The
//! streamed chunks that make up most of a log cost one push and no I/O. That
//! is a session's actor, and equally `seed_jsonl` replaying a recording.
//!
//! [`LiveSessionLogWriter`] is also where a live session's frames are
//! streamed from, for the same reason: it is the one place every frame of a
//! connected session passes through, so anything a viewer should see as it
//! happens has to be published from there. The push cannot fail the durable
//! append - see [`AgentSessionRealtime`].

mod first_output;
mod presentation;
#[cfg(test)]
mod test;

use first_output::FirstOutput;

use std::sync::Arc;

use agent_client_protocol::RawJsonRpcMessage;
use agent_client_protocol::schema::v1::{
    McpServer, RequestId, Response, SessionId, SetSessionConfigOptionResponse,
};
use agent_fold::domain::lifecycle::LifecycleFold;
use agent_fold::domain::model::{
    Author, FoldedMessage, MessagePart, StopReason as TurnStopReason, TurnSignal, TurnState,
};
use agent_fold::domain::model_selection::model_selection;
use agent_fold::domain::ports::FoldedMessageRepo;
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId, AgentSetModelAction};
use agent_runtime_protocol::domain::schema::v0::{
    AcpMessage, SystemEvent, ToRuntimeMessage, ToServerMessage,
};
use dashmap::DashMap;
use dashmap::mapref::entry::Entry;
use entity_access::domain::models::{EntityAccessReceipt, EntityType, OwnerAccessLevel};
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
use tokio::sync::{Mutex, mpsc, oneshot, watch};
use tokio_util::{sync::CancellationToken, task::TaskTracker};
use tracing::Instrument as _;
use tracing::instrument::WithSubscriber as _;

use bots::domain::models::BotId;

use super::coding_preferences::CodingPreferences;
use super::connection::RuntimeAttachment;
use super::error::{AgentSessionError, Result};
use super::lifecycle::session_identity;
use super::model::{
    AgentSession, AgentSessionId, AgentSessionLog, AgentSessionPreview, AgentSessionRenamed,
    AuthorKind, ClaimOutcome, CreateAgentSessionParams, FoldedSessionLog, LogAppended,
    MAX_AGENT_SESSION_NAME_CHARS, MAX_PREVIEW_SESSION_IDS, Message, MessageId, ReplicaId,
    SandboxSize, SessionClaim, SessionLog, SessionManagement, SessionPreviewCandidate,
    StoredAgentSessionLog, StoredQueuedAction, ThreadSession, cursor_run_checkpoint,
};
use super::model::{SessionBot, SessionSource, SessionVisibility, TurnPrompter};
use super::ports::{
    AgentConnector, AgentSessionLifecyclePublisher, AgentSessionLogRepo, AgentSessionLogWriter,
    AgentSessionNameGenerator, AgentSessionQueueChanged, AgentSessionRealtime, AgentSessionRepo,
    Appended, NoInheritedSessionAccess, NoOpAgentSessionNameGenerator, NoOpToolCatalog,
    SessionOwnership, SessionToolCatalog, SessionTurnObserver, SessionViewAccess,
};
use super::retitle::ConversationDigest;
use super::session::actors::{ActorInput, SessionActor, SessionCommand, SessionMessage, Stepped};
use super::session::{CloseReason, Input, PermissionPolicy, StopReason as SessionStopReason};
use crate::domain::events::{AgentSessionLifecycleEvent, SessionRenamedMetadata};

/// Buffered not-yet-accepted commands per session actor.
const COMMAND_BUFFER: usize = 1028;
/// Bound memory usage while draining all sessions during account cleanup.
const USER_CLEANUP_BATCH_SIZE: std::num::NonZeroUsize = std::num::NonZeroUsize::new(100).unwrap();
/// Persistence may delay lifecycle teardown, but never indefinitely.
const SESSION_PERSIST_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(60);
/// How long a command may sit queued behind the ACP handshake
/// (`Booting`/`Initializing`/`Opening`) before the caller gives up on it.
/// The runtime never completes a queued command on its own until it reaches
/// `Live` - see [`super::session::session::SessionMachine::on_command`] - so
/// without this bound a stalled handshake (e.g. the runtime process never
/// sends `AcpReady`, or never answers `initialize`/`session/new`) hangs the
/// caller forever.
#[cfg(not(test))]
const HANDSHAKE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
#[cfg(test)]
const HANDSHAKE_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(50);

struct ActiveSession {
    commands: Option<mpsc::Sender<SessionMessage>>,
    /// The MCP servers last requested for the live connection: the
    /// attachment's, until [`AgentSessionService::replace_mcp_servers`]. An
    /// agent that cannot resume, or refused, still has its previous list.
    mcp_servers: Vec<McpServer>,
    stopped: watch::Receiver<bool>,
    marker: Arc<()>,
    deleting: bool,
    stopping: bool,
    /// Cancelled by the connector the moment its transport ends, when it
    /// offers one - not every connector does. `deliver_action` races this
    /// alongside its reply wait so a command sent to a session whose
    /// transport is already known to be gone fails immediately instead of
    /// waiting out the full command timeout for nothing.
    transport_closed: Option<CancellationToken>,
}

type ActiveSessions = DashMap<AgentSessionId, ActiveSession>;

struct AttachReservation {
    active: Arc<ActiveSessions>,
    id: AgentSessionId,
    marker: Arc<()>,
    stopped: Option<watch::Sender<bool>>,
    committed: bool,
}

impl AttachReservation {
    fn commit(mut self) -> (Arc<()>, watch::Sender<bool>) {
        self.committed = true;
        (
            self.marker.clone(),
            self.stopped.take().expect("reservation owns stop signal"),
        )
    }
}

impl Drop for AttachReservation {
    fn drop(&mut self) {
        if self.committed {
            return;
        }
        if let Some(stopped) = self.stopped.take() {
            let _ = stopped.send(true);
        }
        self.active.remove_if(&self.id, |_, active| {
            Arc::ptr_eq(&active.marker, &self.marker) && !active.stopping
        });
    }
}

/// Durable and live use cases for agent sessions.
#[cfg_attr(feature = "test-utils", mockall::automock)]
pub trait AgentSessionService: Send + Sync + 'static {
    /// Present a durable tool card as the owner without occupying a model turn.
    fn present_tool(
        &self,
        id: AgentSessionId,
        actor: MacroUserIdStr<'static>,
        presentation: super::model::SessionToolPresentation,
    ) -> impl Future<Output = Result<()>> + Send {
        async move {
            let _ = (actor, presentation);
            Err(AgentSessionError::Disconnected(id))
        }
    }

    /// Whether matching presentation frames are durably stored, not merely forwarded.
    fn tool_presentation_persisted(
        &self,
        id: AgentSessionId,
        actor: MacroUserIdStr<'static>,
        presentation: super::model::SessionToolPresentation,
    ) -> impl Future<Output = Result<bool>> + Send {
        async move {
            let _ = (actor, presentation);
            Err(AgentSessionError::Disconnected(id))
        }
    }

    /// Persist a session before any transport is provisioned or attached.
    fn create_session(
        &self,
        params: CreateAgentSessionParams,
    ) -> impl Future<Output = Result<AgentSession>> + Send;

    /// Rotate the credential provided to an authenticated runtime attachment.
    fn set_egress_token_hash(
        &self,
        id: AgentSessionId,
        hash: &str,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Get a persisted agent session by id.
    fn get_session(&self, id: AgentSessionId) -> impl Future<Output = Result<AgentSession>> + Send;

    /// A persisted agent session by id, or `None` when there is none.
    fn find_session(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<Option<AgentSession>>> + Send;

    /// Append a frame observed on the runtime's behalf by something other
    /// than its session actor - the egress proxy's tool approvals - and push
    /// it to the session's viewers. Any replica may call this; the frame is
    /// ordered by when it is stored.
    fn record_frame(
        &self,
        id: AgentSessionId,
        message: ToServerMessage,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Append a frame nothing projects session state from - no turn,
    /// status, or model - and push it to the session's viewers, without the
    /// whole-log fold [`record_frame`](Self::record_frame) runs first. What a
    /// review writes on every save. Any replica may call this; the frame is
    /// ordered by when it is stored.
    fn record_unprojected_frame(
        &self,
        id: AgentSessionId,
        message: ToServerMessage,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Record who prompted the turn `id` is about to run, before it runs.
    fn set_turn_prompter(
        &self,
        id: AgentSessionId,
        prompter: &TurnPrompter,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Record that `user` prompted the session `id` directly, from the
    /// session itself, so a hidden session lists for them.
    fn add_follower(
        &self,
        id: AgentSessionId,
        user: &MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Read the persisted identity of the current turn during recovery.
    fn turn_prompter(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<Option<TurnPrompter>>> + Send;

    /// What `viewer` may see of each of `ids`, for rendering chips.
    ///
    /// Duplicate ids are collapsed, so the answer has one entry per distinct
    /// id. More than [`MAX_PREVIEW_SESSION_IDS`] distinct ids is
    /// [`AgentSessionError::TooManyPreviewIds`].
    fn preview_sessions(
        &self,
        viewer: &MacroUserIdStr<'static>,
        ids: Vec<AgentSessionId>,
    ) -> impl Future<Output = Result<Vec<AgentSessionPreview>>> + Send;

    /// Rename a session after owner access has been verified.
    fn rename_session(
        &self,
        access: &EntityAccessReceipt<OwnerAccessLevel>,
        name: &str,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Archive or unarchive a session after owner access has been verified.
    fn set_archived(
        &self,
        access: &EntityAccessReceipt<OwnerAccessLevel>,
        archived: bool,
    ) -> impl Future<Output = Result<()>> + Send;

    /// A bounded batch of sessions owned by this user, including inactive sessions.
    /// Used by account cleanup, not access-based discovery.
    fn sessions_for_user_cleanup(
        &self,
        owner: &MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<AgentSession>>> + Send;

    /// Delete an agent session by id.
    fn delete_session(&self, id: AgentSessionId) -> impl Future<Output = Result<()>> + Send;

    /// Release this session's live transport, if it has one.
    ///
    /// The actor observes its command channel closing and winds itself down
    /// through the ordinary close path, so this is enough to end a connection;
    /// it does not touch anything durable. A session with no active transport
    /// is already in the state this asks for, so it succeeds.
    fn close_session(&self, id: AgentSessionId) -> impl Future<Output = Result<()>> + Send;

    /// Persist that a session disconnected before a live actor could report it.
    fn mark_disconnected(&self, id: AgentSessionId) -> impl Future<Output = Result<()>> + Send;

    /// Where the session's live actor runs, from this instance's viewpoint:
    /// unmanaged (claimable here), ours, a live peer's - in which case
    /// commands belong at the peer's address rather than in this process -
    /// or nowhere worth sending work, because this instance is draining.
    fn management(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<SessionManagement>> + Send;

    /// Publish that this instance's replica is shutting down.
    ///
    /// Called the moment the process is told to stop, long before it
    /// actually does: from here on peers route around this replica and it
    /// routes work away from itself, so nothing new is started on a process
    /// that will not live to finish it. Sessions already running here keep
    /// running - they hold their claims until their actors wind down.
    fn begin_draining(&self) -> impl Future<Output = Result<()>> + Send;

    /// Attach a new transport to an existing persisted session.
    ///
    /// The attachment carries the connection's handshake gate as well as the
    /// transport, because whether this session runs `initialize` depends on
    /// whether another session on the same connection already did.
    fn attach_session<Connector>(
        &self,
        id: AgentSessionId,
        attachment: RuntimeAttachment<Connector>,
    ) -> impl Future<Output = Result<()>> + Send
    where
        Connector: AgentConnector;

    /// Deliver an action through the session's active transport, under the
    /// action id it will carry onto the wire.
    fn send_action(
        &self,
        id: AgentSessionId,
        user_id: Option<MacroUserIdStr<'static>>,
        action: AgentAction,
        action_id: AgentActionId,
    ) -> impl Future<Output = Result<()>> + Send;

    /// The MCP servers last requested for the session's live connection on
    /// this instance; `None` when no connection is attached here. An agent
    /// that could not take a requested list keeps its previous one until its
    /// next attach.
    fn attached_mcp_servers(&self, id: AgentSessionId) -> Option<Vec<McpServer>>;

    /// Hand the session's agent `servers` from now on. The live connection
    /// re-resumes its ACP session with them before the next prompt reaches
    /// the agent, if the agent can resume; an agent that cannot keeps the
    /// servers it has until its next attach.
    fn replace_mcp_servers(
        &self,
        id: AgentSessionId,
        servers: Vec<McpServer>,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Answer the agent's permission requests under `policy` from now on, on
    /// the session's live connection on this instance. A session attached
    /// nowhere here needs nothing: its next attach takes a fresh policy.
    fn set_permission_policy(
        &self,
        id: AgentSessionId,
        policy: PermissionPolicy,
    ) -> impl Future<Output = Result<()>> + Send;

    /// The session an incoming channel context routes to, if any.
    fn find_for_thread(
        &self,
        thread_id: Option<Uuid>,
        bot_id: Option<BotId>,
    ) -> impl Future<Output = Result<ThreadSession>> + Send;

    /// The bot a session runs for, as viewers see it.
    fn session_bot(&self, id: BotId) -> impl Future<Output = Result<SessionBot>> + Send;

    /// Every user who has driven the session; see
    /// [`AgentSessionLogRepo::participants`].
    fn session_participants(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<Vec<MacroUserIdStr<'static>>>> + Send;

    /// The user-message id the next prompt appended to this session will fold to.
    fn next_prompt_message_id(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<MessageId>> + Send;

    /// The effective ACP history of one session, oldest first, with the agent
    /// whose messages it derives.
    ///
    /// Served unfolded for the web client, which runs the same fold compiled
    /// to WASM so a streamed session and a reloaded one are rendered by one
    /// implementation. See [`SessionLog`] and [`Self::folded_session_log`].
    fn session_log(&self, id: AgentSessionId) -> impl Future<Output = Result<SessionLog>> + Send;

    /// Recover one action from a consistent durable snapshot, including history
    /// replaced by session/load. No observer callback or live actor is required.
    fn recorded_action(
        &self,
        id: AgentSessionId,
        action: AgentActionId,
    ) -> impl Future<Output = Result<Option<super::action_history::RecordedAction>>> + Send;

    /// The same history as [`Self::session_log`], folded server-side into
    /// renderable messages for readers that do not run the fold themselves,
    /// such as SDK programs and agents reading other sessions.
    fn folded_session_log(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<FoldedSessionLog>> + Send;

    /// Push a session's changed queue - the whole queue, every time - to its
    /// viewers.
    ///
    /// Here because this service is the harness's one door to the realtime
    /// stream and its audience: the queue itself lives above, but who is
    /// watching a session is answered here for log frames already.
    fn publish_queue_changed(
        &self,
        event: AgentSessionQueueChanged,
    ) -> impl Future<Output = Result<()>> + Send;

    /// The session's waiting actions, oldest first. Missing row is empty.
    fn list_queued_actions(
        &self,
        id: AgentSessionId,
    ) -> impl Future<Output = Result<Vec<StoredQueuedAction>>> + Send;

    /// Replace the session's waiting actions. An empty slice deletes the row.
    fn replace_queued_actions(
        &self,
        id: AgentSessionId,
        entries: &[StoredQueuedAction],
    ) -> impl Future<Output = Result<()>> + Send;

    /// Persist the sandbox size this session is running at.
    fn set_sandbox_size(
        &self,
        id: AgentSessionId,
        size: SandboxSize,
    ) -> impl Future<Output = Result<()>> + Send;

    /// The user's default sandbox size for new `@coder` sessions.
    ///
    /// A missing preference is [`SandboxSize::Default`].
    fn user_sandbox_size(
        &self,
        user_id: &MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<SandboxSize>> + Send;

    /// Upsert the user's default sandbox size for the next `@coder` mention.
    fn set_user_sandbox_size(
        &self,
        user_id: &MacroUserIdStr<'static>,
        size: SandboxSize,
    ) -> impl Future<Output = Result<()>> + Send;

    /// The user's coding preferences; every preference is off until set.
    fn user_coding_preferences(
        &self,
        user_id: &MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<CodingPreferences>> + Send;

    /// Upsert the user's coding preferences, replacing every field.
    fn set_user_coding_preferences(
        &self,
        user_id: &MacroUserIdStr<'static>,
        preferences: CodingPreferences,
    ) -> impl Future<Output = Result<()>> + Send;
}

/// Agent session service backed by one durable repository and local actors.
///
/// `R` is the persistence adapter implementing both [`AgentSessionRepo`] and
/// [`AgentSessionLogRepo`], e.g. `outbound::postgres::PgAgentSessionRepo`.
/// `Folds` answers "what messages does this session's log derive" -
/// `agent_fold` folding the log on read - and `Rt` streams each frame to
/// whoever is watching the session's channel right now.
#[derive(Clone)]
pub struct AgentSessionServiceImpl<R, Folds, Rt, Namer = NoOpAgentSessionNameGenerator> {
    repo: R,
    folds: Folds,
    realtime: Rt,
    name_generator: Namer,
    /// Told when a session's turn ends or its actor stops - the harness's
    /// prompt-queue gate. Erased so wiring it is not another type parameter.
    turn_observer: Arc<dyn SessionTurnObserver>,
    /// Lists a session's MCP tools for its telemetry. Erased like the
    /// observer, for the same reason.
    tool_catalog: Arc<dyn SessionToolCatalog>,
    /// Answers whether a viewer may see a session when no access row says
    /// so: a document collaborator's inherited access. Erased like the
    /// observer, for the same reason.
    view_access: Arc<dyn SessionViewAccess>,
    /// Where lifecycle facts go - renames, from here; everything else from
    /// the harness. Erased for the same reason as the observer.
    lifecycle_publisher: Arc<dyn AgentSessionLifecyclePublisher>,
    active: Arc<ActiveSessions>,
    /// This service's identity in the session-management lease. Minted at
    /// construction: a restarted process is a new replica, and its claims
    /// are recovered by heartbeat staleness, never inherited.
    replica: ReplicaId,
    tasks: TaskTracker,
    cancellation: CancellationToken,
    lifecycle: Arc<Mutex<()>>,
}

impl<R, Folds, Rt, Namer> AgentSessionServiceImpl<R, Folds, Rt, Namer> {
    /// Build a service from every port it drives.
    ///
    /// Nothing is defaulted: a caller with no viewers passes
    /// [`NoOpRealtime`](super::ports::NoOpRealtime), one with no queue above
    /// it passes [`NoOpTurnObserver`], one with nothing downstream passes
    /// [`NoopLifecyclePublisher`], and one that is the only service instance
    /// in its process mints its own [`ReplicaId`] - each choice visible at the
    /// call site rather than hidden in a builder's default. The one
    /// exception is the tool catalog: it starts as [`NoOpToolCatalog`] and
    /// [`Self::with_tool_catalog`] swaps in a real one, since only a process
    /// with an in-process MCP client can list anything.
    ///
    /// `replica` is this service's identity in the session-management lease.
    /// A restarted process is a new replica whose claims are recovered by
    /// heartbeat staleness, never inherited. A process with more than one
    /// attach-capable instance hands every instance the same id: commands
    /// forward to an address, and every instance in a process shares one.
    pub fn new(
        repo: R,
        folds: Folds,
        realtime: Rt,
        name_generator: Namer,
        turn_observer: Arc<dyn SessionTurnObserver>,
        lifecycle_publisher: Arc<dyn AgentSessionLifecyclePublisher>,
        replica: ReplicaId,
    ) -> Self {
        Self {
            repo,
            folds,
            realtime,
            name_generator,
            turn_observer,
            lifecycle_publisher,
            tool_catalog: Arc::new(NoOpToolCatalog),
            view_access: Arc::new(NoInheritedSessionAccess),
            active: Arc::new(DashMap::new()),
            replica,
            tasks: TaskTracker::new(),
            cancellation: CancellationToken::new(),
            lifecycle: Arc::new(Mutex::new(())),
        }
    }

    /// Replace the no-op tool catalog with one that lists a session's MCP
    /// tools, so its turns' spans carry the tools the agent could choose from.
    #[must_use]
    pub fn with_tool_catalog(mut self, tool_catalog: Arc<dyn SessionToolCatalog>) -> Self {
        self.tool_catalog = tool_catalog;
        self
    }

    /// Resolve inherited session access when previewing, so a document
    /// collaborator's chips render like their reads succeed. Only a process
    /// with an entity-access service can answer, hence a builder rather than
    /// a constructor argument.
    #[must_use]
    pub fn with_view_access(mut self, view_access: Arc<dyn SessionViewAccess>) -> Self {
        self.view_access = view_access;
        self
    }

    /// This service's identity in the session-management lease, for the
    /// composition root to heartbeat while the process lives.
    #[must_use]
    pub fn replica_id(&self) -> ReplicaId {
        self.replica
    }

    /// Stop active actors and wait for their tasks to release their transports.
    pub async fn shutdown(&self) {
        let lifecycle = self.lifecycle.lock().await;
        self.cancellation.cancel();
        for mut session in self.active.iter_mut() {
            session.commands.take();
            session.stopping = true;
        }
        self.tasks.close();
        drop(lifecycle);
        self.tasks.wait().await;
        self.active.clear();
    }

    async fn reserve_attach(&self, id: AgentSessionId) -> Result<AttachReservation> {
        let _lifecycle = self.lifecycle.lock().await;
        if self.cancellation.is_cancelled() {
            return Err(AgentSessionError::Disconnected(id));
        }
        let (stopped_tx, stopped) = watch::channel(false);
        let marker = Arc::new(());
        match self.active.entry(id) {
            Entry::Occupied(_) => Err(AgentSessionError::AlreadyConnected(id)),
            Entry::Vacant(entry) => {
                entry.insert(ActiveSession {
                    commands: None,
                    mcp_servers: Vec::new(),
                    stopped,
                    marker: marker.clone(),
                    deleting: false,
                    stopping: false,
                    transport_closed: None,
                });
                Ok(AttachReservation {
                    active: self.active.clone(),
                    id,
                    marker,
                    stopped: Some(stopped_tx),
                    committed: false,
                })
            }
        }
    }

    async fn activate_reserved<Connector>(
        &self,
        session: AgentSession,
        mut attachment: RuntimeAttachment<Connector>,
        reservation: AttachReservation,
        claim: SessionClaim,
    ) -> Result<()>
    where
        R: AgentSessionRepo + AgentSessionLogRepo + SessionOwnership + Clone,
        Folds: FoldedMessageRepo + Clone + Send + Sync + 'static,
        Rt: AgentSessionRealtime + Clone + Send + Sync + 'static,
        Namer: AgentSessionNameGenerator + Clone,
        Connector: AgentConnector,
    {
        let _lifecycle = self.lifecycle.lock().await;
        let id = session.id;
        if self.cancellation.is_cancelled() {
            return Err(AgentSessionError::Disconnected(id));
        }
        let (commands, command_rx) = mpsc::channel(COMMAND_BUFFER);
        let Some(mut active) = self.active.get_mut(&id) else {
            return Err(AgentSessionError::Disconnected(id));
        };
        if !Arc::ptr_eq(&active.marker, &reservation.marker) || active.stopping {
            return Err(AgentSessionError::Disconnected(id));
        }
        if let Some(activate) = attachment.activation.take() {
            activate(claim)?;
        }
        active.commands = Some(commands.clone());
        active.mcp_servers = attachment.mcp_servers.clone();
        active.transport_closed = attachment.closed.clone();
        drop(active);
        let (marker, stopped_tx) = reservation.commit();

        // The actor owns this session's log writes, so it gets the live writer
        // rather than the bare repository - see module docs. Its fold starts
        // empty and catches itself up on the stored log on the first frame,
        // which costs an attach nothing until the session actually says
        // something. Fenced under the claim taken above: if another replica
        // supersedes this one, the store rejects the next append and the
        // actor tears down through its ordinary log-failure path.
        let initial_model = attachment
            .initial_model
            .filter(|_| session.acp_session_id.is_none());
        let logs = LiveSessionLogWriter::fenced(self.repo.clone(), self.realtime.clone(), claim)
            .with_initial_model(initial_model.clone());
        let actor = SessionActor::new(
            id,
            session.acp_session_id,
            session.workspace,
            attachment.mcp_servers,
            attachment.permission_policy,
            attachment.connector,
            logs,
            command_rx,
            attachment.handshake,
            Arc::new(RetitleAfterTurns {
                observer: Arc::clone(&self.turn_observer),
                repo: self.repo.clone(),
                folds: self.folds.clone(),
                realtime: self.realtime.clone(),
                lifecycle_publisher: self.lifecycle_publisher.clone(),
                name_generator: self.name_generator.clone(),
                tasks: self.tasks.clone(),
            }),
            Arc::clone(&self.tool_catalog),
        )
        .with_initial_model(initial_model);
        self.tasks.spawn(
            run_session(
                actor,
                Arc::downgrade(&self.active),
                marker,
                stopped_tx,
                self.cancellation.clone(),
                self.repo.clone(),
                claim,
                Arc::clone(&self.turn_observer),
            )
            .with_current_subscriber(),
        );
        Ok(())
    }

    async fn deliver_action(
        &self,
        id: AgentSessionId,
        user_id: Option<MacroUserIdStr<'static>>,
        action: AgentAction,
        action_id: AgentActionId,
    ) -> Result<()> {
        let (commands, transport_closed) = self
            .active
            .get(&id)
            .and_then(|entry| Some((entry.commands.clone()?, entry.transport_closed.clone())))
            .ok_or(AgentSessionError::Disconnected(id))?;

        let (completed, result) = oneshot::channel();
        let span = tracing::info_span!(
            "agent.session.command",
            agent.session.id = %id,
            agent.action.name = action.as_ref(),
            agent.command.queue_wait_ms = tracing::field::Empty,
            agent.session.runtime_phase_at_dequeue = tracing::field::Empty,
            agent.command.handshake_wait_ms = tracing::field::Empty,
            otel.status_code = tracing::field::Empty,
            otel.status_description = tracing::field::Empty,
        );
        if commands
            .send(SessionMessage::Action(SessionCommand {
                user_id,
                action,
                action_id,
                completed,
                span,
                enqueued_at: tokio::time::Instant::now(),
            }))
            .await
            .is_err()
        {
            return Err(AgentSessionError::Disconnected(id));
        }
        // Not needed past this point, and holding it would be exactly the bug
        // `begin_stop` exists to avoid: a live sender clone keeping the
        // channel open no matter how many others get dropped, so the actor
        // can only notice by hitting its own much longer internal deadline
        // instead of promptly.
        drop(commands);
        // A transport that has already ended has no reply coming, however
        // long we wait: race the connector's own closed signal (when it has
        // one) alongside the reply so that case fails at once instead of
        // riding out the rest of `HANDSHAKE_TIMEOUT` for nothing. A
        // connector with no such signal just never resolves this side of
        // the select, unchanged from before.
        let transport_closed_first = async {
            match &transport_closed {
                Some(closed) => closed.cancelled().await,
                None => std::future::pending().await,
            }
        };
        let timed_out = tokio::select! {
            res = tokio::time::timeout(HANDSHAKE_TIMEOUT, result) => Some(res),
            () = transport_closed_first => None,
        };
        match timed_out {
            Some(Ok(Ok(result))) => result,
            Some(Ok(Err(_))) => Err(AgentSessionError::Disconnected(id)),
            Some(Err(_elapsed)) => {
                // The actor is presumably still stuck in the handshake, so it
                // is stopped directly - the same "drop the sender, the actor
                // notices and tears itself down" mechanism `close_session`
                // uses - rather than left to queue behind the same stall
                // forever.
                let (stopped, marker) = self.begin_stop(id, false);
                Self::wait_stopped(stopped).await;
                self.active.remove_if(&id, |_, active| {
                    Arc::ptr_eq(&active.marker, &marker) && !active.deleting
                });
                tracing::warn!(%id, "agent session command timed out waiting for the ACP handshake");
                Err(AgentSessionError::Disconnected(id))
            }
            None => {
                // The connector's transport already ended - no wall-clock
                // wait can help, so stop the actor the same way a timeout
                // does and fail now.
                let (stopped, marker) = self.begin_stop(id, false);
                Self::wait_stopped(stopped).await;
                self.active.remove_if(&id, |_, active| {
                    Arc::ptr_eq(&active.marker, &marker) && !active.deleting
                });
                tracing::info!(%id, "agent session command failed fast: transport already closed");
                Err(AgentSessionError::Disconnected(id))
            }
        }
    }

    fn begin_stop(&self, id: AgentSessionId, deleting: bool) -> (watch::Receiver<bool>, Arc<()>) {
        match self.active.entry(id) {
            Entry::Occupied(mut entry) => {
                let active = entry.get_mut();
                let attaching = active.commands.is_none() && !active.stopping;
                active.commands.take();
                active.deleting |= deleting;
                active.stopping = true;
                let stopped = if attaching {
                    let (_stopped_tx, stopped) = watch::channel(true);
                    stopped
                } else {
                    active.stopped.clone()
                };
                (stopped, active.marker.clone())
            }
            Entry::Vacant(entry) => {
                let (_stopped_tx, stopped) = watch::channel(true);
                let marker = Arc::new(());
                entry.insert(ActiveSession {
                    commands: None,
                    mcp_servers: Vec::new(),
                    stopped: stopped.clone(),
                    marker: marker.clone(),
                    deleting,
                    stopping: true,
                    transport_closed: None,
                });
                (stopped, marker)
            }
        }
    }

    async fn wait_stopped(mut stopped: watch::Receiver<bool>) {
        if !*stopped.borrow() {
            let _ = stopped.wait_for(|value| *value).await;
        }
    }
}

impl<R, Folds, Rt, Namer> AgentSessionService for AgentSessionServiceImpl<R, Folds, Rt, Namer>
where
    R: AgentSessionRepo + AgentSessionLogRepo + SessionOwnership + Clone,
    Folds: FoldedMessageRepo + Clone + Send + Sync + 'static,
    Rt: AgentSessionRealtime + Clone + Send + Sync + 'static,
    Namer: AgentSessionNameGenerator + Clone,
{
    async fn present_tool(
        &self,
        id: AgentSessionId,
        actor: MacroUserIdStr<'static>,
        presentation: super::model::SessionToolPresentation,
    ) -> Result<()> {
        self.present_to_actor(id, actor, presentation).await
    }

    async fn tool_presentation_persisted(
        &self,
        id: AgentSessionId,
        actor: MacroUserIdStr<'static>,
        presentation: super::model::SessionToolPresentation,
    ) -> Result<bool> {
        let session = self.repo.get(id).await?;
        if !session.owner_id.is_user(&actor) {
            return Err(AgentSessionError::Forbidden);
        }
        if session.is_archived() {
            return Err(AgentSessionError::Archived(id));
        }
        let entries = AgentSessionLogRepo::list_by_session(&self.repo, id).await?;
        let (started, completed) = presentation::presentation_progress(entries, &presentation)?;
        Ok(started && completed)
    }

    async fn create_session(&self, params: CreateAgentSessionParams) -> Result<AgentSession> {
        params.purpose.for_creation(
            false,
            params.thread_id.is_some() || params.originating_message_id.is_some(),
        )?;
        AgentSessionRepo::create(&self.repo, params).await
    }

    async fn rename_session(
        &self,
        access: &EntityAccessReceipt<OwnerAccessLevel>,
        name: &str,
    ) -> Result<()> {
        let name = validate_agent_session_name(name)?;
        let id = owner_access_session_id(access, "rename")?;
        if self.repo.get(id).await?.is_archived() {
            return Err(AgentSessionError::Archived(id));
        }
        self.repo.set_name(id, name).await?;
        self.realtime
            .publish_renamed(AgentSessionRenamed {
                agent_session_id: id,
                name: name.to_owned(),
            })
            .await
            .inspect_err(|error| {
                tracing::warn!(error = ?error, %id, "failed to publish agent session rename");
            })
            .ok();
        publish_renamed_lifecycle(&self.repo, &self.lifecycle_publisher, id).await;
        Ok(())
    }

    async fn set_archived(
        &self,
        access: &EntityAccessReceipt<OwnerAccessLevel>,
        archived: bool,
    ) -> Result<()> {
        let id = owner_access_session_id(access, "archive")?;
        // Every message in a conversation's channel goes to its current
        // session, and an archived session takes none. Starting fresh is how
        // a conversation retires one; the sessions it left behind archive.
        if archived && self.repo.is_current_conversation_session(id).await? {
            return Err(AgentSessionError::AnswersConversation(id));
        }
        self.repo.set_archived(id, archived).await?;
        self.realtime
            .publish_updated(id)
            .await
            .inspect_err(|error| {
                tracing::warn!(error = ?error, %id, "failed to publish agent session archive update");
            })
            .ok();
        Ok(())
    }

    async fn set_egress_token_hash(&self, id: AgentSessionId, hash: &str) -> Result<()> {
        self.repo.set_egress_token_hash(id, hash).await
    }

    async fn get_session(&self, id: AgentSessionId) -> Result<AgentSession> {
        self.repo.get(id).await
    }

    async fn find_session(&self, id: AgentSessionId) -> Result<Option<AgentSession>> {
        self.repo.find(id).await
    }

    async fn set_turn_prompter(&self, id: AgentSessionId, prompter: &TurnPrompter) -> Result<()> {
        self.repo.set_turn_prompter(id, prompter).await
    }

    async fn add_follower(&self, id: AgentSessionId, user: &MacroUserIdStr<'static>) -> Result<()> {
        self.repo.add_follower(id, user).await
    }

    async fn turn_prompter(&self, id: AgentSessionId) -> Result<Option<TurnPrompter>> {
        self.repo.turn_prompter(id).await
    }

    async fn preview_sessions(
        &self,
        viewer: &MacroUserIdStr<'static>,
        ids: Vec<AgentSessionId>,
    ) -> Result<Vec<AgentSessionPreview>> {
        let ids: Vec<AgentSessionId> = ids
            .into_iter()
            .collect::<std::collections::HashSet<_>>()
            .into_iter()
            .collect();
        if ids.len() > MAX_PREVIEW_SESSION_IDS {
            return Err(AgentSessionError::TooManyPreviewIds(
                MAX_PREVIEW_SESSION_IDS,
            ));
        }
        if ids.is_empty() {
            return Ok(Vec::new());
        }
        let mut candidates: std::collections::HashMap<AgentSessionId, SessionPreviewCandidate> =
            self.repo
                .preview(viewer, &ids)
                .await?
                .into_iter()
                .map(|candidate| (candidate.data.id, candidate))
                .collect();
        let mut previews = Vec::with_capacity(ids.len());
        for id in ids {
            let Some(candidate) = candidates.remove(&id) else {
                previews.push(AgentSessionPreview::DoesNotExist(id));
                continue;
            };
            // Links and originating discussions can grant access without a
            // materialized row. Resolve those through the same view port as
            // the session's read routes.
            let visible = candidate.has_grant || self.view_access.can_view(viewer, id).await?;
            previews.push(if visible {
                AgentSessionPreview::Access(Box::new(candidate.data))
            } else {
                AgentSessionPreview::NoAccess(id)
            });
        }
        let mut profiles = std::collections::HashMap::new();
        for preview in &mut previews {
            let AgentSessionPreview::Access(data) = preview else {
                continue;
            };
            if let std::collections::hash_map::Entry::Vacant(entry) = profiles.entry(data.bot_id) {
                let profile = self.repo.session_bot(data.bot_id).await.inspect_err(|error| {
                    tracing::warn!(error = ?error, bot_id = %data.bot_id, "failed to hydrate session preview bot");
                }).ok();
                entry.insert(profile);
            }
            data.bot = profiles.get(&data.bot_id).cloned().flatten();
        }
        Ok(previews)
    }

    async fn find_for_thread(
        &self,
        thread_id: Option<Uuid>,
        bot_id: Option<BotId>,
    ) -> Result<ThreadSession> {
        self.repo.find_for_thread(thread_id, bot_id).await
    }

    async fn sessions_for_user_cleanup(
        &self,
        owner: &MacroUserIdStr<'static>,
    ) -> Result<Vec<AgentSession>> {
        self.repo
            .recent_for_owner(owner, USER_CLEANUP_BATCH_SIZE)
            .await
    }

    async fn delete_session(&self, id: AgentSessionId) -> Result<()> {
        let (stopped, marker) = self.begin_stop(id, true);
        Self::wait_stopped(stopped).await;
        let result = self.repo.delete(id).await;
        self.active
            .remove_if(&id, |_, active| Arc::ptr_eq(&active.marker, &marker));
        result
    }

    async fn close_session(&self, id: AgentSessionId) -> Result<()> {
        // Dropping the sender is the whole operation: the actor's next step
        // reads `None` from its command channel, treats it as `Abandoned`, and
        // tears the transport down on its way out.
        let (stopped, marker) = self.begin_stop(id, false);
        Self::wait_stopped(stopped).await;
        self.active.remove_if(&id, |_, active| {
            Arc::ptr_eq(&active.marker, &marker) && !active.deleting
        });
        Ok(())
    }

    async fn management(&self, id: AgentSessionId) -> Result<SessionManagement> {
        let view = self.repo.lease_view(id, self.replica).await?;
        if view.asking_replica_draining {
            return Ok(SessionManagement::Draining);
        }
        Ok(match view.holder {
            None => SessionManagement::Unmanaged,
            // A draining holder is still heartbeating and may still be mid
            // turn, but it is leaving: treated as claimable so the next
            // command lands on a replica that is staying, and the fence the
            // takeover bumps is what stops the two writing over each other.
            Some(manager) if manager.draining => SessionManagement::Unmanaged,
            Some(manager) if manager.replica == self.replica => SessionManagement::Ours,
            Some(manager) => SessionManagement::Peer(manager),
        })
    }

    async fn begin_draining(&self) -> Result<()> {
        self.repo.begin_draining(self.replica).await
    }

    /// The out-of-band disconnect: a session marked dead by its opener rather
    /// than by its own actor stopping. Spanned separately from
    /// `agent.session.disconnect` because the two write the same log frame
    /// for entirely different reasons - this one means the runtime never came
    /// up at all.
    #[tracing::instrument(
        name = "agent.session.mark_disconnected",
        err,
        skip(self),
        fields(agent.session.id = %id),
    )]
    async fn mark_disconnected(&self, id: AgentSessionId) -> Result<()> {
        let mut logs = LiveSessionLogWriter::new(self.repo.clone(), self.realtime.clone());
        tokio::time::timeout(
            SESSION_PERSIST_TIMEOUT,
            logs.append(AgentSessionLog {
                agent_session_id: id,
                user_id: None,
                content: Message::ToServer(ToServerMessage::Event {
                    event: SystemEvent::Disconnected,
                }),
                logged_at: None,
            }),
        )
        .await
        .unwrap_or(Err(AgentSessionError::LogTimedOut(id)))
        .map(|_| ())
    }

    #[tracing::instrument(
        name = "agent.session.record_frame",
        err,
        skip(self, message),
        fields(agent.session.id = %id),
    )]
    async fn record_frame(&self, id: AgentSessionId, message: ToServerMessage) -> Result<()> {
        let mut logs = LiveSessionLogWriter::new(self.repo.clone(), self.realtime.clone());
        // Flushed at once: an unclaimed writer publishes to viewers only on
        // flush, and nothing else will flush this one.
        tokio::time::timeout(SESSION_PERSIST_TIMEOUT, async {
            logs.append(AgentSessionLog {
                agent_session_id: id,
                user_id: None,
                content: Message::ToServer(message),
                logged_at: None,
            })
            .await?;
            logs.flush().await
        })
        .await
        .unwrap_or(Err(AgentSessionError::LogTimedOut(id)))
    }

    #[tracing::instrument(
        name = "agent.session.record_unprojected_frame",
        err,
        skip(self, message),
        fields(agent.session.id = %id),
    )]
    async fn record_unprojected_frame(
        &self,
        id: AgentSessionId,
        message: ToServerMessage,
    ) -> Result<()> {
        tokio::time::timeout(SESSION_PERSIST_TIMEOUT, async {
            let stored = self
                .repo
                .create_projected(
                    AgentSessionLog {
                        agent_session_id: id,
                        user_id: None,
                        content: Message::ToServer(message),
                        logged_at: None,
                    },
                    None,
                    None,
                    None,
                )
                .await?;
            // Best effort, as for every other frame: it is already durable,
            // so a viewer who misses it reads it on the next log fetch.
            if let Err(error) = self
                .realtime
                .publish(LogAppended {
                    turn_state: None,
                    agent_session_id: id,
                    entries: vec![stored],
                })
                .await
            {
                tracing::error!(error = ?error, %id, "failed to stream an agent session frame");
            }
            Ok(())
        })
        .await
        .unwrap_or(Err(AgentSessionError::LogTimedOut(id)))
    }

    async fn attach_session<Connector>(
        &self,
        id: AgentSessionId,
        attachment: RuntimeAttachment<Connector>,
    ) -> Result<()>
    where
        Connector: AgentConnector,
    {
        // Reservation first: it is the in-process exclusion, so no sibling
        // attach of this instance can race us to the claim below - which
        // matters because every successful claim bumps the fence, and bumping
        // it under a live actor of our own would fence that actor out.
        let reservation = self.reserve_attach(id).await?;
        let claim = match self.repo.claim(id, self.replica).await? {
            ClaimOutcome::Claimed(claim) => claim,
            ClaimOutcome::ManagedElsewhere(holder) => {
                tracing::info!(%id, %holder, "agent session is managed by another live replica");
                return Err(AgentSessionError::ManagedElsewhere(id));
            }
        };
        let activated = async {
            let session = self.repo.get(id).await?;
            self.activate_reserved(session, attachment, reservation, claim)
                .await
        }
        .await;
        if let Err(error) = activated {
            // The actor that would have released this claim never started;
            // free it here so another replica is not left waiting out our
            // heartbeat to resume the session.
            self.repo
                .release(&claim)
                .await
                .inspect_err(|release_error| {
                    tracing::error!(
                        error = ?release_error,
                        %id,
                        "failed to release an agent session claim after a failed attach"
                    );
                })
                .ok();
            return Err(error);
        }
        Ok(())
    }

    async fn send_action(
        &self,
        id: AgentSessionId,
        user_id: Option<MacroUserIdStr<'static>>,
        action: AgentAction,
        action_id: AgentActionId,
    ) -> Result<()> {
        if self.repo.get(id).await?.is_archived() {
            return Err(AgentSessionError::Archived(id));
        }
        let initial_prompt = initial_prompt_for_rename(&self.folds, id, &action).await;

        self.deliver_action(id, user_id, action, action_id).await?;
        if let Some(initial_prompt) = initial_prompt {
            spawn_initial_agent_session_rename(
                self.repo.clone(),
                self.realtime.clone(),
                self.lifecycle_publisher.clone(),
                self.name_generator.clone(),
                id,
                initial_prompt,
            );
        }
        Ok(())
    }

    fn attached_mcp_servers(&self, id: AgentSessionId) -> Option<Vec<McpServer>> {
        self.active
            .get(&id)
            .filter(|active| active.commands.is_some())
            .map(|active| active.mcp_servers.clone())
    }

    async fn replace_mcp_servers(&self, id: AgentSessionId, servers: Vec<McpServer>) -> Result<()> {
        let commands = {
            let mut active = self
                .active
                .get_mut(&id)
                .ok_or(AgentSessionError::Disconnected(id))?;
            let commands = active
                .commands
                .clone()
                .ok_or(AgentSessionError::Disconnected(id))?;
            active.mcp_servers = servers.clone();
            commands
        };
        commands
            .send(SessionMessage::ReplaceMcpServers(servers))
            .await
            .map_err(|_| AgentSessionError::Disconnected(id))
    }

    async fn set_permission_policy(
        &self,
        id: AgentSessionId,
        policy: PermissionPolicy,
    ) -> Result<()> {
        let Some(commands) = self
            .active
            .get(&id)
            .and_then(|active| active.commands.clone())
        else {
            return Ok(());
        };
        commands
            .send(SessionMessage::SetPermissionPolicy(policy))
            .await
            .map_err(|_| AgentSessionError::Disconnected(id))
    }

    async fn session_bot(&self, id: BotId) -> Result<SessionBot> {
        self.repo.session_bot(id).await
    }

    async fn session_participants(
        &self,
        id: AgentSessionId,
    ) -> Result<Vec<MacroUserIdStr<'static>>> {
        self.repo.participants(id).await
    }

    async fn next_prompt_message_id(&self, id: AgentSessionId) -> Result<MessageId> {
        Ok(MessageId {
            turn: self.folds.next_turn_id(id).await?,
            author: AuthorKind::User,
        })
    }

    #[tracing::instrument(err, skip(self))]
    async fn session_log(&self, id: AgentSessionId) -> Result<SessionLog> {
        let session = self.repo.get(id).await?;
        let entries = AgentSessionLogRepo::list_by_session(&self.repo, id).await?;
        Ok(SessionLog {
            bot: self.repo.session_bot(session.bot_id).await?,
            entries,
        })
    }

    #[tracing::instrument(err, skip(self))]
    async fn recorded_action(
        &self,
        id: AgentSessionId,
        action: AgentActionId,
    ) -> Result<Option<super::action_history::RecordedAction>> {
        let entries = self.repo.list_action_history(id, action).await?;
        Ok(super::action_history::recorded_action(entries, action))
    }

    #[tracing::instrument(err, skip(self))]
    async fn folded_session_log(&self, id: AgentSessionId) -> Result<FoldedSessionLog> {
        let session = self.repo.get(id).await?;
        Ok(FoldedSessionLog {
            bot: self.repo.session_bot(session.bot_id).await?,
            messages: self.folds.messages(id).await?,
        })
    }

    async fn publish_queue_changed(&self, event: AgentSessionQueueChanged) -> Result<()> {
        Ok(self.realtime.publish_queue_changed(event).await?)
    }

    async fn list_queued_actions(&self, id: AgentSessionId) -> Result<Vec<StoredQueuedAction>> {
        self.repo.list_queued_actions(id).await
    }

    async fn replace_queued_actions(
        &self,
        id: AgentSessionId,
        entries: &[StoredQueuedAction],
    ) -> Result<()> {
        self.repo.replace_queued_actions(id, entries).await
    }

    async fn set_sandbox_size(&self, id: AgentSessionId, size: SandboxSize) -> Result<()> {
        self.repo.set_sandbox_size(id, size).await
    }

    async fn user_sandbox_size(&self, user_id: &MacroUserIdStr<'static>) -> Result<SandboxSize> {
        self.repo.user_sandbox_size(user_id).await
    }

    async fn set_user_sandbox_size(
        &self,
        user_id: &MacroUserIdStr<'static>,
        size: SandboxSize,
    ) -> Result<()> {
        self.repo.set_user_sandbox_size(user_id, size).await
    }

    async fn user_coding_preferences(
        &self,
        user_id: &MacroUserIdStr<'static>,
    ) -> Result<CodingPreferences> {
        self.repo.user_coding_preferences(user_id).await
    }

    async fn set_user_coding_preferences(
        &self,
        user_id: &MacroUserIdStr<'static>,
        preferences: CodingPreferences,
    ) -> Result<()> {
        self.repo
            .set_user_coding_preferences(user_id, preferences)
            .await
    }
}

async fn initial_prompt_for_rename<Folds>(
    folds: &Folds,
    id: AgentSessionId,
    action: &AgentAction,
) -> Option<String>
where
    Folds: FoldedMessageRepo,
{
    let AgentAction::Prompt(prompt) = action else {
        return None;
    };
    if prompt
        .notifications
        .as_ref()
        .is_some_and(|input| input.system_turn)
    {
        return None;
    }
    // Whether anyone has *spoken* here yet, rather than whether the log has
    // opened a turn: controls take turns of their own, so a session whose
    // model was set before its first prompt would otherwise never be named.
    folds
        .messages(id)
        .await
        .inspect_err(|error| {
            tracing::warn!(
                error = ?error,
                %id,
                "failed to determine whether agent prompt was the first"
            );
        })
        .ok()
        .filter(|messages| !messages.iter().any(is_user_prompt))
        .map(|_| prompt.name_source().to_owned())
}

/// A message a user wrote, as opposed to a control they issued.
fn is_user_prompt(message: &FoldedMessage) -> bool {
    matches!(message.author, Author::User { .. })
        && message.parts.iter().any(|part| {
            matches!(
                part,
                MessagePart::Text { .. } | MessagePart::Attachment { .. }
            )
        })
}

fn spawn_initial_agent_session_rename<R, Rt, Namer>(
    repo: R,
    realtime: Rt,
    lifecycle_publisher: Arc<dyn AgentSessionLifecyclePublisher>,
    name_generator: Namer,
    id: AgentSessionId,
    initial_prompt: String,
) where
    R: AgentSessionRepo + AgentSessionLogRepo + Clone,
    Rt: AgentSessionRealtime + Send + Sync + 'static,
    Namer: AgentSessionNameGenerator + Send + Sync + 'static,
{
    // Detached, so without a span of its own this work has no session id and
    // no link to the session that spawned it - which is why a rename that
    // fails for every session in a deployment still looks like nothing at
    // all. The outcome is recorded rather than logged because the failure is
    // swallowed here by design: nothing downstream ever notices a session
    // that kept its default name.
    let span = tracing::info_span!(
        "agent.session.rename",
        agent.session.id = %id,
        agent.rename.outcome = tracing::field::Empty,
    );
    tokio::spawn(
        async move {
            let span = tracing::Span::current();
            let result: std::result::Result<&'static str, rootcause::Report> = async {
                let session = repo
                    .get(id)
                    .await
                    .map_err(|error| rootcause::report!(error))?;
                let Some(name) = name_generator
                    .generate_name(&session, &initial_prompt)
                    .await?
                else {
                    return Ok("skipped_no_name");
                };
                let renamed = repo
                    .set_name_if_default(id, &name)
                    .await
                    .map_err(|error| rootcause::report!(error))?;
                if !renamed {
                    return Ok("skipped_already_named");
                }
                realtime
                    .publish_renamed(AgentSessionRenamed {
                        agent_session_id: id,
                        name,
                    })
                    .await?;
                publish_renamed_lifecycle(&repo, &lifecycle_publisher, id).await;
                Ok("renamed")
            }
            .await;

            match result {
                Ok(outcome) => {
                    span.record("agent.rename.outcome", outcome);
                }
                Err(error) => {
                    span.record("agent.rename.outcome", "failed");
                    tracing::warn!(error = ?error, %id, "failed to auto-rename initial agent session");
                }
            }
        }
        .instrument(span),
    );
}

/// A session actor's turn observer: tells the service's observer every fact,
/// and after each turn that ended with a reply, asks the namer whether the
/// session's generated name still fits.
struct RetitleAfterTurns<R, Folds, Rt, Namer> {
    observer: Arc<dyn SessionTurnObserver>,
    repo: R,
    folds: Folds,
    realtime: Rt,
    lifecycle_publisher: Arc<dyn AgentSessionLifecyclePublisher>,
    name_generator: Namer,
    tasks: TaskTracker,
}

impl<R, Folds, Rt, Namer> SessionTurnObserver for RetitleAfterTurns<R, Folds, Rt, Namer>
where
    R: AgentSessionRepo + AgentSessionLogRepo + Clone,
    Folds: FoldedMessageRepo + Clone + Send + Sync + 'static,
    Rt: AgentSessionRealtime + Clone + Send + Sync + 'static,
    Namer: AgentSessionNameGenerator + Clone,
{
    fn signal(&self, id: AgentSessionId, signal: TurnSignal) {
        // Only a reply the agent finished says anything new about the
        // conversation; system-only notification turns and stopped or
        // failed turns do not.
        let replied = matches!(
            signal,
            TurnSignal::TurnEnded {
                notification_noop: false,
                stop: TurnStopReason::EndTurn,
                ..
            }
        );
        self.observer.signal(id, signal);
        if replied {
            spawn_agent_session_retitle(
                &self.tasks,
                self.repo.clone(),
                self.folds.clone(),
                self.realtime.clone(),
                self.lifecycle_publisher.clone(),
                self.name_generator.clone(),
                id,
            );
        }
    }

    fn session_stopped(&self, id: AgentSessionId, reason: SessionStopReason) {
        self.observer.session_stopped(id, reason);
    }

    fn runtime_closed(&self, id: AgentSessionId) {
        self.observer.runtime_closed(id);
    }
}

fn spawn_agent_session_retitle<R, Folds, Rt, Namer>(
    tasks: &TaskTracker,
    repo: R,
    folds: Folds,
    realtime: Rt,
    lifecycle_publisher: Arc<dyn AgentSessionLifecyclePublisher>,
    name_generator: Namer,
    id: AgentSessionId,
) where
    R: AgentSessionRepo + AgentSessionLogRepo + Clone,
    Folds: FoldedMessageRepo + Send + Sync + 'static,
    Rt: AgentSessionRealtime + Send + Sync + 'static,
    Namer: AgentSessionNameGenerator,
{
    // Detached from the turn, like the initial rename, so it gets its own
    // span; the outcome is recorded because a failure is swallowed here.
    let span = tracing::info_span!(
        "agent.session.retitle",
        agent.session.id = %id,
        agent.retitle.outcome = tracing::field::Empty,
    );
    tasks.spawn(
        async move {
            let span = tracing::Span::current();
            let result: std::result::Result<&'static str, rootcause::Report> = async {
                // A name a person chose, the default, or an archived session
                // is never retitled, so most turns stop at this one read.
                let Some(current) = repo
                    .generated_name(id)
                    .await
                    .map_err(|error| rootcause::report!(error))?
                else {
                    return Ok("skipped_not_generated");
                };
                let conversation = ConversationDigest::from_messages(&folds.messages(id).await?);
                if !conversation.has_reply() {
                    return Ok("skipped_no_reply");
                }
                let session = repo
                    .get(id)
                    .await
                    .map_err(|error| rootcause::report!(error))?;
                let Some(name) = name_generator
                    .retitle(&session, &current, &conversation)
                    .await?
                else {
                    return Ok("kept");
                };
                let renamed = repo
                    .replace_generated_name(id, &current, &name)
                    .await
                    .map_err(|error| rootcause::report!(error))?;
                if !renamed {
                    return Ok("skipped_name_changed");
                }
                realtime
                    .publish_renamed(AgentSessionRenamed {
                        agent_session_id: id,
                        name,
                    })
                    .await?;
                publish_renamed_lifecycle(&repo, &lifecycle_publisher, id).await;
                Ok("renamed")
            }
            .await;

            match result {
                Ok(outcome) => {
                    span.record("agent.retitle.outcome", outcome);
                }
                Err(error) => {
                    span.record("agent.retitle.outcome", "failed");
                    tracing::warn!(error = ?error, %id, "failed to retitle agent session");
                }
            }
        }
        .instrument(span),
    );
}

/// Publish `agent_session.renamed` for a session whose name just changed.
///
/// The rename itself is already durable, so a failure to describe it here is
/// logged and swallowed: the event is a courtesy to downstream, not part of
/// the rename.
async fn publish_renamed_lifecycle<R>(
    repo: &R,
    lifecycle_publisher: &Arc<dyn AgentSessionLifecyclePublisher>,
    id: AgentSessionId,
) where
    R: AgentSessionRepo + AgentSessionLogRepo,
{
    let identity = async {
        let session = repo.get(id).await?;
        let (bot, participants) =
            tokio::try_join!(repo.session_bot(session.bot_id), repo.participants(id))?;
        session_identity(&session, &bot, participants)
    }
    .await;
    match identity {
        Ok(identity) => {
            lifecycle_publisher
                .publish(AgentSessionLifecycleEvent::Renamed(
                    SessionRenamedMetadata { identity },
                ))
                .await;
        }
        Err(error) => {
            tracing::warn!(error = ?error, %id, "skipping agent_session.renamed: identity unavailable");
        }
    }
}

/// The telemetry shape of a log frame: its kind, and the status event it
/// carries when it is one.
///
/// Status events are named individually because a session's visible state is
/// projected from them and there are only a handful. ACP traffic is counted
/// but never named - the frame's content is user data and never belongs in a
/// span.
fn frame_telemetry(content: &Message) -> (&'static str, Option<&str>) {
    match content {
        Message::ToServer(ToServerMessage::Event { event }) => ("event", Some(event.as_str())),
        Message::ToServer(_) => ("acp_to_server", None),
        Message::ToRuntime(_) => ("acp_to_runtime", None),
        Message::Notification(_) => ("notification", None),
    }
}

fn validate_agent_session_name(raw: &str) -> Result<&str> {
    let name = raw.trim();
    if name.is_empty() {
        return Err(AgentSessionError::InvalidName("name must not be blank"));
    }
    if name == crate::domain::model::DEFAULT_AGENT_SESSION_NAME {
        return Err(AgentSessionError::InvalidName(
            "name must be more specific than the default",
        ));
    }
    if name.chars().count() > MAX_AGENT_SESSION_NAME_CHARS {
        return Err(AgentSessionError::InvalidName(
            "name must be at most 100 characters",
        ));
    }
    Ok(name)
}

fn owner_access_session_id(
    access: &EntityAccessReceipt<OwnerAccessLevel>,
    operation: &str,
) -> Result<AgentSessionId> {
    if access.entity().entity_type != EntityType::AgentSession {
        return Err(AgentSessionError::Unknown(anyhow::anyhow!(
            "agent session {operation} received access for another entity type"
        )));
    }
    Ok(AgentSessionId::new_from_uuid(
        Uuid::parse_str(&access.entity().entity_id)
            .map_err(|error| anyhow::anyhow!("invalid agent session access receipt: {error}"))?,
    ))
}

/// How long a streamed frame may sit buffered before it must be written and
/// pushed to viewers. The crash window - a process dying loses at most this
/// much of the *tail* of a session's streamed output; flushes happen in
/// append order, so a lost suffix never punches a hole in the middle - and
/// the latency a viewer sees on streamed output.
const LOG_FLUSH_INTERVAL: std::time::Duration = std::time::Duration::from_millis(1500);
/// Coalesce the start of an answer just enough to include words after a
/// Markdown prefix, instead of publishing only `**` or a heading marker.
const FIRST_OUTPUT_FLUSH_INTERVAL: std::time::Duration = std::time::Duration::from_millis(50);
/// How many frames may accumulate before a flush happens regardless of age,
/// bounding memory, the size of one insert and one publish, and what a crash
/// could lose.
const MAX_PENDING_LOG_FRAMES: usize = 256;

/// The [`AgentSessionLogRepo`] a session's actor writes through: the durable
/// append, then the push to whoever is watching the session right now.
///
/// Writes and pushes are batched. Streamed output - the overwhelming bulk of
/// a live session's frames, and the whole of a `session/load` replay - is
/// buffered under a claim and, [`MAX_PENDING_LOG_FRAMES`] at a time or every
/// [`LOG_FLUSH_INTERVAL`], written as one fenced insert and pushed to viewers
/// as one publish, instead of costing a transaction, an audience lookup and
/// a gateway round trip each. The first visible output and initial prose of a
/// live turn use [`FIRST_OUTPUT_FLUSH_INTERVAL`] to avoid delaying the answer's start.
/// Only plain to-server notifications take that
/// path: anything the store projects (system events, a load boundary, a
/// Cursor checkpoint) or the runtime will act on writes the buffer out
/// first and then lands at once through the single-frame path, exactly as
/// before, so history never lacks or reorders a frame the rest of the system
/// reacted to. A writer without a claim writes every frame at once.
///
/// This is also where a writer's fold lives, and the fold is what makes
/// re-attaching correct: [`TurnId`](agent_fold::domain::model::TurnId)s are a
/// counter over the log, so a connection has to know how far along the session
/// already is. Carrying the machine from frame to frame rather than refolding
/// the stored log per frame is what keeps that from being quadratic in the
/// length of the session.
///
/// Public because a session's actor is not the only thing that writes a run of
/// frames in order: `seed_jsonl` replays a whole recording, and wants the same
/// arithmetic rather than a refold per line.
pub struct LiveSessionLogWriter<R, Rt> {
    repo: R,
    realtime: Rt,
    fold: Option<LifecycleFold>,
    /// The management claim this writer appends under, when it has one. A
    /// session actor always writes fenced; the unfenced constructor exists
    /// for writers outside any live-management contest - `seed_jsonl`
    /// replaying a recording, and `mark_disconnected` recording that a
    /// runtime dropped before anything attached.
    claim: Option<SessionClaim>,
    /// Keep the saved selection until the runtime confirms it. Otherwise the
    /// default reported by session/new replaces it even when selection fails.
    initial_model: Option<String>,
    initial_model_request: Option<RequestId>,
    /// Frames appended under the claim but not yet written, with the ids
    /// they were handed at append time, in append order.
    buffer: Vec<BufferedFrame>,
    /// Stored frames not yet pushed to viewers, in log order.
    pending: Vec<StoredAgentSessionLog>,
    /// When the oldest buffered or pending frame must be flushed by; `None`
    /// while there is none, so an idle writer never wakes its actor.
    flush_due: Option<tokio::time::Instant>,
    /// The model last projected onto the session row, so a thousand streamed
    /// frames under one model cost one `UPDATE`, not a thousand.
    projected_model: Option<String>,
    /// Last turn state stored atomically with its frame. Stream publication
    /// uses this durable value, never a state from buffered frames.
    projected_turn: Option<TurnState>,
    /// Publish the start of each live answer without waiting for the batch.
    first_output: FirstOutput,
}

/// One frame waiting for the next write.
struct BufferedFrame {
    id: Uuid,
    log: AgentSessionLog,
}

/// Frames that may wait for the batch: to-server notifications the store
/// projects nothing from. Everything else - requests and responses (the
/// handshake), system events, checkpoints - is durable before `append`
/// returns, through the single-frame path.
fn batches(content: &Message) -> bool {
    matches!(
        content,
        Message::ToServer(ToServerMessage::Acp(AcpMessage(
            RawJsonRpcMessage::Notification(_)
        )))
    ) && cursor_run_checkpoint(content).is_none()
}

/// Frames viewers must see as soon as they are stored rather than with the
/// next batch: anything the runtime will act on, and anything that projects
/// onto the session's status. Replies also unblock clients waiting for the
/// handshake or a selected model/effort before sending their first prompt.
fn flushes_through(content: &Message) -> bool {
    matches!(
        content,
        Message::ToRuntime(_)
            | Message::Notification(_)
            | Message::ToServer(ToServerMessage::Event { .. })
            | Message::ToServer(ToServerMessage::Acp(AcpMessage(
                RawJsonRpcMessage::Response(_)
            )))
    )
}

impl<R, Rt> LiveSessionLogWriter<R, Rt> {
    /// A log writer that streams each frame it writes to whoever is watching
    /// the session.
    ///
    /// The fold starts empty and catches itself up on whatever is already
    /// stored when the first frame arrives, so this is cheap to build and
    /// correct against a session that already has a log.
    pub fn new(repo: R, realtime: Rt) -> Self {
        Self {
            repo,
            realtime,
            fold: None,
            claim: None,
            initial_model: None,
            initial_model_request: None,
            buffer: Vec::new(),
            pending: Vec::new(),
            flush_due: None,
            projected_model: None,
            projected_turn: None,
            first_output: FirstOutput::default(),
        }
    }

    /// [`new`](Self::new), with every append conditioned on `claim` still
    /// holding the session's current fence. What a live actor writes with.
    pub fn fenced(repo: R, realtime: Rt, claim: SessionClaim) -> Self {
        Self {
            repo,
            realtime,
            fold: None,
            claim: Some(claim),
            initial_model: None,
            initial_model_request: None,
            buffer: Vec::new(),
            pending: Vec::new(),
            flush_due: None,
            projected_model: None,
            projected_turn: None,
            first_output: FirstOutput::default(),
        }
    }

    fn with_initial_model(mut self, model: Option<String>) -> Self {
        self.initial_model = model;
        self
    }
}

impl<R, Rt> AgentSessionLogWriter for LiveSessionLogWriter<R, Rt>
where
    R: AgentSessionRepo + AgentSessionLogRepo + Clone,
    Rt: AgentSessionRealtime + Send + Sync + 'static,
{
    async fn present_tool(
        &mut self,
        id: AgentSessionId,
        acp_id: SessionId,
        presentation: super::model::SessionToolPresentation,
    ) -> Result<()> {
        self.persist_presentation(id, acp_id, presentation).await
    }

    async fn append_with_boundary(
        &mut self,
        log: AgentSessionLog,
        boundary: Option<crate::domain::model::HistoryBoundary>,
    ) -> Result<Appended> {
        let session = log.agent_session_id;

        // The wire tap: every frame of every session, both directions,
        // crosses here exactly once. Enable with RUST_LOG=agent_session=trace.
        if tracing::enabled!(tracing::Level::TRACE) {
            let (direction, frame) = match &log.content {
                Message::ToServer(message) => ("to_server", serde_json::to_string(message)),
                Message::ToRuntime(message) => ("to_runtime", serde_json::to_string(message)),
                Message::Notification(message) => ("notification", serde_json::to_string(message)),
            };
            tracing::trace!(
                %session,
                direction,
                frame = frame.as_deref().unwrap_or("<unserializable>"),
                "acp frame"
            );
        }

        // Fold before anything is written: the fold is in memory, so its
        // signals are exact whether the frame lands now or with the batch,
        // and a first frame catches the fold up on everything stored plus
        // everything still buffered before it.
        if self.fold.is_none() {
            match self.catch_up(session).await {
                Ok(fold) => self.fold = Some(fold),
                Err(error) => {
                    tracing::error!(
                        error = ?error,
                        %session,
                        "failed to fold agent session frame"
                    );
                }
            }
        }
        let pushed = self
            .fold
            .as_mut()
            .map(|fold| fold.push(log.clone()))
            .unwrap_or_default();
        let first_output = self.first_output.observe(&pushed.events);

        let turn_state = self
            .fold
            .as_ref()
            .map(|fold| fold.inner().metadata().turn)
            .filter(|turn| self.projected_turn != Some(*turn));

        let log_id = match &self.claim {
            Some(_) if boundary.is_none() && turn_state.is_none() && batches(&log.content) => {
                let id = macro_uuid::generate_uuid_v7();
                self.buffer.push(BufferedFrame {
                    id,
                    log: log.clone(),
                });
                self.flush_due
                    .get_or_insert_with(|| tokio::time::Instant::now() + LOG_FLUSH_INTERVAL);
                if self.buffer.len() + self.pending.len() >= MAX_PENDING_LOG_FRAMES {
                    AgentSessionLogWriter::flush(self).await?;
                }
                id
            }
            Some(claim) => {
                // Whatever is buffered lands first, so history keeps append
                // order around a frame the rest of the system reacts to.
                let claim = *claim;
                self.flush_writes().await?;
                let stored = self
                    .repo
                    .create_projected(log.clone(), Some(&claim), boundary, turn_state)
                    .await?;
                self.projected_turn = turn_state.or(self.projected_turn);
                let id = stored.id;
                let flush_now = flushes_through(&stored.entry.content);
                self.pending.push(stored);
                self.flush_due
                    .get_or_insert_with(|| tokio::time::Instant::now() + LOG_FLUSH_INTERVAL);
                if flush_now || self.pending.len() >= MAX_PENDING_LOG_FRAMES {
                    AgentSessionLogWriter::flush(self).await?;
                }
                id
            }
            None if boundary.is_some() => return Err(AgentSessionError::FencedOut(session)),
            // Unclaimed writers are outside any live contest and write every
            // frame at once - the batch exists for streamed output under a
            // claim, nothing else.
            None => {
                let stored = self
                    .repo
                    .create_projected(log.clone(), None, None, turn_state)
                    .await?;
                self.projected_turn = turn_state.or(self.projected_turn);
                let id = stored.id;
                let flush_now = flushes_through(&stored.entry.content);
                self.pending.push(stored);
                self.flush_due
                    .get_or_insert_with(|| tokio::time::Instant::now() + LOG_FLUSH_INTERVAL);
                if flush_now || self.pending.len() >= MAX_PENDING_LOG_FRAMES {
                    AgentSessionLogWriter::flush(self).await?;
                }
                id
            }
        };

        if first_output && let Some(deadline) = &mut self.flush_due {
            *deadline = (*deadline).min(tokio::time::Instant::now() + FIRST_OUTPUT_FLUSH_INTERVAL);
        }

        if turn_state.is_some()
            && let Err(error) = self.realtime.publish_updated(session).await
        {
            tracing::error!(error = ?error, %session, "failed to publish agent session turn update");
        }

        // Projected when it changes - idempotent, rebuildable from the log,
        // and best-effort, so a failed write must not fail the append.
        let model = self
            .fold
            .as_ref()
            .and_then(|fold| fold.inner().metadata().model.clone());
        // Track this connection's selection request. A session/new reply or an
        // unrelated config response must not release the saved-model guard.
        if let Some(expected) = &self.initial_model
            && self.initial_model_request.is_none()
            && let Message::ToRuntime(message) = &log.content
            && let Some((_, selection)) = AgentSetModelAction::from_runtime(message)
            && selection.model == *expected
            && let ToRuntimeMessage::Acp(AcpMessage(RawJsonRpcMessage::Request(request))) = message
        {
            self.initial_model_request = Some(request.id.clone());
        }
        // Catching up the fold may report a previous connection's model, so
        // only the matching fresh response can confirm startup.
        if let Some(expected) = &self.initial_model
            && let Message::ToServer(ToServerMessage::Acp(AcpMessage(RawJsonRpcMessage::Response(
                Response::Result { id, result, .. },
            )))) = &log.content
            && self.initial_model_request.as_ref() == Some(id)
            && let Ok(response) =
                serde_json::from_value::<SetSessionConfigOptionResponse>(result.clone())
            && model_selection(&response.config_options)
                .is_some_and(|selection| selection.current == *expected)
        {
            self.initial_model = None;
            self.initial_model_request = None;
        }
        if self.initial_model.is_none()
            && let Some(model) = model
            && self.projected_model.as_ref() != Some(&model)
        {
            match self.repo.set_model(session, &model).await {
                Ok(()) => self.projected_model = Some(model),
                Err(error) => {
                    tracing::error!(
                        error = ?error,
                        %session,
                        "failed to project agent session model"
                    );
                }
            }
        }

        Ok(Appended {
            log_id,
            signals: pushed.signals,
        })
    }

    async fn flush(&mut self) -> Result<()> {
        self.flush_writes().await?;
        if self.pending.is_empty() {
            self.flush_due = None;
            return Ok(());
        }
        let entries = std::mem::take(&mut self.pending);
        self.flush_due = None;
        let session = entries[0].entry.agent_session_id;
        // Best-effort: the port drops frames by contract, and every frame
        // here is already durable, so the worst a failure costs is a viewer
        // who has to reload.
        if let Err(error) = self.stream(session, entries).await {
            tracing::error!(
                error = ?error,
                %session,
                "failed to stream agent session frames"
            );
        }
        Ok(())
    }

    fn flush_deadline(&self) -> Option<tokio::time::Instant> {
        self.flush_due
    }
}

impl<R, Rt> LiveSessionLogWriter<R, Rt>
where
    R: AgentSessionRepo + AgentSessionLogRepo + Clone,
    Rt: AgentSessionRealtime + Send + Sync + 'static,
{
    /// Land every buffered frame in one fenced write, leaving them pending
    /// publication.
    ///
    /// The buffer is taken, not borrowed: a failed batch is not retried. Its
    /// commit may have landed, and a retry would duplicate every frame in
    /// it, so a failed flush loses its frames the way a failed per-frame
    /// write used to lose its one - and the actor tears the session down
    /// over the error either way.
    async fn flush_writes(&mut self) -> Result<()> {
        if self.buffer.is_empty() {
            return Ok(());
        }
        let Some(claim) = self.claim else {
            // Nothing is ever buffered without a claim; see `append_with_boundary`.
            return Ok(());
        };
        let entries = std::mem::take(&mut self.buffer)
            .into_iter()
            .map(|frame| StoredAgentSessionLog {
                id: frame.id,
                // Placeholder; the store stamps the row and hands the real
                // time back.
                created_at: chrono::Utc::now(),
                entry: frame.log,
            })
            .collect();
        let stored = self.repo.create_batch_fenced(entries, &claim).await?;
        self.pending.extend(stored);
        Ok(())
    }
}

/// Pure delegation to the wrapped repository: the actor's shutdown path reads
/// and updates the session through its `Logs` handle, and those operations
/// append nothing, so there is nothing for this writer to do with them.
impl<R, Rt> AgentSessionRepo for LiveSessionLogWriter<R, Rt>
where
    R: AgentSessionRepo + AgentSessionLogRepo,
    Rt: AgentSessionRealtime + Send + Sync + 'static,
{
    async fn create(&self, params: CreateAgentSessionParams) -> Result<AgentSession> {
        AgentSessionRepo::create(&self.repo, params).await
    }

    async fn get(&self, id: AgentSessionId) -> Result<AgentSession> {
        self.repo.get(id).await
    }

    async fn find(&self, id: AgentSessionId) -> Result<Option<AgentSession>> {
        self.repo.find(id).await
    }

    async fn preview(
        &self,
        viewer: &MacroUserIdStr<'static>,
        ids: &[AgentSessionId],
    ) -> Result<Vec<SessionPreviewCandidate>> {
        self.repo.preview(viewer, ids).await
    }

    async fn set_egress_token_hash(&self, id: AgentSessionId, hash: &str) -> Result<()> {
        self.repo.set_egress_token_hash(id, hash).await
    }

    async fn set_turn_prompter(&self, id: AgentSessionId, prompter: &TurnPrompter) -> Result<()> {
        self.repo.set_turn_prompter(id, prompter).await
    }

    async fn add_follower(&self, id: AgentSessionId, user: &MacroUserIdStr<'static>) -> Result<()> {
        self.repo.add_follower(id, user).await
    }

    async fn turn_prompter(&self, id: AgentSessionId) -> Result<Option<TurnPrompter>> {
        self.repo.turn_prompter(id).await
    }

    async fn find_by_egress_token_hash(
        &self,
        egress_token_hash: &str,
    ) -> Result<Option<AgentSession>> {
        self.repo.find_by_egress_token_hash(egress_token_hash).await
    }

    async fn session_bot(
        &self,
        id: bots::domain::models::BotId,
    ) -> Result<super::model::SessionBot> {
        self.repo.session_bot(id).await
    }

    async fn recent_for_owner(
        &self,
        owner: &MacroUserIdStr<'_>,
        limit: std::num::NonZeroUsize,
    ) -> Result<Vec<super::model::AgentSession>> {
        self.repo.recent_for_owner(owner, limit).await
    }

    async fn find_for_thread(
        &self,
        thread_id: Option<Uuid>,
        bot_id: Option<bots::domain::models::BotId>,
    ) -> Result<super::model::ThreadSession> {
        self.repo.find_for_thread(thread_id, bot_id).await
    }

    async fn find_all_for_thread(&self, thread_id: Uuid) -> Result<Vec<AgentSession>> {
        self.repo.find_all_for_thread(thread_id).await
    }

    async fn set_acp_session_id(
        &self,
        id: AgentSessionId,
        acp_session_id: SessionId,
    ) -> Result<()> {
        self.repo.set_acp_session_id(id, acp_session_id).await
    }

    async fn set_repo_url(&self, id: AgentSessionId, repo_url: Option<String>) -> Result<()> {
        self.repo.set_repo_url(id, repo_url).await
    }

    async fn set_model(&self, id: AgentSessionId, model: &str) -> Result<()> {
        self.repo.set_model(id, model).await
    }

    async fn set_origin(
        &self,
        id: AgentSessionId,
        source: SessionSource,
        visibility: SessionVisibility,
    ) -> Result<()> {
        self.repo.set_origin(id, source, visibility).await
    }

    async fn set_name(&self, id: AgentSessionId, name: &str) -> Result<()> {
        self.repo.set_name(id, name).await
    }

    async fn set_archived(&self, id: AgentSessionId, archived: bool) -> Result<()> {
        self.repo.set_archived(id, archived).await
    }

    async fn is_current_conversation_session(&self, id: AgentSessionId) -> Result<bool> {
        self.repo.is_current_conversation_session(id).await
    }

    async fn set_name_if_default(&self, id: AgentSessionId, name: &str) -> Result<bool> {
        self.repo.set_name_if_default(id, name).await
    }

    async fn generated_name(&self, id: AgentSessionId) -> Result<Option<String>> {
        self.repo.generated_name(id).await
    }

    async fn replace_generated_name(
        &self,
        id: AgentSessionId,
        current: &str,
        name: &str,
    ) -> Result<bool> {
        self.repo.replace_generated_name(id, current, name).await
    }

    async fn set_sandbox_size(&self, id: AgentSessionId, size: SandboxSize) -> Result<()> {
        self.repo.set_sandbox_size(id, size).await
    }

    async fn user_sandbox_size(&self, user_id: &MacroUserIdStr<'static>) -> Result<SandboxSize> {
        self.repo.user_sandbox_size(user_id).await
    }

    async fn set_user_sandbox_size(
        &self,
        user_id: &MacroUserIdStr<'static>,
        size: SandboxSize,
    ) -> Result<()> {
        self.repo.set_user_sandbox_size(user_id, size).await
    }

    async fn user_coding_preferences(
        &self,
        user_id: &MacroUserIdStr<'static>,
    ) -> Result<CodingPreferences> {
        self.repo.user_coding_preferences(user_id).await
    }

    async fn set_user_coding_preferences(
        &self,
        user_id: &MacroUserIdStr<'static>,
        preferences: CodingPreferences,
    ) -> Result<()> {
        self.repo
            .set_user_coding_preferences(user_id, preferences)
            .await
    }

    async fn delete(&self, id: AgentSessionId) -> Result<()> {
        self.repo.delete(id).await
    }

    async fn list_queued_actions(&self, id: AgentSessionId) -> Result<Vec<StoredQueuedAction>> {
        self.repo.list_queued_actions(id).await
    }

    async fn replace_queued_actions(
        &self,
        id: AgentSessionId,
        entries: &[StoredQueuedAction],
    ) -> Result<()> {
        self.repo.replace_queued_actions(id, entries).await
    }
}

impl<R, Rt> LiveSessionLogWriter<R, Rt>
where
    R: AgentSessionRepo + AgentSessionLogRepo,
    Rt: AgentSessionRealtime,
{
    /// Push the frame just appended out to whoever is watching the session.
    ///
    /// The last frame's kind rides along because this span is the only
    /// per-flush signal a session emits: a status event here is what moves
    /// the composer's whole notion of whether the agent is working, and
    /// without naming it "frames were published" answers nothing.
    #[tracing::instrument(
        name = "agent.session.realtime.publish",
        err,
        skip(self, agent_session_id, entries),
        fields(
            agent.session.id = %agent_session_id,
            agent.log.frame_count = entries.len(),
            agent.log.frame_kind = tracing::field::Empty,
            agent.log.event = tracing::field::Empty,
        )
    )]
    async fn stream(
        &mut self,
        agent_session_id: AgentSessionId,
        entries: Vec<StoredAgentSessionLog>,
    ) -> std::result::Result<(), rootcause::Report> {
        let span = tracing::Span::current();
        if let Some(last) = entries.last() {
            let (frame_kind, event) = frame_telemetry(&last.entry.content);
            span.record("agent.log.frame_kind", frame_kind);
            if let Some(event) = event {
                span.record("agent.log.event", event);
            }
        }
        self.realtime
            .publish(LogAppended {
                turn_state: self.projected_turn,
                agent_session_id,
                entries,
            })
            .await
    }

    /// Walk this connection's fold through the session's stored log and then
    /// through anything still buffered, so it starts from where the session
    /// actually is rather than from nothing.
    ///
    /// Runs once per connection, before its first frame is folded. Everything
    /// it folds is history, and whatever that signalled is discarded, because
    /// a reconnect must not announce past turns again. The caller then pushes
    /// the first frame itself, live, and gets that frame's signals.
    ///
    /// This is what makes re-attaching correct.
    /// [`TurnId`](agent_fold::domain::model::TurnId)s are a counter over the
    /// log, so a fold starting empty would hand `TurnId(0)` to the next prompt
    /// of a session already five turns in - while a reader folding the whole
    /// log went on deriving turn five, and the two would disagree about which
    /// message is which.
    async fn catch_up(
        &self,
        session: AgentSessionId,
    ) -> std::result::Result<LifecycleFold, rootcause::Report> {
        let log = AgentSessionLogRepo::list_by_session(&self.repo, session)
            .await
            .map_err(|error| rootcause::report!(error))?;

        let mut fold = LifecycleFold::new();
        for stored in log {
            let _ = fold.push(stored.entry);
        }
        for frame in &self.buffer {
            let _ = fold.push(frame.log.clone());
        }
        Ok(fold)
    }
}

/// Step the actor until its machine stops, then release the registry entry
/// and the session's management claim.
// One argument per fact the loop owns; a struct here would only move the
// same list one level down.
#[allow(clippy::too_many_arguments)]
async fn run_session<Connector, Logs, Ownership>(
    mut actor: SessionActor<Connector, Logs>,
    active: std::sync::Weak<ActiveSessions>,
    marker: Arc<()>,
    stopped: watch::Sender<bool>,
    cancellation: CancellationToken,
    ownership: Ownership,
    claim: SessionClaim,
    turn_observer: Arc<dyn SessionTurnObserver>,
) where
    Connector: AgentConnector,
    Logs: AgentSessionLogWriter + AgentSessionRepo,
    Ownership: SessionOwnership,
{
    let stop_reason = loop {
        let input = tokio::select! {
            biased;
            () = cancellation.cancelled() => ActorInput::Protocol(Input::Closed(CloseReason::Abandoned)),
            input = actor.next_input() => input,
        };
        let stepped = actor.dispatch_input(input).await;
        if let Stepped::Stopped(reason) = stepped {
            break reason;
        }
    };

    // Refuse late commands before releasing the registry entry, so a caller
    // cannot enqueue into an actor that will never step again.
    actor.close();
    let id = actor.id();

    // Tear down the old transport before allowing another actor to attach.
    drop(actor);
    // Give the claim back before announcing the stop: fence-conditioned, so
    // if a successor already took over this quietly does nothing. Releasing
    // here rather than waiting for heartbeat staleness is what lets another
    // replica resume this session immediately after a graceful stop.
    if let Err(error) = ownership.release(&claim).await {
        tracing::error!(error = ?error, %id, "failed to release an agent session claim");
    }
    let _ = stopped.send(true);
    if let Some(active) = active.upgrade() {
        active.remove_if(&id, |_, current| {
            current.commands.is_some() && Arc::ptr_eq(&current.marker, &marker)
        });
    }
    // Last, after the registry entry is gone: whatever the observer does with
    // the fact - clear a busy flag, dispatch nothing - it sees a session that
    // really has no actor anymore.
    turn_observer.session_stopped(id, stop_reason);
}