Description
Agentboard starts successfully and the browser WebSocket connects, but opening any tmux window fails in the default pty terminal mode with:
ERR_TMUX_SWITCH_FAILED
usage: display-message [-aINpv] [-c target-client] [-d delay]
[-F format] [-t target-pane] [message]
Deleting all tmux sessions and recreating a clean session does not resolve the problem.
Environment
- OS: Linux x86_64
- Agentboard:
@gbasin/agentboard@0.4.4
- Native package:
@gbasin/agentboard-linux-x64@0.4.4
- Node:
v20.19.4
- tmux:
3.2a
- Terminal mode:
pty
- Browser client: Chrome 149 on macOS
Steps to reproduce
-
Create a tmux session:
tmux new-session -d -s agent
-
Start Agentboard:
LOG_LEVEL=debug HOSTNAME=0.0.0.0 agentboard
-
Open the Agentboard web interface.
-
Select the agent tmux window.
Actual result
The debug log reports:
{"connectionId":"cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","sessionName":"agentboard-ws-cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","clientTty":"/dev/pts/3","durationMs":42,"mode":"pty","event":"terminal_proxy_ready"}
{"connectionId":"cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","sessionName":"agentboard-ws-cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","tmuxWindow":"agent:@0","effectiveTarget":"agent:@0","clientTty":"/dev/pts/3","mode":"pty","event":"terminal_switch_attempt"}
{"connectionId":"cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","sessionName":"agentboard-ws-cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","tmuxWindow":"agent:@0","effectiveTarget":"agent:@0","clientTty":"/dev/pts/3","error":"usage: display-message [-aINpv] [-c target-client] [-d delay] [-F format] [-t target-pane] [message]\n","mode":"pty","event":"terminal_switch_failure"}After the failure:
returns no clients.
The Agentboard-created temporary tmux client is discovered successfully as /dev/pts/3, but the terminal switch fails and the client disappears.
Expected result
The browser terminal should attach to and display agent:@0.
Manual tmux verification
The equivalent target-identity commands work correctly when run manually:
target='agent:@0'
fmt=$'#{session_name}\t#{window_id}'
tmux -u display-message -p -t "$target" "$fmt"
echo "exit=$?"
tmux -u display-message -p -t "$target" -F "$fmt"
echo "exit=$?"Both commands output:
and exit with status 0.
Additional manual tests also succeed:
tmux display-message -p -t 'agent:@0' '#{session_name}'
tmux -u display-message -p -t 'agent:@0' '#{session_name}'
tmux -u display-message -p -t 'agent:@0' '#{window_id}'
tmux -u display-message -p -t 'agent:@0' '#{session_name} #{window_id}'
tmux -u display-message -p -t 'agent:@0' $'#{session_name}\t#{window_id}'Installed packages
@gbasin/agentboard@0.4.4
@gbasin/agentboard-linux-x64@0.4.4
tmux 3.2a
The npm dependency tree also reports an apparently unrelated xterm peer-dependency issue:
npm error invalid: @xterm/xterm@5.5.0
Agentboard still starts successfully and reaches the tmux terminal-switch code, so this does not appear to be the direct cause of the tmux failure.
pipe-pane behavior
TERMINAL_MODE=pipe-pane avoids the PTY switch error, but it is not a usable workaround in my environment because the terminal does not render at full width on my devices.
Example:
HOSTNAME=0.0.0.0 TERMINAL_MODE=pipe-pane agentboard
The server starts in pipe-pane mode, but the browser terminal layout is incorrectly sized and does not use the full available width.
Because of that rendering problem, neither available terminal mode is usable:
pty: fails with ERR_TMUX_SWITCH_FAILEDpipe-pane: terminal does not render at full width
Suspected area
This appears to involve the PTY client-switch verification lifecycle:
- Agentboard creates a temporary grouped tmux client.
- The client is discovered successfully at
/dev/pts/3.
- Agentboard attempts to switch it to
agent:@0.
- A
display-message command returns its usage text.
- The temporary client exits or disappears.
The target itself is valid and the corresponding manual display-message commands succeed, so this may be a race condition or compatibility problem around switch-client, client identity verification, or the temporary PTY client lifecycle on tmux 3.2a.
Description
Agentboard starts successfully and the browser WebSocket connects, but opening any tmux window fails in the default
ptyterminal mode with:Deleting all tmux sessions and recreating a clean session does not resolve the problem.
Environment
@gbasin/agentboard@0.4.4@gbasin/agentboard-linux-x64@0.4.4v20.19.43.2aptySteps to reproduce
Create a tmux session:
Start Agentboard:
Open the Agentboard web interface.
Select the
agenttmux window.Actual result
The debug log reports:
{"connectionId":"cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","sessionName":"agentboard-ws-cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","clientTty":"/dev/pts/3","durationMs":42,"mode":"pty","event":"terminal_proxy_ready"} {"connectionId":"cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","sessionName":"agentboard-ws-cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","tmuxWindow":"agent:@0","effectiveTarget":"agent:@0","clientTty":"/dev/pts/3","mode":"pty","event":"terminal_switch_attempt"} {"connectionId":"cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","sessionName":"agentboard-ws-cd1ad840-3c85-44d0-b2dd-5bfec4dddfdb","tmuxWindow":"agent:@0","effectiveTarget":"agent:@0","clientTty":"/dev/pts/3","error":"usage: display-message [-aINpv] [-c target-client] [-d delay] [-F format] [-t target-pane] [message]\n","mode":"pty","event":"terminal_switch_failure"}After the failure:
returns no clients.
The Agentboard-created temporary tmux client is discovered successfully as
/dev/pts/3, but the terminal switch fails and the client disappears.Expected result
The browser terminal should attach to and display
agent:@0.Manual tmux verification
The equivalent target-identity commands work correctly when run manually:
Both commands output:
and exit with status
0.Additional manual tests also succeed:
Installed packages
The npm dependency tree also reports an apparently unrelated xterm peer-dependency issue:
Agentboard still starts successfully and reaches the tmux terminal-switch code, so this does not appear to be the direct cause of the tmux failure.
pipe-pane behavior
TERMINAL_MODE=pipe-paneavoids the PTY switch error, but it is not a usable workaround in my environment because the terminal does not render at full width on my devices.Example:
The server starts in
pipe-panemode, but the browser terminal layout is incorrectly sized and does not use the full available width.Because of that rendering problem, neither available terminal mode is usable:
pty: fails withERR_TMUX_SWITCH_FAILEDpipe-pane: terminal does not render at full widthSuspected area
This appears to involve the PTY client-switch verification lifecycle:
/dev/pts/3.agent:@0.display-messagecommand returns its usage text.The target itself is valid and the corresponding manual
display-messagecommands succeed, so this may be a race condition or compatibility problem aroundswitch-client, client identity verification, or the temporary PTY client lifecycle on tmux 3.2a.