perf: cut tab/workspace switch latency and background churn (#108)

vaayne · web-flow · commit 6a18aa882e15 · 2026-07-31T21:28:10.000+08:00
* app: cut tab and workspace switch latency

Three sources of switching lag, measured against the live app (raw tmux
select-window is ~18ms; Mori took 110-160ms end to end before the tmux
window actually flipped):

- selectWindow/selectPane issued the tmux command in a main-actor Task,
  which queued behind the selection-triggered UI re-render (~60-100ms).
  The command is now Task.detached and fired before any state mutation.
- selectWorktree serialized terminal attach behind a git status, a
  list-sessions round trip, and a full tmux rescan. When the last poll
  (&lt;=5s) saw the session alive, attach now happens immediately and the
  reconcile chain runs behind it.
- The terminal surface cache held only 3 surfaces, so cycling through
  more than three workspaces destroyed and respawned a login shell +
  tmux attach on every switch. Raised to 10.

* tmux: collapse the runtime scan into a single list-panes -a

scanAll ran 1 + sessions + windows subprocess invocations every 5s poll
(dozens of SSH round trips for remote endpoints). A single list-panes -a
row per pane carries session and window context; parseScan groups rows
back into the session tree. tmux guarantees every session has &gt;=1 window
and every window &gt;=1 pane, so grouping loses no nodes. Window currentPath
keeps list-windows semantics by resolving from the active pane.

* ui: stop per-frame agent-pulse renders and redundant tab rebuilds

The sidebar's agent working icon used a SwiftUI repeatForever opacity
animation, which re-rendered the hosting view's display list every frame
for as long as any agent was working (~12% of the main thread at idle,
sampled). It now pulses via a repeating CABasicAnimation on the layer,
which runs on the render server.

TerminalTabsBarView's observation fires for any runtimeWindows change
(every poll); it tore down and recreated every tab NSView each time. It
now snapshots what it last rendered and skips rebuilds when the strip's
windows and selection are unchanged.

* docs: changelog entries for switching performance work
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **iOS (MoriRemote)**: The workspace sidebar gains a bottom quick-filter field (cmd+p style) — type to narrow projects, sessions, branches, and windows by name, title, or path. Matching a session keeps its whole group; otherwise only matching windows are shown. Thumb-reachable at the bottom edge, and it rides above the keyboard.
 - **iOS (MoriRemote)**: The keyboard-dismiss button is now pinned at the far left of the accessory key bar, outside the scrollable key row — it used to sit at the row's right end, forcing a swipe to the very end just to put the keyboard away.
 
+### ⚡ Performance
+
+- **macOS**: Tab and workspace switching is much snappier. The `tmux select-window` call no longer queues behind the selection-triggered UI re-render (~60–100ms saved per tab switch), switching to a workspace whose session was seen alive by the last poll attaches the terminal immediately instead of waiting for a git branch check plus a full tmux rescan, and the terminal surface cache grew from 3 to 10 so cycling through more than three workspaces stops destroying and respawning shells.
+- **macOS**: Less background churn. The 5-second runtime scan is now a single `tmux list-panes -a` invocation instead of one subprocess per session and window (one SSH round trip instead of dozens for remote workspaces), the terminal tab strip only rebuilds when the windows it shows actually change, and the sidebar's agent "breathing" icon pulses via Core Animation instead of re-rendering the SwiftUI tree every frame while an agent is working.
+
 ### 🐛 Bug Fixes
 
 - **iOS (MoriRemote)**: Switching to a tmux window no longer lands you in a stuck pane showing `(repeat) N` at the bottom. Panes that had been scrolled stay in tmux copy-mode across window switches, where digit keys hit tmux's default `(repeat)` command-prompt binding and swallow input; sidebar switches now cancel copy-mode on the target pane so it's immediately typeable.
diff --git a/CHANGELOG.zh-Hans.md b/CHANGELOG.zh-Hans.md
@@ -16,6 +16,11 @@
 - **iOS (MoriRemote)**：工作区侧栏底部新增快速筛选框（类似 cmd+p）——输入即可按名称、标题或路径过滤项目、会话、分支和窗口。匹配到会话时保留整组；否则只显示匹配的窗口。位于底部方便拇指操作，弹出键盘时会自动上浮。
 - **iOS (MoriRemote)**：收起键盘按钮固定在快捷键条最左侧、可滚动按键区之外——此前它在滚动条最右端，每次收键盘都要滑到最末尾。
 
+### ⚡ 性能
+
+- **macOS**：标签页与工作区切换明显更跟手。`tmux select-window` 不再排在选中态触发的 UI 重渲染之后（每次切换省约 60–100ms）；切换到上次轮询确认存活的工作区会立即挂载终端，不再等待 git 分支检查和全量 tmux 扫描；终端 surface 缓存从 3 个提升到 10 个，超过三个工作区来回切换时不再反复销毁重建 shell。
+- **macOS**：后台开销更低。每 5 秒的运行时扫描合并为单条 `tmux list-panes -a`（原来每个 session、每个 window 各起一个子进程，远程工作区从几十次 SSH 往返降为一次）；终端标签条只在其显示内容真正变化时才重建；侧边栏 agent"呼吸"图标改用 Core Animation 脉动，agent 工作期间不再逐帧重渲染 SwiftUI 树。
+
 ### 🐛 问题修复
 
 - **iOS (MoriRemote)**：切换 tmux 窗口后不再出现底部显示 `(repeat) N`、无法输入的卡死状态。滚动过的 pane 会一直停留在 tmux copy-mode，切换窗口也不退出，此时数字键会命中 tmux 默认的 `(repeat)` 命令提示绑定并吞掉输入；现在从侧栏切换时会自动退出目标 pane 的 copy-mode，切过去即可直接输入。
diff --git a/Packages/MoriTmux/Sources/MoriTmux/TmuxBackend.swift b/Packages/MoriTmux/Sources/MoriTmux/TmuxBackend.swift
@@ -82,32 +82,13 @@ public actor TmuxBackend: TmuxControlling {
     }
 
     public func scanAll() async throws -> [TmuxSession] {
-        // 1. List all sessions
-        let sessionsOutput = try await runner.run(
-            "list-sessions", "-F", TmuxParser.sessionFormat
+        // A single list-panes -a returns every session/window/pane in one tmux
+        // invocation (one subprocess locally, one round trip over SSH) instead
+        // of 1 + sessions + windows separate ones.
+        let output = try await runner.run(
+            "list-panes", "-a", "-F", TmuxParser.scanFormat
         )
-        var sessions = TmuxParser.parseSessions(sessionsOutput)
-
-        // 2. For each session, list windows
-        for i in sessions.indices {
-            let windowsOutput = try await runner.run(
-                "list-windows", "-t", sessions[i].sessionId,
-                "-F", TmuxParser.windowFormat
-            )
-            sessions[i].windows = TmuxParser.parseWindows(windowsOutput)
-
-            // 3. For each window, list panes
-            for j in sessions[i].windows.indices {
-                let target = "\(sessions[i].sessionId):\(sessions[i].windows[j].windowId)"
-                let panesOutput = try await runner.run(
-                    "list-panes", "-t", target,
-                    "-F", TmuxParser.paneFormat
-                )
-                sessions[i].windows[j].panes = TmuxParser.parsePanes(panesOutput)
-            }
-        }
-
-        return sessions
+        return TmuxParser.parseScan(output)
     }
 
     /// List tmux session names without deep window/pane scans.
diff --git a/Packages/MoriTmux/Sources/MoriTmux/TmuxParser.swift b/Packages/MoriTmux/Sources/MoriTmux/TmuxParser.swift
@@ -43,8 +43,90 @@ public enum TmuxParser {
         "#{@mori-agent-name}",
     ].joined(separator: delimiter)
 
+    /// Format string for the single-command full scan (`tmux list-panes -a -F`).
+    /// One row per pane, prefixed with its session and window context so the whole
+    /// session → window → pane tree comes back in a single tmux invocation instead
+    /// of 1 + sessions + windows separate ones. tmux guarantees every session has
+    /// at least one window and every window at least one pane, so grouping rows
+    /// loses no nodes.
+    public static let scanFormat: String = [
+        "#{session_id}",
+        "#{session_name}",
+        "#{session_windows}",
+        "#{session_attached}",
+        "#{window_id}",
+        "#{window_index}",
+        "#{window_name}",
+        "#{window_active}",
+    ].joined(separator: delimiter) + delimiter + paneFormat
+
+    /// Number of session/window context fields prefixed to each `scanFormat` row.
+    private static let scanContextFieldCount = 8
+
     // MARK: - Parsing
 
+    /// Parse the output of `tmux list-panes -a -F scanFormat` into the full
+    /// session tree. Rows are grouped by session and window in output order.
+    /// A window's `currentPath` mirrors `list-windows` semantics (which resolves
+    /// pane variables against the active pane): it is taken from the window's
+    /// active pane, falling back to the first pane.
+    public static func parseScan(_ output: String) -> [TmuxSession] {
+        var sessions: [TmuxSession] = []
+        var sessionIndexById: [String: Int] = [:]
+        var windowIndexById: [String: [String: Int]] = [:]
+
+        for fields in parseLines(output) {
+            guard fields.count >= scanContextFieldCount + 5,
+                  let pane = parsePane(Array(fields[scanContextFieldCount...])) else { continue }
+            let sessionId = fields[0]
+
+            let sessionIndex: Int
+            if let existing = sessionIndexById[sessionId] {
+                sessionIndex = existing
+            } else {
+                sessionIndex = sessions.count
+                sessionIndexById[sessionId] = sessionIndex
+                sessions.append(TmuxSession(
+                    sessionId: sessionId,
+                    name: fields[1],
+                    windowCount: Int(fields[2]) ?? 0,
+                    isAttached: fields[3] == "1"
+                ))
+            }
+
+            let windowId = fields[4]
+            let windowIndex: Int
+            if let existing = windowIndexById[sessionId]?[windowId] {
+                windowIndex = existing
+            } else {
+                windowIndex = sessions[sessionIndex].windows.count
+                windowIndexById[sessionId, default: [:]][windowId] = windowIndex
+                sessions[sessionIndex].windows.append(TmuxWindow(
+                    windowId: windowId,
+                    windowIndex: Int(fields[5]) ?? 0,
+                    name: fields[6],
+                    isActive: fields[7] == "1"
+                ))
+            }
+
+            let window = sessions[sessionIndex].windows[windowIndex]
+            var panes = window.panes
+            panes.append(pane)
+            let currentPath = panes.first(where: { $0.isActive })?.currentPath
+                ?? panes.first?.currentPath
+            sessions[sessionIndex].windows[windowIndex] = TmuxWindow(
+                windowId: window.windowId,
+                windowIndex: window.windowIndex,
+                name: window.name,
+                isActive: window.isActive,
+                currentPath: currentPath,
+                panes: panes
+            )
+        }
+
+        return sessions
+    }
+
     /// Parse the output of `tmux list-sessions -F` into `TmuxSession` models.
     public static func parseSessions(_ output: String) -> [TmuxSession] {
         parseLines(output).compactMap { fields in
@@ -83,7 +165,11 @@ public enum TmuxParser {
 
     /// Parse the output of `tmux list-panes -F` into `TmuxPane` models.
     public static func parsePanes(_ output: String) -> [TmuxPane] {
-        parseLines(output).compactMap { fields in
+        parseLines(output).compactMap(parsePane)
+    }
+
+    /// Parse a single `paneFormat` field row into a `TmuxPane`.
+    private static func parsePane(_ fields: [String]) -> TmuxPane? {
             guard fields.count >= 5 else { return nil }
             let paneId = fields[0]
             let tty = fields[1].isEmpty ? nil : fields[1]
@@ -109,7 +195,6 @@ public enum TmuxParser {
                 agentState: agentState,
                 agentName: agentName
             )
-        }
     }
 
     // MARK: - Private
diff --git a/Packages/MoriTmux/Tests/MoriTmuxTests/main.swift b/Packages/MoriTmux/Tests/MoriTmuxTests/main.swift
@@ -138,6 +138,70 @@ func testParsePanesEmpty() {
     assertEqual(panes.count, 0)
 }
 
+// MARK: - TmuxParser: Full Scan Parsing Tests
+
+func testParseScanGroupsSessionsWindowsPanes() {
+    // Two sessions; first session has two windows, second window has two panes.
+    let output = """
+    $0\tdev\t2\t1\t@0\t1\tzsh\t1\t%0\t/dev/ttys001\t1\t/Users/test\tzsh\t100\tzsh\t90\t111\t\t
+    $0\tdev\t2\t1\t@1\t2\tvim\t0\t%1\t/dev/ttys002\t0\t/Users/test/src\tvim\t200\tvim\t190\t222\t\t
+    $0\tdev\t2\t1\t@1\t2\tvim\t0\t%2\t/dev/ttys003\t1\t/Users/test/docs\tless\t300\tless\t290\t333\tworking\tclaude
+    $1\tmori/main\t1\t0\t@2\t1\tnode\t1\t%3\t/dev/ttys004\t1\t/Users/test/mori\tnode\t400\tnode\t390\t444\t\t
+    """
+    let sessions = TmuxParser.parseScan(output)
+    assertEqual(sessions.count, 2)
+
+    assertEqual(sessions[0].sessionId, "$0")
+    assertEqual(sessions[0].name, "dev")
+    assertEqual(sessions[0].windowCount, 2)
+    assertTrue(sessions[0].isAttached)
+    assertEqual(sessions[0].windows.count, 2)
+
+    assertEqual(sessions[0].windows[0].windowId, "@0")
+    assertEqual(sessions[0].windows[0].windowIndex, 1)
+    assertEqual(sessions[0].windows[0].name, "zsh")
+    assertTrue(sessions[0].windows[0].isActive)
+    assertEqual(sessions[0].windows[0].panes.count, 1)
+    assertEqual(sessions[0].windows[0].panes[0].paneId, "%0")
+
+    assertEqual(sessions[0].windows[1].windowId, "@1")
+    assertFalse(sessions[0].windows[1].isActive)
+    assertEqual(sessions[0].windows[1].panes.count, 2)
+    assertEqual(sessions[0].windows[1].panes[0].paneId, "%1")
+    assertEqual(sessions[0].windows[1].panes[1].paneId, "%2")
+    assertEqual(sessions[0].windows[1].panes[1].agentState, "working")
+    assertEqual(sessions[0].windows[1].panes[1].agentName, "claude")
+
+    assertEqual(sessions[1].sessionId, "$1")
+    assertEqual(sessions[1].name, "mori/main")
+    assertFalse(sessions[1].isAttached)
+    assertEqual(sessions[1].windows.count, 1)
+    assertEqual(sessions[1].windows[0].panes[0].paneId, "%3")
+}
+
+func testParseScanWindowPathFromActivePane() {
+    // list-windows resolves pane variables against the active pane; the scan
+    // groups panes itself, so the window path must come from the active pane
+    // (%2 here), not the first one.
+    let output = """
+    $0\tdev\t1\t1\t@0\t1\tzsh\t1\t%1\t/dev/ttys002\t0\t/Users/test/src\tvim\t200\tvim\t190\t222\t\t
+    $0\tdev\t1\t1\t@0\t1\tzsh\t1\t%2\t/dev/ttys003\t1\t/Users/test/docs\tless\t300\tless\t290\t333\t\t
+    """
+    let sessions = TmuxParser.parseScan(output)
+    assertEqual(sessions.count, 1)
+    assertEqual(sessions[0].windows.count, 1)
+    assertEqual(sessions[0].windows[0].currentPath, "/Users/test/docs")
+}
+
+func testParseScanEmpty() {
+    assertEqual(TmuxParser.parseScan("").count, 0)
+}
+
+func testParseScanMalformed() {
+    let sessions = TmuxParser.parseScan("$0\tdev\t1\t1\t@0\n")
+    assertEqual(sessions.count, 0, "Should skip rows missing pane fields")
+}
+
 func testParsePanesWithActivity() {
     let output = "%0\t/dev/ttys001\t1\t/Users/test\tzsh\t1710784200\n"
     let panes = TmuxParser.parsePanes(output)
@@ -653,6 +717,10 @@ testParsePanesSingle()
 testParsePanesMultiple()
 testParsePanesEmptyOptionals()
 testParsePanesEmpty()
+testParseScanGroupsSessionsWindowsPanes()
+testParseScanWindowPathFromActivePane()
+testParseScanEmpty()
+testParseScanMalformed()
 testParsePanesWithActivity()
 testParsePanesMultipleWithActivity()
 testParsePanesActivityEmptyField()
diff --git a/Packages/MoriUI/Sources/MoriUI/WorktreeSidebarView.swift b/Packages/MoriUI/Sources/MoriUI/WorktreeSidebarView.swift
@@ -592,28 +592,83 @@ private enum SidebarStatus { case waiting, running, idle, error }
 /// (template-tinted to the running colour), or a generic AI glyph when the agent
 /// is unknown. Breathes to signal live activity — asset images can't carry an SF
 /// `symbolEffect`, so the pulse is a plain opacity animation.
-private struct AgentWorkingIcon: View {
+private struct AgentWorkingIcon: NSViewRepresentable {
     let asset: String?
     let color: Color
-    @State private var breathing = false
-    var body: some View {
-        Group {
-            if let asset, let image = AgentIconLoader.image(named: asset) {
-                Image(nsImage: image)
-                    .renderingMode(.template)
-                    .resizable()
-                    .scaledToFit()
-                    .frame(width: 12, height: 12)
-            } else {
-                Image(systemName: "sparkles")
-                    .font(.system(size: 11, weight: .medium))
-            }
+
+    func makeNSView(context: Context) -> PulsingIconView {
+        PulsingIconView()
+    }
+
+    func updateNSView(_ view: PulsingIconView, context: Context) {
+        let image: NSImage?
+        if let asset, let assetImage = AgentIconLoader.image(named: asset) {
+            image = assetImage
+        } else {
+            image = NSImage(systemSymbolName: "sparkles", accessibilityDescription: nil)?
+                .withSymbolConfiguration(.init(pointSize: 11, weight: .medium))
         }
-        .foregroundStyle(color)
-        .opacity(breathing ? 0.45 : 1)
-        .animation(.easeInOut(duration: 0.85).repeatForever(autoreverses: true), value: breathing)
-        .onAppear { breathing = true }
+        view.configure(image: image, tint: NSColor(color))
+    }
+
+    func sizeThatFits(_ proposal: ProposedViewSize, nsView: PulsingIconView, context: Context) -> NSSize? {
+        NSSize(width: 12, height: 12)
+    }
+}
+
+/// Pulses via a repeating Core Animation opacity animation on the layer instead
+/// of a SwiftUI `repeatForever` animation: CA runs on the render server, while
+/// the SwiftUI animation forced the hosting view to re-render its display list
+/// every frame for as long as any agent was working.
+private final class PulsingIconView: NSView {
+    private let imageView = NSImageView()
+
+    override init(frame: NSRect) {
+        super.init(frame: frame)
+        wantsLayer = true
+        imageView.imageScaling = .scaleProportionallyUpOrDown
+        imageView.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(imageView)
+        NSLayoutConstraint.activate([
+            imageView.centerXAnchor.constraint(equalTo: centerXAnchor),
+            imageView.centerYAnchor.constraint(equalTo: centerYAnchor),
+            imageView.widthAnchor.constraint(lessThanOrEqualToConstant: 12),
+            imageView.heightAnchor.constraint(lessThanOrEqualToConstant: 12),
+        ])
     }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    override var intrinsicContentSize: NSSize {
+        NSSize(width: 12, height: 12)
+    }
+
+    func configure(image: NSImage?, tint: NSColor) {
+        image?.isTemplate = true
+        imageView.image = image
+        imageView.contentTintColor = tint
+    }
+
+    override func viewDidMoveToWindow() {
+        super.viewDidMoveToWindow()
+        // CA strips animations whenever the layer leaves the tree (row scrolled
+        // out, window changes), so re-add on every attach.
+        guard window != nil, let layer else { return }
+        guard layer.animation(forKey: Self.pulseKey) == nil else { return }
+        let pulse = CABasicAnimation(keyPath: "opacity")
+        pulse.fromValue = 1.0
+        pulse.toValue = 0.45
+        pulse.duration = 0.85
+        pulse.autoreverses = true
+        pulse.repeatCount = .infinity
+        pulse.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+        layer.add(pulse, forKey: Self.pulseKey)
+    }
+
+    private static let pulseKey = "mori.agent.pulse"
 }
 
 /// Loads bundled agent SVGs as tintable template images. SwiftPM doesn't compile
diff --git a/Sources/Mori/App/TerminalAreaViewController.swift b/Sources/Mori/App/TerminalAreaViewController.swift
@@ -112,7 +112,11 @@ final class TerminalAreaViewController: NSViewController, ThemedSurface {
     init(terminalHost: TerminalHost? = nil) {
         let host = terminalHost ?? GhosttyAdapter()
         self.terminalHost = host
-        self.surfaceCache = TerminalSurfaceCache(maxSize: 3, terminalHost: host)
+        // Each cached surface keeps a live tmux client + shell attached; evicting
+        // one means a full shell restart + reattach on the next switch, which is
+        // the dominant cost of workspace switching. 10 covers typical workspace
+        // counts; raise if users report thrash with more.
+        self.surfaceCache = TerminalSurfaceCache(maxSize: 10, terminalHost: host)
         super.init(nibName: nil, bundle: nil)
         installSurfaceCloseObserver()
     }
diff --git a/Sources/Mori/App/TerminalTabsBarView.swift b/Sources/Mori/App/TerminalTabsBarView.swift
@@ -91,12 +91,22 @@ final class TerminalTabsBarView: NSView {
         ])
     }
 
+    /// Snapshot of the last rendered state. Observation fires for any change to
+    /// the tracked state (every poll touches `runtimeWindows`); comparing against
+    /// the snapshot skips tearing down and recreating every tab view when nothing
+    /// this strip displays actually changed.
+    private var renderedWindows: [RuntimeWindow]?
+    private var renderedSelectedWindowId: String?
+
     private func updateAndObserve() {
         withObservationTracking {
-            rebuildTabs(
-                windows: appState.windowsForSelectedWorktree,
-                selectedWindowId: appState.uiState.selectedWindowId
-            )
+            let windows = appState.windowsForSelectedWorktree
+            let selectedWindowId = appState.uiState.selectedWindowId
+            if windows != renderedWindows || selectedWindowId != renderedSelectedWindowId {
+                renderedWindows = windows
+                renderedSelectedWindowId = selectedWindowId
+                rebuildTabs(windows: windows, selectedWindowId: selectedWindowId)
+            }
         } onChange: { [weak self] in
             Task { @MainActor [weak self] in
                 self?.updateAndObserve()
diff --git a/Sources/Mori/App/WorkspaceManager.swift b/Sources/Mori/App/WorkspaceManager.swift
