cctop 0.28.0

//! Handing a tab's agent to rmux, so it outlives the cctop that started it.
//!
//! A pane normally runs its agent on a pty [`shim::host`](crate::shim::host)
//! owns, which means the agent's life is cctop's life: quit, and the agent goes
//! with it. That is the wrong bargain for a coding session. Nothing about
//! watching sessions should require staying in the monitor.
//!
//! So the pane runs `rmux new-session` instead of the agent, and the agent runs
//! inside the rmux server. What cctop hosts is then only the rmux *client* —
//! closing the pane detaches, quitting cctop detaches, and the agent notices
//! neither. Everything else is unchanged: it is still a process on a pty cctop
//! can draw and type into, so [`attach`](crate::attach) and the pane machinery
//! need to know nothing about any of this.
//!
//! Reattaching falls out of the same command. `new-session -A` attaches to the
//! session if it exists and creates it otherwise, so reopening a tab is the same
//! call as opening it, and the agent is found exactly where it was left —
//! scrollback and all.

use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::process::Command;

/// Prefix on every rmux session cctop creates.
///
/// A namespace, so `cctop-*` is unambiguously ours and a user's own sessions are
/// never adopted, reattached to, or killed by anything here.
const PREFIX: &str = "cctop";

/// The multiplexer cctop drives.
///
/// One name in one place, so a second hard-coded `"rmux"` cannot drift from it.
/// cctop used to speak tmux's command surface and choose between the two with
/// `CCTOP_MUX`; rmux reimplements that surface, so the commands here —
/// `new-session -A`, `set-option`, `list-panes -F`, `kill-session` — are the
/// ones tmux always took. What is no longer optional is the daemon they reach.
///
/// The cost of dropping the choice, said plainly because it lands on upgrade:
/// the two keep separate daemons and separate sessions, so agents still running
/// under a tmux server are still running and cctop simply stops being able to
/// see them. `tmux attach -t cctop-…` reaches them, and nothing here kills one.
pub const BIN: &str = "rmux";

/// How long one exchange with the daemon may take before cctop gives up.
///
/// Not the SDK's own 5s default. Shares used to be minted with a tunnel rmux
/// raised itself, which answered only once an ssh session to localhost.run was
/// up, and at 5s the page was told "could not open that terminal" while the
/// daemon went on to finish a share nobody was waiting for any more. The daemon
/// no longer dials anything for cctop (see [`share_link_with`]), so a mint is
/// quick again; the ceiling stays generous because a daemon busy with a dozen
/// agents is slow to answer, and giving up early costs more than waiting.
const DAEMON_DEADLINE: std::time::Duration = std::time::Duration::from_secs(30);

/// Run one piece of SDK work against the local daemon and wait for it.
///
/// The SDK is async and cctop is not. Everything here is one short exchange
/// with a daemon on a unix socket, so a current-thread runtime built for the
/// call is the whole of what "async" needs to mean at this boundary — no
/// runtime is kept, and nothing above this function learns that one existed.
fn on_daemon<T, F, Fut>(work: F) -> Result<T, String>
where
    F: FnOnce(rmux_sdk::Rmux) -> Fut,
    Fut: std::future::Future<Output = rmux_sdk::Result<T>>,
{
    let runtime = tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .map_err(|error| format!("could not start a runtime for rmux: {error}"))?;
    runtime.block_on(async move {
        // `connect_or_start` rather than `connect`: the daemon is started by
        // whichever of these runs first, and a cctop that only ever asks
        // questions should still get answers.
        let rmux = rmux_sdk::Rmux::builder()
            .default_timeout(DAEMON_DEADLINE)
            .connect_or_start()
            .await
            .map_err(|error| format!("{error}"))?;
        work(rmux).await.map_err(|error| format!("{error}"))
    })
}

/// Whether the multiplexer can be used at all.
///
/// Only that the binary exists: a server does not have to be running, since
/// `new-session` starts one. This is checked per launch rather than cached —
/// installing rmux while cctop runs should not require restarting it, and the
/// cost is one `rmux -V` against a launch that spawns a terminal anyway.
pub fn available() -> bool {
    Command::new(BIN)
        .arg("-V")
        .output()
        .is_ok_and(|out| out.status.success())
}

/// A way to put rmux on this machine, when one can be found.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Install {
    /// What to call the package manager in the offer, so the user is agreeing
    /// to something they recognise rather than to "install rmux" in the
    /// abstract.
    pub manager: &'static str,
    /// The command to run, ready for a pane.
    pub argv: Vec<String>,
}

impl Install {
    /// The command as it would be typed, for the modal to show.
    ///
    /// The argv is `sh -c <script>`, so the interesting part is the last word
    /// and printing the whole vector would only bury it.
    pub fn shown(&self) -> &str {
        self.argv.last().map(String::as_str).unwrap_or_default()
    }
}

/// The ways rmux can be put on this machine, best first: what to call each one
/// in the offer, the command that has to exist for it to be possible, and the
/// command that does it.
///
/// All three are root-free, which is why there is no `sudo` anywhere below.
/// rmux also ships through apt and dnf, and both want a signed repository added
/// first — three commands, a key, and a distribution name to get right. cctop
/// offering to run that on someone's machine is offering to misconfigure a
/// package source; the routes here install one binary and are undone by
/// deleting it.
///
/// Homebrew leads because a machine that has it is a machine whose owner
/// administers it that way. cargo is next because a cctop installed by cargo —
/// which is most of them — already has it, and it builds the same version this
/// was written against. The install script is last because it is the one that
/// needs nothing, which also makes it the one with least to recommend it.
const MANAGERS: &[(&str, &str, &str)] = &[
    ("Homebrew", "brew", "brew install rmux"),
    ("cargo", "cargo", "cargo install rmux --locked"),
    (
        "rmux.io",
        "curl",
        "curl -fsSL https://rmux.io/install.sh | sh",
    ),
];

/// How cctop would install rmux here, if it can work out how.
///
/// `None` is the honest answer for a machine with none of the three. Offering
/// an install that cannot run is worse than the silent fallback it would
/// replace, since the user has then been told rmux is one keypress away and
/// watched the keypress fail.
///
/// Nothing here runs anything: it only decides what *would* be run, so the
/// decision can be shown to the user before any of it happens.
pub fn installer() -> Option<Install> {
    let (manager, _, command) = MANAGERS
        .iter()
        .find(|(_, needs, _)| crate::shim::is_command(needs))?;
    Some(Install {
        manager,
        // A script rather than an argv because the last entry is a pipeline,
        // and because a pane runs this on a pty where a shell is what reads it.
        argv: vec!["sh".to_string(), "-c".to_string(), command.to_string()],
    })
}

/// The command that puts `argv` in the rmux session called `name`, attaching to
/// it instead if it is already there.
///
/// `-c` sets the working directory for a session being created and is ignored
/// for one being attached to, which is the behaviour wanted in both cases: a new
/// agent starts in its project, and an existing one is not moved.
pub fn attach_or_create(argv: &[String], name: &str, cwd: Option<&Path>) -> Vec<String> {
    let mut out = vec![
        BIN.to_string(),
        "new-session".to_string(),
        "-A".to_string(),
        "-s".to_string(),
        name.to_string(),
    ];
    if let Some(dir) = cwd.filter(|d| d.is_dir()) {
        out.push("-c".into());
        out.push(dir.to_string_lossy().into_owned());
    }
    // `--` so an agent's own flags are never read as rmux's.
    out.push("--".into());
    out.extend(argv.iter().cloned());
    out
}

/// How many lines of an agent's output a cctop-owned rmux session keeps.
///
/// rmux reports no `history-limit` until one is set, so what a pane keeps
/// unasked is rmux's business and not something to rely on — tmux's answer was
/// 2000, which is a few minutes of a working agent: a pane you can scroll but
/// not scroll *back* to anything. Naming a number is what makes the scrollback
/// a property of cctop's sessions rather than of whatever the daemon defaults
/// to this release. These lines cost nothing until they exist and are gone with
/// the session.
const HISTORY_LINES: &str = "50000";

/// Create the session before the client that attaches to it, so the agent's
/// pane is made with cctop's options already set.
///
/// This exists for `history-limit` alone. A pane's scrollback is allocated when
/// the pane is *made* and never resized, so unlike `mouse` or `status` it cannot
/// be set on a session already running the agent — [`quiet`] and [`mouse`] fix a
/// session after the fact, and this is the one thing that has to happen before
/// it. Hence the detour: the session is created holding a placeholder, the
/// options are set on it, and the agent goes into a second window made after
/// they were, which is what makes its pane new enough to have read them. Then
/// the placeholder window goes, leaving the one-window session everything else
/// here expects. `respawn-pane` looks like the shorter way and is not — it
/// replaces the process and keeps the pane, scrollback and all.
///
/// Best effort in the strongest sense — every failure leaves the session absent
/// or removed, and [`attach_or_create`] then creates it exactly as it did
/// before, with rmux's own defaults. Nothing here can cost a launch, and a
/// session that already exists is left alone: it is someone's running agent, and
/// this would take its window out from under it.
pub fn prepare(argv: &[String], name: &str, cwd: Option<&Path>) {
    crate::elog::event(
        "rmux",
        "prepare",
        serde_json::json!({ "session": name, "cmd": argv.join(" ") }),
    );
    if exists(name) {
        return;
    }
    let dir = cwd.filter(|d| d.is_dir()).map(|d| d.to_string_lossy());
    let mut create: Vec<String> = ["new-session", "-d", "-P", "-F", "#{window_id}", "-s", name]
        .into_iter()
        .map(str::to_string)
        .collect();
    if let Some(dir) = &dir {
        create.extend(["-c", dir].map(str::to_string));
    }
    // Set on the session rather than on the command, because the command is not
    // what runs it: a placeholder window does, and the agent is typed into that
    // window afterwards. Everything the agent is started with therefore has to
    // be in the session's own environment, which also covers the detached
    // launch that hands rmux the agent as the command.
    for (var, value) in crate::opencode::launch_env(argv) {
        create.push("-e".into());
        create.push(format!("{var}={value}"));
    }
    // A window running nothing is a session that ends before it can be
    // configured, so the placeholder has to outlive the two commands after it.
    // The day is only how long an unreachable failure would sit around.
    create.extend(["--", "sleep", "86400"].map(str::to_string));
    let Ok(out) = Command::new(BIN).args(&create).output() else {
        return;
    };
    if !out.status.success() {
        return;
    }
    let placeholder = String::from_utf8_lossy(&out.stdout).trim().to_string();

    // One invocation for the three: `;` is rmux's own separator between
    // commands, which is why these need no shell to be read as three.
    let _ = Command::new(BIN)
        .args(["set-option", "-t", name, "history-limit", HISTORY_LINES])
        .args([";", "set-option", "-t", name, "mouse", "on"])
        .args([";", "set-option", "-t", name, "status", "off"])
        // Several cctops may hold a client on this session at once — that is
        // what sharing tabs means. Left at rmux's default the window is sized to
        // the *smallest* of them, so one cctop in a narrow terminal cramps the
        // agent for everybody. `latest` sizes it to whichever client is being
        // used, which is the one whose window is worth fitting.
        .args([";", "set-option", "-t", name, "window-size", "latest"])
        .output();

    // Current, not background: this is the window the client is about to attach
    // to, and the placeholder is on its way out.
    let mut window = vec!["new-window", "-t", name];
    if let Some(dir) = &dir {
        window.extend(["-c", dir]);
    }
    window.push("--");
    window.extend(argv.iter().map(String::as_str));
    let made = Command::new(BIN)
        .args(&window)
        .output()
        .is_ok_and(|out| out.status.success());
    if !made {
        // The session exists but holds a placeholder where the agent should be,
        // and `new-session -A` would happily attach to that. Removing it puts
        // the launch back on the path it would have taken had none of this run.
        let _ = kill(name);
        return;
    }
    // Last, so the session is never briefly windowless — killing its only window
    // is killing the session, and with it the agent just put in the other one.
    let _ = Command::new(BIN)
        .args(["kill-window", "-t", &placeholder])
        .output();
}

/// Start `argv` in a new session called `name` with no client on it at all.
///
/// For a tab this cctop stands for without watching — see
/// `ui::tabs::Shared` — whose agent is being replaced. The
/// launch path cannot be borrowed for it: that starts a client, and a client on
/// a tab nobody here is looking at is the thing sharing tabs exists to avoid.
///
/// [`prepare`] first, so the session has cctop's options from its first pane
/// just as a launched one does; it is best effort and may leave nothing
/// behind, in which case the session is created the plain way.
pub fn start_detached(argv: &[String], name: &str, cwd: Option<&Path>) -> Result<(), String> {
    prepare(argv, name, cwd);
    if exists(name) {
        return Ok(());
    }
    let mut create = vec![
        "new-session".to_string(),
        "-d".to_string(),
        "-s".to_string(),
        name.to_string(),
    ];
    if let Some(dir) = cwd.filter(|d| d.is_dir()) {
        create.push("-c".into());
        create.push(dir.to_string_lossy().into_owned());
    }
    create.push("--".into());
    create.extend(argv.iter().cloned());
    let out = Command::new(BIN)
        .args(&create)
        .output()
        .map_err(|e| format!("rmux: {e}"))?;
    if out.status.success() {
        return Ok(());
    }
    Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
}

/// The command that attaches to an existing rmux session and nothing else.
///
/// Distinct from [`attach_or_create`] so that picking an agent from the
/// launcher which has since ended reports that, rather than silently creating
/// an empty session wearing its name.
pub fn attach(name: &str) -> Vec<String> {
    vec![
        BIN.to_string(),
        "attach-session".to_string(),
        "-t".to_string(),
        format!("={name}"),
    ]
}

/// One browser share of a multiplexer session.
#[derive(Clone)]
pub struct Share {
    /// The link that can type into the agent. A shell credential, and named
    /// that way so nothing here hands it out by accident.
    ///
    /// An `Option` because rmux mints one per role and a `--spectator-only`
    /// share has none — [`web_share`] refuses that rather than reaching for the
    /// read-only link, which is a different thing wearing the same shape.
    pub operator: Option<String>,
    /// The pairing code the browser asks for after the link, absent under
    /// `--no-pin`. Useless without the link and useless on its own, which is why
    /// it is safe to put on the status line while the link goes to the clipboard.
    pub pin: Option<String>,
}

/// Open `name`'s terminal to a browser.
///
/// `public` is an origin that reaches the daemon's share listener from off
/// this machine, which rmux writes into the link's fragment as the endpoint
/// the browser opens its socket to. Without one the endpoint is this
/// machine's loopback: correct, and reachable only from a browser already on
/// it. [`share_link_with`] decides which, and where `public` comes from.
///
/// Asked over the daemon's own IPC rather than by running `rmux web-share` and
/// reading its output. That is not a tidiness: the CLI prints the operator link
/// on stderr and the spectator link on stdout, the two are the same shape, and
/// the *stream* is the only thing telling them apart. Handing out input to a
/// live coding agent should not rest on which file descriptor a line arrived
/// on, and here it does not — the two links are separate fields.
fn web_share(name: &str, public: Option<&str>) -> Result<Share, String> {
    share_with(name, false, None, public)
}

/// cctop's quick tunnel to the daemon's share listener, and the port it
/// carries — a daemon that restarted listens somewhere else, and the tunnel to
/// the old port is replaced rather than handed out.
///
/// Not the tunnel `cctop serve --tunnel` holds, though both are quick tunnels
/// from the same client. That one lands on cctop's own server, where every
/// route — the socket relay included — wants the page's token, and a link
/// opened cold on `share.rmux.io` has never seen that token. Putting it in the
/// share link would hand whoever gets the link the whole dashboard. So a share
/// with no page of cctop's around it gets a tunnel straight to rmux's
/// listener, whose own token, PIN and encryption are the whole of its door.
///
/// One for the process, however many sessions are shared: the listener is one
/// per daemon and tells shares apart by the token in the fragment. Held until
/// cctop exits, which is when the shares it handed out stop answering.
static PUBLIC: std::sync::Mutex<Option<(u16, crate::serve::tunnel::Tunnel)>> =
    std::sync::Mutex::new(None);

/// The origin of a quick tunnel to the daemon's share listener, starting one
/// if none is up. An error where the edge cannot be reached, which leaves the
/// caller a loopback share.
///
/// Blocking for as long as the registration takes — a few seconds — and with
/// the lock held, so two pages asking at once register one tunnel, not two.
fn public_origin() -> Result<String, String> {
    let port = on_daemon(|rmux| async move { rmux.web_config().await })?.port;
    let mut held = PUBLIC.lock().map_err(|_| "the share tunnel is poisoned")?;
    if let Some((at, tunnel)) = held.as_ref()
        && *at == port
    {
        return Ok(tunnel.url.clone());
    }
    // The first line only: the rest is advice about `--tunnel`, a flag this
    // caller never had.
    let tunnel = crate::serve::tunnel::start(port).map_err(|e| {
        format!("{e}")
            .lines()
            .next()
            .unwrap_or_default()
            .to_string()
    })?;
    let url = tunnel.url.clone();
    *held = Some((port, tunnel));
    Ok(url)
}

/// The share for `name`, minted on the first ask and reused after it.
///
/// Reused because a share is not free. rmux keeps one per mint — `rmux
/// web-share list` grows a row each time — and when rmux raised its own tunnel
/// per share, a page reopened five times hit the relay's per-address rate
/// limit and came back untunnelled. One share per session per cctop is also
/// the honest number: it is one terminal, and every link minted for it opens
/// the same one.
///
/// Keyed by whether it is the embedded flavour, because that is a different
/// link and not a different terminal — see [`web_share_embedded`].
///
/// Whether the link reaches off this machine is the `bool`; see
/// [`share_link_with`] for which road it takes.
///
/// Held for the life of the process. If the session it belongs to ends, the
/// share ends with it and the cached link stops answering — which is correct,
/// since there is no terminal left for it to reach either.
pub fn share_link(
    name: &str,
    embedded: bool,
    frontend: Option<&str>,
) -> Result<(Share, bool), String> {
    share_link_with(name, embedded, frontend, false)
}

/// How long a minted share is kept and handed out again. Well inside the
/// share's own lifetime ([`SHARE_TTL`]), so a link is never served after the
/// daemon has expired it; and short enough that a link minted while the way out
/// was down — a loopback fallback — is retried for a tunnel before long.
const SHARE_REUSE: std::time::Duration = std::time::Duration::from_secs(20 * 60);

/// How long rmux keeps a share cctop minted, stated rather than left to the
/// daemon's default so [`SHARE_REUSE`] can be measured against it.
const SHARE_TTL: std::time::Duration = std::time::Duration::from_secs(6 * 60 * 60);

/// [`share_link`], with `fresh` to mint a new share even when one is held —
/// what a page asks for when the link it was given would not connect.
pub fn share_link_with(
    name: &str,
    embedded: bool,
    frontend: Option<&str>,
    fresh: bool,
) -> Result<(Share, bool), String> {
    /// A share, whether its endpoint is reachable off this machine, and when
    /// it was minted.
    type Reachable = (Share, bool, std::time::Instant);
    /// Session, flavour, and the frontend it opens in: a link minted for
    /// one origin's copy of the app does not open on another's.
    type Key = (String, bool, Option<String>);
    static CACHE: std::sync::Mutex<Option<HashMap<Key, Reachable>>> = std::sync::Mutex::new(None);
    let key = (name.to_string(), embedded, frontend.map(str::to_string));
    if !fresh
        && let Ok(cache) = CACHE.lock()
        && let Some((share, tunnelled, at)) = cache.as_ref().and_then(|c| c.get(&key))
        && at.elapsed() < SHARE_REUSE
    {
        return Ok((share.clone(), *tunnelled));
    }
    let mint = |public: Option<&str>| match embedded {
        true => web_share_embedded(name, frontend, public),
        false => web_share(name, public),
    };
    // Every share goes out through a Cloudflare quick tunnel of cctop's, or
    // stays on loopback. rmux encrypts terminal traffic end to end between
    // the browser and the daemon — ChaCha20-Poly1305 under keys from an
    // X25519 + ML-KEM handshake, the link's token mixed in — so whoever carries
    // the socket carries ciphertext, and the choice of carrier is about
    // whether it works, not about who can read it.
    //
    // It used to be localhost.run, raised by rmux per share, because a
    // WebSocket through cctop's quick tunnel came back 404. That was the
    // tunnel client dropping the upgrade (see `vendor/cloudflare-quick-tunnel`
    // and the `[patch]` in Cargo.toml), not Cloudflare, and with it fixed the
    // second way out of the machine was only a second thing to drop: its ssh
    // sessions were behind most of the refused frames and slow enough to time
    // the mint out.
    //
    // A share that opens in cctop's own page rides the road that page came
    // by — loopback, the LAN, `--tunnel`'s trycloudflare host — as a loopback
    // share with its endpoint rewritten to cctop's relay at the page's origin
    // (see [`relay_link`]); a page on this machine connects to loopback
    // direct. Anything else — `W` in the dashboard, a page whose origin could
    // not be read — gets the tunnel to rmux's listener in [`public_origin`].
    //
    // Loopback is the fallback, not a failure: a machine with no way out still
    // has a terminal worth opening from a browser on it, and the `bool` says
    // which came back so nobody is handed a link that silently only works from
    // one desk.
    let made = match frontend.filter(|_| embedded) {
        Some(origin) => {
            let share = mint(None)?;
            match is_loopback_url(origin) {
                true => (share, false),
                false => match share
                    .operator
                    .as_deref()
                    .and_then(|url| relay_link(url, origin))
                {
                    Some(relayed) => (
                        Share {
                            operator: Some(relayed),
                            pin: share.pin,
                        },
                        true,
                    ),
                    // An endpoint not shaped as expected: straight to rmux's
                    // listener instead of through the page's relay.
                    None => tunnelled(mint)?,
                },
            }
        }
        None => tunnelled(mint)?,
    };
    if let Ok(mut cache) = CACHE.lock() {
        cache
            .get_or_insert_with(HashMap::new)
            .insert(key, (made.0.clone(), made.1, std::time::Instant::now()));
    }
    Ok(made)
}

/// A share through [`public_origin`]'s tunnel, or on loopback where there is
/// no tunnel to be had — and which of the two, as the `bool`.
///
/// The tunnel's error is kept for when loopback fails too, since then it is
/// the more likely of the two to say what is wrong.
fn tunnelled(
    mint: impl Fn(Option<&str>) -> Result<Share, String>,
) -> Result<(Share, bool), String> {
    match public_origin() {
        Ok(origin) => Ok((mint(Some(&origin))?, true)),
        Err(why) => Ok((mint(None).map_err(|_| why)?, false)),
    }
}

/// The loopback ports cctop has relayed a share's socket to. The relay route
/// forwards only to these: a relay that would forward to any local port is a
/// way into every service on this machine that trusts localhost.
static RELAYED: std::sync::Mutex<Option<std::collections::HashSet<u16>>> =
    std::sync::Mutex::new(None);

/// Whether the relay may forward to `port` — one a share of cctop's named.
pub fn relayable(port: u16) -> bool {
    RELAYED
        .lock()
        .ok()
        .and_then(|set| set.as_ref().map(|s| s.contains(&port)))
        .unwrap_or(false)
}

/// A share link whose socket goes through cctop's relay instead of straight
/// to the daemon's loopback endpoint, for a page that is not on this machine.
///
/// The link's fragment carries `e=ws://127.0.0.1:<port>/<path>`, which a
/// browser elsewhere cannot reach. It becomes `e=wss://<page host>/rmux-ws/
/// <port>/<path>` — `ws` for a page served over plain http — and the port is
/// recorded so the relay will forward to it. `None` for an endpoint that is
/// not a loopback one, which is then left for the caller to deal with.
fn relay_link(url: &str, origin: &str) -> Option<String> {
    let (base, fragment) = url.split_once('#')?;
    let (scheme, host) = match origin.split_once("://")? {
        ("https", rest) => ("wss", rest.split('/').next()?),
        ("http", rest) => ("ws", rest.split('/').next()?),
        _ => return None,
    };
    let mut port_seen = None;
    let params: Vec<String> = fragment
        .split('&')
        .map(|param| match param.strip_prefix("e=") {
            Some(endpoint) => {
                let rest = endpoint
                    .strip_prefix("ws://127.0.0.1:")
                    .or_else(|| endpoint.strip_prefix("ws://localhost:"));
                match rest.and_then(|r| r.split_once('/')) {
                    Some((port, path)) if port.parse::<u16>().is_ok() => {
                        port_seen = port.parse::<u16>().ok();
                        format!("e={scheme}://{host}/rmux-ws/{port}/{path}")
                    }
                    _ => param.to_string(),
                }
            }
            None => param.to_string(),
        })
        .collect();
    let port = port_seen?;
    if let Ok(mut set) = RELAYED.lock() {
        set.get_or_insert_with(Default::default).insert(port);
    }
    Some(format!("{base}#{}", params.join("&")))
}

/// Whether `url` is served from this machine's loopback — `127.0.0.1`,
/// `localhost`, `::1` — where a browser opening it is on this machine too.
fn is_loopback_url(url: &str) -> bool {
    let rest = url
        .strip_prefix("https://")
        .or_else(|| url.strip_prefix("http://"))
        .unwrap_or(url);
    let host = rest.split('/').next().unwrap_or_default();
    let host = match host.strip_prefix('[') {
        Some(v6) => v6.split(']').next().unwrap_or_default(),
        None => host.rsplit_once(':').map_or(host, |(h, _)| h),
    };
    host == "localhost" || host == "::1" || host.starts_with("127.")
}

/// The same share, minted to live inside cctop's own page.
///
/// Four differences, all of them because the frame is not a browser tab:
///
/// - **No navigation bar and no disclaimer toast.** rmux draws both for a link
///   somebody was sent cold. Here the surrounding page is cctop's, the reader
///   arrived through it, and a second chrome inside the frame is chrome twice.
/// - **Operator only.** A spectator link nobody will ever use is a credential
///   minted for nothing.
/// - **No pairing code.** The PIN exists to protect a link that travelled on
///   its own — over chat, over mail — from being opened by whoever ended up
///   holding it. This one never travels: it is minted per request, behind the
///   page's token, and delivered into a frame's `src`. Anyone who can reach
///   that fetch can already mint another, so a PIN in the way of the reader
///   would be friction guarding a door that is already open behind it.
/// - **A dark palette**, which is the page's.
///
/// The road out is the one thing it does not change: `public` means what it
/// does for [`web_share`].
///
/// The consequence, stated once because it is the whole of the security model:
/// **whoever holds the page link can type into this agent's terminal**, not
/// merely prompt it. That is a shell, and it is why this is behind the same
/// `--no-actions` switch as everything else that acts.
///
/// `frontend` is where the app the link opens in is served, when that is not
/// `share.rmux.io` — cctop's own copy, at the origin the page asking was
/// reached on (see [`crate::serve`]'s `term` module). rmux mints the link for
/// that frontend and names the daemon's endpoint in it, and the daemon accepts
/// the app from there; a link minted for `share.rmux.io` and opened elsewhere
/// is refused.
fn web_share_embedded(
    name: &str,
    frontend: Option<&str>,
    public: Option<&str>,
) -> Result<Share, String> {
    share_with(name, true, frontend, public)
}

fn share_with(
    name: &str,
    embedded: bool,
    frontend: Option<&str>,
    public: Option<&str>,
) -> Result<Share, String> {
    let name = name.to_string();
    let frontend = frontend.map(str::to_string);
    let public = public.map(str::to_string);
    on_daemon(move |rmux| async move {
        let session = rmux.session(rmux_sdk::SessionName::new(name)?).await?;
        let mut builder = session.share();
        if let Some(public) = public {
            builder = builder.tunnel_url(public);
        }
        if let Some(frontend) = frontend {
            builder = builder.frontend_url(frontend);
        }
        // Stated, not left to the daemon: the reuse window is measured against it.
        builder = builder.ttl(SHARE_TTL);
        if embedded {
            builder = builder
                // Several browsers on one agent at once — the workspace tile,
                // its session page, a popped-out window. With one operator
                // allowed, whichever connected second was refused.
                .max_operators(8)
                .operator_only()
                .no_navbar()
                .no_disclaimer()
                .no_pin()
                .dark_theme();
        }
        let handle = builder.await?;
        Ok(Share {
            operator: handle.operator_url().map(str::to_string),
            pin: handle.operator_pairing_code().map(str::to_string),
        })
    })
    .and_then(|share| match share.operator {
        // `--spectator-only` is a share this cannot return: there is no
        // operator link in it, and the read-only one is not a substitute.
        None => Err("the share came back without an operator link".to_string()),
        Some(_) => Ok(share),
    })
}

/// A rmux session name for a session being resumed.
///
/// Derived from the session's identity rather than allocated, which is what
/// makes resuming idempotent: pressing `R` twice finds the same rmux session and
/// reattaches to it, instead of starting a second agent on one transcript.
///
/// The whole id goes in, never a prefix of it. Names built from a prefix were
/// not unique: a Codex id is `rollout-<timestamp>-<uuid>`, so the first 24
/// characters end mid-timestamp at the minute — two Codex sessions started in
/// the same minute mapped to one rmux name, and resuming the second reattached
/// to the first while cctop reported it had opened the one asked for. Nothing
/// here can know where a provider keeps the distinguishing part of its id, so
/// the only safe answer is to keep all of it. rmux imposes no length limit worth
/// respecting — a 76-character name works — and the launcher already shortens
/// what it shows.
pub fn name_for_session(provider: &str, session_id: &str) -> String {
    // rmux reads `.` and `:` as address syntax, so neither can survive in a name.
    let id: String = session_id
        .chars()
        .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
        .collect();
    sanitize(&format!("{PREFIX}-{provider}-{id}"))
}

/// A free rmux session name for a freshly launched agent.
///
/// Unlike a resume there is nothing to be idempotent about — two `claude` tabs
/// are two agents — so this counts up until it finds a name nobody is using.
pub fn free_name(label: &str) -> String {
    let base = sanitize(&format!("{PREFIX}-{label}"));
    if !exists(&base) {
        return base;
    }
    // Bounded: past a hundred live rmux sessions of one name, reusing the last
    // is a better failure than looping. `new-session -A` then attaches to it,
    // which is odd but harmless — and nobody has a hundred of these.
    (2..100)
        .map(|n| format!("{base}-{n}"))
        .find(|name| !exists(name))
        .unwrap_or(base)
}

/// Reduce a label to what rmux accepts in a session name.
fn sanitize(text: &str) -> String {
    let cleaned: String = text
        .chars()
        .map(|c| match c {
            c if c.is_ascii_alphanumeric() || c == '-' || c == '_' => c,
            _ => '-',
        })
        .collect();
    // Collapse the runs the mapping above creates, so `claude --resume` does not
    // become `claude---resume`.
    let mut out = String::with_capacity(cleaned.len());
    for c in cleaned.chars() {
        if c == '-' && out.ends_with('-') {
            continue;
        }
        out.push(c);
    }
    out.trim_matches('-').to_string()
}

/// Whether a rmux session by this name is alive.
pub fn exists(name: &str) -> bool {
    Command::new(BIN)
        .args(["has-session", "-t", &format!("={name}")])
        .output()
        .is_ok_and(|out| out.status.success())
}

/// Whether the agent in a session asked for the mouse itself.
///
/// `#{mouse_any_flag}` is rmux's record of the request the pane's own program
/// made — the DECSET it emitted — and it is the flag `MouseDown3Pane` consults
/// before choosing `send-keys -M` over its pane menu. Forwarding a right-click
/// is only safe while this is set: with it the click reaches the agent, and
/// without it the menu opens over the pane with splits and kills on it.
pub fn mouse_wanted(name: &str) -> bool {
    // `mouse_any_flag` is a pane format, which neither `display-message -t` nor
    // `list-panes -t` will resolve against a session name — and the `=` exact
    // target the rest of this module uses is rejected there outright. Asking
    // every pane and matching the name here is the form that answers at all.
    let Ok(out) = Command::new(BIN)
        .args([
            "list-panes",
            "-a",
            "-F",
            "#{session_name} #{mouse_any_flag}",
        ])
        .output()
    else {
        return false;
    };
    let want = format!("{name} 1");
    String::from_utf8_lossy(&out.stdout)
        .lines()
        .any(|line| line == want)
}

/// End a rmux session, taking the agent inside it with it.
///
/// The `=` prefix makes the target an exact name rather than a prefix match —
/// without it, killing `cctop-claude` would also kill `cctop-claude-2`.
pub fn kill(name: &str) -> Result<(), String> {
    let out = Command::new(BIN)
        .args(["kill-session", "-t", &format!("={name}")])
        .output()
        .map_err(|e| format!("rmux: {e}"))?;
    crate::elog::event(
        "rmux",
        "kill",
        serde_json::json!({ "session": name, "ok": out.status.success() }),
    );
    if out.status.success() {
        return Ok(());
    }
    Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
}

/// Turn off the status bar in one of cctop's own rmux sessions.
///
/// Two reasons, and the second is the one that matters. A cctop pane already has
/// a border with the agent's name on it and a footer under it, so rmux's bar is a
/// row of duplicate chrome inside someone else's frame.
///
/// More importantly it carries a clock, which rmux repaints every
/// `status-interval` — 15 seconds by default and 1 second in plenty of configs.
/// A pane's fallback idleness test is "has the screen stopped changing", so a
/// ticking clock is indistinguishable from an agent still working: with a
/// one-second interval no rmux-backed pane could ever go quiet, and the fallback
/// silently reported every abandoned agent as busy forever.
///
/// Scoped to the one session, so a user's own sessions and their global settings
/// are untouched. Best effort: a bar that stays on is cosmetic plus a weaker
/// fallback, and never worth failing a launch over.
pub fn quiet(name: &str) {
    // `=`, like every other target in this module. tmux rejected an exact-match
    // prefix on `set-option` outright ("no such session: =cctop-x") and this
    // was the one call that had to go without it; rmux takes it, so the
    // weaker form — a bare name, which rmux prefix-matches — is no longer the
    // only option here.
    let _ = Command::new(BIN)
        .args(["set-option", "-t", &format!("={name}"), "status", "off"])
        .output();
    // Let the agent's own notifications out. A harness that wants a desktop
    // notification wraps it in rmux's passthrough sequence, and rmux swallows
    // that unless told otherwise — so the OSC 9 an agent sends when it is
    // blocked never reached the pane's parser, where cctop now listens for it.
    // The bell always got through; this is the half that says what about.
    //
    // A pane option, not a session one, and set here rather than in [`prepare`]:
    // a pane inherits its options from the global set when it is made, so there
    // is nothing to configure until the agent's own pane exists. Best effort
    // like the rest — rmux before 3.3 has no such option and rejects it, which
    // costs a process and leaves the pane exactly as it was.
    let _ = Command::new("rmux")
        .args(["set-option", "-p", "-t", name, "allow-passthrough", "on"])
        .output();
    // And let the agent copy out. `set-clipboard` defaults to `external`,
    // which rmux reads as *clipboard writes from inside a pane are dropped* —
    // so a copy in Claude Code went nowhere until this. Server-scoped rather
    // than session: rmux stores the option globally whichever target names it,
    // so `-s` says honestly what `-t` would do anyway.
    let _ = Command::new(BIN)
        .args(["set-option", "-s", "set-clipboard", "on"])
        .output();
}

/// Record on the session itself what this tab is called.
///
/// The session is the only thing every cctop can see, so it is the only place a
/// tab's name can live if the tabs are to look the same in all of them. Without
/// it a cctop that did not start the agent has nothing to go on but the session
/// name — `cctop-claude-32cca860` for a launch, a sanitised uuid for a resume —
/// and the same agent would be called two different things on two screens.
///
/// Best effort, like every other option set here: a tab named after its session
/// is worse than one named properly, and better than a launch that failed.
pub fn set_label(name: &str, label: &str) {
    let _ = Command::new("rmux")
        .args(["set-option", "-t", name, "@cctop_label", label])
        .output();
}

/// Record which account the agent in `name` was started under.
///
/// The same trick as [`set_label`], for the same reason: the profile reached the
/// agent as an environment variable, and nothing outside the process can read
/// one back. Without it written down here, the answer lives only in the `Pane`
/// that chose it — and a pane is traded for a `Shared` on every tab switch, so
/// the account a border reports would fall back to whichever one cctop itself
/// would have used. The default profile writes nothing: unset is what it means.
pub fn set_profile(name: &str, profile: &str) {
    let _ = Command::new("rmux")
        .args(["set-option", "-t", name, "@cctop_profile", profile])
        .output();
}

/// What the agent in a session last reported about itself, recorded on the
/// session by whichever cctop heard it say so.
///
/// The point of writing it down at all is that the hooks are delivered live,
/// over a socket, to whoever happens to be listening — so a cctop that was not
/// running when the event fired never learns it, and a cctop that restarts
/// forgets everything it knew. The session outlives both, so it is the one
/// place the answer can wait.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct State {
    /// What was reported.
    pub signal: crate::hook::Signal,
    /// When, in unix seconds. Wall clock rather than an `Instant`, because the
    /// process that wrote it is not the one that reads it.
    pub at: u64,
}

impl State {
    /// Whether this can still be true. The same rule a live report is held to —
    /// see [`Signal::is_current_after`](crate::hook::Signal::is_current_after) —
    /// measured against the clock the two processes share.
    pub fn is_current(&self, now: u64) -> bool {
        let elapsed = std::time::Duration::from_secs(now.saturating_sub(self.at));
        self.signal.is_current_after(elapsed)
    }

    /// How the option is spelled: the signal's own word, then when it was
    /// written. Both halves matter — a state with no time on it cannot be aged
    /// out, and a stale `working` believed forever is what the age exists to
    /// prevent.
    fn encode(signal: crate::hook::Signal, at: u64) -> String {
        format!("{}@{at}", signal.label())
    }

    fn decode(text: &str) -> Option<State> {
        let (word, at) = text.rsplit_once('@')?;
        Some(State {
            signal: crate::hook::Signal::from_label(word)?,
            at: at.parse().ok()?,
        })
    }
}

/// Wall-clock seconds, which is the only clock two cctops share.
pub fn now_secs() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
}

/// Record on the session what its agent last reported about itself.
///
/// The fourth thing written onto the session rather than kept in this process,
/// and the one with the shortest shelf life — but written for the reason the
/// label, the profile and the order are: every cctop draws the same tab, and a
/// fact only one of them heard is a tab that means two different things on two
/// screens.
///
/// It is deliberately cctop that writes this and not `cctop hook`. The hook
/// runs inside the agent's own process tree, many times a minute, under a
/// deadline it must never miss — see the module docs in
/// [`hook`](crate::hook) — and `rmux set-option` is a process spawn plus a
/// round trip to the daemon. Doing it here costs the same information one
/// subprocess per *change of state*, on cctop's time rather than the agent's.
///
/// Best effort, like its neighbours: a state that failed to save is a tab that
/// falls back to guessing at its screen, which is where it was before.
pub fn set_state(name: &str, signal: crate::hook::Signal) {
    let _ = Command::new(BIN)
        .args([
            "set-option",
            "-t",
            &format!("={name}"),
            "@cctop_state",
            &State::encode(signal, now_secs()),
        ])
        .output();
}

/// Record where this session's tab sits in the bar.
///
/// The third thing written onto the session rather than kept in this process,
/// and for the reason the other two are: every cctop on the machine draws the
/// same bar, and an arrangement one of them invented would otherwise last only
/// as long as it did. A tab dragged to the front stayed there until the next
/// F10 and then went back to being sorted by age, which is the arrangement
/// nobody chose.
///
/// Best effort, like its neighbours: an order that failed to save is a bar in
/// the old arrangement, not a broken one.
pub fn set_order(name: &str, order: usize) {
    let _ = Command::new(BIN)
        .args(["set-option", "-t", name, "@cctop_order", &order.to_string()])
        .output();
}

/// Record the tab's colour on the session, by name — "amber", not an index, so
/// the word means the same thing to a cctop on a different palette.
///
/// The same trick as [`set_label`], for the same reason: the colour is a
/// property of the tab everywhere it is shown, and the session is the only
/// place every cctop can read it back from. An empty `color` clears it — the
/// option reads back as unset either way, so there is nothing to take off.
///
/// Best effort, like its neighbours: a colour that failed to save is a tab in
/// the default ink, not a broken one.
pub fn set_color(name: &str, color: &str) {
    let _ = Command::new(BIN)
        .args([
            "set-option",
            "-t",
            &format!("={name}"),
            "@cctop_color",
            color,
        ])
        .output();
}

/// Record on the session that it is a pane of a tab led by another session.
///
/// The last of the `@cctop_*` options, and the one that makes a split outlive
/// the cctop that made it. Everything else here describes a tab; this one says
/// which sessions belong to the same tab, which is what there was no way to
/// record before.
///
/// Written onto every pane of the split, the leading one included, so the name
/// the others point at does not depend on a pane still existing. An empty `tab`
/// takes the option off, which is how a pane pulled out of a split stops being
/// part of it.
///
/// Best effort, like its neighbours.
pub fn set_tab(name: &str, tab: &str) {
    let _ = Command::new(BIN)
        .args(["set-option", "-t", &format!("={name}"), "@cctop_tab", tab])
        .output();
}

/// Record this session's place among its tab's panes.
///
/// Written per pane rather than once per tab, because the tab is not a thing
/// that can be written to — it is the leading session, and writing its position
/// there would record the *tab's* position rather than this pane's.
pub fn set_pane(name: &str, pane: usize) {
    let _ = Command::new(BIN)
        .args([
            "set-option",
            "-t",
            &format!("={name}"),
            "@cctop_pane",
            &pane.to_string(),
        ])
        .output();
}

/// Record how the tab lays its panes out, on every one of them.
///
/// On every pane because the option has to be readable from whichever session
/// happens to be listed; it is one fact with as many copies as the tab has
/// panes, and they cannot disagree because one call writes them all.
pub fn set_axis(names: &[&str], axis: Axis) {
    let word = axis.as_str();
    for name in names {
        let _ = Command::new(BIN)
            .args(["set-option", "-t", &format!("={name}"), "@cctop_axis", word])
            .output();
    }
}

/// Every cctop-owned session, in the order their tabs were last left in.
///
/// [`running`] answers "which is newest", which is what the launcher wants.
/// The tab bar wants "which is first", and those are different questions the
/// moment anybody drags a tab.
pub fn running_in_tab_order() -> Vec<Running> {
    in_tab_order(running())
}

/// The ordering itself, given the sessions — the half worth testing.
///
/// Sessions nobody has arranged keep the order they had, which is oldest
/// first: a bar that renumbered itself when an unarranged agent appeared would
/// move tabs under someone typing into one. A stable sort is what leaves them
/// alone.
pub fn in_tab_order_of(newest_first: Vec<Running>) -> Vec<Running> {
    in_tab_order(newest_first)
}

fn in_tab_order(newest_first: Vec<Running>) -> Vec<Running> {
    let mut out: Vec<Running> = newest_first.into_iter().rev().collect();
    out.sort_by_key(|s| s.order.unwrap_or(u64::MAX));
    out
}

/// Let the wheel scroll one of cctop's own rmux sessions.
///
/// Without this a rmux-backed pane cannot be scrolled at all. rmux is on the
/// alternate screen, so the scrollback of whatever terminal cctop is running in
/// holds none of the agent's output, and the history that does hold it is
/// reachable only from copy-mode — which, with `mouse` off, only a prefix key
/// opens. Turning it on makes the wheel enter copy-mode and scroll, the way it
/// does in every terminal without rmux in the way.
///
/// Scoped to the one session and best effort, for the same reasons as
/// [`quiet`]: a user's own sessions keep their own setting, and a pane that
/// cannot be scrolled is not worth failing a launch over.
///
/// rmux keeps no history for a pane on the alternate screen, so this does
/// nothing for an agent that draws there — Claude writes to the normal buffer
/// and scrolls, but an agent that takes the alternate screen has nothing behind
/// it to scroll back to, under rmux or anywhere else.
pub fn mouse(name: &str) {
    // Same reason as `quiet` for the bare name: `set-option` rejects `=`.
    let _ = Command::new(BIN)
        .args(["set-option", "-t", name, "mouse", "on"])
        .output();
}

/// Let PageUp, PageDown, Home and End scroll one of cctop's rmux sessions, as
/// [`mouse`] lets the wheel. Returns whether the key was spent on scrolling.
///
/// Only for an agent on the normal screen, which is Claude outside fullscreen:
/// one on the alternate screen has no history here (see [`mouse`]) and binds
/// these keys to its own scrolling, so they go to it untouched.
///
/// PageUp enters copy-mode with `-e`, so paging back down past the bottom
/// leaves it again on its own — and once in copy-mode, PageUp and PageDown are
/// its own keys, so forwarding them is what scrolls. Home enters it too, at
/// the top of the history. End is the composer's while nothing is scrolled
/// back, and only in copy-mode means the live screen.
///
/// Asking rmux costs a process per key, which these keys can afford.
pub fn scroll_key(name: &str, code: crossterm::event::KeyCode) -> bool {
    use crossterm::event::KeyCode;
    // Pane commands want the trailing colon: `=name` alone is a pane-less
    // target and rmux rejects it.
    let target = format!("={name}:");
    // The target straight after the command: display-message's format is its
    // trailing argument, and a flag after it would be read as more message.
    let run = |args: &[&str]| {
        Command::new(BIN)
            .arg(args[0])
            .args(["-t", &target])
            .args(&args[1..])
            .output()
    };
    let Ok(out) = run(&["display-message", "-p", "#{alternate_on} #{pane_in_mode}"]) else {
        return false;
    };
    let (alternate, scrolled) = match String::from_utf8_lossy(&out.stdout).trim() {
        "0 0" => (false, false),
        "0 1" => (false, true),
        _ => (true, false),
    };
    if alternate {
        return false;
    }
    let args: &[&str] = match (code, scrolled) {
        (KeyCode::PageUp, false) => &["copy-mode", "-eu"],
        (KeyCode::Home, false) => {
            return run(&["copy-mode", "-e"]).is_ok_and(|out| out.status.success())
                && run(&["send-keys", "-X", "history-top"]).is_ok_and(|out| out.status.success());
        }
        (KeyCode::Home, true) => &["send-keys", "-X", "history-top"],
        (KeyCode::End, true) => &["send-keys", "-X", "cancel"],
        _ => return false,
    };
    run(args).is_ok_and(|out| out.status.success())
}

/// One cctop-owned rmux session, and the agent living in it.
///
/// The pid is the point. Everything cctop knows about a live agent — what its
/// hooks reported, what its transcript says, whether it is asking a question —
/// is keyed by the agent's own process, and a rmux-backed pane hosts the rmux
/// *client* instead. Without the pid on this side of the wall, an agent handed
/// to rmux is an agent cctop can only look at.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Running {
    /// The rmux session name, which is also cctop's handle on it.
    pub name: String,
    /// The agent's own pid: the pane's child, not any client's.
    ///
    /// `None` only in the moment between the session existing and its command
    /// being spawned, which resolves itself by the next look.
    pub pid: Option<u32>,
    /// Where the agent is working, which is the only human-readable thing a
    /// session name does not already carry.
    pub cwd: Option<PathBuf>,
    /// Whether a client is already looking at this session.
    ///
    /// Not necessarily one of ours — a `rmux attach` in another terminal counts,
    /// and reattaching to it from here would leave the two clients arguing over
    /// one window's size.
    pub attached: bool,
    /// When the session's window last produced output, in unix seconds.
    ///
    /// This is what lets a tab nobody is watching still say its agent has gone
    /// quiet — the same reading a pane takes off its own screen, from the one
    /// place that has it when there is no pane.
    ///
    /// `window_activity` and not `session_activity`, which is not what its name
    /// suggests: rmux advances the session's clock on *client* activity, so a
    /// detached session's stands still however much its agent prints. Reading
    /// that one drew every unwatched agent as idle a few seconds after the last
    /// keystroke — and, with a tool call in flight, blinked its tab as if it
    /// were holding a permission prompt. The window's clock follows the output.
    pub activity: Option<u64>,
    /// What the cctop that started this agent called its tab, when it said.
    ///
    /// Written onto the session by [`set_label`] so that every other cctop names
    /// the tab the same thing. Nothing else can supply it: a resumed session is
    /// labelled after the conversation it is going back to, which the rmux name
    /// — a sanitised provider and uuid — cannot be read back out of.
    pub label: Option<String>,
    /// The account this agent was started under, when it was not the default
    /// one. Written onto the session by [`set_profile`], which says why.
    pub profile: Option<String>,
    /// What this agent last reported about itself, when a cctop has heard it
    /// and written it down. See [`set_state`], and [`State`] for why the
    /// session is where it lives.
    ///
    /// This is the one field here that a cctop could also have worked out for
    /// itself — but only if it was running at the time. Read back, it is what
    /// lets a cctop opened just now draw a tab that has been holding a
    /// permission prompt since before it started.
    pub state: Option<State>,
    /// Where this session's tab was last dragged to, if anywhere.
    ///
    /// Written onto the session by [`set_order`] for the same reason the label
    /// is: the session outlives every cctop, so it is the only place an
    /// arrangement of tabs can live. Without it the bar was rebuilt from
    /// creation times on every start, and a tab dragged to the front was back
    /// where it began the next time cctop opened.
    pub order: Option<u64>,
    /// The colour the tab was painted, as [`set_color`] wrote it — a name like
    /// "amber", left for [`ui::theme::Hue`](crate::ui::theme::Hue) to decode.
    /// Opaque here for the reason `label` and `profile` are strings: this
    /// module is the transport, not the palette.
    pub color: Option<String>,
    /// Which tab this session is a pane of, by that tab's leading session name.
    ///
    /// Written by [`set_tab`] and read back to rebuild a split. This is the
    /// whole of tab *identity*: before it there was none, and a tab was exactly
    /// "whatever session is attached here" — so a split could not be put down
    /// and picked up, and two sessions that belonged together came back as two
    /// tabs that had never met.
    ///
    /// Absent means this session is a tab on its own, which is what every
    /// session started before this option existed still is. Written onto the
    /// leading pane as well as the others, so that closing or killing the pane
    /// the name came from does not orphan the rest.
    pub tab: Option<String>,
    /// This session's position among its tab's panes, counting from zero.
    ///
    /// Not the order the sessions were created in: the second pane of a split
    /// can be years younger than the first, and a split is not its panes' birth
    /// order. Read by [`set_pane`]'s writer, and meaningless without `tab`.
    pub pane: Option<u64>,
    /// Whether the tab lays its panes out left to right or top to bottom, as
    /// [`Axis`] writes it. Read back with the tab, since it is a property of the
    /// tab and every pane records the same answer.
    pub axis: Option<String>,
    /// The size rmux has fitted the session's window to, columns by rows.
    ///
    /// The window is fitted to one attached client at a time, so a client that
    /// is larger — this cctop's pane, while a browser holds the window — gets
    /// the window in its top-left corner and nothing rmux redraws around it.
    /// The pane blanks what lies outside, and knows from this when its own
    /// client needs to take the window back.
    pub window: Option<(u16, u16)>,
}

impl Running {
    /// A session cctop has written nothing about yet.
    ///
    /// A real state, not a fixture: between rmux creating a session and cctop
    /// labelling it, every option reads back unset. Which is what a session
    /// started by a cctop older than any one of these options is forever, so
    /// this is the shape an unarranged tab has in the wild and not only in a
    /// test — but nothing in the binary builds one, since the list comes from
    /// rmux rather than being constructed here.
    #[cfg(test)]
    pub fn unrecorded(name: &str) -> Running {
        Running {
            name: name.to_string(),
            pid: None,
            cwd: None,
            attached: false,
            activity: None,
            label: None,
            profile: None,
            order: None,
            state: None,
            color: None,
            tab: None,
            pane: None,
            axis: None,
            window: None,
        }
    }

    /// How the tab this session belongs to lays its panes out.
    ///
    /// Read off the session rather than passed in, because every pane of a
    /// split records the same answer and so any one of them can answer for the
    /// tab — which is what lets a tab be rebuilt from whichever of its sessions
    /// the listing happened to name first. Side by side when nothing says, which
    /// is what a session nobody ever split is, and not a guess.
    pub fn axis(&self) -> Axis {
        self.axis
            .as_deref()
            .and_then(Axis::parse)
            .unwrap_or(Axis::Side)
    }
}

/// Group sessions into the tabs they belong to, keeping the bar's order.
///
/// One session is one tab until [`set_tab`] says otherwise, so this is a
/// partition that mostly has one part. A session is its own tab when it records
/// no tab, and also when the tab it names is not itself present — a pane whose
/// leader has been closed is a tab again rather than a member of nothing.
///
/// Panes are ordered by [`Running::pane`], not by the order they were listed:
/// `running` answers newest first, which is the launcher's question, and a split
/// whose panes came back reversed would draw them the wrong way round.
///
/// Tabs keep the order [`in_tab_order`] gave the sessions, so a split's bar
/// position is its leading session's — which is the one it had.
///
/// Returns each tab's sessions, leading session first.
pub fn tabbed(sessions: Vec<Running>) -> Vec<Vec<Running>> {
    // First pass: which tab each session claims, and every tab anyone claims.
    // Two passes because a session naming a tab has to find the tab that session
    // *is* — the leader, which may be listed after it. `running` answers newest
    // first, so the second pane of a split routinely arrives before its first.
    let named: Vec<String> = sessions.iter().filter_map(|s| s.tab.clone()).collect();
    let mut tabs: Vec<(String, Vec<Running>)> = Vec::new();
    for session in sessions {
        // Belongs to a tab that is genuinely present. A session naming a tab
        // nobody else claims is its own tab, which is what a pane whose leader
        // has been closed becomes.
        let owner = match session.tab.clone() {
            Some(tab) if named.iter().filter(|t| **t == tab).count() > 1 => tab,
            _ => session.name.clone(),
        };
        match tabs.iter_mut().find(|(name, _)| *name == owner) {
            Some((_, panes)) => panes.push(session),
            None => tabs.push((owner, vec![session])),
        }
    }
    for (_, panes) in &mut tabs {
        // Numbered position, not the order listed: `running` answers newest
        // first, and a split whose panes came back reversed draws them the wrong
        // way round. A pane nobody numbered sorts first, which is the leading
        // one — so an unnumbered pair keeps its order and the default only ever
        // decides ties.
        panes.sort_by_key(|s| s.pane.unwrap_or(0));
    }
    tabs.into_iter().map(|(_, panes)| panes).collect()
}

/// Which way a tab lays out its panes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Axis {
    Side,
    Stacked,
}

impl Axis {
    /// The word [`set_axis`] writes and [`Running::axis`] reads back.
    pub fn as_str(self) -> &'static str {
        match self {
            Axis::Side => "side",
            Axis::Stacked => "stacked",
        }
    }

    /// A word this cctop does not know reads as no answer, never a guess.
    pub fn parse(word: &str) -> Option<Axis> {
        match word {
            "side" => Some(Axis::Side),
            "stacked" => Some(Axis::Stacked),
            _ => None,
        }
    }
}

/// Every cctop-owned rmux session currently alive, newest first.
///
/// What the UI needs to say "there are agents still running out there" after a
/// restart, and to offer them back — with enough about each to say which is
/// which, rather than a list of names.
///
/// Newest first because that is the order they are wanted in: the agent you
/// walked away from most recently is the one you are most likely coming back
/// for.
pub fn running() -> Vec<Running> {
    // One call for all of it. Every field below resolves in a pane's context —
    // rmux looks up the session a pane belongs to — so asking per session would
    // be a subprocess each for the same answer.
    let Ok(out) = Command::new(BIN)
        .args([
            "list-panes",
            "-a",
            "-F",
            "#{session_name}\t#{pane_pid}\t#{pane_current_path}\t#{session_attached}\t#{session_created}\t#{window_activity}\t#{@cctop_label}\t#{@cctop_profile}\t#{@cctop_order}\t#{@cctop_state}\t#{@cctop_color}\t#{@cctop_tab}\t#{@cctop_pane}\t#{@cctop_axis}\t#{window_width}\t#{window_height}",
        ])
        .output()
    else {
        return Vec::new();
    };
    if !out.status.success() {
        // No server running: no sessions, not an error.
        return Vec::new();
    }

    let prefix = format!("{PREFIX}-");
    let mut found: Vec<(u64, Running)> = Vec::new();
    for line in String::from_utf8_lossy(&out.stdout).lines() {
        let mut parts = line.split('\t');
        let Some(name) = parts
            .next()
            .map(str::trim)
            .filter(|n| n.starts_with(&prefix))
        else {
            continue;
        };
        // A session with splits or extra windows lists several panes. The agent
        // is the one cctop started, which is the first — later panes are the
        // user's own, opened inside the session after the fact.
        if found.iter().any(|(_, s)| s.name == name) {
            continue;
        }
        let pid = parts.next().and_then(|p| p.trim().parse::<u32>().ok());
        let cwd = parts
            .next()
            .map(str::trim)
            .filter(|p| !p.is_empty())
            .map(PathBuf::from);
        let attached = parts.next().map(str::trim).is_some_and(|a| a != "0");
        let created = parts
            .next()
            .and_then(|c| c.trim().parse::<u64>().ok())
            .unwrap_or(0);
        let activity = parts.next().and_then(|a| a.trim().parse::<u64>().ok());
        // Unset reads back as the empty string, not as a missing field.
        let mut option = || {
            parts
                .next()
                .map(str::trim)
                .filter(|v| !v.is_empty())
                .map(str::to_string)
        };
        let label = option();
        let profile = option();
        let order = option().and_then(|v| v.parse::<u64>().ok());
        // A word this cctop does not know, or a value some other tool wrote,
        // reads as nothing reported rather than as a guess.
        let state = option().as_deref().and_then(State::decode);
        let color = option();
        // The tab a split is made of. A session without one is a tab of its own,
        // which is every session started before the option existed — so an older
        // database of tabs needs no migration, only this reading.
        let tab = option();
        let pane = option().and_then(|v| v.parse::<u64>().ok());
        let axis = option();
        let width = option().and_then(|v| v.parse::<u16>().ok());
        let height = option().and_then(|v| v.parse::<u16>().ok());
        let window = width.zip(height);
        found.push((
            created,
            Running {
                name: name.to_string(),
                pid,
                cwd,
                attached,
                activity,
                label,
                profile,
                order,
                state,
                color,
                tab,
                pane,
                axis,
                window,
            },
        ));
    }
    // Descending, so the agent left most recently is the one offered first.
    found.sort_by_key(|(created, _)| std::cmp::Reverse(*created));
    found.into_iter().map(|(_, s)| s).collect()
}

/// The size rmux has fitted `name`'s window to, columns by rows.
///
/// Asked off the draw loop by a pane about to type into a window some other
/// client may have resized; see [`Running::window`].
pub fn window_size(name: &str) -> Option<(u16, u16)> {
    // Pane commands want the trailing colon; see `scroll_key`.
    let target = format!("={name}:");
    let out = Command::new(BIN)
        .args([
            "display-message",
            "-t",
            &target,
            "-p",
            "#{window_width} #{window_height}",
        ])
        .output()
        .ok()?;
    let text = String::from_utf8_lossy(&out.stdout);
    let mut parts = text.split_whitespace().map(|v| v.parse::<u16>().ok());
    parts.next().flatten().zip(parts.next().flatten())
}

/// The clients attached to `name`, as `(is_browser, cols, rows)`.
///
/// A browser on a web share is a client with no tty; everything else — this
/// cctop's pane, an `rmux attach` in a terminal — has one. The web page asks
/// this to tell whether the window is already a browser's, which is a fact rmux
/// has rather than one the page would have to measure off its own drawing.
pub fn clients(name: &str) -> Vec<(bool, u16, u16)> {
    let Ok(out) = Command::new(BIN)
        .args([
            "list-clients",
            "-t",
            &format!("={name}"),
            "-F",
            "#{client_tty}\t#{client_width}\t#{client_height}",
        ])
        .output()
    else {
        return Vec::new();
    };
    String::from_utf8_lossy(&out.stdout)
        .lines()
        .filter_map(|line| {
            let mut parts = line.split('\t');
            let tty = parts.next()?.trim();
            let cols = parts.next()?.trim().parse().ok()?;
            let rows = parts.next()?.trim().parse().ok()?;
            Some((tty.is_empty(), cols, rows))
        })
        .collect()
}

/// Just the names, for the callers that only need to know which exist.
pub fn sessions() -> Vec<String> {
    running().into_iter().map(|s| s.name).collect()
}

/// The pid of the agent inside the session called `name`.
///
/// Targeted rather than a scan of [`running`], because this is asked per pane
/// and the answer for one session should not cost a listing of them all.
pub fn agent_pid(name: &str) -> Option<u32> {
    // The `=` that makes a target exact everywhere else in this module is a
    // parse error to `list-panes` under rmux ("can't find pane: =cctop-…"),
    // and the bare name it does accept prefix-matches — `cctop-claude-abc`
    // finds `cctop-claude-abc-2` when the first is gone. So the name comes back
    // in the format and is checked here: exact by answer rather than by syntax,
    // which is also the version that cannot be undone by either daemon
    // changing its mind about `=`.
    let out = Command::new(BIN)
        .args([
            "list-panes",
            "-t",
            name,
            "-F",
            "#{session_name}\t#{pane_pid}",
        ])
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    // First pane again: see [`running`].
    String::from_utf8_lossy(&out.stdout)
        .lines()
        .filter_map(|line| line.split_once('\t'))
        .find(|(session, _)| *session == name)
        .and_then(|(_, pid)| pid.trim().parse().ok())
}

/// The cctop session holding the agent running as `pid`, if one is.
///
/// The reverse of [`agent_pid`], and the question asked by anything that starts
/// from a process and needs to know whether cctop can reach its terminal: an
/// agent handed to rmux is on no pty of cctop's, so every other route to it
/// fails, but the session name is a way in.
pub fn holding(pid: u32) -> Option<String> {
    running()
        .into_iter()
        .find(|agent| agent.pid == Some(pid))
        .map(|agent| agent.name)
}

/// What the session's first pane shows right now, as bytes a vt100 parser of
/// its size can replay.
///
/// For the dashboard's Preview panel, which has no client of its own to read a
/// screen from: a tab this cctop is not looking at gives up its rmux client (see
/// [`Tab::detach`](crate::ui::tabs::Tab::detach)), so on the dashboard nearly
/// every agent tab has no parser behind it. Asking rmux for the screen is the
/// read-only way to see it — attaching a client would resize the window to the
/// panel, which the agent would then redraw for.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Capture {
    pub cols: u16,
    pub rows: u16,
    /// Where the cursor is, or `None` when the agent has hidden it.
    pub cursor: Option<(u16, u16)>,
    /// The visible rows with their colours, joined by `\r\n`.
    pub bytes: Vec<u8>,
}

/// Capture the screen of the session called `name`. See [`Capture`].
///
/// Two commands, because the first is what makes the second exact: a bare
/// session name prefix-matches (see [`agent_pid`]), so the session is checked by
/// its answer and the capture then targets the pane by its `%id`, which cannot
/// land on a neighbour.
pub fn capture(name: &str) -> Option<Capture> {
    let out = Command::new(BIN)
        .args([
            "list-panes",
            "-t",
            name,
            "-F",
            "#{session_name}\t#{pane_id}\t#{pane_width}\t#{pane_height}\t#{cursor_x}\t#{cursor_y}\t#{cursor_flag}",
        ])
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    let listing = String::from_utf8_lossy(&out.stdout);
    let fields: Vec<&str> = listing
        .lines()
        .map(|line| line.split('\t').collect::<Vec<_>>())
        .find(|f| f.len() == 7 && f[0] == name)?;
    let num = |i: usize| fields[i].trim().parse::<u16>().ok();
    let (cols, rows) = (num(2)?, num(3)?);
    let cursor = match fields[6].trim() {
        "0" => None,
        _ => Some((num(5)?, num(4)?)),
    };
    let out = Command::new(BIN)
        .args(["capture-pane", "-p", "-e", "-t", fields[1]])
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    Some(Capture {
        cols,
        rows,
        cursor,
        bytes: capture_bytes(&out.stdout),
    })
}

/// Turn `capture-pane -p` output into what a parser can replay.
///
/// Newlines become `\r\n`, since a bare `\n` only moves down, and the last is
/// dropped: on the bottom row it would scroll the whole capture up by one.
/// Attributes are left running across the joins — rmux carries them from one
/// line into the next rather than restating them, so resetting at each line
/// would strip the colour off every row that continues a span.
fn capture_bytes(raw: &[u8]) -> Vec<u8> {
    let raw = raw.strip_suffix(b"\n").unwrap_or(raw);
    let mut bytes = Vec::with_capacity(raw.len() + raw.len() / 32);
    for (i, line) in raw.split(|&b| b == b'\n').enumerate() {
        if i > 0 {
            bytes.extend_from_slice(b"\r\n");
        }
        bytes.extend_from_slice(line);
    }
    bytes
}

/// Serialises the tests that drive a real rmux server.
///
/// The server is one shared, machine-wide thing, and its *lifetime* is the part
/// that races: killing the last session stops the server, and a `new-session`
/// that reaches the socket while it is going down fails outright. Two tests
/// creating and killing sessions at once therefore fail each other at random,
/// which is what happens without this — nothing about the code under test is
/// racy, the fixture is.
#[cfg(test)]
pub fn test_lock() -> std::sync::MutexGuard<'static, ()> {
    static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
    // A test that panicked while holding the lock has poisoned it. The next one
    // still wants its turn rather than a second failure caused by the first.
    LOCK.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}

#[cfg(test)]
mod tests {
    #[test]
    fn a_share_for_a_page_elsewhere_goes_through_the_pages_own_origin() {
        let url = "https://x.trycloudflare.com/term/#e=ws://127.0.0.1:45691/share&t=abc&navbar=off";
        let relayed = super::relay_link(url, "https://x.trycloudflare.com/term/").expect("relayed");
        assert_eq!(
            relayed,
            "https://x.trycloudflare.com/term/#e=wss://x.trycloudflare.com/rmux-ws/45691/share&t=abc&navbar=off"
        );
        assert!(super::relayable(45691));
        assert!(!super::relayable(22), "only ports a share named");
        let lan = super::relay_link(
            "http://10.0.0.5:7778/term/#e=ws://127.0.0.1:5000/share&t=x",
            "http://10.0.0.5:7778/term/",
        );
        assert_eq!(
            lan.as_deref(),
            Some("http://10.0.0.5:7778/term/#e=ws://10.0.0.5:7778/rmux-ws/5000/share&t=x")
        );
        // Already a public endpoint: not ours to rewrite.
        assert!(
            super::relay_link(
                "https://h/term/#e=wss://a.trycloudflare.com/share&t=x",
                "https://h/term/"
            )
            .is_none()
        );
    }

    #[test]
    fn a_page_on_this_machine_is_told_from_one_reached_from_elsewhere() {
        use super::is_loopback_url;
        assert!(is_loopback_url("http://127.0.0.1:7778/term/"));
        assert!(is_loopback_url("http://localhost:7778/term/"));
        assert!(is_loopback_url("http://[::1]:7778/term/"));
        assert!(!is_loopback_url("http://192.168.1.20:7778/term/"));
        assert!(!is_loopback_url(
            "https://quiet-river.trycloudflare.com/term/"
        ));
        assert!(!is_loopback_url("http://localhost.example.com/term/"));
    }

    /// A capture replays as the screen it came from: every row on its own line,
    /// nothing scrolled off the top, and a colour that runs across a line break
    /// still running.
    #[test]
    fn a_capture_replays_without_scrolling_or_losing_colour() {
        let raw = b"one\n\x1b[31mtwo\nthree\x1b[39m\n";
        assert_eq!(
            super::capture_bytes(raw),
            b"one\r\n\x1b[31mtwo\r\nthree\x1b[39m".to_vec()
        );
        let mut parser = vt100::Parser::new(3, 10, 0);
        parser.process(&super::capture_bytes(raw));
        assert_eq!(parser.screen().contents(), "one\ntwo\nthree");
        assert_eq!(
            parser.screen().cell(2, 0).unwrap().fgcolor(),
            vt100::Color::Idx(1)
        );
    }

    /// The option is one string in a tab-separated listing, so its spelling is
    /// load-bearing in both directions: a word this cctop cannot read, or a
    /// time it cannot parse, has to come back as "nothing reported" rather than
    /// as the wrong state.
    #[test]
    fn a_state_survives_being_written_down_and_read_back() {
        use crate::hook::Signal;
        for signal in [
            Signal::NeedsInput,
            Signal::Idle,
            Signal::Busy,
            Signal::Acting,
            Signal::Compacting,
            Signal::Started,
            Signal::Ended,
        ] {
            let text = State::encode(signal, 1_700_000_000);
            assert_eq!(
                State::decode(&text),
                Some(State {
                    signal,
                    at: 1_700_000_000
                }),
                "{text} did not survive the round trip"
            );
        }

        assert_eq!(State::decode(""), None, "an unset option says nothing");
        assert_eq!(
            State::decode("asking"),
            None,
            "a state with no time on it cannot be aged out, so it is not a state"
        );
        assert_eq!(
            State::decode("dreaming@1700000000"),
            None,
            "a signal from a newer cctop is not guessed at"
        );
    }

    /// The asymmetry that makes this safe to leave lying on a session: a
    /// question outlives the cctop that heard it, a claim to be working does
    /// not. Without it, an agent killed mid-tool would leave a session
    /// asserting "working" at every cctop that ever opened afterwards.
    #[test]
    fn a_recorded_question_keeps_but_a_recorded_claim_to_be_working_lapses() {
        let now = 1_700_000_000;
        let hour_ago = |signal| State {
            signal,
            at: now - 3_600,
        };
        assert!(
            hour_ago(crate::hook::Signal::NeedsInput).is_current(now),
            "somebody back from lunch still has a prompt to answer"
        );
        assert!(hour_ago(crate::hook::Signal::Idle).is_current(now));
        assert!(!hour_ago(crate::hook::Signal::Busy).is_current(now));
        assert!(!hour_ago(crate::hook::Signal::Acting).is_current(now));
        assert!(
            State {
                signal: crate::hook::Signal::Busy,
                at: now - 60
            }
            .is_current(now),
            "a turn a minute in is an ordinary turn"
        );
    }

    /// A split comes back as one tab, in the order it was left, divided the same
    /// way — which is the whole of what tab identity is for.
    ///
    /// The bug: there was no identity, so a tab was "whatever session is
    /// attached here". A split could not be put down and picked up, and came
    /// back from a restart as two tabs that had never met.
    ///
    /// Given out of order on purpose: `running` answers newest first, so the
    /// second pane of a split routinely arrives before its first, and a grouping
    /// that trusted the listing order would draw them reversed.
    #[test]
    fn a_split_comes_back_as_one_tab_in_the_order_it_was_left() {
        let pane_of = |name: &str, tab: Option<&str>, pane: Option<u64>| Running {
            tab: tab.map(str::to_string),
            pane,
            ..Running::unrecorded(name)
        };

        let groups = tabbed(vec![
            // Second pane first, and it is the newer session.
            pane_of("cctop-shell", Some("cctop-claude"), Some(1)),
            pane_of("cctop-claude", Some("cctop-claude"), Some(0)),
        ]);
        assert_eq!(groups.len(), 1, "two sessions of one tab are one tab");
        let names: Vec<&str> = groups[0].iter().map(|s| s.name.as_str()).collect();
        assert_eq!(names, ["cctop-claude", "cctop-shell"], "and in pane order");

        // A session nobody split is a tab of one, which is every session that
        // predates the option — so an older arrangement needs no migration.
        let groups = tabbed(vec![
            pane_of("cctop-claude", None, None),
            pane_of("cctop-codex", None, None),
        ]);
        assert_eq!(groups.len(), 2);

        // The axis comes off whichever session carries it, and every pane of a
        // split records the same answer, so the leader can answer for the tab.
        assert_eq!(groups[0][0].axis(), Axis::Side, "nothing said");
        let stacked = pane_of("cctop-stacked", Some("cctop-stacked"), Some(0));
        let mut stacked = stacked;
        stacked.axis = Some("stacked".into());
        assert_eq!(stacked.axis(), Axis::Stacked);
        // A word this cctop does not know is no answer, never a guess.
        let mut odd = pane_of("cctop-odd", None, None);
        odd.axis = Some("diagonal".into());
        assert_eq!(odd.axis(), Axis::Side);

        // A pane whose leader has been closed is a tab again, rather than a
        // member of a tab that is not there.
        let groups = tabbed(vec![pane_of("cctop-orphan", Some("cctop-gone"), Some(1))]);
        assert_eq!(groups.len(), 1);
        assert_eq!(groups[0][0].name, "cctop-orphan");
    }

    /// The claim the whole feature rests on: the state outlives the cctop that
    /// wrote it, because it is on the session and the session is not ours.
    ///
    /// Against a real daemon for the same reason the order test is — only rmux
    /// can say whether the option survived a process that has since gone.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_state_written_onto_a_session_survives_in_it() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let ours = format!("cctop-state-{}", std::process::id());
        let dir = std::env::temp_dir();
        start_session(&ours, Some(&dir), &["sh", "-c", "sleep 30"]);

        let before = wait_for(|| running().into_iter().find(|s| s.name == ours));
        set_state(&ours, crate::hook::Signal::NeedsInput);
        let after = wait_for(|| {
            running()
                .into_iter()
                .find(|s| s.name == ours && s.state.is_some())
        });
        end_session(&ours);

        assert_eq!(
            before.map(|s| s.state),
            Some(None),
            "born reporting nothing about itself"
        );
        assert_eq!(
            after.and_then(|s| s.state).map(|s| s.signal),
            Some(crate::hook::Signal::NeedsInput),
            "the held question did not come back off the session"
        );
    }

    /// The order written onto a session is the order read back off it.
    ///
    /// Against a real daemon, because that is the whole claim: the arrangement
    /// has to outlive the process that made it, and only rmux can say whether
    /// it did. The unit above tests the sorting; this tests that there is
    /// anything to sort by.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn an_order_written_onto_a_session_survives_in_it() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let ours = format!("cctop-order-{}", std::process::id());
        let dir = std::env::temp_dir();
        start_session(&ours, Some(&dir), &["sh", "-c", "sleep 30"]);

        let before = wait_for(|| running().into_iter().find(|s| s.name == ours));
        set_order(&ours, 3);
        let after = wait_for(|| {
            running()
                .into_iter()
                .find(|s| s.name == ours && s.order.is_some())
        });
        end_session(&ours);

        assert_eq!(before.map(|s| s.order), Some(None), "born with an order");
        assert_eq!(
            after.map(|s| s.order),
            Some(Some(3)),
            "the order did not come back off the session"
        );
    }

    /// The bar's order comes from what was written on the sessions, and the
    /// sessions nobody arranged keep the order they always had.
    ///
    /// The bug: the arrangement lived only in the running process, so a tab
    /// dragged to the front was back among the others — sorted by age — the
    /// next time cctop opened.
    #[test]
    fn arranged_tabs_lead_and_the_rest_stay_oldest_first() {
        let at = |name: &str, order: Option<u64>| Running {
            order,
            ..Running::unrecorded(name)
        };
        // As `running` gives them: newest first.
        let found = vec![
            at("newest", None),
            at("arranged-second", Some(1)),
            at("middle", None),
            at("arranged-first", Some(0)),
            at("oldest", None),
        ];
        let names: Vec<String> = in_tab_order(found).into_iter().map(|s| s.name).collect();
        assert_eq!(
            names,
            [
                "arranged-first",
                "arranged-second",
                "oldest",
                "middle",
                "newest"
            ]
        );

        // With nothing arranged it is exactly what it was before: oldest first.
        let plain = vec![at("newest", None), at("middle", None), at("oldest", None)];
        let names: Vec<String> = in_tab_order(plain).into_iter().map(|s| s.name).collect();
        assert_eq!(names, ["oldest", "middle", "newest"]);
    }

    /// The share path, against a real daemon and through the same call the `W`
    /// key makes. There is nothing left to unit-test here: the operator link
    /// and its pairing code are fields on a typed handle rather than lines
    /// picked out of two streams, so what is worth checking is that the daemon
    /// answers and that what comes back is the operator's link and not the
    /// spectator's.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_real_rmux_session_comes_back_with_an_operator_link() {
        let _guard = test_lock();
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let name = format!("cctop-share-{}", std::process::id());
        start_session(&name, None, &["sleep", "30"]);

        // Untunnelled, so the test needs no network: registering a quick
        // tunnel from a unit test would dial Cloudflare on every `cargo test`.
        // What is being checked here is the daemon's answer, which is the same
        // either way — the endpoint is loopback instead of a hostname. The
        // tunnelled road has a test of its own below.
        let share = web_share(&name, None);
        // Killing the session ends its share; `web-share -X` would also end any
        // the user has open, which is not this test's to touch.
        end_session(&name);

        let share = share.expect("rmux shared the session");
        let operator = share.operator.expect("an operator link");
        assert!(operator.starts_with("https://"), "not a link: {operator}");
        // Untunnelled, so the endpoint in the fragment is the daemon's own
        // loopback listener — never a public host.
        let endpoint = operator
            .split_once('#')
            .and_then(|(_, fragment)| fragment.split('&').find_map(|p| p.strip_prefix("e=")));
        assert!(
            endpoint.is_none_or(|e| e.starts_with("ws://127.0.0.1:")),
            "a public endpoint appeared: {operator}"
        );
        assert!(
            operator.contains("#t=") || operator.contains("&t="),
            "no share token in the link: {operator}"
        );
        // The spectator link is minted alongside it and must not be what came
        // back: it is the same shape and grants a different thing.
        assert!(
            !operator.contains("spectator"),
            "that is not the operator link: {operator}"
        );
    }

    /// The road `W` takes, end to end: a share minted with no page around it
    /// comes back on a trycloudflare host, and a WebSocket upgrade sent to the
    /// endpoint in its fragment is answered `101` by rmux at the far side of
    /// the tunnel. The upgrade is the part that once came back 404, which is
    /// why the share spent a while on localhost.run instead.
    ///
    /// Needs rmux and the internet, and dials Cloudflare, so it runs only when
    /// asked for. Point it at a throwaway daemon with `RMUX_TMPDIR`.
    #[test]
    #[ignore = "needs a real rmux server and the internet"]
    fn a_share_with_no_page_upgrades_through_the_quick_tunnel() {
        let _guard = test_lock();
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let name = format!("cctop-tunnel-{}", std::process::id());
        start_session(&name, None, &["sleep", "120"]);
        let minting = std::time::Instant::now();
        let share = share_link(&name, false, None);
        eprintln!("minted in {:?}", minting.elapsed());
        let share = share.inspect_err(|_| end_session(&name));
        let (share, reachable) = share.expect("rmux shared the session");
        let operator = share.operator.expect("an operator link");
        let endpoint = operator
            .split_once('#')
            .and_then(|(_, fragment)| fragment.split('&').find_map(|p| p.strip_prefix("e=")))
            .unwrap_or_default()
            .to_string();
        let mut answer = String::new();
        let asked = std::time::Instant::now();
        // A fresh trycloudflare name can take a while to resolve everywhere,
        // which is a fact about DNS, not about the upgrade.
        for _ in 0..30 {
            let out = Command::new("curl")
                .args(["-sS", "--http1.1", "-o", "/dev/null", "-w", "%{http_code}"])
                .args(["--max-time", "5"])
                .args(["-H", "Connection: Upgrade", "-H", "Upgrade: websocket"])
                .args(["-H", "Sec-WebSocket-Version: 13"])
                .args(["-H", "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ=="])
                .args(["-H", "Origin: https://share.rmux.io"])
                .arg(endpoint.replacen("wss://", "https://", 1))
                .output();
            answer = out
                .map(|o| String::from_utf8_lossy(&o.stdout).into_owned())
                .unwrap_or_default();
            if answer == "101" {
                break;
            }
            std::thread::sleep(std::time::Duration::from_secs(2));
        }
        end_session(&name);
        eprintln!(
            "endpoint {endpoint} answered {answer} after {:?}",
            asked.elapsed()
        );
        assert!(reachable, "came back on loopback: {operator}");
        assert!(
            endpoint.starts_with("wss://") && endpoint.contains(".trycloudflare.com/"),
            "not a quick-tunnel endpoint: {endpoint}"
        );
        assert_eq!(answer, "101", "the upgrade did not survive the tunnel");
    }

    use super::*;

    /// Whatever is offered has to be runnable as offered. An install the user
    /// accepts and then watches fail on a missing `sudo`, or on a script that
    /// was never a command, is worse than never having offered.
    #[test]
    fn an_offered_install_is_a_command_that_could_run() {
        let Some(install) = installer() else {
            return;
        };
        assert_eq!(install.argv[0], "sh");
        assert_eq!(install.argv[1], "-c");
        assert_eq!(install.shown(), install.argv[2]);
        assert!(install.shown().contains("rmux"));
        if let Some(rest) = install.shown().strip_prefix("sudo ") {
            assert!(crate::shim::is_command("sudo"));
            // Only the leading command is elevated, so a second one after `&&`
            // needs its own sudo. apt is the entry where this matters.
            assert!(!rest.contains("&& apt-get install") || rest.contains("&& sudo"));
        }
    }

    /// The wrapped command has to attach-or-create by exact name, start in the
    /// project, and keep the agent's own flags away from rmux.
    #[test]
    fn the_wrapper_attaches_or_creates_and_passes_the_agent_through() {
        let argv: Vec<String> = ["claude", "--resume", "abc"]
            .iter()
            .map(|s| s.to_string())
            .collect();
        let dir = std::env::temp_dir();
        let out = attach_or_create(&argv, "cctop-claude-abc", Some(&dir));

        assert_eq!(
            &out[..5],
            &["rmux", "new-session", "-A", "-s", "cctop-claude-abc"]
        );
        // The agent's flags come after `--`, so rmux cannot claim them.
        let sep = out.iter().position(|a| a == "--").expect("separator");
        assert_eq!(&out[sep + 1..], &argv[..]);
        assert!(out.contains(&"-c".to_string()));

        // A directory that is not there is left off rather than failing the
        // spawn, matching what the pty path does with a stale cwd.
        let gone = attach_or_create(&argv, "n", Some(Path::new("/nonexistent/gone")));
        assert!(!gone.contains(&"-c".to_string()));
    }

    /// Resuming the same session twice must name the same rmux session, or `-A`
    /// has nothing to reattach to and the point is lost.
    #[test]
    fn a_session_always_maps_to_the_same_rmux_name() {
        let a = name_for_session("claude", "32cca860-b503-43f8-8b95-7b75880abb8b");
        let b = name_for_session("claude", "32cca860-b503-43f8-8b95-7b75880abb8b");
        assert_eq!(a, b);
        assert_ne!(a, name_for_session("claude", "other-id"));
        // Different providers can share a session id without colliding.
        assert_ne!(
            a,
            name_for_session("codex", "32cca860-b503-43f8-8b95-7b75880abb8b")
        );
    }

    /// Two different sessions must never map to one name, or `R` on the second
    /// silently reattaches to the first — the worst failure this module has,
    /// because cctop reports having opened the session that was asked for.
    ///
    /// The shape that broke it: a Codex id is `rollout-<timestamp>-<uuid>`, and
    /// the name was built from a 24-character prefix, which ends inside the
    /// timestamp at the minute. Everything that distinguishes two sessions
    /// started in the same minute was cut off.
    #[test]
    fn two_sessions_never_share_a_name() {
        let first = name_for_session("codex", "rollout-2026-08-06T16-47-27-019fd565-d014-7b71");
        let second = name_for_session("codex", "rollout-2026-08-06T16-47-59-019fd999-aaaa-8c62");
        assert_ne!(
            first, second,
            "two Codex sessions from the same minute share a rmux session"
        );

        // The same for ids that differ only at the very end, which is where a
        // uuid keeps most of what makes it one.
        assert_ne!(
            name_for_session("claude", "32cca860-b503-43f8-8b95-7b75880abb8a"),
            name_for_session("claude", "32cca860-b503-43f8-8b95-7b75880abb8b")
        );

        // And a provider name that is a prefix of another's must not let one
        // provider's session wear the other's name.
        assert_ne!(
            name_for_session("code", "x-abc"),
            name_for_session("codex", "abc")
        );
    }

    /// rmux reads `.` and `:` as address syntax, so a name carrying either would
    /// target something other than the session meant — including, for a `:`,
    /// a *window* of it.
    #[test]
    fn names_carry_nothing_rmux_would_read_as_an_address() {
        for name in [
            name_for_session("claude", "/home/x/proj:1.2"),
            free_name("claude --resume /a/b"),
            sanitize("--leading and trailing--"),
        ] {
            assert!(
                !name.contains(['.', ':', ' ', '/']),
                "unsafe rmux name: {name}"
            );
            assert!(!name.starts_with('-') && !name.ends_with('-'), "{name}");
            assert!(!name.contains("--"), "collapsed runs: {name}");
        }
    }

    /// Every name is inside cctop's namespace, which is what keeps the kill and
    /// list paths off a user's own rmux sessions.
    #[test]
    fn names_stay_inside_the_cctop_namespace() {
        assert!(name_for_session("claude", "abc").starts_with("cctop-"));
        assert!(free_name("zsh").starts_with("cctop-"));
    }

    /// Finding the agent behind a session is the whole point of handing one to
    /// rmux and still knowing what it is doing: the pid reported here is what
    /// every hook, transcript, and table row is keyed by. Nothing smaller than a
    /// real server tests it, since the answer comes from rmux itself.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_session_reports_the_agent_inside_it() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        // Unique per test process, so a run never adopts or kills a session
        // belonging to a real cctop on the same machine.
        let ours = format!("cctop-probe-{}", std::process::id());
        let theirs = format!("outside-probe-{}", std::process::id());
        let dir = std::env::temp_dir();

        for name in [&ours, &theirs] {
            start_session(name, Some(&dir), &["sh", "-c", "sleep 30"]);
        }

        let found = wait_for(|| running().into_iter().find(|s| s.name == ours));
        let pid = agent_pid(&ours);
        let listed = sessions();
        let outsider = running().into_iter().any(|s| s.name == theirs);
        // The reverse lookup, which is what lets `a` on a session row reach an
        // agent that cctop put in rmux rather than telling the user cctop never
        // started it.
        let back = pid.and_then(holding);
        // Quieting the session is best effort, but it has to actually land: the
        // status bar it removes is what made an idle pane look busy forever.
        quiet(&ours);
        let status = Command::new(BIN)
            .args(["show-options", "-t", &ours, "status"])
            .output()
            .ok()
            .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_string());
        for name in [&ours, &theirs] {
            end_session(name);
        }

        let found = found.expect("the session cctop just created was not listed");
        // The pid is the pane's own child — the agent — and not a client's.
        assert_eq!(found.pid, pid, "the two ways of asking disagreed");
        assert!(found.pid.is_some_and(|p| p > 0), "no agent pid: {found:?}");
        assert_eq!(found.cwd.as_deref(), Some(dir.as_path()));
        // Nothing is looking at it: it was created detached.
        assert!(!found.attached);
        assert!(listed.contains(&ours));

        // Pid to session and back again agree, or `a` on a rmux-backed agent has
        // no way to find the session holding it.
        assert_eq!(back.as_deref(), Some(ours.as_str()));
        assert_eq!(status.as_deref(), Some("status off"), "status bar left on");

        // The namespace holds, which is what keeps every path here off a user's
        // own sessions.
        assert!(!outsider, "a session outside cctop's namespace was listed");
        assert!(!listed.contains(&theirs));

        // And once it is gone there is no agent to name.
        assert_eq!(agent_pid(&ours), None);
        assert!(!exists(&ours));
    }

    /// Two options on one session, read back off one listing.
    ///
    /// The profile is written beside the label because it has the same problem:
    /// it exists only in the process that chose it, and every other cctop — and
    /// this one after a tab switch — has nothing but the session. Worth a real
    /// server because the failure mode is positional: both arrive as fields of
    /// one `-F` line, an unset one comes back as the empty string rather than as
    /// a missing field, and reading them in the wrong order would put an account
    /// name in the tab bar.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_session_remembers_which_account_its_agent_runs_as() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let named = format!("cctop-probe-named-{}", std::process::id());
        let plain = format!("cctop-probe-plain-{}", std::process::id());
        for name in [&named, &plain] {
            start_session(name, None, &["sh", "-c", "sleep 30"]);
        }
        set_profile(&named, "work");
        // Deliberately no label on this one: the label field then reads back
        // empty, and the profile after it must still be the profile.
        let found = wait_for(|| running().into_iter().find(|s| s.name == named));
        let bare = running().into_iter().find(|s| s.name == plain);
        for name in [&named, &plain] {
            end_session(name);
        }

        let found = found.expect("the session cctop just created was not listed");
        assert_eq!(found.profile.as_deref(), Some("work"));
        assert_eq!(found.label, None);
        // The default account writes nothing, and nothing is what it reads as —
        // not an empty string that would name a profile no one has.
        assert_eq!(bare.and_then(|s| s.profile), None);
    }

    /// The colour written onto a session comes back off it, and clearing it
    /// comes back as nothing — the empty string and the absent option read
    /// alike, which is what makes "no colour" writable at all.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_session_remembers_the_colour_its_tab_was_painted() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let ours = format!("cctop-probe-color-{}", std::process::id());
        start_session(&ours, None, &["sh", "-c", "sleep 30"]);

        let before = wait_for(|| running().into_iter().find(|s| s.name == ours));
        set_color(&ours, "violet");
        let painted = wait_for(|| {
            running()
                .into_iter()
                .find(|s| s.name == ours && s.color.is_some())
        });
        set_color(&ours, "");
        let cleared = wait_for(|| {
            running()
                .into_iter()
                .find(|s| s.name == ours && s.color.is_none())
        });
        end_session(&ours);

        assert_eq!(
            before
                .expect("the session cctop just created was not listed")
                .color,
            None,
            "a fresh session claimed a colour"
        );
        assert_eq!(
            painted.and_then(|s| s.color).as_deref(),
            Some("violet"),
            "the colour written did not come back"
        );
        assert!(cleared.is_some(), "the cleared colour was still reported");
    }

    /// A pane's scrollback is fixed when the pane is made, so the only proof
    /// [`prepare`] works is a real session reporting what its pane actually got
    /// — the option can read back as set while the pane still holds rmux's 2000.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_prepared_session_holds_the_agent_with_room_to_scroll_back() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let name = format!("cctop-prep-{}", std::process::id());
        let dir = std::env::temp_dir();
        let argv = vec!["sh".to_string(), "-c".to_string(), "sleep 30".to_string()];

        // The one session here that cannot go through [`start_session`], since
        // making it *is* what is under test — so the retry it would have given
        // is spelled out. `prepare` is best effort by design and says nothing
        // when the daemon it reached was shutting down; asking again is the
        // same cure for the same race.
        for _ in 0..20 {
            prepare(&argv, &name, Some(&dir));
            if exists(&name) {
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(100));
        }
        let ask = |fmt: &str| {
            Command::new(BIN)
                .args(["display-message", "-p", "-t", &name, fmt])
                .output()
                .ok()
                .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_string())
        };
        let history = wait_for(|| ask("#{history_limit}"));
        let windows = ask("#{session_windows}");
        let mouse = ask("#{mouse}");
        let agent = agent_pid(&name);
        end_session(&name);

        assert_eq!(
            history.as_deref(),
            Some(HISTORY_LINES),
            "the agent's pane kept rmux's default scrollback"
        );
        assert_eq!(mouse.as_deref(), Some("1"), "the wheel would do nothing");
        // The placeholder is gone: a second window would leave the agent sharing
        // a session with a `sleep`, and every lookup here assumes the one pane.
        assert_eq!(
            windows.as_deref(),
            Some("1"),
            "placeholder window left over"
        );
        assert!(agent.is_some_and(|p| p > 0), "no agent in the session");
    }

    /// The flag is the pane program's own answer, so it can only be checked
    /// against real panes: one whose program emitted `?1000h` reads as wanting
    /// the mouse, and one running a plain `sleep` does not.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn mouse_wanted_is_the_pane_programs_own_answer() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let asked = format!("cctop-mw-yes-{}", std::process::id());
        let asleep = format!("cctop-mw-no-{}", std::process::id());
        start_session(
            &asked,
            None,
            &["sh", "-c", "printf '\\033[?1000h'; sleep 30"],
        );
        start_session(&asleep, None, &["sleep", "30"]);

        // The flag lands when the program's DECSET does, and "not yet" reads
        // the same as "never" — so the wanting side is the one waited on.
        let wanted = wait_for(|| mouse_wanted(&asked).then_some(()));
        let quiet = mouse_wanted(&asleep);
        end_session(&asked);
        end_session(&asleep);

        assert!(wanted.is_some(), "the pane's DECSET never reached rmux");
        assert!(!quiet, "a pane that never asked read as asking");
    }

    /// An agent nobody is attached to still has to read as busy while it is
    /// printing. `session_activity` does not say so — rmux advances that on
    /// client activity, so a detached session's stands still — and reading it
    /// blinked every unwatched working tab as if it were asking a question.
    /// Only a real detached session producing output shows the difference.
    #[test]
    #[ignore = "needs a real rmux server"]
    fn a_detached_session_that_is_printing_never_reads_as_quiet() {
        if !available() {
            eprintln!("skipping: rmux not installed");
            return;
        }
        let _turn = test_lock();
        let ours = format!("cctop-probe-busy-{}", std::process::id());
        start_session(
            &ours,
            None,
            &["sh", "-c", "while true; do date; sleep 0.2; done"],
        );

        let now = || {
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_secs())
                .unwrap_or(0)
        };
        let reading = || {
            running()
                .into_iter()
                .find(|s| s.name == ours)
                .and_then(|s| s.activity)
        };
        let first = wait_for(reading);

        // Poll rather than sleep a fixed interval and sample once. Under a
        // loaded `cargo test` the printing loop, the rmux call and even
        // teardown can each take seconds, so a single reading after a fixed
        // sleep flaked on scheduling rather than on the clock. What is waited
        // for is still the whole claim: the clock has moved well past the
        // first reading — more than the one bump a session's creation could
        // give `session_activity` — *and* is current at the moment it was
        // read. `now` is taken before asking, so a slow answer is not held
        // against the reading it returns. A clock that only moves on
        // keystrokes never gets there, however long the deadline.
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(30);
        let mut last = None;
        let moved = first.and_then(|first| {
            loop {
                let asked_at = now();
                let later = reading();
                last = later.map(|later| (later, asked_at));
                if let Some(later) = later
                    && later >= first + 2
                    && asked_at.saturating_sub(later) <= 2
                {
                    break Some(later);
                }
                if std::time::Instant::now() >= deadline {
                    break None;
                }
                std::thread::sleep(std::time::Duration::from_millis(200));
            }
        });
        end_session(&ours);

        let first = first.expect("no activity reported for a session that is printing");
        assert!(
            moved.is_some(),
            "the clock stood still or lagged while the agent printed: \
             first {first}, last (reading, asked at) {last:?}"
        );
    }

    /// Start a detached session for a test, waiting out a daemon that is still
    /// shutting down.
    ///
    /// The backstop behind [`end_session`]. Even with every test waiting for
    /// its own sessions to go, the server's exit is its own asynchronous thing:
    /// `kill-session` answers before the socket is closed, so a `new-session`
    /// aimed at it can still come back `Connection reset by peer` and fail a
    /// test that has nothing to do with shutdown. There is nothing to wait
    /// *for* here — the dying socket is replaced by the one the next
    /// `new-session` starts — so the cure is to ask again. A call that is
    /// wrong rather than early fails exactly as it did before, two seconds
    /// later and carrying rmux's own complaint.
    fn start_session(name: &str, cwd: Option<&Path>, command: &[&str]) {
        let mut last = String::new();
        for attempt in 0..20 {
            if attempt > 0 {
                std::thread::sleep(std::time::Duration::from_millis(100));
            }
            let mut rmux = Command::new(BIN);
            rmux.args(["new-session", "-d", "-s", name]);
            if let Some(dir) = cwd {
                rmux.args(["-c", &dir.to_string_lossy()]);
            }
            rmux.arg("--").args(command);
            match rmux.output() {
                Ok(out) if out.status.success() => return,
                Ok(out) => last = String::from_utf8_lossy(&out.stderr).trim().to_string(),
                Err(e) => last = e.to_string(),
            }
        }
        panic!("could not start {name}: {last}");
    }

    /// End a session and wait for it to actually be gone.
    ///
    /// Killing the last session stops the server, and a `new-session` that
    /// reaches the socket while it is on its way down fails outright — so a
    /// test that released [`test_lock`] the moment `kill` returned would hand
    /// the next one a daemon mid-shutdown. That is the race [`test_lock`]
    /// exists for, and serialising the tests does not close it on its own.
    ///
    /// Every test that makes a session ends it through here, so no test's
    /// teardown is the one that leaves the next a closing socket.
    fn end_session(name: &str) {
        let _ = kill(name);
        wait_for(|| (!exists(name)).then_some(()));
    }

    /// rmux creates sessions and spawns their commands asynchronously, so poll
    /// rather than guess a sleep long enough for a loaded runner.
    fn wait_for<T>(mut f: impl FnMut() -> Option<T>) -> Option<T> {
        for _ in 0..50 {
            if let Some(v) = f() {
                return Some(v);
            }
            std::thread::sleep(std::time::Duration::from_millis(100));
        }
        None
    }
}