Repository navigation
Closed
Description
Problem
On macOS, with three AgentDesk TUI instances running, opening a fourth sometimes leaves the fourth UI unresponsive. This occurs across Terminal and iTerm. Multi-instance support should remain usable without disrupting existing agent sessions.
Observations
- The affected environment had 20 running tmux sessions and 65 attached control-mode clients, with three clients on most sessions and four on some.
- In the inspected checkout, each TUI creates a separate control-mode connection to every running session, so connection count scales with TUI instances × sessions.
- A
tmux display-messageresponsiveness probe completed in approximately 4 ms during inspection. - MCP pooling was disabled.
- No frozen-process stack trace or command-timeout evidence was captured. Control-mode fan-out is a hypothesis, not an established root cause.
- Exact installed binary version and correspondence with the inspected checkout still need confirmation.
Relevant paths
internal/ui/home.go: startup connects pipes to all running sessions; an approximately 20-second sweep reconnects missing pipes. Output events feed status processing.internal/tmux/controlpipe.go: launchestmux -C attach-session; handshake waits up to 2 seconds.SendCommandacquirescmdMu, writes to stdin, then waits up to 3 seconds for a response. That response timeout does not bound mutex acquisition or the stdin write.internal/tmux/pipemanager.go: pipe lifecycle, output forwarding and reconnection.internal/statedb/statedb.goandcmd/agent-desk/main.go: shared SQLite state and instance registration. WAL and busy timeout do not rule out contention.
Investigation and acceptance criteria
- Reproduce with isolated application state and a dedicated tmux server/socket, approximately 20 synthetic sessions producing output, and four or more concurrent TUIs. Do not experiment on live agent sessions.
- Capture stacks/profiling or targeted instrumentation during a freeze; identify the actual blocked path. Consider UI-loop blocking, lock contention, pipe writes/response handling, output backpressure, reconnect churn, SQLite contention and resource exhaustion.
- Implement the smallest evidence-backed fix, with focused regression coverage.
- Preserve background session status, notifications and list freshness. Restricting pipes to the selected session is not sufficient unless these behaviors are preserved.
- Verify responsiveness through selection changes, attach/detach and instance shutdown, without leaked clients or reconnect storms.
- Provide safe installation/rollback guidance. Do not impose a three-instance limit or terminate existing sessions.
A separate long-lived tmux socket reachability issue is being filed independently; it should not be assumed to explain this freeze.
Metadata
Metadata
Assignees
Labels
No labels
Activity
Release v1.0.28: tmux servers get room for every window (#3, #4)
millwright-software commentedon Nov 11, 2026
Fixed in v1.0.28. The full evidence is in documentation/worklog/2026-11-11-tmux-file-limit.md.
Root cause: the tmux server runs out of open files. Control-mode fan-out is the multiplier, not the cause on its own.
RLIMIT_NOFILEbut restores the original in every child it execs, so a tmux server agent-desk started got the macOS default of 256. The live server here read 256 (tmux run-shell 'ulimit -n') and held 117 files with one window on 25 sessions.server exited unexpectedly. It fails fast and doesn't hang, while the server and its panes keep running.Reproduction. Isolated
TMUX_TMPDIR, throwawayHOME, real agent-desk windows, 6 sessions, server capped at 64:Fix:
tmux.RaiseFileLimit()runs first inmainand sets the soft limit to 16384, bounded by the hard limit, so a server agent-desk starts inherits it. Verified from a shell at 256: v1.0.28's server gets 16384, v1.0.27's gets 256.PipeManager.Connectbudgets pipes against the server's free files. It probes the server (about 70 ms, cached), debits 3 per pipe and keeps 64 in reserve. When there is no room, it polls instead of connecting. Verified: three windows on a server capped at 100 held it at 35 files, and windows without pipes still had live previews and no ✕.There is no instance limit, and no live session was used for any of this. A server started before v1.0.28 keeps its limit until it exits: closing a window frees room at once, and lifting the cap takes a new server. The troubleshooting guide's "tmux File Limit" section covers this.
Release v1.0.28: tmux servers get room for every window (#3, #4)