Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Fixed
- **Remote tmux link (`:ssh-tmux`) rendering**: the remote tmux client is now as large as the linked pane instead of the whole Bilterm window (full-screen programs and wrapped lines drew in the wrong place); a hydrate restores alternate screen, cursor position and visibility, application cursor keys and mouse modes (re-attaching while `vim` ran left the cursor in the wrong place and stale rows on the primary screen); a UTF-8 character split across two `%output` lines is no longer turned into replacement characters; `%extended-output` is understood.
- **Remote tmux link flooding**: Bilterm asks tmux for `pause-after` flow control and re-captures a paused pane, so a flooding remote pane no longer starves input (Ctrl-C typed in Bilterm now arrives).
- **Remote tmux link input**: a paste larger than 4096 bytes was silently truncated; pastes are now delivered complete and in order.
- **Remote tmux link reconnect**: a stalled connection is noticed in about 15 to 20 seconds instead of about 55 (link keepalive 5 s); backoff has jitter; the UI thread no longer sleeps while collecting the transport's exit code; a missing or too-old remote tmux is named in the failure text.
- `tmux_link_state()` / `:ssh-tmux info` no longer report `idle` while a removed link's transport is still attached.

### Added
- `:ssh-tmux -- <host> [session]` reaches hosts named `info`, `reconnect`, `disconnect` or `prefill`.
- The link sets `destroy-unattached off` on the session it attaches to, so a remote `tmux.conf` cannot make a disconnect destroy the session.
- `tests/tmux_link_transcripts.rs` (recorded control-mode transcripts through the real parser into a pane) and `tests/tmux_link_live.rs` (real tmux on a private socket, `BILTERM_TMUX_LIVE=1`).

## [3.3.0] - 2026-11-09

Milestone v3.3.0 "Beyond Herdr": always-on foreground RPC, first-class agent/pane/workspace CLI, semantic agent introspection, worktree swarm DAG runner, Mission Control HUD, and hierarchical `D:(W,S,Y,P)` coordinates (Phases 65–71, 71 phases total).
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
- **Agent-to-Agent Messaging & Coordination (`:agent`)**: Direct inter-agent communication across terminal panes without knowing terminal internals. Features stable per-pane agent addressing (`:agent name`), bounded mailboxes (`MAX_INBOX_DEPTH = 64`), and 3 delivery modes: `mailbox` (queued), `nudge` (injected only when idle/waiting; suppressed during password locks or `ALT_SCREEN`), and `file` (0600 payload files for large transfers). Includes hop-count loop guards (`MAX_HOPS = 8`) and rate limits. → *[User Guide Ch. 11](docs/user-guide/11-navigator-sidebar-and-agent-traffic.md)*
- **Unified Registry & Fuzzy Finder (`:find`, `Ctrl+Alt+F`)**: Instant fuzzy search across agents, active and saved sessions, and command history (`:find agent|session|history <query>`). Features zero-trust secret masking and redaction to protect tokens and passwords in history logs. → *[User Guide Ch. 12](docs/user-guide/12-find-registry-and-history.md)*
- **UI Modernization & 8 Design Profiles (`:appearance`, `:mode`)**: Switch between 8 built-in visual profiles (`Obsidian` dark slate default, `Legacy` Borland Blue, `Midnight`, `Arctic`, `Liquid`, `Amber`, `Synthwave`, `Solarized`) and 3 display modes (`:mode standard|minimal|zen`), with custom profile saving, export, and import. → *[User Guide Ch. 4](docs/user-guide/04-themes-glyphs-and-config.md)*
- **Persistent SSH + Remote tmux Fleet (`:ssh-tmux`)**: Launch remote sessions via `:ssh-tmux <host> [session]` backed by remote `tmux -CC`. Resilient state machine automatically reconnects with exponential backoff on network drop, hydrates scrollback via `capture-pane`, and prevents accidental closure with exit hold banners. → *[User Guide Ch. 5](docs/user-guide/05-tmux-integration.md)*
- **Persistent SSH + Remote tmux Fleet (`:ssh-tmux`)**: Launch remote sessions via `:ssh-tmux <host> [session]` backed by remote `tmux -CC`. Resilient state machine automatically reconnects with exponential backoff on network drop, sizes the remote window to the linked pane, hydrates scrollback, cursor and alternate-screen state via `capture-pane`, leaves the remote session running on every kind of disconnect, and prevents accidental closure with exit hold banners. → *[User Guide Ch. 5](docs/user-guide/05-tmux-integration.md)*
- **First-Class Utility Windows (`:fonts`, `:commands`, `:script` / `:studio`)**: Dedicated floating, pinnable (`*`), and dockable workbench windows. Live typography preview in `:fonts`, command palette execution history in `:commands`, and full Script Studio in `:script` / `:studio` featuring a multi-line `.bt` editor, live action recorder (`[● Rec]`), and single-step debugger (`[F10/n Step]`).
- **Session Reorganization & Packing Viewer (`:sessions map`, `:window move`)**: Treemap-style container packing visualizer in Braille/UTF-8 box-drawing or native GUI vector rendering with mouse drag-and-drop. Migrate live windows across sessions (`:window move <session>`), perform multi-select bulk operations (`:window bulk move|close|tile|pin`), and safely revert topology with single-step undo (`:window undo`). → *[User Guide Ch. 3](docs/user-guide/03-window-manager-and-z-stack.md)*
- **Daemon Supervisor & Multi-Daemon Architecture (`:daemon`)**: Auto-spawned singleton background daemon with stale-lock recovery. Manage named daemons (`--daemon --name <n>`) with cross-daemon discovery, RPC/MCP bridging, and headless HTTP+SSE transport (`--http 127.0.0.1:PORT`).
Expand Down
30 changes: 25 additions & 5 deletions docs/user-guide/05-tmux-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ Persistent remote terminal sessions are managed via `:ssh-tmux` (`src/tmux/link.

When `:ssh-tmux <user@host> [session]` is invoked, Bilterm spawns a dedicated PTY child running `ssh -tt` with frozen connection options (`src/remote/mod.rs`):
- `-tt`: Allocates a pseudo-terminal on the remote host so `tmux -CC` has an underlying tty for ioctls.
- `-o ServerAliveInterval=15`: Sends keepalive probes every 15 seconds to prevent NAT or stateful firewall timeouts.
- `-o ServerAliveCountMax=3`: Drops dead connections after 3 unanswered keepalives (45 seconds).
- `-o ServerAliveInterval=5`: Sends a keepalive probe every 5 seconds (an interactive `:ssh` pane uses 15).
- `-o ServerAliveCountMax=3`: Drops a dead connection after 3 unanswered keepalives, so a stalled network is noticed in about 15 to 20 seconds and the link starts reconnecting.
- `-o TCPKeepAlive=yes`: Enables kernel-level TCP keepalives.
- `-o ConnectTimeout=15`: Fails connection attempts quickly when the remote host is unreachable.
- `-o ControlMaster=no` and `-o ControlPath=none`: Bypasses OpenSSH socket multiplexing. Every connection and reconnection opens a completely fresh TCP connection, preventing corrupted or stale control sockets from stalling reconnection loops.
Expand Down Expand Up @@ -131,12 +131,29 @@ This applies both to a first `:ssh-tmux <user@host> <session>` that attaches to
1. **First pane immediately**: Bilterm maps the first remote pane to the local pane as soon as the control stream is up.
2. **Pane discovery**: It discovers the remaining panes with `list-panes`.
3. Bilterm waits 300 ms after attach greeting for pane layouts to settle.
4. It sends `refresh-client -C <cols>x<rows>` followed by `capture-pane -p -e -J -S -2000 -t %N` for each mapped pane.
4. It sends `refresh-client -C <cols>x<rows>` with the size of the **linked pane** (not the whole Bilterm window), one `display-message` that reports every pane's screen state (alternate screen, cursor position and visibility, application cursor keys, mouse modes), then `capture-pane -p -e -J -S -2000 -t %N` for each mapped pane. A remote window shown in a pane of its own gets that pane's size (`refresh-client -C @<window>:<cols>x<rows>`, tmux 3.4+).
5. Live `%output` lines are held during capture to prevent interleaved text corruption.
6. Screen lines and scrollback are parsed via `render_capture` and fed into each pane's `VtParser`.
6. Screen lines and scrollback are fed into each pane's `VtParser` together with the reported state, so a re-attach while `vim` or `htop` runs lands on the alternate screen with the cursor where the remote has it.
7. Normal output is released. Stale panes that no longer exist on the remote host are flagged with orphan banners rather than being abruptly removed.
8. **Idle sessions**: Typed commands are delivered right away, even if the remote session has not produced any output yet (for example, an idle shell).

### 4.6.1 What Survives a Disconnect

The remote tmux session, and everything running in it, is left running in every case below. Bilterm never sends `kill-session`, `kill-server` or `kill-window`, and it sets `destroy-unattached off` on the session it attaches to.

| Event | Remote session | Bilterm |
|---|---|---|
| ssh process dies, network drops | keeps running | reconnects by itself (backoff 1 s doubling to 30 s, plus up to 25 % jitter, 20 attempts), same session, same panes |
| Network stalls without closing | keeps running | noticed after about 15 to 20 s, then as above |
| `:ssh-tmux disconnect` (`x` on the banner, `Ctrl+X Q`) | keeps running | link stops; `Enter`/`r` or `:ssh-tmux reconnect` re-attaches |
| `:quit`, `:detach`, terminal closed, crash or `kill -9` of Bilterm | keeps running | run `:ssh-tmux <host> [session]` again after the restart |

`:ssh-tmux <host> [session]` is attach-or-create (`tmux new-session -A -s <session>`): the same host and session name always lead to the same remote session, never to a duplicate. The default session name is `bilterm`.

While the link is down, typed input is not queued: the pane shows `Link down: input not delivered` and the bytes are dropped, so nothing unexpected runs in a remote shell after a reconnect. Pastes of any practical size (up to 1 MiB per paste) are sent complete and in order.

A host that is literally named `info`, `reconnect`, `disconnect` or `prefill` is reached with `--`: `:ssh-tmux -- info [session]`.

### 4.7 Single Link Guard and Fresh TCP Policy

- **One Link at a Time**: Bilterm currently supports one active remote `tmux -CC` link. Attempting to run `:ssh-tmux` while a link is `Connecting`, `Connected`, or in `Backoff` returns an error: `"a tmux link to <dest>/<session> is already active; run :ssh-tmux disconnect first"`.
Expand All @@ -152,7 +169,10 @@ If your remote session terminates immediately upon disconnect, verify your remot
### 4.9 Known Limits

- **`csh` / `tcsh` shells**: The remote wrapper relies on POSIX `sh`, `bash`, or `zsh` login shell syntax. C-shell variants are not supported.
- **Raw-mode capture**: `capture-pane` captures terminal grid text and colors, but cannot capture internal TUI cursor states or alternate-screen state machines of running programs (`vim`, `htop`).
- **Restored state**: A hydrate restores text, colours, alternate screen, cursor position and visibility, application cursor keys and mouse reporting. Other modes (bracketed paste, keypad mode, scroll regions, character sets) are not reported by tmux and come back when the program next sets them.
- **Several panes in one remote window**: The remote client size follows the linked primary pane. Panes that share one remote window keep the sizes tmux gives them, which can differ from the local pane sizes.
- **Detach and re-attach of Bilterm itself**: `:detach` / `bilterm attach` and a restart do not restore the link. The remote session keeps running; run `:ssh-tmux <host> [session]` again to re-attach to it.
- **Floods**: When a remote pane prints faster than Bilterm can draw, tmux pauses that pane and Bilterm re-captures its screen and continues it (`pause-after`, tmux 3.2+). Lines that scrolled by during a pause are in tmux's history, not in Bilterm's scrollback.
- **Multi-link**: Only one remote `tmux -CC` bridge is active at a time in this version.
- **Window names**: Remote window names are hydrated when `%window-renamed` events arrive (gap G10 from Chapter 12).

Expand Down
2 changes: 1 addition & 1 deletion docs/user-guide/07-troubleshooting-and-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@
```
- If `tcpkeepalive 0` or sleep triggers, TCP connections are dropped when the display sleeps. Enable network keepalives with `sudo pmset -a tcpkeepalive 1`, or prevent sleep during long jobs using `caffeinate -s`.
6. **SSH Keepalives & Network Timeouts**:
- Bilterm automatically applies `-o ServerAliveInterval=15 -o ServerAliveCountMax=3 -o TCPKeepAlive=yes -o ConnectTimeout=15` to both `:ssh` and `:ssh-tmux` connections.
- Bilterm automatically applies `-o ServerAliveCountMax=3 -o TCPKeepAlive=yes -o ConnectTimeout=15` to both `:ssh` and `:ssh-tmux` connections, with `-o ServerAliveInterval=15` for `:ssh` panes and `-o ServerAliveInterval=5` for the `:ssh-tmux` link (a stalled link is noticed in about 15 to 20 seconds).
- If stateful NAT gateways or firewalls drop idle connections faster than 15 seconds, adjust your local `~/.ssh/config` or remote `sshd_config` `ClientAliveInterval`.
7. **Restored Workspace Shows `(not connected)`**:
- When restoring a saved workspace session, Bilterm honestly labels previously remote panes as `(not connected)` if they are running a local shell rather than a live remote transport.
Expand Down
18 changes: 16 additions & 2 deletions src/colon_command/parse_link.rs
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
//! Reserved words of `:ssh-tmux` / `:sshtmux` (Phase 51.1, P-13): `reconnect`, `disconnect`,
//! `info`, `prefill`. Everything else (a host, `list`, `ls`, `status`) falls through to the
//! existing `ssh-tmux` arm in `parse.rs`.
//! existing `ssh-tmux` arm in `parse.rs`. A host that is literally named like a reserved word is
//! reached with `--`: `:ssh-tmux -- info [session]`.

use super::ColonCommand;
use crate::wm::link_cmd::RemoteLinkOp;

const USAGE: &str = "Usage: :ssh-tmux reconnect | disconnect | info | prefill";
const USAGE: &str =
"Usage: :ssh-tmux reconnect | disconnect | info | prefill (a host with such a name: :ssh-tmux -- <host>)";

/// Answers only for head `ssh-tmux`/`sshtmux` whose first argument is a reserved word.
pub(super) fn parse_link_colon_command(
Expand All @@ -15,6 +17,18 @@ pub(super) fn parse_link_colon_command(
if !matches!(head, "ssh-tmux" | "sshtmux") {
return None;
}
// `--` ends the reserved words: `:ssh-tmux -- info [session]` connects to a host named `info`.
if parts.get(1) == Some(&"--") {
return Some(match parts.get(2) {
Some(target) if !target.starts_with('-') && parts.len() <= 4 => {
Ok(ColonCommand::SshTmuxConnect {
target: (*target).to_string(),
session: parts.get(3).copied().unwrap_or("bilterm").to_string(),
})
}
_ => Err("Usage: :ssh-tmux -- <user@host|profile> [session]".to_string()),
});
}
let op = RemoteLinkOp::from_word(parts.get(1)?)?;
if parts.len() > 2 {
return Some(Err(USAGE.to_string()));
Expand Down
1 change: 0 additions & 1 deletion src/pane/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,6 @@ fn remote_input_tap_collects_and_caps() {

// Capped at REMOTE_INPUT_CAP between drains; the excess is dropped.
let cap = crate::tmux::link::REMOTE_INPUT_CAP;
assert_eq!(cap, 4096);
pane.write_to_pty(&b"a".repeat(cap - 10)).unwrap();
pane.write_to_pty(&b"b".repeat(100)).unwrap();
pane.write_to_pty(b"more").unwrap();
Expand Down
11 changes: 8 additions & 3 deletions src/remote/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ fn default_true() -> bool {
true
}

/// `ServerAliveInterval` of the tmux link transport.
pub const LINK_ALIVE_INTERVAL_SECS: u32 = 5;
pub const CONTROL_PATH_LEAF: &str = "ssh-%C";
pub const CONTROL_DIR_MAX_BYTES: usize = 40;

Expand Down Expand Up @@ -107,7 +109,7 @@ impl RemoteHostProfile {
}

fn push_common_args(&self, args: &mut Vec<String>, control_dir: Option<&Path>, is_link: bool) {
push_keepalive_args(args);
push_keepalive_args(args, is_link);
if is_link {
args.push("-o".to_string());
args.push("ControlMaster=no".to_string());
Expand Down Expand Up @@ -190,9 +192,12 @@ impl RemoteHostProfile {
}
}

fn push_keepalive_args(args: &mut Vec<String>) {
/// Keepalives: a link notices a dead peer after `5s x 3` (it reconnects by itself, so a short
/// detection time costs nothing); an interactive `:ssh` pane keeps the gentler `15s x 3`.
fn push_keepalive_args(args: &mut Vec<String>, is_link: bool) {
let interval = if is_link { LINK_ALIVE_INTERVAL_SECS } else { 15 };
args.push("-o".to_string());
args.push("ServerAliveInterval=15".to_string());
args.push(format!("ServerAliveInterval={interval}"));
args.push("-o".to_string());
args.push("ServerAliveCountMax=3".to_string());
args.push("-o".to_string());
Expand Down
Loading
Loading