Skip to content

feat(cli): focus a session from outside the TUI - #1087

Draft
agent-manager-bots[bot] wants to merge 4 commits into
mainfrom
feat/cli-focus-session
Draft

agent-manager-bots[bot] wants to merge 4 commits into
mainfrom
feat/cli-focus-session

Conversation

@agent-manager-bots

Copy link
Copy Markdown
Contributor

What changed

agent-manager focus <session-id> and agent-manager select <session-id> bring a session forward in the running manager window from any shell, and the focus_session MCP tool does what focus does. The manager unfolds the groups above the session, drops a status filter or the archive view if it hides the row, moves the cursor there and, for focus, opens it the way enter does. Help, messages, the search and the row menu close the way esc closes them. A dialog that may hold typed input stays open with the cursor moved under it.

This supersedes #726 (feat(cli): focus a session from outside the TUI, #726) by @calsmith1-nokia. The first commit is his work, authored by him and ported onto the package layout from #735. The second commit is mine.

Changes vs #726

Review cases from the 2026-10-07 review

  1. Stale PID signalled with SIGUSR1. Kept his socket design, so nothing is ever signalled. Each manager window now listens on its own socket named after its process, beside the tmux server's socket. A socket a crashed manager left refuses the connection, so it never stands in for a live one.
  2. A notification click closed the New Session form. Only layers holding no typed input close. A clicked notification also keeps main's behavior of leaving you in the session when it names the one you are in.
  3. "focused" printed when the manager only selected. One connection per request with the answer on the same connection, as in feat(cli): focus a session from outside the TUI #726. Because opening a session now runs on the effect lane, the manager answers only after the open lands, or with the reason it did not open.
  4. A select on the focused session kept focus. select leaves focus even on that session.

Extras from #725 (CLI command to focus a session from outside the TUI, applied immediately rather than on the next poll, #725), #947 and #1084

  • Non-zero exit with the reason when the id is unknown, the session is archived, no manager window is running, or the manager refused. --json prints the reason as an error object.
  • Picking the manager. The command connects to every live socket for this tmux server. With two or more windows it refuses and names their processes instead of guessing, which is what agent-manager focus <session-id>: let a script or dashboard select a session in the running manager #1084 asked for.
  • MCP tool focus_session, described as one to call only when the user asked to be taken to a session.
  • A manager that cannot listen says so on the status bar instead of staying unreachable.

Conflict resolution

  • The listener lives in internal/sessioncmd/focus_endpoint.go, the reveal logic in rail.Model.RevealSession, and the request handling in internal/ui/rail_adapter_forward.go, to fit the file and boundary checks.
  • addTool, toolAnnotations and textContent moved from mcpserver.go to internal/mcpserver/tools.go so mcpserver.go stays under 1000 lines.

Why

Scripts, dashboards and launchers want to take the user to a session without waiting for a poll or racing the manager's state.

Closes #725

Scope

Required behavior

A request reaches only a manager window on the same tmux server, never signals a process, and reports exactly what the manager did.

Why this approach

A per-window Unix socket gives liveness by connecting, a private answer per request, and a way to see that several windows are running. agent-manager serve has no window and does not listen.

Tool coverage

No tool-dependent behavior. It moves the manager's own cursor and opens rows the way enter does for every CLI.

How it was verified

  • gofmt -l . prints nothing
  • go vet ./... passes
  • go test -race ./... (ran env -u TMUX TMUX_TMPDIR=/tmp/am726t go test -race -p 4 -timeout 30m on internal/sessioncmd, internal/cli, internal/mcpserver, internal/tmux, internal/ui/rail and internal/ui, all pass. CI runs the rest)
  • go build ./... passes, also with GOOS=windows and GOOS=darwin
  • Ran it against real sessions, in an isolated HOME, config dir and TMUX_TMPDIR with a separate tmux server
    • focus on a session two folded groups deep unfolded them and focused it, returning in about 70 ms
    • select while focused left focus and moved the cursor
    • focus with the New Session form open kept the typed name and exited 1 naming the dialog
    • unknown id, archived session and no manager each exited 1 with the reason
    • two manager windows gave exit 1 naming both processes
    • after one was killed with SIGKILL, its stale socket was skipped and the request reached the live one, and a manager started a minute later removed the stale socket
  • New behavior covers every applicable CLI
  • Holds for every supported platform. Linux tested live. Windows builds and uses the same Unix socket beside the psmux socket but was not run live
  • No new keys or settings

Visual evidence

Not applicable because: the change is a CLI and MCP entry point. Before and after screen captures from the live check are text, and the result shows as the cursor moving to the unfolded row and the FOCUS badge.

calsmith1-nokia and others added 2 commits November 16, 2026 23:41
agent-manager focus <session-id> and select <session-id> bring a session
forward in the running manager from any shell. The manager answers on a
Unix socket beside its tmux server's socket. The command connects, sends
the session id and whether to open it, and reads back on the same
connection what the manager did. Nothing is signalled and no request is
shared, so a request cannot be answered for another, and the exit status
reports the manager's own outcome.

On a request the manager unfolds the groups above the session, drops a
status filter hiding it and moves the cursor. focus then runs what enter
does on that row and answers once the open lands. Layers that hold nothing
typed (help, messages, the search, the row menu, a lifted row, a divider
drag) close the way esc closes them. A dialog that may hold unfinished
input stays open with the cursor moved under it, and focus reports that it
did not open the session. A select leaves focus even on the session it
names. A clicked notification takes the same select path, so it reaches
sessions in folded groups. focus_session exposes the focus command over
MCP.

Ported from #726 onto the package layout #735 introduced.

Refs #725
Each manager window now listens on its own socket, named after its
process, beside the tmux server's socket. The command connects to every
one that answers. None answering means no window is running, and two or
more means the request is refused naming their processes, since nothing
says which window the user is looking at. A socket left by a manager that
crashed refuses the connection, so it never stands in for a live one, and
a manager starting up removes such sockets once they are a minute old.
Nothing is ever signalled by a recorded process id.

A manager that cannot listen now says so on the status bar instead of
staying silently unreachable, and it creates the tmux socket directory the
way tmux does when it starts before the tmux server.

A clicked notification leaves the user in the session when that is the
one it names, as it did before, and moves the cursor like a select
otherwise. A request for a live session while the archive view is on
switches back to the live list.

Closes #725
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Staticcheck ST1005 rejects error strings that open with a capital.
Windows cannot set times on a Unix socket, so the sweep takes the current time and the test runs it as if an hour later. The sweep reads the socket with Lstat.

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLI command to focus a session from outside the TUI, applied immediately rather than on the next poll

2 participants