Skip to content

armgit / agtx

Public Imported from GitHub
0

πŸ„πŸΌβ€β™‚οΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.

39.0 KB
Raw Blame
//! Non-blocking pane input: the path a keystroke takes from the popup to tmux.
//!
//! ```text
//! crossterm key event
//!         β”‚
//!         β–Ό
//!  PaneInputSink::send      (TUI thread β€” enqueue only, never waits for tmux)
//!         β”‚
//!   bounded channel
//!         β”‚
//!         β–Ό
//!   one broker thread ── coalesces adjacent text, flushes before every key
//!         β”‚
//!         β”œβ”€β–Ί control-mode client   (persistent process, cheap per command)
//!         └─► subprocess fallback   (`tmux send-keys`, one process per command)
//! ```
//!
//! The broker is the **single ordering authority** for popup input. Nothing else
//! may write keys to a task pane while a popup is open: `Text("abc")`,
//! `Key("Left")`, `Text("X")`, `Key("Enter")` must reach tmux in that order, and
//! they do because one thread executes them in receive order β€” across batching,
//! across a backend switch, and across a reconnect.
//!
//! Coalescing is what makes fast typing cheap: adjacent characters for the same
//! target become one `send-keys -l`. It is bounded by a few milliseconds and by
//! a byte cap, and **never** delays a key that is not literal text, because a
//! delayed Enter is a visibly broken editor.

use anyhow::Result;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::mpsc::{Receiver, RecvTimeoutError, SyncSender, TrySendError};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use super::control::{tmux_quote, ControlClient};
use super::operations::{CaptureSpec, PaneSnapshot, PANE_METRICS_FORMAT};
use super::TmuxOperations;

/// One request to put something into a pane.
///
/// Typed rather than preformatted tmux commands: the broker has to be able to
/// tell literal text from a key name to decide what may be batched, and a
/// formatted `send-keys` string has already thrown that distinction away.
#[derive(Debug, Clone)]
pub enum PaneInput {
    /// Literal text (`send-keys -l`). Never goes through tmux's key-name lookup,
    /// so text that spells `Space` or `Up` stays text.
    Text { target: String, text: String },
    /// A tmux **key name** (`Enter`, `Escape`, `C-c`, `M-b`, `F5`).
    Key { target: String, key: String },
    /// A whole block of text, bracketed-paste semantics.
    Paste { target: String, text: String },
    /// Deliver everything buffered now. Sent when a popup closes or changes
    /// target, so queued text can never land in a different task's pane.
    Flush,
    /// Flush and acknowledge only after the active backend has executed every
    /// preceding command. This is the ownership boundary used before the TUI
    /// performs a synchronous tmux operation outside the broker.
    Barrier { ack: std::sync::mpsc::Sender<bool> },
    /// Read a pane's content and geometry back over the same connection.
    ///
    /// A *read* in an input queue looks out of place until you ask what it is
    /// ordered against: the capture must show the keys typed before it, and the
    /// broker is the only thing that knows whether those have been flushed. It
    /// is also far cheaper here than as a pair of `tmux` processes, which is
    /// where the popup's echo lag came from.
    ///
    /// The reply is `None` when there is no control connection β€” the caller
    /// then falls back to the subprocess capture, which is where it started.
    Capture {
        target: String,
        spec: CaptureSpec,
        ack: std::sync::mpsc::Sender<Option<PaneSnapshot>>,
    },
    /// Flush, then stop the broker.
    Shutdown,
}

impl PaneInput {
    /// The pane this request is for, if it names one.
    pub fn target(&self) -> Option<&str> {
        match self {
            PaneInput::Text { target, .. }
            | PaneInput::Key { target, .. }
            | PaneInput::Paste { target, .. }
            | PaneInput::Capture { target, .. } => Some(target),
            PaneInput::Flush | PaneInput::Barrier { .. } | PaneInput::Shutdown => None,
        }
    }
}

impl PartialEq for PaneInput {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::Text { target: a, text: b }, Self::Text { target: c, text: d }) => {
                a == c && b == d
            }
            (Self::Key { target: a, key: b }, Self::Key { target: c, key: d }) => a == c && b == d,
            (Self::Paste { target: a, text: b }, Self::Paste { target: c, text: d }) => {
                a == c && b == d
            }
            (
                Self::Capture {
                    target: a, spec: b, ..
                },
                Self::Capture {
                    target: c, spec: d, ..
                },
            ) => a == c && b == d,
            (Self::Flush, Self::Flush)
            | (Self::Barrier { .. }, Self::Barrier { .. })
            | (Self::Shutdown, Self::Shutdown) => true,
            _ => false,
        }
    }
}

impl Eq for PaneInput {}

/// Why an enqueue failed. Named, because the caller's recovery differs per case
/// and "the input was dropped" must never be silent.
#[derive(Debug, Clone, thiserror::Error, PartialEq, Eq)]
pub enum InputError {
    /// The broker is behind and the bounded queue is full.
    #[error("pane input queue is full")]
    QueueFull,
    /// The broker thread is gone.
    #[error("pane input broker is not running")]
    Disconnected,
    /// An acknowledged flush was not answered in time. The queued prefix is
    /// still being delivered β€” it is *late*, not lost, which is why this is not
    /// `Disconnected`: that variant tells the user to restart agtx, and here
    /// there is nothing wrong to restart.
    #[error("pane input did not drain in time")]
    Timeout,
}

/// Where popup input is handed off. Implementations must not block the caller.
pub trait PaneInputSink: Send + Sync {
    fn send(&self, input: PaneInput) -> std::result::Result<(), InputError>;

    fn text(&self, target: &str, text: &str) -> std::result::Result<(), InputError> {
        self.send(PaneInput::Text {
            target: target.to_string(),
            text: text.to_string(),
        })
    }

    fn key(&self, target: &str, key: &str) -> std::result::Result<(), InputError> {
        self.send(PaneInput::Key {
            target: target.to_string(),
            key: key.to_string(),
        })
    }

    fn paste(&self, target: &str, text: &str) -> std::result::Result<(), InputError> {
        self.send(PaneInput::Paste {
            target: target.to_string(),
            text: text.to_string(),
        })
    }

    fn flush(&self) -> std::result::Result<(), InputError> {
        self.send(PaneInput::Flush)
    }

    /// Flush and wait until tmux has executed the queued prefix.
    ///
    /// The default keeps test/embedding sinks simple. The production broker
    /// overrides this with an acknowledged barrier.
    fn flush_sync(&self) -> std::result::Result<(), InputError> {
        self.flush()
    }

    /// Deliver what is queued and stop. Called when agtx exits, so the last
    /// characters typed into a pane are not lost with the process.
    fn shutdown(&self) {
        let _ = self.flush();
    }

    /// Capture a pane over the input connection, if there is one.
    ///
    /// `None` means "not available here" β€” no control connection, a full queue,
    /// a wedged broker β€” and every caller must have a subprocess capture to fall
    /// back to. It is deliberately not an error type: a missed capture costs one
    /// frame at the fallback's speed, which is not worth a code path of its own.
    fn capture(&self, _target: &str, _spec: CaptureSpec) -> Option<PaneSnapshot> {
        None
    }

    /// Point future control-mode connections at a different session.
    ///
    /// agtx switches project in place, and a session that no longer exists is
    /// one the control client cannot attach to. An **already open** connection
    /// is left alone on purpose: commands carry their own target and are
    /// executed server-wide, so a client attached to the previous project still
    /// delivers correctly. This only matters for the next connect.
    fn set_session(&self, _session: &str) {}
}

/// What the broker writes through. Two implementations ship: the persistent
/// control client and the one-process-per-command fallback.
pub(crate) trait PaneBackend: Send {
    fn text(&mut self, target: &str, text: &str) -> Result<()>;
    fn key(&mut self, target: &str, key: &str) -> Result<()>;
    fn paste(&mut self, target: &str, text: &str) -> Result<()>;
    /// Block until everything written so far has actually been executed.
    /// A no-op for a backend that is synchronous anyway.
    fn barrier(&mut self) -> bool {
        true
    }
    /// Read a pane back. Only the control backend implements this: on the
    /// subprocess path the caller's own `capture-pane` is the same two processes
    /// for the same cost, so routing it through the broker would buy nothing and
    /// block the input thread behind it.
    fn capture(&mut self, _target: &str, _spec: CaptureSpec) -> Result<PaneSnapshot> {
        anyhow::bail!("capture is not supported on the {} backend", self.label())
    }
    fn healthy(&self) -> bool {
        true
    }
    fn label(&self) -> &'static str;
}

/// The historical path: one `tmux` process per command, via [`TmuxOperations`]
/// so test mocks keep working unchanged.
pub(crate) struct SubprocessBackend {
    ops: Arc<dyn TmuxOperations>,
}

impl SubprocessBackend {
    pub(crate) fn new(ops: Arc<dyn TmuxOperations>) -> Self {
        Self { ops }
    }
}

impl PaneBackend for SubprocessBackend {
    fn text(&mut self, target: &str, text: &str) -> Result<()> {
        self.ops.send_text(target, text)
    }
    fn key(&mut self, target: &str, key: &str) -> Result<()> {
        self.ops.send_key(target, key)
    }
    fn paste(&mut self, target: &str, text: &str) -> Result<()> {
        self.ops.paste_text(target, text)
    }
    fn label(&self) -> &'static str {
        "subprocess"
    }
}

/// The persistent path. Keys and text go down the control connection; a paste
/// still goes through `load-buffer`, which needs a pipe rather than a command
/// argument, so it is delegated β€” behind a barrier, because the two travel
/// different sockets and only the barrier keeps them ordered.
pub(crate) struct ControlBackend {
    /// `Option` only so [`Drop`] can move the client out and close it. A dropped
    /// `ControlClient` would otherwise leave an attached `tmux -C` process
    /// running for the life of the server β€” one per reconnect.
    client: Option<ControlClient>,
    paste_via: SubprocessBackend,
}

impl ControlBackend {
    pub(crate) fn new(client: ControlClient, ops: Arc<dyn TmuxOperations>) -> Self {
        Self {
            client: Some(client),
            paste_via: SubprocessBackend::new(ops),
        }
    }

    fn client(&mut self) -> Result<&mut ControlClient> {
        self.client
            .as_mut()
            .ok_or_else(|| anyhow::anyhow!("control client already closed"))
    }
}

impl Drop for ControlBackend {
    fn drop(&mut self) {
        if let Some(client) = self.client.take() {
            client.shutdown();
        }
    }
}

/// How long a barrier waits before giving up and letting the paste race. Chosen
/// well above a healthy round trip: reaching it means tmux is wedged, and
/// blocking the broker further would not help.
const BARRIER_TIMEOUT: Duration = Duration::from_millis(250);

/// How long a pane capture waits for its reply.
///
/// Not a budget but a wedge detector: a healthy round trip is far below it. It
/// is generous because it is paid on a background refresh thread, not on the
/// input path, and because giving up costs one frame at the fallback's speed,
/// not a dropped keystroke.
const CAPTURE_TIMEOUT: Duration = Duration::from_millis(250);

/// How long the *caller* waits for a capture, queue time included.
///
/// Longer than [`CAPTURE_TIMEOUT`] on purpose: that one bounds the tmux round
/// trip, this one also covers whatever is queued ahead of the request. Same
/// distinction as [`FLUSH_SYNC_TIMEOUT`] against [`BARRIER_TIMEOUT`].
const CAPTURE_ACK_TIMEOUT: Duration = Duration::from_millis(750);

impl PaneBackend for ControlBackend {
    fn text(&mut self, target: &str, text: &str) -> Result<()> {
        let cmd = format!(
            "send-keys -t {} -l -- {}",
            tmux_quote(target),
            tmux_quote(text)
        );
        self.client()?.write_command(&cmd)
    }
    fn key(&mut self, target: &str, key: &str) -> Result<()> {
        // No `-l`: this is exactly the key-name lookup `send_key` documents, and
        // the reason a key and literal text cannot share one request type.
        let cmd = format!("send-keys -t {} -- {}", tmux_quote(target), tmux_quote(key));
        self.client()?.write_command(&cmd)
    }
    fn paste(&mut self, target: &str, text: &str) -> Result<()> {
        // `load-buffer` needs a pipe, not a command argument, so a paste stays on
        // the subprocess path. It travels a *different* socket, so without the
        // barrier it could overtake text still queued on this connection.
        let _ = self.barrier();
        // Reported, never propagated. The broker reads an `Err` from this
        // backend as an *ambiguous control write* and tears the connection
        // down β€” but nothing was written to it here, and the request already
        // ran on the fallback it would be moved to. Propagating would kill a
        // healthy connection over an unrelated failure.
        if let Err(e) = self.paste_via.paste(target, text) {
            tracing::warn!(error = %e, "pane paste failed on the subprocess backend");
        }
        Ok(())
    }
    fn capture(&mut self, target: &str, spec: CaptureSpec) -> Result<PaneSnapshot> {
        // Both commands in one round trip: they are written back to back and only
        // the last reply is waited for. Fetching them together is also what keeps
        // them consistent β€” the cursor row is an index into the content.
        let mut cmds = vec![format!(
            "capture-pane -t {}{} -p -S -{}",
            tmux_quote(target),
            if spec.escapes { " -e" } else { "" },
            spec.history.max(0)
        )];
        if spec.metrics {
            // Single quotes, not `tmux_quote`: tmux performs no replacements
            // inside them, so `#{cursor_x}` reaches display-message intact
            // instead of being escaped to a literal `\#{cursor_x}`.
            cmds.push(format!(
                "display -p -t {} '{}'",
                tmux_quote(target),
                PANE_METRICS_FORMAT
            ));
        }
        let mut blocks = self.client()?.query(&cmds, CAPTURE_TIMEOUT)?;
        if blocks.len() != cmds.len() {
            anyhow::bail!("expected {} reply blocks, got {}", cmds.len(), blocks.len());
        }
        let metrics = if spec.metrics {
            blocks
                .pop()
                .and_then(|lines| lines.first().and_then(|l| super::parse_pane_metrics(l)))
        } else {
            None
        };
        let lines = blocks.pop().unwrap_or_default();
        // Rebuilt exactly as `capture-pane`'s stdout: one trailing newline per
        // row, so a caller cannot tell the two backends apart.
        let mut content = Vec::new();
        for line in lines {
            content.extend_from_slice(line.as_bytes());
            content.push(b'\n');
        }
        Ok(PaneSnapshot { content, metrics })
    }
    fn barrier(&mut self) -> bool {
        if let Some(client) = self.client.as_mut() {
            let completed = client.barrier(BARRIER_TIMEOUT);
            if !completed {
                tracing::debug!("tmux control barrier timed out");
            }
            completed
        } else {
            false
        }
    }
    fn healthy(&self) -> bool {
        self.client.as_ref().map(|c| c.alive()).unwrap_or(false)
    }
    fn label(&self) -> &'static str {
        "control"
    }
}

/// Why the broker decided to deliver its buffered text.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum FlushReason {
    /// The batching window elapsed.
    Window,
    /// The queue ran dry, so the buffered text had nothing left to join.
    Idle,
    /// A non-text request came next.
    BeforeKey,
    /// The next text is for a different pane.
    TargetChange,
    /// The buffer hit its byte cap.
    Full,
    /// A `Flush` request.
    Explicit,
    /// The broker is stopping.
    Shutdown,
}

/// How long adjacent characters may wait to be combined **during a burst**.
///
/// It is not paid by ordinary typing: text is flushed as soon as the queue is
/// empty, and between two keystrokes a human makes it always is. That is the
/// difference between taxing every character and charging only while characters
/// are genuinely backed up.
///
/// So this bounds how long a *backlog* may keep growing before it goes out, and
/// raising it trades echo latency for fewer commands only in that case.
pub const DEFAULT_BATCH_WINDOW: Duration = Duration::from_millis(2);

/// Byte cap on one coalesced `send-keys`. Well under any command-length limit,
/// and it bounds how much text a single failed write can lose.
const MAX_BATCH_BYTES: usize = 4096;

/// Bounded queue depth. Deep enough that a human cannot fill it (it is ~40
/// seconds of typing at 25 keys/s) and shallow enough to bound memory if tmux
/// stops consuming.
pub const DEFAULT_QUEUE_CAPACITY: usize = 1024;

/// Reconnect backoff bounds for the control client.
const RECONNECT_MIN: Duration = Duration::from_millis(250);
const RECONNECT_MAX: Duration = Duration::from_secs(5);

/// How long an acknowledged flush waits for the broker to answer.
///
/// **Not** a second copy of [`BARRIER_TIMEOUT`]. The barrier sits *behind the
/// queue*, so this wait is dominated by draining whatever is already in it β€” and
/// on the subprocess backend every queued command is its own process, so a
/// barrier-sized budget expires mid-drain and hands back a guarantee that was
/// not kept.
///
/// So this is the "the broker is wedged" guard instead. The work it waits on is
/// the user's own keystrokes, so in practice it returns in microseconds; the cap
/// only exists so a hung tmux cannot freeze the TUI thread forever.
const FLUSH_SYNC_TIMEOUT: Duration = Duration::from_secs(2);

/// Bounds on quitting: how long to keep trying to enqueue the stop request, and
/// how long to wait for the broker's final flush afterwards.
const SHUTDOWN_ENQUEUE_WAIT: Duration = Duration::from_millis(200);
const SHUTDOWN_DRAIN_WAIT: Duration = Duration::from_millis(500);

/// How to build the input pipeline.
#[derive(Debug, Clone)]
pub struct InputConfig {
    /// tmux server name (`-L`).
    pub server: String,
    /// Session the control client attaches to. Commands still carry their own
    /// targets; this is only an attach point.
    pub session: String,
    /// Try the persistent control-mode backend. On by default; a failure to
    /// connect, or a connection lost later, falls back to the subprocess
    /// backend on its own. See `control_mode_enabled` for the escape hatch.
    pub control_mode: bool,
    pub batch_window: Duration,
    pub capacity: usize,
    /// Raised by the control connection when tmux reports a window closing, so
    /// the status refresh can look immediately instead of on its next tick.
    /// `None` disables the reporting.
    pub window_events: Option<Arc<AtomicBool>>,
}

impl InputConfig {
    pub fn new(server: impl Into<String>, session: impl Into<String>) -> Self {
        Self {
            server: server.into(),
            session: session.into(),
            control_mode: true,
            batch_window: DEFAULT_BATCH_WINDOW,
            capacity: DEFAULT_QUEUE_CAPACITY,
            window_events: None,
        }
    }
}

/// Handle held by the TUI. `send` is an enqueue and nothing else.
pub struct BrokerSink {
    tx: SyncSender<PaneInput>,
    depth: Arc<AtomicUsize>,
    high_water: Arc<AtomicUsize>,
    /// Read by the control factory at every connect, so a project switch is
    /// picked up without restarting the broker.
    session: Arc<Mutex<String>>,
    /// Set by the broker as the last thing it does. Lets shutdown wait for the
    /// final flush *without* an unbounded `join` β€” see below.
    finished: Arc<AtomicBool>,
    join: Mutex<Option<std::thread::JoinHandle<()>>>,
}

impl BrokerSink {
    /// Queue depth right now, and the deepest it has ever been. Diagnostics only.
    pub fn depth(&self) -> (usize, usize) {
        (
            self.depth.load(Ordering::Relaxed),
            self.high_water.load(Ordering::Relaxed),
        )
    }
}

impl PaneInputSink for BrokerSink {
    fn set_session(&self, session: &str) {
        if let Ok(mut current) = self.session.lock() {
            if *current != session {
                tracing::debug!(session, "control-mode attach point changed");
                *current = session.to_string();
            }
        }
    }

    /// Flush, stop the broker thread, and wait for it β€” but never forever.
    ///
    /// Quitting must not be able to hang. The broker can be blocked inside a
    /// `tmux` subprocess that is not coming back, and both a blocking `send` and
    /// a plain `join` would then wait for it with no bound. So both steps are
    /// bounded, and if the broker misses its window the thread is simply left to
    /// the exiting process. Safe to call twice.
    fn shutdown(&self) {
        let deadline = Instant::now() + SHUTDOWN_ENQUEUE_WAIT;
        let mut queued = false;
        while Instant::now() < deadline {
            self.depth.fetch_add(1, Ordering::Relaxed);
            match self.tx.try_send(PaneInput::Shutdown) {
                Ok(()) => {
                    queued = true;
                    break;
                }
                // Backed up: give the broker a moment to drain, since what is
                // queued is the user's last keystrokes.
                Err(TrySendError::Full(_)) => {
                    self.depth.fetch_sub(1, Ordering::Relaxed);
                    std::thread::sleep(Duration::from_millis(5));
                }
                Err(TrySendError::Disconnected(_)) => {
                    self.depth.fetch_sub(1, Ordering::Relaxed);
                    queued = true;
                    break;
                }
            }
        }
        if !queued {
            tracing::warn!("pane input broker did not accept shutdown; leaving it to exit");
            return;
        }
        let deadline = Instant::now() + SHUTDOWN_DRAIN_WAIT;
        while !self.finished.load(Ordering::Relaxed) {
            if Instant::now() >= deadline {
                tracing::warn!("pane input broker did not finish draining in time");
                return;
            }
            std::thread::sleep(Duration::from_millis(2));
        }
        if let Ok(mut join) = self.join.lock() {
            if let Some(handle) = join.take() {
                let _ = handle.join();
            }
        }
    }

    fn capture(&self, target: &str, spec: CaptureSpec) -> Option<PaneSnapshot> {
        let (ack, done) = std::sync::mpsc::channel();
        self.send(PaneInput::Capture {
            target: target.to_string(),
            spec,
            ack,
        })
        .ok()?;
        // Bounded by the same reasoning as the broker's own timeout, plus the
        // queue ahead of it: this runs on the popup's refresh thread, so waiting
        // costs a frame and never a keystroke.
        done.recv_timeout(CAPTURE_ACK_TIMEOUT).ok().flatten()
    }

    fn flush_sync(&self) -> std::result::Result<(), InputError> {
        let (ack, done) = std::sync::mpsc::channel();
        self.send(PaneInput::Barrier { ack })?;
        match done.recv_timeout(FLUSH_SYNC_TIMEOUT) {
            Ok(true) => Ok(()),
            // The control barrier gave up; the broker is alive and answered.
            Ok(false) => Err(InputError::Timeout),
            Err(std::sync::mpsc::RecvTimeoutError::Timeout) => Err(InputError::Timeout),
            Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => Err(InputError::Disconnected),
        }
    }

    fn send(&self, input: PaneInput) -> std::result::Result<(), InputError> {
        // Counted *before* the send, and rolled back if it fails. The other
        // order is a race: the broker can receive and decrement between the
        // successful `try_send` and this `fetch_add`, taking the counter below
        // zero β€” which on a `usize` is not a small error but `usize::MAX`.
        // Over-counting for a few nanoseconds is the harmless direction.
        let depth = self.depth.fetch_add(1, Ordering::Relaxed) + 1;
        self.high_water.fetch_max(depth, Ordering::Relaxed);
        match self.tx.try_send(input) {
            Ok(()) => Ok(()),
            Err(TrySendError::Full(_)) => {
                self.depth.fetch_sub(1, Ordering::Relaxed);
                Err(InputError::QueueFull)
            }
            Err(TrySendError::Disconnected(_)) => {
                self.depth.fetch_sub(1, Ordering::Relaxed);
                Err(InputError::Disconnected)
            }
        }
    }
}

/// Start the broker thread and return the sink the TUI enqueues into.
pub fn spawn(config: InputConfig, ops: Arc<dyn TmuxOperations>) -> Arc<BrokerSink> {
    let (tx, rx) = std::sync::mpsc::sync_channel(config.capacity);
    let depth = Arc::new(AtomicUsize::new(0));
    let high_water = Arc::new(AtomicUsize::new(0));
    let session = Arc::new(Mutex::new(config.session.clone()));
    let finished = Arc::new(AtomicBool::new(false));

    let control_factory: Option<ControlFactory> = if config.control_mode {
        let server = config.server.clone();
        let session = Arc::clone(&session);
        let ops = Arc::clone(&ops);
        let window_events = config.window_events.clone();
        Some(Box::new(move |generation| {
            let attach = session
                .lock()
                .map(|s| s.clone())
                .map_err(|_| anyhow::anyhow!("attach session poisoned"))?;
            let client =
                ControlClient::connect_with(&server, &attach, generation, window_events.clone())?;
            Ok(Box::new(ControlBackend::new(client, Arc::clone(&ops))) as Box<dyn PaneBackend>)
        }))
    } else {
        None
    };

    let broker = Broker {
        rx,
        depth: Arc::clone(&depth),
        batch_window: config.batch_window,
        fallback: Box::new(SubprocessBackend::new(ops)),
        control: None,
        control_factory,
        generation: 0,
        next_attempt: Some(Instant::now()),
        backoff: RECONNECT_MIN,
        pending: None,
        deadline: None,
        fallbacks: 0,
        finished: Arc::clone(&finished),
    };

    let join = std::thread::Builder::new()
        .name("agtx-pane-input".to_string())
        .spawn(move || broker.run())
        .ok();
    if join.is_none() {
        // Nothing will ever set `finished`, and `shutdown` would then wait out
        // its whole drain budget on every quit. Mark it done now; the sink's
        // sends fail with `Disconnected`, which the TUI already surfaces.
        tracing::error!("failed to start the pane input broker thread");
        finished.store(true, Ordering::Relaxed);
    }

    Arc::new(BrokerSink {
        tx,
        depth,
        high_water,
        session,
        finished,
        join: Mutex::new(join),
    })
}

type ControlFactory = Box<dyn FnMut(u64) -> Result<Box<dyn PaneBackend>> + Send>;

pub(crate) struct Broker {
    rx: Receiver<PaneInput>,
    depth: Arc<AtomicUsize>,
    batch_window: Duration,
    fallback: Box<dyn PaneBackend>,
    control: Option<Box<dyn PaneBackend>>,
    control_factory: Option<ControlFactory>,
    generation: u64,
    next_attempt: Option<Instant>,
    backoff: Duration,
    pending: Option<(String, String)>,
    deadline: Option<Instant>,
    fallbacks: u64,
    finished: Arc<AtomicBool>,
}

impl Broker {
    pub(crate) fn run(mut self) {
        loop {
            let next = match self.deadline {
                Some(deadline) => {
                    let wait = deadline.saturating_duration_since(Instant::now());
                    match self.rx.recv_timeout(wait) {
                        Ok(input) => Some(input),
                        Err(RecvTimeoutError::Timeout) => {
                            self.flush(FlushReason::Window);
                            continue;
                        }
                        Err(RecvTimeoutError::Disconnected) => None,
                    }
                }
                None => self.rx.recv().ok(),
            };

            let Some(input) = next else {
                // Every sink handle was dropped: deliver what is buffered rather
                // than losing the last word the user typed.
                self.flush(FlushReason::Shutdown);
                break;
            };
            self.depth.fetch_sub(1, Ordering::Relaxed);

            match input {
                PaneInput::Text { target, text } => self.push_text(target, text),
                PaneInput::Key { target, key } => {
                    self.flush(FlushReason::BeforeKey);
                    self.dispatch(|b| b.key(&target, &key), "key");
                }
                PaneInput::Paste { target, text } => {
                    self.flush(FlushReason::BeforeKey);
                    let len = text.len();
                    self.dispatch(|b| b.paste(&target, &text), "paste");
                    tracing::debug!(bytes = len, "pane paste delivered");
                }
                PaneInput::Capture { target, spec, ack } => {
                    // Ordered against the keys, not merely concurrent with them:
                    // a capture that overtook buffered text would render a frame
                    // missing characters the user has already typed, which is
                    // the exact illusion this whole path exists to remove.
                    self.flush(FlushReason::BeforeKey);
                    let snapshot = self.capture(&target, spec);
                    let _ = ack.send(snapshot);
                }
                PaneInput::Flush => self.flush(FlushReason::Explicit),
                PaneInput::Barrier { ack } => {
                    self.flush(FlushReason::Explicit);
                    let completed = self.barrier();
                    let _ = ack.send(completed);
                }
                PaneInput::Shutdown => {
                    self.flush(FlushReason::Shutdown);
                    break;
                }
            }
        }
        if let Some(control) = self.control.take() {
            drop(control);
        }
        self.finished.store(true, Ordering::Relaxed);
    }

    fn push_text(&mut self, target: String, text: String) {
        match &mut self.pending {
            Some((pending_target, buf)) if *pending_target == target => {
                buf.push_str(&text);
                if buf.len() >= MAX_BATCH_BYTES {
                    self.flush(FlushReason::Full);
                }
            }
            Some(_) => {
                // Different pane: everything buffered belongs to the old one and
                // must land there first.
                self.flush(FlushReason::TargetChange);
                self.pending = Some((target, text));
                self.deadline = Some(Instant::now() + self.batch_window);
            }
            None => {
                self.pending = Some((target, text));
                self.deadline = Some(Instant::now() + self.batch_window);
            }
        }
        // Nothing else is queued, so there is nothing left to coalesce *with*:
        // waiting out the window would add its full length to the echo latency
        // of every keystroke a human types, since at typing speed the broker is
        // always idle between characters. Batching is for bursts β€” a paste
        // arriving as keystrokes, a held key β€” and a burst is exactly the case
        // where this counter is non-zero.
        if self.depth.load(Ordering::Relaxed) == 0 {
            self.flush(FlushReason::Idle);
        }
    }

    fn flush(&mut self, reason: FlushReason) {
        self.deadline = None;
        let Some((target, text)) = self.pending.take() else {
            return;
        };
        let chars = text.chars().count();
        self.dispatch(|b| b.text(&target, &text), "text");
        // Lengths and reasons only: pane input is never logged.
        tracing::trace!(?reason, chars, "pane text flushed");
    }

    fn barrier(&mut self) -> bool {
        match self.control.as_mut() {
            Some(control) if control.healthy() => control.barrier(),
            // The subprocess backend is synchronous. If control died after the
            // preceding dispatch, that dispatch was deliberately treated as
            // ambiguous and cannot be made safer by waiting here.
            _ => true,
        }
    }

    /// Run one operation on the best available backend.
    ///
    /// A control-mode write error is **ambiguous** β€” a partial write may already
    /// have reached tmux β€” so the request is dropped rather than replayed on the
    /// fallback. Repeating an Enter is worse than losing one, and the *next*
    /// request goes to the fallback anyway because the failure marks the
    /// connection dead.
    fn dispatch(&mut self, op: impl FnOnce(&mut dyn PaneBackend) -> Result<()>, kind: &str) {
        self.maybe_connect();
        let started = Instant::now();
        if let Some(control) = self.control.as_mut() {
            if control.healthy() {
                match op(control.as_mut()) {
                    Ok(()) => {
                        tracing::trace!(
                            kind,
                            backend = "control",
                            micros = started.elapsed().as_micros() as u64,
                            "pane input delivered"
                        );
                        return;
                    }
                    Err(e) => {
                        self.drop_control(&format!("write failed: {e}"));
                        tracing::warn!(kind, "pane input dropped after an ambiguous control write");
                        return;
                    }
                }
            }
            self.drop_control("connection closed");
        }
        self.fallbacks += 1;
        if let Err(e) = op(self.fallback.as_mut()) {
            tracing::warn!(kind, error = %e, "pane input failed on the subprocess backend");
        } else {
            tracing::trace!(
                kind,
                backend = "subprocess",
                micros = started.elapsed().as_micros() as u64,
                "pane input delivered"
            );
        }
    }

    /// Capture a pane on the control connection, or `None` if there isn't one.
    ///
    /// Never falls back to the subprocess itself: the caller already owns that
    /// path, and doing it here would block the broker β€” and therefore the next
    /// keystroke β€” behind the `tmux` process startup it would cost.
    fn capture(&mut self, target: &str, spec: CaptureSpec) -> Option<PaneSnapshot> {
        self.maybe_connect();
        let started = Instant::now();
        let outcome = match self.control.as_mut() {
            Some(control) if control.healthy() => control.capture(target, spec),
            Some(_) => Err(anyhow::anyhow!("connection closed")),
            None => return None,
        };
        match outcome {
            Ok(snapshot) => {
                tracing::trace!(
                    bytes = snapshot.content.len(),
                    micros = started.elapsed().as_micros() as u64,
                    "pane captured over the control connection"
                );
                Some(snapshot)
            }
            Err(e) => {
                // A read that failed is not the ambiguous write `dispatch`
                // guards against, so a healthy connection is kept: dropping it
                // over a slow capture would demote every subsequent *keystroke*
                // to the subprocess path to fix a read that is far cheaper.
                if self.control.as_ref().map(|c| c.healthy()) != Some(true) {
                    self.drop_control(&format!("capture failed: {e}"));
                } else {
                    tracing::debug!(error = %e, "pane capture failed; using the subprocess path");
                }
                None
            }
        }
    }

    fn drop_control(&mut self, reason: &str) {
        if self.control.take().is_some() {
            tracing::info!(
                generation = self.generation,
                reason,
                "tmux control connection lost; falling back to subprocess"
            );
        }
        self.next_attempt = Some(Instant::now() + self.backoff);
        self.backoff = (self.backoff * 2).min(RECONNECT_MAX);
    }

    fn maybe_connect(&mut self) {
        if self.control.is_some() || self.control_factory.is_none() {
            return;
        }
        match self.next_attempt {
            Some(at) if Instant::now() < at => return,
            None => return,
            _ => {}
        }
        self.next_attempt = None;
        self.generation += 1;
        let generation = self.generation;
        let factory = self.control_factory.as_mut().expect("checked above");
        match factory(generation) {
            Ok(backend) => {
                tracing::info!(
                    generation,
                    backend = backend.label(),
                    "pane input backend ready"
                );
                self.control = Some(backend);
                self.backoff = RECONNECT_MIN;
            }
            Err(e) => {
                tracing::info!(generation, error = %e, "tmux control connect failed; using subprocess");
                self.next_attempt = Some(Instant::now() + self.backoff);
                self.backoff = (self.backoff * 2).min(RECONNECT_MAX);
            }
        }
    }
}

/// A sink that records requests instead of sending them. For tests that assert
/// what the UI enqueued without needing a tmux server.
#[cfg(any(test, feature = "test-mocks"))]
#[derive(Default)]
pub struct RecordingSink {
    sent: Mutex<Vec<PaneInput>>,
    /// When set, every `send` fails with it β€” for exercising `QueueFull`.
    fail_with: Mutex<Option<InputError>>,
}

#[cfg(any(test, feature = "test-mocks"))]
impl RecordingSink {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn taken(&self) -> Vec<PaneInput> {
        self.sent.lock().map(|s| s.clone()).unwrap_or_default()
    }

    pub fn fail_with(&self, err: InputError) {
        if let Ok(mut slot) = self.fail_with.lock() {
            *slot = Some(err);
        }
    }
}

#[cfg(any(test, feature = "test-mocks"))]
impl PaneInputSink for RecordingSink {
    /// Records the barrier rather than degrading to a plain `Flush`, so a test
    /// can tell the two apart. Without this the default turns `flush_sync` into
    /// `flush` and nothing pins which one a call site asked for.
    fn flush_sync(&self) -> std::result::Result<(), InputError> {
        let (ack, _done) = std::sync::mpsc::channel();
        self.send(PaneInput::Barrier { ack })
    }

    fn send(&self, input: PaneInput) -> std::result::Result<(), InputError> {
        if let Ok(slot) = self.fail_with.lock() {
            if let Some(err) = slot.as_ref() {
                return Err(err.clone());
            }
        }
        if let Ok(mut sent) = self.sent.lock() {
            sent.push(input);
        }
        Ok(())
    }
}

#[cfg(test)]
#[path = "input_tests.rs"]
mod input_tests;