agentmux_srv/backend/blockcontroller/shell/

pty.rs

// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! PTY geometry resolution and platform-specific shell detection.

use portable_pty::PtySize;

use super::controller::ShellController;
use crate::backend::obj::RuntimeOpts;

/// PTY read buffer size (matches Go's 4096).
pub(super) const PTY_READ_BUF_SIZE: usize = 4096;

// There is deliberately no PTY_COALESCE_WINDOW here any more.
//
// It used to be 20ms: how long the output flusher waited, after the first
// chunk of a batch, for more chunks to arrive before broadcasting — added to
// cut the IPC/wakeup rate under a fast producer, per
// `docs/reports/REPORT_RENDERER_CPU_UNBATCHED_PTY_OUTPUT_2026_09_11.md`. Its
// own doc comment argued "20ms is well under human-perceptible latency, so a
// keystroke echo still appears with no felt delay". That was wrong on the
// path that matters: a keystroke into an idle pane echoes exactly one chunk,
// so the window was never satisfied early and every echo paid the full 20ms
// — more than a 60Hz frame — before it was even broadcast.
//
// The flusher now drains only what is already queued (see
// `run_pty_output_flusher`), which keeps the batching the report asked for
// under real bursts while adding nothing when idle. Reintroducing a timed
// wait here would re-break typing; if one is ever genuinely needed for the
// Windows-10 DWM flash that PR #208 originally chased, the bound set by
// SPEC_TERM_DOUBLE_RAF_TEAROUT_2026_05_30 is ~2-4ms, not 20ms.

/// Hard cap on how many bytes one coalesced batch accumulates before it is
/// flushed regardless of the time window — bounds both broadcast latency and
/// memory during a sustained, very fast burst (e.g. `yes` piped through a
/// shell pane). 64x a single PTY_READ_BUF_SIZE read: generous headroom for
/// real bursts (a build's stdout in a 20ms window) while still bounded.
pub(super) const PTY_COALESCE_MAX_BYTES: usize = 64 * PTY_READ_BUF_SIZE;

/// Capacity of the channel handing PTY-read chunks from the blocking read
/// loop to the async coalescing flusher (reagentx P1 on PR #3206).
/// `PTY_COALESCE_MAX_BYTES` only bounds the batch currently being
/// assembled — it does nothing about chunks still sitting in the channel
/// if the flusher falls behind the read rate (slow disk, lock contention,
/// several busy panes at once). An unbounded channel there would let a
/// sustained fast producer (`yes`, a large `cat`) grow queued memory
/// without limit. 128 chunks x up to ~PTY_READ_BUF_SIZE each is ~512KiB of
/// worst-case queued-but-not-yet-batched data per pane — real headroom
/// above one coalesced batch, but strictly bounded. The read loop sends
/// via `blocking_send`, which blocks the calling (already-blocking-pool)
/// thread once the channel is full, propagating real backpressure to the
/// PTY read rate — and from there, via the kernel's own PTY buffer, to the
/// child process itself, the same way a slow terminal reader naturally
/// backpressures a fast writer.
pub(super) const PTY_CHANNEL_CAPACITY: usize = 128;

/// Bound on how long the wait task waits for the coalescing flusher to
/// drain trailing output after the direct child has already been reaped
/// (codex P1 on PR #3206, third round). Normally resolves almost
/// immediately: the read loop observes real PTY EOF once the direct child
/// exits and drops `pty_tx`, closing the flusher's channel. But EOF depends
/// on every process holding the PTY slave fd closing it, not just the
/// direct child — a background descendant that inherited the fd and
/// ignores SIGHUP can keep it open indefinitely, in which case the flusher
/// would never see its channel close and its `JoinHandle` would never
/// resolve on its own. An unbounded await here would then hang child
/// reaping's own downstream cleanup (STATUS_DONE, run_lock release)
/// forever, for a case that must never block them. The original 10s mirrored
/// `persistent/process_waiter.rs`'s stdout-reader bound for the same
/// descendant-held-descriptor scenario: generous enough that normal
/// flushing (one already-queued drain plus a write, milliseconds) never trips
/// it, but a hard ceiling so a genuinely stuck descendant can't hang pane
/// teardown. Unlike `persistent/process_waiter.rs`'s bound, expiry does NOT abort the
/// flusher (reagentx P1 on PR #3206, same round): there, one combined async
/// reader task both reads and processes, so aborting it genuinely stops the
/// read. Here reading (a separate `spawn_blocking` doing a raw, blocking,
/// un-cancellable OS `read()`) and flushing are two different tasks —
/// aborting only the flusher can't reclaim the read loop's thread either
/// way, and would additionally make every later `blocking_send` find the
/// receiver gone and silently drop it, permanently losing any further
/// output from a still-live descendant. Letting the `JoinHandle` simply
/// drop on timeout detaches the flusher (and transitively its read loop)
/// to keep running independently in the background instead, so nothing
/// produced after teardown gives up waiting is silently lost.
///
/// **1s, reduced from 10s (2026-09-15,
/// `docs/specs/SPEC_TERM_EXIT_RESPAWN_LOOP_2026_09_15.md` §12).** The
/// reasoning above is unchanged and still correct — what changed is a
/// measurement of how often the ceiling is actually hit. On Windows this
/// bound is reached on *essentially every ordinary shell exit*, not as the
/// rare stuck-descendant case it was sized for: ConPTY's own console-host
/// process routinely outlives the direct child and holds the PTY open, so
/// the read loop never sees EOF and the flusher never resolves on its own.
/// Because `STATUS_DONE` is published only after this wait, every `exit`
/// left the pane visibly inert for the full ceiling — the user-reported
/// "terminal hangs when I type exit," reproduced in srv logs as a flat 10s
/// gap between `process exited` and any further activity.
///
/// Waiting longer buys nothing in that case (the flusher cannot finish
/// until an EOF that may never come — which is exactly why expiry detaches
/// rather than aborts), while costing the full ceiling of dead UI time on
/// every single exit. 1s keeps ~50x headroom over the legitimate case this
/// bound exists for (a final flush is bounded by one drain of what is
/// already queued, plus one FileStore write and broadcast) and cuts the
/// pathological
/// case's user-visible cost by 10x. Nothing else about the behavior
/// changes: expiry still detaches the flusher and its read loop to keep
/// running in the background, so late output is still never lost.
pub(super) const FLUSHER_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(1);

/// How long to wait for the STRONG completion signal — the flusher task
/// ending, which means the read loop saw true EOF and every byte the child
/// produced is committed — before falling back to the bounded flush barrier.
///
/// Short on purpose. Where EOF works (Linux, macOS) it arrives within
/// milliseconds of the child being reaped, so this grace is ample and the
/// pre-barrier guarantee is kept intact. Where it never arrives at all
/// (Windows/ConPTY — see `FLUSHER_DRAIN_TIMEOUT`) no amount of waiting helps,
/// so anything longer is pure dead UI time.
pub(super) const FLUSHER_EOF_GRACE: std::time::Duration = std::time::Duration::from_millis(100);

/// Budget for the fallback flush barrier. Deliberately the REMAINDER of
/// `FLUSHER_DRAIN_TIMEOUT` after `FLUSHER_EOF_GRACE`, so the two waits split
/// one budget instead of each claiming a full one — the worst-case exit delay
/// is unchanged from before the barrier existed, rather than doubled (muxreview
/// P2 on PR #3261).
pub(super) const FLUSHER_BARRIER_TIMEOUT: std::time::Duration =
    FLUSHER_DRAIN_TIMEOUT.saturating_sub(FLUSHER_EOF_GRACE);

/// Resolve the initial PTY geometry from the resync `rt_opts` payload.
///
/// The agent pane is a custom UI (not xterm.js), so the PTY never receives
/// a `fitAddon` resize and must be born at the right width — otherwise the
/// first batch of agent/tool output wraps at the fallback width until a
/// post-spawn resize RPC lands, and that RPC races controller startup (it
/// can fail outright). The frontend computes cols from the pane and passes
/// them as `rtopts.termsize` on the `controllerresync` command (see
/// `usePtyWidth.ts` / `launch-flow.ts`).
///
/// Falls back to the historical 25x200 default when `rt_opts` is absent,
/// unparseable, or carries the serde-default termsize (`rows==0 && cols==0`,
/// per `obj::is_default_term_size`). Per-field guards let a cols-only
/// payload keep the default row count. Each axis is clamped to `[1, 1000]`
/// so the `i64 → u16` cast is lossless and a bogus value cannot open a
/// zero-size or wrapped-size PTY.
/// See docs/analysis/AGENT_PANE_PTY_RESIZE_RACE_2026_06_16.md.
pub(super) fn pty_size_from_rt_opts(rt_opts: &Option<serde_json::Value>) -> PtySize {
    // Historical fallback geometry. Cols 200 keeps the agent-pane live-log
    // from hard-wrapping at ~80 before the dynamic resize lands.
    const DEFAULT_PTY_ROWS: u16 = 25;
    const DEFAULT_PTY_COLS: u16 = 200;
    let (mut rows, mut cols) = (DEFAULT_PTY_ROWS, DEFAULT_PTY_COLS);
    if let Some(v) = rt_opts {
        if let Ok(rt) = serde_json::from_value::<RuntimeOpts>(v.clone()) {
            let ts = &rt.termsize;
            // rows==0 && cols==0 is the serde default → treat as absent.
            if !(ts.rows == 0 && ts.cols == 0) {
                if ts.cols > 0 {
                    cols = ts.cols.clamp(1, 1000) as u16;
                }
                if ts.rows > 0 {
                    rows = ts.rows.clamp(1, 1000) as u16;
                }
            }
        }
    }
    PtySize {
        rows,
        cols,
        pixel_width: 0,
        pixel_height: 0,
    }
}

impl ShellController {
    /// Inherent-method wrapper over [`pty_size_from_rt_opts`], preserving the
    /// pre-split `ShellController::pty_size_from_rt_opts(...)` call site the
    /// unit tests use.
    #[cfg(test)]
    pub(super) fn pty_size_from_rt_opts(rt_opts: &Option<serde_json::Value>) -> PtySize {
        pty_size_from_rt_opts(rt_opts)
    }

    /// The size `start()` opens the PTY at, recorded for a paired device that
    /// watches the terminal (`blockcontroller::term_size`); resizes are
    /// recorded as they are sent (`blockcontroller::send_input`).
    pub(super) fn spawn_pty_size(&self, rt_opts: &Option<serde_json::Value>) -> PtySize {
        let size = pty_size_from_rt_opts(rt_opts);
        crate::backend::blockcontroller::term_size::record(&self.block_id, size.rows, size.cols);
        size
    }
}