diff --git a/agents/agentd/cmd/agentd/main.go b/agents/agentd/cmd/agentd/main.go
index eb99dae6..2bd00e6a 100644
--- a/agents/agentd/cmd/agentd/main.go
+++ b/agents/agentd/cmd/agentd/main.go
@@ -1914,6 +1914,8 @@ func (a *Agent) handleMessage(msgType string, payload json.RawMessage) {
a.handleTerminalInput(payload)
case "terminal.resize":
a.handleTerminalResize(payload)
+ case "terminal.navigate":
+ a.handleTerminalNavigate(payload)
case "terminal.control":
a.handleTerminalControl(payload)
case "terminal.detach":
@@ -5480,6 +5482,43 @@ func (a *Agent) handleTerminalResize(payload json.RawMessage) {
}
}
+func (a *Agent) handleTerminalNavigate(payload json.RawMessage) {
+ var req protocol.TerminalNavigatePayload
+ if err := json.Unmarshal(payload, &req); err != nil {
+ log.Printf("Failed to parse terminal.navigate: %v", err)
+ return
+ }
+
+ navigation := tmux.TerminalNavigation{Op: tmux.TerminalNavigationOp(req.Op)}
+ switch navigation.Op {
+ case tmux.NavigateSelectWindow:
+ if req.WindowIndex == nil {
+ log.Printf("Failed to parse terminal.navigate: select_window requires window_index")
+ return
+ }
+ navigation.WindowIndex = *req.WindowIndex
+ case tmux.NavigateSelectPane:
+ if strings.TrimSpace(req.PaneID) == "" {
+ log.Printf("Failed to parse terminal.navigate: select_pane requires pane_id")
+ return
+ }
+ navigation.PaneID = req.PaneID
+ case tmux.NavigateZoom:
+ if req.On == nil {
+ log.Printf("Failed to parse terminal.navigate: zoom requires on")
+ return
+ }
+ navigation.On = *req.On
+ default:
+ log.Printf("Failed to parse terminal.navigate: unsupported op %q", req.Op)
+ return
+ }
+
+ if err := a.terminalManager.Navigate(req.ChannelID, navigation); err != nil {
+ log.Printf("Failed to navigate terminal: %v", err)
+ }
+}
+
func (a *Agent) handleTerminalControl(payload json.RawMessage) {
var req protocol.TerminalChannelPayload
if err := json.Unmarshal(payload, &req); err != nil {
diff --git a/agents/agentd/cmd/agentd/main_terminal_test.go b/agents/agentd/cmd/agentd/main_terminal_test.go
index e78b044a..7f56eba5 100644
--- a/agents/agentd/cmd/agentd/main_terminal_test.go
+++ b/agents/agentd/cmd/agentd/main_terminal_test.go
@@ -67,6 +67,48 @@ func TestTerminalAuditHandlerEmitsAdditiveAuditEvent(t *testing.T) {
}
}
+func TestHandleTerminalNavigateRoutesToGroupedViewerOnPrivateSocket(t *testing.T) {
+ tmuxClient := newPrivateCommandTmux(t)
+ panes, err := tmuxClient.ListPanes()
+ if err != nil || len(panes) != 1 {
+ t.Fatalf("initial panes=%+v err=%v", panes, err)
+ }
+ if _, err := tmuxClient.NewWindow("command-test", "second", ""); err != nil {
+ t.Fatalf("create second window: %v", err)
+ }
+ if err := tmuxClient.SelectWindow("command-test:0"); err != nil {
+ t.Fatalf("restore origin window: %v", err)
+ }
+
+ manager := tmux.NewTerminalManager(tmuxClient, t.TempDir())
+ manager.SetPerViewerPTY(true)
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("navigate-channel", panes[0].PaneID, tmux.AttachOptions{SessionID: "session-1"}); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ agent := &Agent{terminalManager: manager}
+ windowIndex := 1
+ payload, err := json.Marshal(protocol.TerminalNavigatePayload{
+ ChannelID: "navigate-channel",
+ Op: "select_window",
+ WindowIndex: &windowIndex,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ agent.handleMessage(protocol.TypeTerminalNavigate, payload)
+
+ panes, err = tmuxClient.ListPanes()
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, pane := range panes {
+ if pane.SessionName == "command-test" && pane.WindowIndex == 0 && !pane.WindowActive {
+ t.Fatal("terminal.navigate changed the origin session's current window")
+ }
+ }
+}
+
func TestTerminalAttachSupersedesStaleChannelAfterControlPlaneReconnect(t *testing.T) {
tmuxClient := newPrivateCommandTmux(t)
panes, err := tmuxClient.ListPanes()
diff --git a/agents/agentd/internal/protocol/messages.go b/agents/agentd/internal/protocol/messages.go
index b557f6b8..80f50b4c 100644
--- a/agents/agentd/internal/protocol/messages.go
+++ b/agents/agentd/internal/protocol/messages.go
@@ -32,6 +32,7 @@ const (
TypeTerminalAttach = "terminal.attach"
TypeTerminalInput = "terminal.input"
TypeTerminalResize = "terminal.resize"
+ TypeTerminalNavigate = "terminal.navigate"
TypeTerminalDetach = "terminal.detach"
TypeTerminalControl = "terminal.control"
TypeTerminalOutput = "terminal.output"
diff --git a/agents/agentd/internal/protocol/terminal.go b/agents/agentd/internal/protocol/terminal.go
index 9f9387d7..612c1d66 100644
--- a/agents/agentd/internal/protocol/terminal.go
+++ b/agents/agentd/internal/protocol/terminal.go
@@ -21,6 +21,14 @@ type TerminalResizePayload struct {
Rows int `json:"rows"`
}
+type TerminalNavigatePayload struct {
+ ChannelID string `json:"channel_id"`
+ Op string `json:"op"`
+ WindowIndex *int `json:"window_index,omitempty"`
+ PaneID string `json:"pane_id,omitempty"`
+ On *bool `json:"on,omitempty"`
+}
+
type TerminalChannelPayload struct {
ChannelID string `json:"channel_id"`
}
diff --git a/agents/agentd/internal/tmux/pty_bridge_test.go b/agents/agentd/internal/tmux/pty_bridge_test.go
index fdfb1328..dd21beee 100644
--- a/agents/agentd/internal/tmux/pty_bridge_test.go
+++ b/agents/agentd/internal/tmux/pty_bridge_test.go
@@ -72,6 +72,37 @@ func TestViewerPTYBridgePinsAndReleasesLetterboxedWindow(t *testing.T) {
}
}
+func TestViewerPTYBridgeMovesLetterboxPinWhenSelectingWindow(t *testing.T) {
+ runner := newFakeTmuxRunner()
+ runner.outputs["display-message -p -t %7 #{session_name}\t#{window_index}\t#{pane_index}"] = []byte("agents\t2\t1\n")
+ bridge, err := newViewerPTYBridge(runner, viewerPTYOptions{
+ ChannelID: "channel-1",
+ PaneID: "%7",
+ Cols: 160,
+ Rows: 50,
+ Letterbox: true,
+ ResumeToken: "resume-1",
+ })
+ if err != nil {
+ t.Fatalf("newViewerPTYBridge: %v", err)
+ }
+ defer bridge.close(false)
+
+ if err := bridge.SelectWindow(3); err != nil {
+ t.Fatalf("select letterboxed viewer window: %v", err)
+ }
+ for _, want := range [][]string{
+ {"set-option", "-w", "-t", "ac-view-channel-1:2", "window-size", "latest"},
+ {"select-window", "-t", "ac-view-channel-1:3"},
+ {"set-option", "-w", "-t", "ac-view-channel-1:3", "window-size", "manual"},
+ {"resize-window", "-t", "ac-view-channel-1:3", "-x", "160", "-y", "50"},
+ } {
+ if !runner.hasRun(want) {
+ t.Fatalf("missing letterbox navigation command %v; runs=%v", want, runner.runs)
+ }
+ }
+}
+
func TestViewerPTYBridgeLetterboxUsesPrivateTmuxSocket(t *testing.T) {
client, _ := newPrivateTmuxClient(t)
panes, err := client.ListPanes()
@@ -113,6 +144,256 @@ func TestViewerPTYBridgeLetterboxUsesPrivateTmuxSocket(t *testing.T) {
}
}
+func TestTerminalNavigateSelectWindowUsesViewerSessionOnPrivateTmuxSocket(t *testing.T) {
+ client, _ := newPrivateTmuxClient(t)
+ panes, err := client.ListPanes()
+ if err != nil || len(panes) != 1 {
+ t.Fatalf("initial private panes=%+v err=%v", panes, err)
+ }
+ if _, err := client.NewWindow("hook-test", "second", ""); err != nil {
+ t.Fatalf("create second private window: %v", err)
+ }
+ if err := client.SelectWindow("hook-test:0"); err != nil {
+ t.Fatalf("restore origin window: %v", err)
+ }
+
+ runner := newExecTmuxRunner(client)
+ manager := newTerminalManagerWithRunner(client, runner, t.TempDir())
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("navigate-integration", panes[0].PaneID, AttachOptions{
+ SessionID: "session-1",
+ Cols: 120,
+ Rows: 40,
+ }); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+
+ if err := manager.Navigate("navigate-integration", TerminalNavigation{Op: NavigateSelectWindow, WindowIndex: 1}); err != nil {
+ t.Fatalf("navigate viewer window: %v", err)
+ }
+
+ if output, err := runner.Output("display-message", "-p", "-t", "hook-test", "#{window_index}"); err != nil {
+ t.Fatalf("read origin current window: %v", err)
+ } else if got := strings.TrimSpace(string(output)); got != "0" {
+ t.Fatalf("origin current window=%q, want 0", got)
+ }
+ if output, err := runner.Output("display-message", "-p", "-t", viewerSessionName("navigate-integration"), "#{window_index}"); err != nil {
+ t.Fatalf("read viewer current window: %v", err)
+ } else if got := strings.TrimSpace(string(output)); got != "1" {
+ t.Fatalf("viewer current window=%q, want 1", got)
+ }
+}
+
+func TestTerminalNavigateSelectPaneUsesViewerSessionOnPrivateTmuxSocket(t *testing.T) {
+ client, _ := newPrivateTmuxClient(t)
+ panes, err := client.ListPanes()
+ if err != nil || len(panes) != 1 {
+ t.Fatalf("initial private panes=%+v err=%v", panes, err)
+ }
+ originPaneID := panes[0].PaneID
+ target, err := client.SplitPaneWithOptions(originPaneID, "horizontal", nil, "")
+ if err != nil {
+ t.Fatalf("split private pane: %v", err)
+ }
+ if err := client.SelectPane(originPaneID); err != nil {
+ t.Fatalf("restore origin pane: %v", err)
+ }
+
+ runner := newExecTmuxRunner(client)
+ manager := newTerminalManagerWithRunner(client, runner, t.TempDir())
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("pane-navigation", originPaneID, AttachOptions{SessionID: "session-1"}); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ if err := manager.Navigate("pane-navigation", TerminalNavigation{Op: NavigateSelectPane, PaneID: target.PaneID}); err != nil {
+ t.Fatalf("navigate viewer pane: %v", err)
+ }
+
+ if output, err := runner.Output("display-message", "-p", "-t", "hook-test", "#{window_index}"); err != nil {
+ t.Fatalf("read origin current window: %v", err)
+ } else if got := strings.TrimSpace(string(output)); got != "0" {
+ t.Fatalf("origin current window=%q, want 0", got)
+ }
+ if output, err := runner.Output("display-message", "-p", "-t", viewerSessionName("pane-navigation"), "#{pane_id}"); err != nil {
+ t.Fatalf("read viewer current pane: %v", err)
+ } else if got := strings.TrimSpace(string(output)); got != target.PaneID {
+ t.Fatalf("viewer current pane=%q, want %q", got, target.PaneID)
+ }
+}
+
+func TestTerminalNavigateZoomSetsRequestedStateOnPrivateTmuxSocket(t *testing.T) {
+ client, _ := newPrivateTmuxClient(t)
+ panes, err := client.ListPanes()
+ if err != nil || len(panes) != 1 {
+ t.Fatalf("initial private panes=%+v err=%v", panes, err)
+ }
+ if _, err := client.SplitPaneWithOptions(panes[0].PaneID, "horizontal", nil, ""); err != nil {
+ t.Fatalf("split private pane: %v", err)
+ }
+
+ manager := newTerminalManagerWithRunner(client, newExecTmuxRunner(client), t.TempDir())
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("zoom-navigation", panes[0].PaneID, AttachOptions{SessionID: "session-1"}); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ if err := manager.Navigate("zoom-navigation", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("enable viewer zoom: %v", err)
+ }
+ assertWindowZoomed(t, client, true)
+
+ // The operation is a state setter, not resize-pane's raw toggle.
+ if err := manager.Navigate("zoom-navigation", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("keep viewer zoom enabled: %v", err)
+ }
+ assertWindowZoomed(t, client, true)
+
+ if err := manager.Navigate("zoom-navigation", TerminalNavigation{Op: NavigateZoom, On: false}); err != nil {
+ t.Fatalf("disable viewer zoom: %v", err)
+ }
+ assertWindowZoomed(t, client, false)
+}
+
+func TestTerminalDetachUnzoomsChannelAppliedFocusOnPrivateTmuxSocket(t *testing.T) {
+ client, _ := newPrivateTmuxClient(t)
+ panes, err := client.ListPanes()
+ if err != nil || len(panes) != 1 {
+ t.Fatalf("initial private panes=%+v err=%v", panes, err)
+ }
+ if _, err := client.SplitPaneWithOptions(panes[0].PaneID, "horizontal", nil, ""); err != nil {
+ t.Fatalf("split private pane: %v", err)
+ }
+
+ manager := newTerminalManagerWithRunner(client, newExecTmuxRunner(client), t.TempDir())
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("detach-zoom", panes[0].PaneID, AttachOptions{SessionID: "session-1"}); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ if err := manager.Navigate("detach-zoom", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("enable viewer zoom: %v", err)
+ }
+ assertWindowZoomed(t, client, true)
+
+ manager.Detach("detach-zoom")
+ assertWindowZoomed(t, client, false)
+}
+
+func TestTerminalNavigationUnzoomsAppliedFocusBeforeSwitchingWindows(t *testing.T) {
+ runner := newFakeTmuxRunner()
+ runner.outputs["display-message -p -t %7 #{session_name}\t#{window_index}\t#{pane_index}"] = []byte("agents\t2\t1\n")
+ manager := newTerminalManagerWithRunner(nil, runner, t.TempDir())
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("switch-focused", "%7", AttachOptions{SessionID: "session-1"}); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ if err := manager.Navigate("switch-focused", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("enable viewer zoom: %v", err)
+ }
+ if err := manager.Navigate("switch-focused", TerminalNavigation{Op: NavigateSelectWindow, WindowIndex: 3}); err != nil {
+ t.Fatalf("switch focused viewer window: %v", err)
+ }
+
+ if got := runner.lastRunIndex([]string{"resize-pane", "-Z", "-t", "ac-view-switch-focused:"}); got < 0 {
+ t.Fatal("focused viewer was never unzoomed")
+ } else if selected := runner.runIndex([]string{"select-window", "-t", "ac-view-switch-focused:3"}); selected < 0 || got > selected {
+ t.Fatalf("unzoom index=%d select index=%d; runs=%v", got, selected, runner.runs)
+ }
+ manager.mu.RLock()
+ zoomApplied := manager.viewerByChannel["switch-focused"].zoomApplied
+ manager.mu.RUnlock()
+ if zoomApplied {
+ t.Fatal("viewer still records applied zoom after switching away")
+ }
+}
+
+func TestTerminalDroppedAndSweptViewerUnzoomsAppliedFocus(t *testing.T) {
+ runner := newFakeTmuxRunner()
+ runner.outputs["display-message -p -t %7 #{session_name}\t#{window_index}\t#{pane_index}"] = []byte("agents\t2\t1\n")
+ manager := newTerminalManagerWithRunner(nil, runner, t.TempDir())
+ defer manager.Close()
+ attached, err := manager.AttachWithOptions("stale-focused", "%7", AttachOptions{SessionID: "session-1"})
+ if err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ if err := manager.Navigate("stale-focused", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("enable viewer zoom: %v", err)
+ }
+
+ manager.MarkChannelsStale()
+ if runner.zoomState() {
+ t.Fatal("dropped channel left its applied zoom active")
+ }
+
+ manager.mu.Lock()
+ viewer := manager.viewerByToken[attached.ResumeToken]
+ viewer.zoomApplied = true
+ runner.setZoomState(true)
+ viewer.staleAt = time.Now().Add(-manager.viewerTTL - time.Second)
+ manager.mu.Unlock()
+ manager.Sweep(time.Now())
+ if runner.zoomState() {
+ t.Fatal("swept channel left its applied zoom active")
+ }
+}
+
+func TestTerminalSupersededViewerUnzoomsAppliedFocus(t *testing.T) {
+ runner := newFakeTmuxRunner()
+ runner.outputs["display-message -p -t %7 #{session_name}\t#{window_index}\t#{pane_index}"] = []byte("agents\t2\t1\n")
+ manager := newTerminalManagerWithRunner(nil, runner, t.TempDir())
+ defer manager.Close()
+ attached, err := manager.AttachWithOptions("superseded-focused", "%7", AttachOptions{SessionID: "session-1"})
+ if err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ if err := manager.Navigate("superseded-focused", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("enable viewer zoom: %v", err)
+ }
+ manager.mu.Lock()
+ manager.viewerByChannel["superseded-focused"].stale = true
+ manager.mu.Unlock()
+
+ if _, err := manager.AttachWithOptions("replacement", "%7", AttachOptions{
+ SessionID: "session-1",
+ ResumeToken: attached.ResumeToken,
+ }); err != nil {
+ t.Fatalf("resume stale viewer: %v", err)
+ }
+ if runner.zoomState() {
+ t.Fatal("superseded channel left its applied zoom active")
+ }
+}
+
+func TestTerminalOwnsSuccessfulZoomRequestWhenWindowWasAlreadyZoomed(t *testing.T) {
+ runner := newFakeTmuxRunner()
+ runner.outputs["display-message -p -t %7 #{session_name}\t#{window_index}\t#{pane_index}"] = []byte("agents\t2\t1\n")
+ manager := newTerminalManagerWithRunner(nil, runner, t.TempDir())
+ defer manager.Close()
+ if _, err := manager.AttachWithOptions("already-focused", "%7", AttachOptions{SessionID: "session-1"}); err != nil {
+ t.Fatalf("attach viewer: %v", err)
+ }
+ runner.setZoomState(true)
+ if err := manager.Navigate("already-focused", TerminalNavigation{Op: NavigateZoom, On: true}); err != nil {
+ t.Fatalf("adopt existing zoom: %v", err)
+ }
+
+ manager.Detach("already-focused")
+ if runner.zoomState() {
+ t.Fatal("successful zoom request was not owned and cleared on detach")
+ }
+}
+
+func assertWindowZoomed(t *testing.T, client *Client, want bool) {
+ t.Helper()
+ panes, err := client.ListPanes()
+ if err != nil {
+ t.Fatalf("list panes for zoom state: %v", err)
+ }
+ for _, pane := range panes {
+ if pane.WindowZoomed != want {
+ t.Fatalf("pane %s zoomed=%v, want %v", pane.PaneID, pane.WindowZoomed, want)
+ }
+ }
+}
+
func TestViewerSessionNameAvoidsSanitizationCollisions(t *testing.T) {
first := viewerSessionName("channel/one")
second := viewerSessionName("channel:one")
@@ -459,6 +740,7 @@ type fakeTmuxRunner struct {
starts []fakePTYStart
processes []*fakePTYProcess
options map[string]string
+ zoomed bool
}
type fakePTYStart struct {
@@ -476,6 +758,12 @@ func newFakeTmuxRunner() *fakeTmuxRunner {
func (r *fakeTmuxRunner) Output(args ...string) ([]byte, error) {
r.mu.Lock()
defer r.mu.Unlock()
+ if len(args) == 5 && args[0] == "display-message" && args[4] == "#{window_zoomed_flag}" {
+ if r.zoomed {
+ return []byte("1\n"), nil
+ }
+ return []byte("0\n"), nil
+ }
if len(args) == 6 && args[0] == "show-options" && args[1] == "-p" && args[2] == "-v" && args[3] == "-t" {
return []byte(r.options[args[4]+" "+args[5]]), nil
}
@@ -486,6 +774,9 @@ func (r *fakeTmuxRunner) Run(args ...string) error {
r.mu.Lock()
defer r.mu.Unlock()
r.runs = append(r.runs, append([]string(nil), args...))
+ if len(args) == 4 && args[0] == "resize-pane" && args[1] == "-Z" {
+ r.zoomed = !r.zoomed
+ }
if len(args) == 6 && args[0] == "set-option" && args[1] == "-p" && args[2] == "-t" {
r.options[args[3]+" "+args[4]] = args[5]
}
@@ -495,6 +786,40 @@ func (r *fakeTmuxRunner) Run(args ...string) error {
return nil
}
+func (r *fakeTmuxRunner) runIndex(want []string) int {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ for index, args := range r.runs {
+ if reflect.DeepEqual(args, want) {
+ return index
+ }
+ }
+ return -1
+}
+
+func (r *fakeTmuxRunner) lastRunIndex(want []string) int {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ for index := len(r.runs) - 1; index >= 0; index-- {
+ if reflect.DeepEqual(r.runs[index], want) {
+ return index
+ }
+ }
+ return -1
+}
+
+func (r *fakeTmuxRunner) zoomState() bool {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return r.zoomed
+}
+
+func (r *fakeTmuxRunner) setZoomState(zoomed bool) {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ r.zoomed = zoomed
+}
+
func (r *fakeTmuxRunner) StartPTY(args []string, env []string, size TerminalSize) (PTYProcess, error) {
r.mu.Lock()
defer r.mu.Unlock()
diff --git a/agents/agentd/internal/tmux/terminal.go b/agents/agentd/internal/tmux/terminal.go
index b4b61eb3..73555c1d 100644
--- a/agents/agentd/internal/tmux/terminal.go
+++ b/agents/agentd/internal/tmux/terminal.go
@@ -82,12 +82,30 @@ type terminalViewer struct {
resumeToken string
readOnly bool
letterbox bool
+ zoomApplied bool
bridge *viewerPTYBridge
detachedAt time.Time
stale bool
staleAt time.Time
}
+type TerminalNavigationOp string
+
+const (
+ NavigateSelectWindow TerminalNavigationOp = "select_window"
+ NavigateSelectPane TerminalNavigationOp = "select_pane"
+ NavigateZoom TerminalNavigationOp = "zoom"
+)
+
+// TerminalNavigation describes an operation against a channel's grouped tmux
+// session. It never targets the origin session directly.
+type TerminalNavigation struct {
+ Op TerminalNavigationOp
+ WindowIndex int
+ PaneID string
+ On bool
+}
+
// AttachOptions contains additive terminal.attach fields.
type AttachOptions struct {
SessionID string
@@ -199,6 +217,7 @@ func (m *TerminalManager) Sweep(now time.Time) {
}
}
if viewer.bridge != nil {
+ m.cleanupViewerZoomLocked(viewer, "sweep")
expiredBridges = append(expiredBridges, viewer.bridge)
viewer.bridge = nil
}
@@ -277,6 +296,7 @@ func (m *TerminalManager) MarkChannelsStale() {
}
viewer.stale = true
viewer.staleAt = now
+ m.cleanupViewerZoomLocked(viewer, "connection drop")
}
}
@@ -422,6 +442,7 @@ func (m *TerminalManager) attachViewerPTY(channelID, paneID string, opts AttachO
viewer.resumeToken = resumeToken
viewer.readOnly = readonly
viewer.letterbox = opts.Letterbox
+ viewer.zoomApplied = false
viewer.bridge = bridge
viewer.detachedAt = time.Time{}
viewer.stale = false
@@ -452,6 +473,7 @@ func (m *TerminalManager) supersedeStaleViewerLocked(viewer *terminalViewer) {
if m.paneController[viewer.paneID] == channelID {
delete(m.paneController, viewer.paneID)
}
+ m.cleanupViewerZoomLocked(viewer, "supersede")
if viewer.bridge != nil {
viewer.bridge.close(false)
viewer.bridge = nil
@@ -598,6 +620,7 @@ func (m *TerminalManager) Detach(channelID string) (string, bool) {
if m.channelPerViewer[channelID] {
viewer := m.viewerByChannel[channelID]
+ m.cleanupViewerZoomLocked(viewer, "detach")
delete(m.viewerByChannel, channelID)
delete(m.channelPerViewer, channelID)
viewer.channelID = ""
@@ -723,6 +746,69 @@ func (m *TerminalManager) SendInput(channelID string, data string) error {
return m.client.SendKeysRaw(paneID, data)
}
+// Navigate changes the current target of a grouped viewer without replacing
+// its PTY bridge. The origin tmux session keeps its own current window.
+func (m *TerminalManager) Navigate(channelID string, navigation TerminalNavigation) error {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ _, exists := m.channelToPane[channelID]
+ viewer := m.viewerByChannel[channelID]
+ var bridge *viewerPTYBridge
+ if viewer != nil {
+ bridge = viewer.bridge
+ }
+ if !exists {
+ return fmt.Errorf("channel %s not found", channelID)
+ }
+ if bridge == nil {
+ return fmt.Errorf("channel %s does not use a grouped viewer session", channelID)
+ }
+
+ switch navigation.Op {
+ case NavigateSelectWindow:
+ if navigation.WindowIndex < 0 {
+ return fmt.Errorf("window index must be non-negative")
+ }
+ if err := m.unzoomViewerLocked(viewer, "window switch"); err != nil {
+ return err
+ }
+ return bridge.SelectWindow(navigation.WindowIndex)
+ case NavigateSelectPane:
+ if strings.TrimSpace(navigation.PaneID) == "" {
+ return fmt.Errorf("pane id is required")
+ }
+ if err := m.unzoomViewerLocked(viewer, "pane switch"); err != nil {
+ return err
+ }
+ return bridge.SelectPane(navigation.PaneID)
+ case NavigateZoom:
+ if err := bridge.SetZoom(navigation.On); err != nil {
+ return err
+ }
+ viewer.zoomApplied = navigation.On
+ return nil
+ default:
+ return fmt.Errorf("unsupported terminal navigation op %q", navigation.Op)
+ }
+}
+
+func (m *TerminalManager) unzoomViewerLocked(viewer *terminalViewer, reason string) error {
+ if viewer == nil || !viewer.zoomApplied || viewer.bridge == nil {
+ return nil
+ }
+ if err := viewer.bridge.SetZoom(false); err != nil {
+ return fmt.Errorf("unzoom viewer during %s: %w", reason, err)
+ }
+ viewer.zoomApplied = false
+ return nil
+}
+
+func (m *TerminalManager) cleanupViewerZoomLocked(viewer *terminalViewer, reason string) {
+ if err := m.unzoomViewerLocked(viewer, reason); err != nil {
+ log.Printf("Failed to %v", err)
+ }
+}
+
// TakeControl promotes the given channel to controller for its pane.
func (m *TerminalManager) TakeControl(channelID string) error {
m.mu.Lock()
@@ -859,6 +945,7 @@ func (m *TerminalManager) Close() {
seenViewerBridges := make(map[*viewerPTYBridge]struct{})
for _, viewer := range m.viewerByToken {
if viewer.bridge != nil {
+ m.cleanupViewerZoomLocked(viewer, "manager close")
if _, seen := seenViewerBridges[viewer.bridge]; !seen {
viewerBridges = append(viewerBridges, viewer.bridge)
seenViewerBridges[viewer.bridge] = struct{}{}
diff --git a/agents/agentd/internal/tmux/viewer_pty.go b/agents/agentd/internal/tmux/viewer_pty.go
index a8882b2d..0986393e 100644
--- a/agents/agentd/internal/tmux/viewer_pty.go
+++ b/agents/agentd/internal/tmux/viewer_pty.go
@@ -7,6 +7,7 @@ import (
"io"
"os"
"os/exec"
+ "strconv"
"strings"
"sync"
"time"
@@ -279,6 +280,106 @@ func (b *viewerPTYBridge) Size() TerminalSize {
return b.size
}
+func (b *viewerPTYBridge) SelectWindow(windowIndex int) error {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ select {
+ case <-b.closed:
+ return fmt.Errorf("viewer PTY is closed")
+ default:
+ }
+
+ target := b.viewSession + ":" + strconv.Itoa(windowIndex)
+ return b.selectWindowLocked(target)
+}
+
+func (b *viewerPTYBridge) SelectPane(paneID string) error {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ select {
+ case <-b.closed:
+ return fmt.Errorf("viewer PTY is closed")
+ default:
+ }
+
+ described, err := b.runner.Output("display-message", "-p", "-t", paneID, "#{window_index}\t#{pane_index}")
+ if err != nil {
+ return fmt.Errorf("describe viewer pane %s: %w", paneID, err)
+ }
+ parts := strings.Split(strings.TrimSpace(string(described)), "\t")
+ if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+ return fmt.Errorf("unexpected tmux pane target %q for %s", strings.TrimSpace(string(described)), paneID)
+ }
+
+ windowTarget := b.viewSession + ":" + parts[0]
+ paneTarget := windowTarget + "." + parts[1]
+ resolved, err := b.runner.Output("display-message", "-p", "-t", paneTarget, "#{pane_id}")
+ if err != nil || strings.TrimSpace(string(resolved)) != paneID {
+ return fmt.Errorf("pane %s is not in grouped viewer session", paneID)
+ }
+ if err := b.selectWindowLocked(windowTarget); err != nil {
+ return fmt.Errorf("select viewer pane window: %w", err)
+ }
+ if err := b.runner.Run("select-pane", "-t", paneTarget); err != nil {
+ return fmt.Errorf("select viewer pane: %w", err)
+ }
+ return nil
+}
+
+func (b *viewerPTYBridge) selectWindowLocked(target string) error {
+ previous := b.windowTarget
+ if b.letterbox && previous != target {
+ if err := b.runner.Run("set-option", "-w", "-t", previous, "window-size", "latest"); err != nil {
+ return fmt.Errorf("release previous viewer window sizing: %w", err)
+ }
+ }
+ if err := b.runner.Run("select-window", "-t", target); err != nil {
+ return fmt.Errorf("select viewer window: %w", err)
+ }
+ if b.letterbox && previous != target {
+ if err := b.runner.Run("set-option", "-w", "-t", target, "window-size", "manual"); err != nil {
+ _ = b.runner.Run("set-option", "-w", "-t", target, "window-size", "latest")
+ return fmt.Errorf("pin selected viewer window sizing: %w", err)
+ }
+ if err := b.runner.Run(
+ "resize-window",
+ "-t", target,
+ "-x", fmt.Sprintf("%d", b.size.Cols),
+ "-y", fmt.Sprintf("%d", b.size.Rows),
+ ); err != nil {
+ _ = b.runner.Run("set-option", "-w", "-t", target, "window-size", "latest")
+ return fmt.Errorf("size selected viewer window: %w", err)
+ }
+ }
+ b.windowTarget = target
+ return nil
+}
+
+func (b *viewerPTYBridge) SetZoom(on bool) error {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ select {
+ case <-b.closed:
+ return fmt.Errorf("viewer PTY is closed")
+ default:
+ }
+
+ zoomed, err := b.runner.Output("display-message", "-p", "-t", b.viewSession, "#{window_zoomed_flag}")
+ if err != nil {
+ return fmt.Errorf("read viewer zoom state: %w", err)
+ }
+ isZoomed := strings.TrimSpace(string(zoomed)) == "1"
+ if isZoomed == on {
+ return nil
+ }
+ // Zoom is a window-shared tmux property even though navigation targets the
+ // grouped viewer. Callers must surface that shared effect predictably.
+ if err := b.runner.Run("resize-pane", "-Z", "-t", b.viewSession+":"); err != nil {
+ return fmt.Errorf("set viewer zoom state: %w", err)
+ }
+ return nil
+}
+
func (b *viewerPTYBridge) DetachChannel(channelID string) {
if b.fanout != nil {
b.fanout.Detach(channelID)
diff --git a/agents/agentd/internal/ws/protocol_fixtures_test.go b/agents/agentd/internal/ws/protocol_fixtures_test.go
index 063881f0..2f372508 100644
--- a/agents/agentd/internal/ws/protocol_fixtures_test.go
+++ b/agents/agentd/internal/ws/protocol_fixtures_test.go
@@ -71,6 +71,7 @@ func TestProtocolFixtureMatrixRoundTripsProductionTypes(t *testing.T) {
protocol.TypeMCPGetProjectConfig, protocol.TypeMCPUpdateProject, protocol.TypeMCPServers,
protocol.TypeMCPConfig, protocol.TypeMCPProjectConfig, protocol.TypeMCPUpdateResult,
protocol.TypeTerminalAttach, protocol.TypeTerminalInput, protocol.TypeTerminalResize,
+ protocol.TypeTerminalNavigate,
protocol.TypeTerminalDetach, protocol.TypeTerminalControl, protocol.TypeTerminalOutput,
protocol.TypeTerminalAttached, protocol.TypeTerminalDetached, protocol.TypeTerminalError,
protocol.TypeTerminalReadOnly, protocol.TypeTerminalLag, protocol.TypeTerminalAudit,
@@ -151,6 +152,8 @@ func fixtureMessageTarget(t *testing.T, messageType string, agentMessage bool) a
return &protocol.ServerMessage[protocol.TerminalInputPayload]{}
case protocol.TypeTerminalResize:
return &protocol.ServerMessage[protocol.TerminalResizePayload]{}
+ case protocol.TypeTerminalNavigate:
+ return &protocol.ServerMessage[protocol.TerminalNavigatePayload]{}
case protocol.TypeTerminalDetach:
return &protocol.ServerMessage[protocol.TerminalChannelPayload]{}
case protocol.TypeTerminalOutput:
diff --git a/apps/dashboard/src/components/TerminalView.tsx b/apps/dashboard/src/components/TerminalView.tsx
index 59857933..b8568c55 100644
--- a/apps/dashboard/src/components/TerminalView.tsx
+++ b/apps/dashboard/src/components/TerminalView.tsx
@@ -191,6 +191,7 @@ export function TerminalView({
disconnect,
suspend,
takeControl,
+ navigate,
sendInput,
} = useTerminalConnection({
sessionId,
@@ -268,6 +269,7 @@ export function TerminalView({
detach: disconnect,
suspend,
takeControl,
+ navigate,
focus: () => terminalRef.current?.focus(),
copySelection,
copyLastLines: (lines = 50) => copyLastLines(lines),
@@ -296,6 +298,7 @@ export function TerminalView({
copySelection,
disconnect,
onControllerChange,
+ navigate,
paste,
terminalRef,
suspend,
diff --git a/apps/dashboard/src/components/terminal/PersistentTerminalHost.tsx b/apps/dashboard/src/components/terminal/PersistentTerminalHost.tsx
index dc84d58a..ed9360ac 100644
--- a/apps/dashboard/src/components/terminal/PersistentTerminalHost.tsx
+++ b/apps/dashboard/src/components/terminal/PersistentTerminalHost.tsx
@@ -41,6 +41,7 @@ export function PersistentTerminalSlot({
sessionId,
hostId,
paneId,
+ tmuxSessionKey,
autoAttach,
letterbox,
className,
@@ -55,7 +56,7 @@ export function PersistentTerminalSlot({
const unregister = terminalHostStore.registerSurface({
id,
- descriptor: { sessionId, hostId, paneId, autoAttach, letterbox },
+ descriptor: { sessionId, hostId, paneId, tmuxSessionKey, autoAttach, letterbox },
target,
visible: isSurfaceVisible(target),
controllerRef,
@@ -69,7 +70,7 @@ export function PersistentTerminalSlot({
resizeObserver.disconnect();
unregister();
};
- }, [autoAttach, controllerRef, hostId, id, letterbox, paneId, sessionId]);
+ }, [autoAttach, controllerRef, hostId, id, letterbox, paneId, sessionId, tmuxSessionKey]);
return (
state.terminalWarmTimeoutMinutes ?? DEFAULT_TERMINAL_WARM_TIMEOUT_MINUTES
);
- const terminalContext = snapshot.descriptor
+ const attachmentDescriptor = snapshot.attachmentDescriptor ?? snapshot.descriptor;
+ const terminalContext = attachmentDescriptor
? {
descriptorKey: snapshot.descriptorKey!,
- letterbox: snapshot.descriptor.letterbox,
- warmKey: getTerminalWarmKey(snapshot.descriptor),
+ letterbox: attachmentDescriptor.letterbox,
+ warmKey: getTerminalWarmKey(attachmentDescriptor),
}
: undefined;
@@ -165,14 +167,14 @@ export function PersistentTerminalHost() {
return (
<>
- {portalNode && snapshot.descriptor && createPortal(
+ {portalNode && attachmentDescriptor && createPortal(
diff --git a/apps/dashboard/src/components/terminal/protocol.test.ts b/apps/dashboard/src/components/terminal/protocol.test.ts
index 01abd0f5..1dad09c1 100644
--- a/apps/dashboard/src/components/terminal/protocol.test.ts
+++ b/apps/dashboard/src/components/terminal/protocol.test.ts
@@ -1,7 +1,34 @@
-import { describe, expect, it } from 'vitest';
-import { buildTerminalHello, buildTerminalWebSocketUrl, decodeTerminalFrame } from './protocol';
+import { describe, expect, it, vi } from 'vitest';
+import {
+ buildTerminalHello,
+ buildTerminalWebSocketUrl,
+ decodeTerminalFrame,
+ sendTerminalNavigation,
+} from './protocol';
describe('browser terminal protocol', () => {
+ it('emits typed navigation frames only on an open terminal socket', () => {
+ const send = vi.fn();
+ const socket = { readyState: 1, send } as unknown as WebSocket;
+ expect(sendTerminalNavigation(socket, {
+ type: 'navigate',
+ op: 'select_pane',
+ pane_id: '%7',
+ })).toBe(true);
+ expect(send).toHaveBeenCalledWith(JSON.stringify({
+ type: 'navigate',
+ op: 'select_pane',
+ pane_id: '%7',
+ }));
+
+ expect(sendTerminalNavigation({ readyState: 3, send } as unknown as WebSocket, {
+ type: 'navigate',
+ op: 'zoom',
+ on: true,
+ })).toBe(false);
+ expect(send).toHaveBeenCalledTimes(1);
+ });
+
it('negotiates binary mode and writes ArrayBuffer frames as bytes', () => {
expect(buildTerminalHello()).toEqual({ type: 'hello', binary: true });
diff --git a/apps/dashboard/src/components/terminal/protocol.ts b/apps/dashboard/src/components/terminal/protocol.ts
index 01753d71..505f9036 100644
--- a/apps/dashboard/src/components/terminal/protocol.ts
+++ b/apps/dashboard/src/components/terminal/protocol.ts
@@ -2,6 +2,7 @@ import {
BrowserTerminalServerMessageSchema,
TerminalDimensionSchema,
type BrowserTerminalClientMessage,
+ type BrowserTerminalNavigateMessage,
type BrowserTerminalServerMessage,
} from '@agent-command/schema';
@@ -15,6 +16,15 @@ export function buildTerminalHello(): BrowserTerminalClientMessage {
return { type: 'hello', binary: true };
}
+export function sendTerminalNavigation(
+ socket: WebSocket | null,
+ message: BrowserTerminalNavigateMessage
+): boolean {
+ if (socket?.readyState !== 1) return false;
+ socket.send(JSON.stringify(message));
+ return true;
+}
+
export function buildTerminalWebSocketUrl(
baseUrl: string,
dimensions?: { cols: number; rows: number },
diff --git a/apps/dashboard/src/components/terminal/terminalHostStore.test.ts b/apps/dashboard/src/components/terminal/terminalHostStore.test.ts
index 474eccff..77b5e324 100644
--- a/apps/dashboard/src/components/terminal/terminalHostStore.test.ts
+++ b/apps/dashboard/src/components/terminal/terminalHostStore.test.ts
@@ -18,6 +18,7 @@ function controller(readOnly: boolean): TerminalController {
detach: () => undefined,
suspend: () => false,
takeControl: () => undefined,
+ navigate: () => false,
focus: () => undefined,
copySelection: () => undefined,
copyLastLines: () => undefined,
@@ -92,6 +93,121 @@ describe('persistent terminal host', () => {
expect(host.getSnapshot().terminalInstance).toBeNull();
});
+ it('retargets within one tmux session without replacing the live attachment or xterm instance', () => {
+ const host = createTerminalHostStore();
+ const first = {
+ sessionId: 'session-a',
+ hostId: 'host-1',
+ paneId: '%1',
+ tmuxSessionKey: 'host-1\u0000agents',
+ autoAttach: true,
+ };
+ const second = {
+ sessionId: 'session-b',
+ hostId: 'host-1',
+ paneId: '%2',
+ tmuxSessionKey: 'host-1\u0000agents',
+ autoAttach: true,
+ };
+ const terminal = {} as XTerminal;
+ const leaveFirst = host.registerSurface({
+ id: 'first',
+ descriptor: first,
+ target: {} as HTMLDivElement,
+ visible: true,
+ });
+ host.setTerminalInstance(getTerminalDescriptorKey(first), terminal);
+ host.setController({ ...controller(false), navigate: () => true });
+ expect(host.navigateWithinAttachment(second, [
+ { type: 'navigate', op: 'select_window', window_index: 2 },
+ { type: 'navigate', op: 'select_pane', pane_id: '%2' },
+ ])).toBe(true);
+
+ leaveFirst();
+ host.registerSurface({
+ id: 'second',
+ descriptor: second,
+ target: {} as HTMLDivElement,
+ visible: true,
+ });
+
+ expect(host.getSnapshot()).toMatchObject({
+ descriptor: second,
+ attachmentDescriptor: first,
+ descriptorKey: 'session-a\u0000%1',
+ terminalInstance: terminal,
+ });
+ });
+
+ it('emits navigation only when the target shares the live attachment key', () => {
+ const host = createTerminalHostStore();
+ const descriptor = {
+ sessionId: 'session-a',
+ hostId: 'host-1',
+ paneId: '%1',
+ tmuxSessionKey: 'host-1\u0000agents',
+ autoAttach: true,
+ };
+ host.registerSurface({
+ id: 'first',
+ descriptor,
+ target: {} as HTMLDivElement,
+ visible: true,
+ });
+ const navigate = vi.fn(() => true);
+ host.setController({ ...controller(false), navigate } as TerminalController);
+
+ const sameTmuxSession = {
+ ...descriptor,
+ sessionId: 'session-b',
+ paneId: '%2',
+ };
+ expect(host.navigateWithinAttachment(sameTmuxSession, [
+ { type: 'navigate', op: 'select_window', window_index: 2 },
+ { type: 'navigate', op: 'select_pane', pane_id: '%2' },
+ ])).toBe(true);
+ expect(navigate).toHaveBeenCalledTimes(2);
+
+ expect(host.navigateWithinAttachment({
+ ...sameTmuxSession,
+ tmuxSessionKey: 'host-1\u0000other',
+ }, [{ type: 'navigate', op: 'select_window', window_index: 0 }])).toBe(false);
+ expect(navigate).toHaveBeenCalledTimes(2);
+ });
+
+ it('falls back to a pane-specific reattach when same-session navigation was not emitted', () => {
+ const host = createTerminalHostStore();
+ const first = {
+ sessionId: 'session-a',
+ hostId: 'host-1',
+ paneId: '%1',
+ tmuxSessionKey: 'host-1\u0000agents',
+ autoAttach: true,
+ };
+ const second = { ...first, sessionId: 'session-b', paneId: '%2' };
+ const leaveFirst = host.registerSurface({
+ id: 'first',
+ descriptor: first,
+ target: {} as HTMLDivElement,
+ visible: true,
+ });
+ host.setTerminalInstance(getTerminalDescriptorKey(first), {} as XTerminal);
+
+ leaveFirst();
+ host.registerSurface({
+ id: 'second',
+ descriptor: second,
+ target: {} as HTMLDivElement,
+ visible: true,
+ });
+
+ expect(host.getSnapshot()).toMatchObject({
+ descriptorKey: 'session-b\u0000%2',
+ attachmentDescriptor: second,
+ terminalInstance: null,
+ });
+ });
+
it('snapshots the prior pane buffer when a different session takes the host', () => {
const host = createTerminalHostStore();
const first = { sessionId: 'session-a', paneId: '%1', autoAttach: true };
diff --git a/apps/dashboard/src/components/terminal/terminalHostStore.ts b/apps/dashboard/src/components/terminal/terminalHostStore.ts
index 4ba2443a..ec17d907 100644
--- a/apps/dashboard/src/components/terminal/terminalHostStore.ts
+++ b/apps/dashboard/src/components/terminal/terminalHostStore.ts
@@ -1,4 +1,5 @@
import type { MutableRefObject } from 'react';
+import type { BrowserTerminalNavigateMessage } from '@agent-command/schema';
import type { ConnectionStatus, TerminalController, XTerminal } from './types';
import type { TerminalGridDimensions } from '@/hooks/terminalGrid';
import { captureTerminalWarmBuffer } from '@/hooks/terminalWarmCache';
@@ -7,12 +8,14 @@ export interface TerminalHostDescriptor {
sessionId: string;
hostId?: string;
paneId?: string;
+ tmuxSessionKey?: string;
autoAttach: boolean;
letterbox?: TerminalGridDimensions;
}
export interface TerminalHostSnapshot {
descriptor: TerminalHostDescriptor | null;
+ attachmentDescriptor: TerminalHostDescriptor | null;
descriptorKey: string | null;
target: HTMLDivElement | null;
visible: boolean;
@@ -33,6 +36,7 @@ interface SurfaceRegistration {
const EMPTY_SNAPSHOT: TerminalHostSnapshot = {
descriptor: null,
+ attachmentDescriptor: null,
descriptorKey: null,
target: null,
visible: false,
@@ -43,10 +47,9 @@ const EMPTY_SNAPSHOT: TerminalHostSnapshot = {
};
export function getTerminalDescriptorKey(descriptor: TerminalHostDescriptor): string {
- // Identity is session+pane ONLY. Letterbox dims must never be part of the
- // key: they can change while attached (topology updates), and a key change
- // remounts the terminal — which detaches, releases the agentd size pin,
- // changes the dims again, and loops attach/detach indefinitely.
+ // Identity starts as session+pane. A successful viewer-scoped navigation
+ // explicitly preserves the existing key in the store. Letterbox dims must
+ // never be part of this identity or they recreate the attach/detach loop.
return `${descriptor.sessionId}\u0000${descriptor.paneId || ''}`;
}
@@ -61,6 +64,7 @@ export function createTerminalHostStore() {
let order = 0;
let controller: TerminalController | null = null;
let activeControllerRef: MutableRefObject | undefined;
+ const pendingRetargetDescriptorKeys = new Set();
const emit = () => {
for (const listener of listeners) listener();
@@ -95,12 +99,27 @@ export function createTerminalHostStore() {
return;
}
- const descriptorKey = getTerminalDescriptorKey(activeSurface.descriptor);
+ const targetDescriptorKey = getTerminalDescriptorKey(activeSurface.descriptor);
+ const sameTmuxSession = Boolean(
+ activeSurface.descriptor.tmuxSessionKey
+ && activeSurface.descriptor.tmuxSessionKey === snapshot.attachmentDescriptor?.tmuxSessionKey
+ );
+ const alreadySelected = snapshot.descriptor
+ ? getTerminalDescriptorKey(snapshot.descriptor) === targetDescriptorKey
+ : false;
+ const preserveNavigatedAttachment = sameTmuxSession && (
+ pendingRetargetDescriptorKeys.has(targetDescriptorKey) || alreadySelected
+ );
+ const descriptorKey = preserveNavigatedAttachment && snapshot.descriptorKey
+ ? snapshot.descriptorKey
+ : targetDescriptorKey;
+ pendingRetargetDescriptorKeys.delete(targetDescriptorKey);
const descriptorChanged = descriptorKey !== snapshot.descriptorKey;
if (descriptorChanged) {
- if (snapshot.descriptor && snapshot.terminalInstance) {
+ const attachmentDescriptor = snapshot.attachmentDescriptor ?? snapshot.descriptor;
+ if (attachmentDescriptor && snapshot.terminalInstance) {
captureTerminalWarmBuffer(
- getTerminalWarmKey(snapshot.descriptor),
+ getTerminalWarmKey(attachmentDescriptor),
snapshot.terminalInstance
);
}
@@ -109,6 +128,9 @@ export function createTerminalHostStore() {
setActiveControllerRef(activeSurface.controllerRef);
snapshot = {
descriptor: activeSurface.descriptor,
+ attachmentDescriptor: descriptorChanged
+ ? activeSurface.descriptor
+ : snapshot.attachmentDescriptor ?? activeSurface.descriptor,
descriptorKey,
target: activeSurface.target,
visible: activeSurface.visible,
@@ -162,6 +184,24 @@ export function createTerminalHostStore() {
emit();
}
},
+ navigateWithinAttachment(
+ descriptor: TerminalHostDescriptor,
+ messages: BrowserTerminalNavigateMessage[]
+ ) {
+ if (
+ !descriptor.tmuxSessionKey
+ || descriptor.tmuxSessionKey !== snapshot.attachmentDescriptor?.tmuxSessionKey
+ || controller?.status !== 'connected'
+ ) {
+ return false;
+ }
+ const navigated = messages.length > 0
+ && messages.every((message) => controller?.navigate(message) ?? false);
+ if (navigated) {
+ pendingRetargetDescriptorKeys.add(getTerminalDescriptorKey(descriptor));
+ }
+ return navigated;
+ },
setTerminalInstance(descriptorKey: string, instance: XTerminal | null) {
if (snapshot.descriptorKey !== descriptorKey) return;
snapshot = { ...snapshot, terminalInstance: instance };
@@ -177,6 +217,7 @@ export function createTerminalHostStore() {
setActiveControllerRef(undefined);
controller = null;
order = 0;
+ pendingRetargetDescriptorKeys.clear();
snapshot = EMPTY_SNAPSHOT;
emit();
},
diff --git a/apps/dashboard/src/components/terminal/types.ts b/apps/dashboard/src/components/terminal/types.ts
index a82b6645..6a5a82a0 100644
--- a/apps/dashboard/src/components/terminal/types.ts
+++ b/apps/dashboard/src/components/terminal/types.ts
@@ -1,3 +1,5 @@
+import type { BrowserTerminalNavigateMessage } from '@agent-command/schema';
+
export type XTerminal = import('@xterm/xterm').Terminal;
export type XFitAddon = import('@xterm/addon-fit').FitAddon;
export type XSearchAddon = import('@xterm/addon-search').SearchAddon;
@@ -17,6 +19,7 @@ export interface TerminalController {
detach: () => void;
suspend: () => boolean;
takeControl: () => void;
+ navigate: (message: BrowserTerminalNavigateMessage) => boolean;
focus: () => void;
copySelection: () => void;
copyLastLines: (lines?: number) => void;
diff --git a/apps/dashboard/src/components/tmux/TmuxActionSheet.tsx b/apps/dashboard/src/components/tmux/TmuxActionSheet.tsx
index 9cb80923..d236a11b 100644
--- a/apps/dashboard/src/components/tmux/TmuxActionSheet.tsx
+++ b/apps/dashboard/src/components/tmux/TmuxActionSheet.tsx
@@ -33,11 +33,13 @@ interface TmuxActionSheetProps {
idlePending: boolean;
terminating: boolean;
onClose: () => void;
+ onDetach?: () => void;
onIdleToggle: () => void;
onSendTo: () => void;
onOpenMcp: () => void;
onTerminate: () => void;
onLaunchWindowHere?: () => void;
+ onSelectSession: (sessionId: string) => void;
}
export function TmuxActionSheet({
@@ -47,11 +49,13 @@ export function TmuxActionSheet({
idlePending,
terminating,
onClose,
+ onDetach,
onIdleToggle,
onSendTo,
onOpenMcp,
onTerminate,
onLaunchWindowHere,
+ onSelectSession,
}: TmuxActionSheetProps) {
const title = session ? getSessionDisplayName(session) : 'No pane selected';
@@ -87,7 +91,7 @@ export function TmuxActionSheet({
variant="outline"
className="justify-start gap-2"
disabled={!session}
- onClick={() => terminalControllerRef.current?.detach()}
+ onClick={() => onDetach ? onDetach() : terminalControllerRef.current?.detach()}
>
Detach
@@ -112,7 +116,13 @@ export function TmuxActionSheet({
- {session && }
+ {session && (
+
+ )}