libtmux 0.1.0-alpha.10

//! Session handles and their snapshot getters.

mod settings;

use std::ffi::{OsStr, OsString};
use std::fmt;
use std::hash::{Hash, Hasher};
use std::sync::Arc;

use crate::formats::TmuxText;
use crate::internal::core::Core;
use crate::internal::listing::{self, Pushdown as _};
use crate::internal::scoped;
use crate::pane::Pane;
#[cfg(feature = "query")]
use crate::query::{FilterSchema, Filterable};
#[cfg(feature = "query")]
use crate::snapshot::SessionFields;
use crate::snapshot::SessionInfo;
use crate::target::{ServerIdentity, SessionId};
use crate::window::Window;
use crate::{Command, CommandResult, Error, ObjectKind};

/// What a session's environment holds for one name.
///
/// tmux keeps two different things under a name: a value, and a mark saying a
/// process started here must *not* inherit the name at all. They are not the
/// same as absence, and they are not the same as each other.
///
/// # Examples
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
/// # runtime.block_on(async {
/// use libtmux::EnvironmentEntry;
///
/// let guard = libtmux::test::TestServer::new().await?;
/// let session = guard.server().new_session("env").await?;
///
/// session.set_environment("EDITOR", "hx").await?;
/// assert!(matches!(
///     session.environment("EDITOR").await?,
///     Some(EnvironmentEntry::Set(value)) if value.as_bytes() == b"hx",
/// ));
///
/// // Hiding a name is not unsetting it: a process started here is handed the
/// // name *absent*, which tmux still records and reports.
/// session.hide_environment("EDITOR").await?;
/// assert_eq!(
///     session.environment("EDITOR").await?,
///     Some(EnvironmentEntry::Removed),
/// );
///
/// // Never set at all is the third thing, and the only one that is `None`.
/// assert_eq!(session.environment("NEVER_SET").await?, None);
///
/// guard.shutdown().await?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// # })?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum EnvironmentEntry {
    /// tmux holds this value, exactly as stored.
    Set(TmuxText),
    /// tmux will remove this name from the environment it hands out.
    Removed,
}

/// One tmux session, together with the snapshot it was discovered with.
///
/// A `Session` is cheap to clone and shares its connection with the [`Server`]
/// that produced it, but owns its snapshot outright. Cloning therefore does
/// not share observed state: refreshing one clone leaves the others as they
/// were.
///
/// Getters are synchronous because they read the owned snapshot. Anything that
/// consults tmux is `async`.
///
/// [`Server`]: crate::Server
///
/// # Examples
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
/// # runtime.block_on(async {
/// let guard = libtmux::test::TestServer::new().await?;
/// let session = guard.server().new_session("work").await?;
///
/// // The name is read from the snapshot this handle owns, so it costs
/// // nothing; asking tmux for the windows is `async` because it does.
/// assert_eq!(session.name().to_string_lossy(), "work");
/// assert_eq!(session.windows().await?.len(), 1);
///
/// guard.shutdown().await?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// # })?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone)]
pub struct Session {
    core: Arc<Core>,
    info: SessionInfo,
}

impl Session {
    /// Build a handle from a hydrated snapshot.
    pub(crate) const fn new(core: Arc<Core>, info: SessionInfo) -> Self {
        Self { core, info }
    }

    /// Find the session this process is running in.
    ///
    /// Resolved through the pane, because `TMUX_PANE` names exactly one pane
    /// while a server's `TMUX` value names the session that was current when
    /// the client attached, which may since have changed.
    ///
    /// `Ok(None)` means tmux no longer has that pane.
    ///
    /// # Errors
    ///
    /// Returns an error when `TMUX_PANE` is absent or is not a pane ID, or
    /// when the listing fails.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// # let guard = libtmux::test::TestServer::new().await?;
    /// # let server = guard.server();
    /// use libtmux::{Pane, Session};
    ///
    /// let session = server.new_session("locating-session").await?;
    /// let pane = session.panes().await?.remove(0);
    ///
    /// // Standing in for the environment tmux gives a process it starts.
    /// let found = Session::from_env_value(server, Some(pane.id().as_ref())).await?;
    ///
    /// assert_eq!(found.expect("the session exists").id(), session.id());
    /// # guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn from_env(server: &crate::Server) -> Result<Option<Self>, Error> {
        Self::from_env_value(server, std::env::var_os("TMUX_PANE")).await
    }

    /// Find a session from an explicit `TMUX_PANE` value.
    ///
    /// # Errors
    ///
    /// Returns an error when the value is absent or is not a pane ID, or when
    /// the listing fails.
    pub async fn from_env_value(
        server: &crate::Server,
        value: Option<impl AsRef<OsStr>>,
    ) -> Result<Option<Self>, Error> {
        let Some(pane) = Pane::from_env_value(server, value).await? else {
            return Ok(None);
        };

        server.session_by_id(pane.session_id()).await
    }

    /// Return the tmux session identity.
    ///
    /// This is the `$`-prefixed id tmux assigns, which is stable across
    /// renames. It is always present.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.session("work").await?;
    ///
    /// assert!(session.id().to_string().starts_with('$'));
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn id(&self) -> &SessionId {
        self.info.session_id()
    }

    /// Return the session name.
    ///
    /// Names are byte-preserving: tmux permits bytes that are not valid UTF-8,
    /// so this is [`TmuxText`] rather than `str`.
    #[must_use]
    pub fn name(&self) -> &TmuxText {
        self.info.session_name()
    }

    /// Return the session's working directory.
    #[must_use]
    pub fn path(&self) -> &TmuxText {
        self.info.session_path()
    }

    /// Return how many windows the session contains.
    #[must_use]
    pub fn window_count(&self) -> u32 {
        *self.info.session_windows()
    }

    /// Return how many clients are attached to the session.
    #[must_use]
    pub fn attached_client_count(&self) -> u32 {
        *self.info.session_attached()
    }

    /// Report whether any client is attached.
    ///
    /// A session tmux has never reported on is treated as unattached.
    #[must_use]
    pub fn is_attached(&self) -> bool {
        self.attached_client_count() > 0
    }

    /// Return when the session was created, as a Unix timestamp.
    #[must_use]
    pub fn created(&self) -> i64 {
        *self.info.session_created()
    }

    /// Return when a client last attached, as a Unix timestamp.
    ///
    /// This is `None` for a session that has never been attached, which is the
    /// ordinary state for one started with `new-session -d`.
    #[must_use]
    pub fn last_attached(&self) -> Option<i64> {
        self.info.session_last_attached().copied().available()
    }

    /// Return the identity of the server this session belongs to.
    #[must_use]
    pub(crate) fn server_identity(&self) -> &ServerIdentity {
        self.core.configuration().identity()
    }

    /// List the windows linked into this session, in tmux's own order.
    ///
    /// This is the lenient form; use [`Session::windows`] when the reason
    /// for an empty result matters.
    pub async fn windows_or_empty(&self) -> Vec<Window> {
        self.windows().await.unwrap_or_else(|error| {
            listing::trace_discarded("list-windows", &error);
            Vec::new()
        })
    }

    /// List the windows linked into this session, preserving any failure.
    ///
    /// A window linked into other sessions appears here once, under this
    /// session's own index for it.
    ///
    /// # Errors
    ///
    /// Returns an error when the list command cannot run, or when its output
    /// cannot be decoded into snapshots.
    pub async fn windows(&self) -> Result<Vec<Window>, Error> {
        let target = self.id().to_string();
        let projections =
            listing::windows(&self.core, listing::Scope::Target(&target), None).await?;

        Ok(projections
            .into_iter()
            .map(|projection| Window::new(Arc::clone(&self.core), projection))
            .collect())
    }

    /// The windows under this session that a matcher accepts.
    ///
    /// Empty when the listing fails, which suits a status line. Use
    /// [`Self::search_windows`] when the difference matters.
    ///
    /// Filtering happens here rather than in tmux. A [`crate::query::FilterExpr`]
    /// is built to stay compilable to a tmux `-f` predicate, so pushing one
    /// down later would change what this costs and not what it answers.
    #[cfg(feature = "query")]
    #[must_use]
    pub async fn search_windows_or_empty<M: crate::query::Matcher<Window>>(
        &self,
        matcher: M,
    ) -> Vec<Window> {
        self.search_windows(matcher).await.unwrap_or_else(|error| {
            listing::trace_discarded("list-windows", &error);
            Vec::new()
        })
    }

    /// The windows under this session that a matcher accepts, reporting why
    /// if the listing fails.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the listing.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// use libtmux::query::Filterable as _;
    ///
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.server().new_session("searched").await?;
    /// session.new_window("build").await?;
    ///
    /// let fields = libtmux::Window::filter_fields();
    /// let found = session.search_windows(&fields.window_name.eq("build")).await?;
    /// assert_eq!(found.len(), 1);
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "query")]
    pub async fn search_windows<M: crate::query::Matcher<Window>>(
        &self,
        matcher: M,
    ) -> Result<Vec<Window>, Error> {
        use crate::query::QueryIteratorExt as _;

        let all = self.windows().await?;
        Ok(all.iter().matching(matcher).cloned().collect())
    }

    /// Move to the next window, and return it.
    ///
    /// `None` when there is no next window, which a session holding one
    /// window never has. That is an ordinary state rather than a failure, so
    /// it is reported as absence; an error means tmux could not be reached or
    /// refused the move for some other reason.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the move.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.server().new_session("moving").await?;
    ///
    /// // One window, so there is nowhere to go and nothing broke.
    /// assert!(session.next_window().await?.is_none());
    ///
    /// session.new_window("second").await?;
    /// assert!(session.next_window().await?.is_some());
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn next_window(&self) -> Result<Option<Window>, Error> {
        self.step("next-window").await
    }

    /// Move to the previous window, and return it.
    ///
    /// `None` when there is none; see [`Self::next_window`].
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the move.
    pub async fn previous_window(&self) -> Result<Option<Window>, Error> {
        self.step("previous-window").await
    }

    /// Move to the window that was active before this one, and return it.
    ///
    /// `None` when nothing else has been active yet; see
    /// [`Self::next_window`].
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the move.
    pub async fn last_window(&self) -> Result<Option<Window>, Error> {
        self.step("last-window").await
    }

    /// Run one window move and report what became active.
    async fn step(&self, command: &'static str) -> Result<Option<Window>, Error> {
        let target = self.id().to_string();
        let result = self
            .core
            .execute(Command::new(command).arg("-t").arg(&target))
            .await?;
        if !result.success() {
            let stderr = result.stderr_lossy();
            if crate::error::NO_SUCH_NEIGHBOUR.contains(&stderr.trim_end()) {
                return Ok(None);
            }
            return Err(Error::from_refused_result(
                command,
                &result,
                Some(OsStr::new(&target)),
            ));
        }

        let active = self
            .active_window()
            .await
            .map_err(|error| error.after_effect(command))?;
        active
            .ok_or_else(|| {
                Error::ObjectGone {
                    kind: ObjectKind::Session,
                    id: target,
                }
                .after_effect(command)
            })
            .map(Some)
    }
    /// Return the session's active window.
    ///
    /// # Errors
    ///
    /// Returns an error when the window listing fails. A session always has an
    /// active window, so `Ok(None)` means the session disappeared between the
    /// snapshot and this call.
    pub async fn active_window(&self) -> Result<Option<Window>, Error> {
        Ok(self.windows().await?.into_iter().find(Window::is_active))
    }

    /// List every pane in this session, in tmux's own order.
    ///
    /// This is the lenient form; use [`Session::panes`] when the reason
    /// for an empty result matters.
    pub async fn panes_or_empty(&self) -> Vec<Pane> {
        self.panes().await.unwrap_or_else(|error| {
            listing::trace_discarded("list-panes", &error);
            Vec::new()
        })
    }

    /// List every pane in this session, preserving any failure.
    ///
    /// # Errors
    ///
    /// Returns an error when the list command cannot run, or when its output
    /// cannot be decoded into snapshots.
    pub async fn panes(&self) -> Result<Vec<Pane>, Error> {
        let target = self.id().to_string();
        let projections =
            listing::panes(&self.core, listing::Scope::SessionTarget(&target), None).await?;

        Ok(projections
            .into_iter()
            .map(|projection| Pane::new(Arc::clone(&self.core), projection))
            .collect())
    }
    /// Replace this handle's snapshot with the session's current state.
    ///
    /// Only the receiver changes. Clones keep the snapshot they were taken
    /// with, because each handle owns its own.
    ///
    /// # Errors
    ///
    /// Returns [`Error::ObjectGone`] when the session no longer exists, or a
    /// listing error when tmux could not be read.
    pub async fn refresh(&mut self) -> Result<&mut Self, Error> {
        let info = listing::sessions(&self.core, None)
            .await?
            .into_iter()
            .find(|info| info.session_id() == self.id())
            .ok_or_else(|| Error::ObjectGone {
                kind: ObjectKind::Session,
                id: self.id().to_string(),
            })?;

        self.info = info;
        Ok(self)
    }

    /// Return a new handle holding the session's current state.
    ///
    /// # Errors
    ///
    /// Returns [`Error::ObjectGone`] when the session no longer exists, or a
    /// listing error when tmux could not be read.
    pub async fn refreshed(&self) -> Result<Self, Error> {
        let mut refreshed = self.clone();
        refreshed.refresh().await?;
        Ok(refreshed)
    }

    /// Create a window in this session and return it.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the command or its output cannot be
    /// decoded.
    /// tmux expands the name as a format before it checks it, so `#(command)`
    /// in one runs a shell command. See [the crate documentation][crate#a-name-reaches-tmux-as-a-format]
    /// before passing text a caller supplied.
    pub async fn new_window(&self, options: impl Into<NewWindowOptions>) -> Result<Window, Error> {
        let options = options.into();
        let session = self.id().to_string();
        let projection =
            listing::create_window(&self.core, |format| options.into_command(&session, format))
                .await?;

        Ok(Window::new(Arc::clone(&self.core), projection))
    }

    /// Rename the session and update this handle.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the name, which includes one that
    /// is empty or already taken.
    /// tmux expands the name as a format before it checks it, so `#(command)`
    /// in one runs a shell command. See [the crate documentation][crate#a-name-reaches-tmux-as-a-format]
    /// before passing text a caller supplied.
    pub async fn rename(&mut self, name: impl Into<OsString>) -> Result<&mut Self, Error> {
        listing::mutate(
            &self.core,
            "rename-session",
            Command::new("rename-session")
                .arg("-t")
                .arg(self.id().to_string())
                .arg("--")
                .arg(name.into()),
        )
        .await?;

        self.refresh()
            .await
            .map_err(|error| error.after_effect("rename-session"))?;
        Ok(self)
    }

    /// Kill the session.
    ///
    /// This consumes the handle: every other handle to the same session is now
    /// stale, and refreshing one reports [`Error::ObjectGone`].
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the command.
    pub async fn kill(self) -> Result<(), Error> {
        listing::mutate(
            &self.core,
            "kill-session",
            Command::new("kill-session")
                .arg("-t")
                .arg(self.id().to_string()),
        )
        .await
    }

    /// Run a raw tmux command against this session.
    ///
    /// The escape hatch for anything this crate does not wrap. `-t` is placed
    /// after the subcommand for you, because tmux stops reading flags at the
    /// first positional: a target appended after one is taken as text, and the
    /// command then succeeds having acted on something else.
    ///
    /// A non-zero exit status comes back in the [`CommandResult`] rather than
    /// as an error, the same as [`crate::Server::cmd`].
    ///
    /// # Errors
    ///
    /// Returns an error when the process cannot be started, captured, or
    /// awaited.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.server().new_session("raw").await?;
    ///
    /// let result = session
    ///     .cmd(libtmux::Command::new("display-message").arg("-p").arg("#{session_name}"))
    ///     .await?;
    /// assert_eq!(result.stdout_lossy().trim(), "raw");
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn cmd(&self, command: Command) -> Result<CommandResult, Error> {
        self.core
            .execute(command.targeting(self.id().to_string()))
            .await
    }

    /// Expand a tmux format string in this session's context.
    ///
    /// This returns `display-message` output instead of showing it in front of
    /// a person with [`Self::display`]. See [`crate::Server::format`] for the
    /// shell boundary around command and recursive formats.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the format.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.server().new_session("shown").await?;
    ///
    /// let expanded = session.format("#{session_name}").await?;
    /// assert_eq!(expanded.to_string_lossy(), "shown");
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn format(&self, template: &str) -> Result<TmuxText, Error> {
        let result = self
            .cmd(
                Command::new("display-message")
                    .arg("-p")
                    .arg(OsString::from(template)),
            )
            .await?;
        if !result.success() {
            return Err(Error::from_refused_result(
                "display-message",
                &result,
                Some(OsStr::new(&self.id().to_string())),
            ));
        }

        // `-p` ends its output with a newline that frames it rather than
        // belonging to the expansion.
        let stdout = result.stdout();
        Ok(TmuxText::from(
            stdout.strip_suffix(b"\n").unwrap_or(stdout).to_vec(),
        ))
    }

    /// Show a message on the clients viewing this session.
    ///
    /// The showing half of tmux's `display-message`. Nothing is returned
    /// because nothing is read: use [`Self::format`] to get text back.
    /// Succeeds when nobody is watching, having shown it to nobody.
    /// Like [`Self::format`], this interprets the message as a tmux format;
    /// command and recursive formats can run shell commands.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the message.
    pub async fn display(&self, message: &str) -> Result<(), Error> {
        let result = self
            .cmd(Command::new("display-message").arg(OsString::from(message)))
            .await?;
        if result.success() {
            return Ok(());
        }

        Err(Error::from_refused_result(
            "display-message",
            &result,
            Some(OsStr::new(&self.id().to_string())),
        ))
    }

    /// Lock every client attached to this session.
    ///
    /// tmux runs the `lock-command` to lock, so what a locked client shows is
    /// that command's business rather than this one's.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the lock.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.server().new_session("locked").await?;
    ///
    /// // Locking a session nobody is attached to is accepted and does nothing.
    /// session.lock().await?;
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn lock(&self) -> Result<(), Error> {
        listing::mutate(
            &self.core,
            "lock-session",
            Command::new("lock-session")
                .arg("-t")
                .arg(self.id().to_string()),
        )
        .await
    }

    /// Detach every client attached to this session.
    ///
    /// Succeeds when no client was attached. tmux reports that as a failure,
    /// but the state this asks for -- nobody attached to this session -- is
    /// already true, and a caller that has to tell "detached them" from
    /// "there was nobody" can compare [`crate::Server::clients_or_empty`] before and
    /// after.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached or refuses the detach for
    /// any other reason.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// let guard = libtmux::test::TestServer::new().await?;
    /// let session = guard.server().new_session("busy").await?;
    ///
    /// // Nothing is attached in a headless fixture, so this is a no-op.
    /// session.detach_clients().await?;
    ///
    /// guard.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn detach_clients(&self) -> Result<(), Error> {
        let target = self.id().to_string();
        let result = self
            .core
            .execute(Command::new("detach-client").arg("-s").arg(&target))
            .await?;
        if result.success() {
            return Ok(());
        }

        // tmux says this when it has no client to act on, which is the state
        // the caller was asking for.
        let stderr = result.stderr_lossy();
        if stderr.trim_end() == crate::error::NO_CURRENT_CLIENT {
            return Ok(());
        }

        Err(Error::from_refused_result(
            "detach-client",
            &result,
            Some(OsStr::new(&target)),
        ))
    }

    /// Create a window, run an operation with it, then kill it.
    ///
    /// Once this future is polled, the scope owns creation and cleanup.
    /// Cancellation or unwinding can let an in-flight creation finish, but a
    /// window whose creation yields a handle is killed while the Tokio runtime
    /// remains active. Ordinary handle `Drop` remains non-destructive.
    ///
    /// Setup and teardown failures convert into the operation's own error
    /// type, so a caller writes one `?` rather than unwrapping twice. When
    /// both the operation and cleanup fail, the cleanup error is returned as
    /// [`Error::AfterEffect`], because tmux had already accepted the scope's
    /// creation; the operation error is discarded. When the operation fails
    /// and cleanup succeeds, its generic error is returned unchanged: the
    /// scope cannot certify replay safety for arbitrary callback work.
    /// A canceled caller cannot receive a cleanup error, so tracing is its
    /// only report.
    ///
    /// # Errors
    ///
    /// Returns the operation's error, or a converted [`Error`] when the
    /// window could not be created or could not be killed after creation.
    pub async fn with_window<T, E>(
        &self,
        options: impl Into<NewWindowOptions>,
        operation: impl AsyncFnOnce(&Window) -> Result<T, E>,
    ) -> Result<T, E>
    where
        E: From<Error>,
    {
        let session = self.clone();
        let options = options.into();
        scoped::run(
            "with-window",
            async move { session.new_window(options).await },
            Window::kill,
            operation,
        )
        .await
    }

    /// Find this session's window with the given name.
    ///
    /// Names are compared as bytes. A session can hold several windows with
    /// one name, in which case the first in tmux's order is returned.
    ///
    /// # Errors
    ///
    /// Returns an error when the window listing fails.
    pub async fn window(&self, name: impl AsRef<[u8]>) -> Result<Option<Window>, Error> {
        let name = name.as_ref();

        Ok(self
            .windows()
            .await?
            .into_iter()
            .find(|window| window.name() == name))
    }

    /// Find this session's window at the given index.
    ///
    /// # Errors
    ///
    /// Returns an error when the window listing fails.
    pub async fn window_at(&self, index: i32) -> Result<Option<Window>, Error> {
        // An index is an integer, so tmux can match it and return one row.
        let target = self.id().to_string();
        let projections = listing::windows(
            &self.core,
            listing::Scope::Target(&target),
            Some(&index.predicate("window_index")),
        )
        .await?;

        Ok(projections
            .into_iter()
            .next()
            .map(|projection| Window::new(Arc::clone(&self.core), projection)))
    }
}

/// Sessions compare by server endpoint and session id.
///
/// Equal-looking ids on different servers are different sessions, and two
/// handles for the same session remain equal even when their snapshots were
/// taken at different times.
impl PartialEq for Session {
    fn eq(&self, other: &Self) -> bool {
        self.server_identity() == other.server_identity() && self.id() == other.id()
    }
}

impl Eq for Session {}

impl Hash for Session {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.server_identity().hash(state);
        self.id().hash(state);
    }
}

/// Renders identity only, never snapshot text.
///
/// Session names can carry arbitrary bytes from the user's environment, so
/// they stay out of diagnostics.
impl fmt::Debug for Session {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Session")
            .field("id", &self.id())
            .finish_non_exhaustive()
    }
}

/// Filtering a session uses the same handles as the snapshot beneath it.
///
/// Matching and validation delegate to that snapshot, so an expression can
/// only name fields the catalog knows. The companion is re-parameterized to
/// [`Session`] so the type a listing returns is the type an expression
/// filters.
#[cfg(feature = "query")]
impl Filterable for Session {
    type Fields = SessionFields<Self>;

    const FILTER_TARGET: &'static str = <SessionInfo as Filterable>::FILTER_TARGET;

    fn filter_fields() -> Self::Fields {
        Self::Fields::for_target(Self::FILTER_TARGET)
    }

    fn __filter_matches(&self, predicate: &crate::query::__private::Predicate) -> bool {
        self.info.__filter_matches(predicate)
    }

    fn __filter_validate(
        predicate: &crate::query::__private::Predicate,
    ) -> Result<(), crate::query::FilterExpressionError> {
        <SessionInfo as Filterable>::__filter_validate(predicate)
    }
}

#[cfg(feature = "query")]
impl FilterSchema for Session {
    fn __filter_schema() -> crate::query::__private::FilterSchemaDescriptor {
        <SessionInfo as FilterSchema>::__filter_schema()
    }
}

/// Options for creating a window in a session.
///
/// A bare name is accepted wherever this is: `session.new_window("editor")`.
///
/// # Examples
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
/// # runtime.block_on(async {
/// use libtmux::NewWindowOptions;
///
/// let guard = libtmux::test::TestServer::new().await?;
/// let session = guard.server().new_session("work").await?;
///
/// let window = session
///     .new_window(NewWindowOptions::new("editor").environment("EDITOR", "vi"))
///     .await?;
/// assert_eq!(window.name().to_string_lossy(), "editor");
///
/// // A bare name works too, because `new_window` takes anything that converts.
/// session.new_window("logs").await?;
/// assert_eq!(session.windows().await?.len(), 3);
///
/// guard.shutdown().await?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// # })?;
/// # Ok(())
/// # }
/// ```
#[must_use = "options describe a window but do not create one"]
#[derive(Clone)]
pub struct NewWindowOptions {
    name: Option<OsString>,
    start_directory: Option<std::path::PathBuf>,
    command: Option<OsString>,
    index: Option<i32>,
    placement: Option<WindowPlacement>,
    environment: Vec<(OsString, OsString)>,
    replace_existing: bool,
    select: bool,
}

impl fmt::Debug for NewWindowOptions {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("NewWindowOptions")
            .field("has_name", &self.name.is_some())
            .field("has_start_directory", &self.start_directory.is_some())
            .field("has_command", &self.command.is_some())
            .field("index", &self.index)
            .field("placement", &self.placement)
            .field("environment_count", &self.environment.len())
            .field("replace_existing", &self.replace_existing)
            .field("select", &self.select)
            .finish()
    }
}

/// Where a new window goes, relative to the index it is given.
///
/// Without one, tmux takes the first free index.
///
/// # Examples
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
/// # runtime.block_on(async {
/// use libtmux::{NewWindowOptions, WindowPlacement};
///
/// let guard = libtmux::test::TestServer::new().await?;
/// let session = guard.server().new_session("work").await?;
/// let first = session.active_window().await?.expect("a session has a window");
///
/// // Inserting before an index shifts the windows already at or after it, so
/// // the index a caller holds is only good until the next insert.
/// let inserted = session
///     .new_window(
///         NewWindowOptions::new("inserted")
///             .index(first.index())
///             .placement(WindowPlacement::Before),
///     )
///     .await?;
/// assert!(inserted.index() <= first.index());
///
/// guard.shutdown().await?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// # })?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum WindowPlacement {
    /// Insert before the target index, shifting later windows along.
    Before,
    /// Insert after it.
    After,
}

impl NewWindowOptions {
    /// Describe a window with no name, letting tmux choose one.
    pub const fn unnamed() -> Self {
        Self {
            name: None,
            start_directory: None,
            command: None,
            index: None,
            placement: None,
            environment: Vec::new(),
            replace_existing: false,
            select: false,
        }
    }

    /// Describe a window with the given name.
    pub fn new(name: impl Into<OsString>) -> Self {
        Self {
            name: Some(name.into()),
            ..Self::unnamed()
        }
    }

    /// Set the window's working directory.
    ///
    /// tmux expands this as a format, so [`crate::escape_format`] belongs
    /// around text a program did not write.
    pub fn start_directory(mut self, directory: impl Into<std::path::PathBuf>) -> Self {
        self.start_directory = Some(directory.into());
        self
    }

    /// Run a command instead of the default shell.
    pub fn command(mut self, command: impl Into<OsString>) -> Self {
        self.command = Some(command.into());
        self
    }

    /// Place the window at a window index rather than the first free one.
    pub const fn index(mut self, index: i32) -> Self {
        self.index = Some(index);
        self
    }

    /// Insert relative to the index rather than at it.
    ///
    /// Without an index this is relative to the session's current window,
    /// which is what tmux does.
    pub const fn placement(mut self, placement: WindowPlacement) -> Self {
        self.placement = Some(placement);
        self
    }

    /// Set an environment variable for the process the new window starts.
    ///
    /// Call this more than once for more than one variable. tmux applies
    /// these to the new process only, not to the session.
    pub fn environment(mut self, name: impl Into<OsString>, value: impl Into<OsString>) -> Self {
        self.environment.push((name.into(), value.into()));
        self
    }

    /// Replace whatever already occupies the target index.
    ///
    /// Without this, an index that is taken is an error rather than a silent
    /// overwrite.
    pub const fn replace_existing(mut self) -> Self {
        self.replace_existing = true;
        self
    }

    /// Make the new window active in its session.
    ///
    /// Creation does not select by default, so building a workspace does not
    /// leave the session pointing at whichever window happened to be last.
    pub const fn select(mut self) -> Self {
        self.select = true;
        self
    }

    /// Lower these options into a `new-window` command for one session.
    ///
    /// `print_format` is placed with the other flags because tmux stops
    /// parsing flags at the first positional, and the shell command is one.
    fn into_command(self, session: &str, print_format: &str) -> Command {
        let target = self
            .index
            .map_or_else(|| session.to_owned(), |index| format!("{session}:{index}"));
        let mut command = Command::new("new-window")
            .arg("-P")
            .arg("-F")
            .arg(print_format)
            .arg("-t")
            .arg(target);
        if !self.select {
            command = command.arg("-d");
        }
        match self.placement {
            Some(WindowPlacement::Before) => command = command.arg("-b"),
            Some(WindowPlacement::After) => command = command.arg("-a"),
            None => {}
        }
        if self.replace_existing {
            command = command.arg("-k");
        }
        if let Some(name) = self.name {
            command = command.arg("-n").arg(name);
        }
        if let Some(directory) = self.start_directory {
            command = command.arg("-c").arg(directory.into_os_string());
        }
        for (name, value) in self.environment {
            command = command
                .arg("-e")
                .sensitive_arg(crate::window::assignment(&name, &value));
        }
        if let Some(shell_command) = self.command {
            command = command.sensitive_arg(shell_command);
        }
        command
    }
}

impl<T: Into<OsString>> From<T> for NewWindowOptions {
    fn from(name: T) -> Self {
        Self::new(name)
    }
}

/// Renders the session id, which is what a tmux target wants.
impl fmt::Display for Session {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{}", self.id())
    }
}

#[cfg(test)]
mod option_tests {
    use super::NewWindowOptions;

    #[test]
    fn new_window_options_redact_process_inputs() {
        let secret = "sentinel-window-process";
        let options = NewWindowOptions::new("work")
            .environment("TOKEN", secret)
            .command(secret);
        assert!(!format!("{options:?}").contains(secret));

        let summary = options.into_command("$1", "#{window_id}").summary();
        assert_eq!(summary.sensitive_argument_count(), 2);
        assert!(!summary.to_string().contains(secret));
    }
}