Skip to content

macOS: fourth concurrent AgentDesk TUI becomes unresponsive #3

Closed

Description

@er0826-dex

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-message responsiveness 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: launches tmux -C attach-session; handshake waits up to 2 seconds. SendCommand acquires cmdMu, 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.go and cmd/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.

Activity

  1. millwright-software commented on Nov 11, 2026

    @millwright-software
    Owner

    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.

    • Each control client costs the server 3 files: its socket plus the stdin and stdout it passes over. Measured: 5 clients raised the server's count from 34 to 49.
    • Go raises its own soft RLIMIT_NOFILE but 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.
    • At the limit, tmux refuses new clients with server exited unexpectedly. It fails fast and doesn't hang, while the server and its panes keep running.

    Reproduction. Isolated TMUX_TMPDIR, throwaway HOME, real agent-desk windows, 6 sessions, server capped at 64:

    • Window 3 tipped the server after connecting 5 of its 6 pipes.
    • From then on, in every window, including the first, previews stuck on "Loading preview...", attach did nothing, the unpiped session went ✕, and the status loop took 4.9 s. Keys still moved the cursor.
    • Quitting window 3 restored everything; no server kill was needed.

    Fix:

    • tmux.RaiseFileLimit() runs first in main and 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.Connect budgets 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 ✕.
    • A yellow banner says when the server is refusing clients, when sessions are going without pipes, or when another window won't fit.
    • The pipe lifecycle bugs found under macOS: durable tmux socket location and safe handling of unreachable long-lived servers #4 are fixed too.

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions