perf(runtime): unblock event loop + bypass server for switch action

[panosAthDBX]

Summary

Brings rapid M-N session switching from ~1.5s/switch under load to ~60ms/switch on an interactive setup with 4 sessions, 3 attached sidebars, and a chatty remote hermes watcher pushing 3-5 events/sec.

Three layers, ordered by where they unblock:

1. Keybinding & script overhead (~30%)

• run-shell -b on all bindings so tmux's input loop doesn't block while shells run. Without -b, rapid presses serialise on tmux's command queue and reentrant tmux calls inside the script compound the wait.
• Pass #{client_tty}|#{session_name}|#{window_id} as a positional arg from the bind-key, skipping a tmux display-message fork (~16ms).
• server-common.sh: alive-check tmpfile (5s TTL) skips the ~80ms healthcheck curl on the hot path; plugin-dir / bun lookup deferred to the cold-start branch only.
• Bump curl -m 0.2 → -m 1.5, --connect-timeout 0.1 → 0.3, end with || true; exit 0 so tmux's run-shell never surfaces curl exit 28 (timeout) in the status line during transient spikes.

2. Server-side event loop (~40%)

• Drop invalidateCurrentSessionCache() from broadcastStateImmediate. The 500ms TTL cache was being wiped on every broadcast (per agent-emit, dozens/sec under chatty watchers), defeating its purpose. handleFocus() still invalidates on real focus changes.
• Swap raw getCurrentSession() → getCachedCurrentSession() at the hot computeState / ensure-sidebar / toggle sites.
• Debounce broadcastState (30ms) and refreshPaneAgents (250ms). Sub-perception; coalesce bursts that previously each triggered a fresh tmux subprocess (or tmux list-panes -a + ps + lsof in the case of refreshPaneAgents).
• New AsyncReadCapable interface + isAsyncReadCapable guard. TmuxClient gains runAsync (uses Bun.spawn(...).exited) and async siblings: listSessionsAsync, listPanesAsync, listClientsAsync, getCurrentSessionAsync, getActiveSessionDirsAsync, getAllPaneCountsAsync. TmuxProvider implements them; its async listSessions runs the two underlying tmux subprocesses (list-sessions + active-session-dirs) in parallel via Promise.all.
• computeState() and broadcastStateImmediate() are now async. Provider list calls in computeState run through Promise.all on the async API where available; legacy providers fall back to sync. broadcastStateImmediate uses an in-flight + trailing flag so concurrent triggers coalesce instead of stacking.

3. Bypass server for the switch action (the rest)

• Server writes ORDERING_FILE (/tmp/opensessions.<KEY>.ordering) on every state broadcast — one visible session name per line.
• switch-index.sh fast-path: read line N from the file, call tmux switch-client -t <name> directly. The server-side POST still goes out (backgrounded) so the server can update unseen flags / sidebar focus / custom ordering, but user-perceived latency is just one tmux fork. The existing tmux hook (client-session-changed → /focus) keeps the server in sync.
• Cold-path fallback preserved: if ordering file is missing (boot, or ordering not yet broadcast), behave as before.

Numbers

Metric	Before	After
GET / healthcheck	218 ms	20 ms
POST /switch-index isolated	1033 ms (timed out at 1 s)	54 ms
5 parallel POSTs total	timed out	32 ms
switch-index.sh end-to-end (warm)	270 ms	60 ms
5 rapid-fire switches	~1.5 s	~280 ms

Test plan

• bun build apps/server/src/main.ts — clean
• Server boots, sidebars spawn in all 3 sessions, ordering file written
• M-N rapid-fires don't surface "returned 28" in tmux status
• Cold-path fallback still works (delete ordering file, switch still goes through server)
• Maintainer: run existing test suites in packages/runtime/test/ to confirm broadcastStateImmediate async migration doesn't regress sidebar coordinator state machine
• Maintainer: verify zellij provider still works (it doesn't implement AsyncReadCapable so the runtime falls back to sync paths via the type guard)

Notes

• Stacked on top of feat(themes): follow macOS Appearance and auto-switch dark/light #32 (themes + earlier perf). Several runtime/server index.ts lines touched in both. Strictly speaking this can land independently if feat(themes): follow macOS Appearance and auto-switch dark/light #32 merges first, otherwise will need a small rebase.
• Local edits get clobbered on TPM update — opening this so the perf wins don't have to be re-applied each cycle.

This pull request and its description were written by Isaac.

[inspect-review]

inspect review

Triage: 75 entities analyzed | 0 critical, 0 high, 25 medium, 50 low
Verdict: standard_review

Findings (1)

1. [low] cleanup() does not clear the new broadcast debounce timer, so broadcastStateImmediate() can still run after shutdown. Evidence: broadcastState() sets broadcastDebounceTimer via setTimeout(..., BROADCAST_DEBOUNCE_MS) in packages/runtime/src/server/index.ts, but cleanup() clears debounceTimer/sidebarEnforceTimer/etc. and never clears broadcastDebounceTimer.

---

Reviewed by inspect | Entity-level triage found 0 high-risk changes

[inspect-review]

inspect review

Triage: 87 entities analyzed | 0 critical, 0 high, 31 medium, 56 low
Verdict: standard_review

Findings (7)

1. [low] Race condition in broadcastStateImmediate: broadcastTrailing flag can be set after broadcastInFlight is cleared but before the queueMicrotask callback executes, causing the trailing broadcast to be lost
2. [low] Incorrect background color in TUI: changed from P().crust to P().base, but this breaks the visual hierarchy since base is typically lighter/brighter than crust in most themes
3. [low] Potential null pointer exception in switch-index.sh: TARGET variable can be empty if awk finds no match, but tmux switch-client is called unconditionally without checking if TARGET is non-empty
4. [low] Stale cache data bug: getCachedCurrentSession() is used in computeState() but the cache is never invalidated on broadcastStateImmediate, meaning the currentSession in the broadcast can be stale for up to 500ms even after a real session switch
5. [low] Asymmetric cache trust in enforceSidebarWidth: reuseCache option skips invalidateSidebarPaneCache() but the caller (ensureSidebarInWindow) assumes the cache is fresh based on a 300ms TTL that may have already expired by the time enforceSidebarWidth is called
6. [low] Missing null check in switch-index.sh fast path: if ORDERING_FILE exists but is empty or malformed, TARGET will be empty and the fire-and-forget curl will POST an invalid context string with empty session name
7. [low] Unhandled promise rejection: watchMacSystemAppearance callback is async (onChange: (mode) => void | Promise) but the watcher invokes it with void check() which swallows any promise rejection from the callback

---

Reviewed by inspect | Entity-level triage found 0 high-risk changes

[inspect-review]

inspect review

Triage: 87 entities analyzed | 0 critical, 0 high, 31 medium, 56 low
Verdict: standard_review

Findings (7)

1. [low] Race condition in broadcastStateImmediate: broadcastTrailing flag can be set after broadcastInFlight is cleared but before the function returns, causing the trailing broadcast to be lost. The queueMicrotask at the end checks broadcastTrailing, but another concurrent call could set it to true after the check but before the function exits.
2. [low] Incorrect cache invalidation logic in broadcastStateImmediate: The comment says 'do NOT invalidate currentSession cache here' but the cache is never invalidated on focus changes either. handleFocus calls invalidateCurrentSessionCache() but then immediately calls getCachedCurrentSession() in computeState, which will return stale data if the cache TTL hasn't expired yet.
3. [low] Potential null pointer exception in switch-index.sh: The script reads ORDERING_FILE and extracts TARGET with awk, but if awk returns empty string (index out of bounds), the script proceeds to call 'tmux switch-client -t ""' which will fail. The check '[ -n "$TARGET" ]' guards the fast path, but if it's empty, the script falls through to the cold path without any error handling.
4. [low] Missing await in system theme watcher callback: The onChange callback in watchMacSystemAppearance is declared as '(mode) => void | Promise' but the internal check() function that calls it uses 'await onChange(mode)' inside a try-catch. However, the actual usage in server/index.ts passes 'syncSystemTheme' which is async, but the callback is invoked as 'void check()' from the file watcher and safety timer, meaning promise rejections could be unhandled if the try-catch doesn't catch them.
5. [low] Incorrect pruning logic in AgentTracker.pruneTerminal: The code checks 'if (age <= TERMINAL_PRUNE_MS) continue;' which skips pruning for events YOUNGER than the threshold, but then checks 'if (isUnseen && age <= TERMINAL_HARD_PRUNE_MS) continue;' which also skips for events younger than the hard threshold. However, this means events between TERMINAL_PRUNE_MS and TERMINAL_HARD_PRUNE_MS that are NOT unseen will be pruned, but the comment says 'Seen + non-alive: prune after TERMINAL_PRUNE_MS (5 min)'. The logic should be: if seen and age > TERMINAL_PRUNE_MS, prune; if unseen and age > TERMINAL_HARD_PRUNE_MS, prune.
6. [low] Singleton guard race condition: The PID file check uses process.kill(existingPid, 0) to probe if a process is alive, but between the probe and writing the new PID, another process could start and write its own PID. This creates a TOCTOU (time-of-check-time-of-use) race where multiple servers could all pass the check and start simultaneously.
7. [low] Missing null check in computeState: The code maps over sessionLists[i] with 'for (const s of sessionLists[i]!)' using non-null assertion, but if a provider's listSessionsAsync() rejects, the Promise.all will reject and the entire function will throw. However, the code should handle partial failures gracefully since one provider failing shouldn't crash the entire state computation.

---

Reviewed by inspect | Entity-level triage found 0 high-risk changes