PRD: Adopt proven tmux management patterns

[semantic-craft]

Problem Statement

Tmux Kit already provides a native macOS control surface for local tmux sessions, windows, panes, command execution, focus, and layout backup. The recent stale-state incident showed that accurate session visibility is foundational: if a real tmux session exists but the UI does not show it, the user loses trust in the Dashboard and menu-bar switcher.

The user also wants Tmux Kit to learn from mature adjacent projects, especially devload/TmuxBar and daxliar/tmux-bar, so the app becomes a more efficient tmux management layer without becoming a heavy terminal emulator or reimplementing tmux itself.

The product problem is: make active tmux work easier to monitor, prioritize, preview, and act on from the macOS UI, while keeping Tmux Kit lightweight, local, predictable, and faithful to the tmux server state.

Solution

Add a focused set of proven tmux management patterns to Tmux Kit:

• Keep session state fresh and visibly trustworthy with lightweight refresh semantics already started in the current branch.
• Add pinned sessions so the menu-bar popover and Dashboard prioritize the sessions the user cares about most.
• Add session/pane preview surfaces using existing tmux capture behavior, so the user can inspect the active pane before switching.
• Add clearer empty/error/stale/debug state reporting, so "no sessions" is never confused with "could not reach tmux" or "state may be old".
• Preserve stable tmux targeting by continuing to use stable IDs instead of fuzzy session names for mutations.

This should remain a native macOS menu-bar/Dashboard experience, not a full terminal replacement.

User Stories

1. As a tmux user, I want Tmux Kit to show newly created sessions promptly, so that I can trust the UI as the current view of tmux.
2. As a tmux user, I want the menu-bar popover to refresh when opened, so that I do not make decisions from stale state.
3. As a tmux user, I want the Dashboard to refresh when shown, so that reopening the Dashboard reflects current sessions, windows, and panes.
4. As a tmux user, I want the app to refresh after wake and foreground activation, so that my session list recovers after sleep or context switching.
5. As a tmux user, I want refresh-in-progress feedback, so that I know the app is updating rather than empty or frozen.
6. As a tmux user, I want pinned sessions, so that my important workspaces stay visible even when many sessions exist.
7. As a tmux user, I want pinned sessions to appear before recents in the menu-bar popover, so that I can switch to important work quickly.
8. As a tmux user, I want pinned sessions to remain pinned across app restarts, so that my workspace organization persists.
9. As a tmux user, I want to pin or unpin a session from a context menu, so that I can manage priority without opening Settings.
10. As a tmux user, I want pinned sessions to survive session recreation when the name is reused, so that common project sessions remain prioritized.
11. As a tmux user, I want the Dashboard to show which sessions are pinned, so that priority is visible and editable.
12. As a tmux user, I want to preview a session's active pane before switching, so that I can identify the right workspace quickly.
13. As a tmux user, I want the preview to show recent terminal output, so that I can tell whether an agent, build, or shell is active.
14. As a tmux user, I want the preview to show active command and current directory, so that I can distinguish similar sessions.
15. As a tmux user, I want previews to fail quietly with a clear message, so that a tmux capture failure does not break the Dashboard.
16. As a tmux user, I want previews to avoid excessive refresh work, so that the app remains lightweight.
17. As a tmux user, I want "No tmux sessions" to mean only that the tmux server has no sessions, so that errors are not hidden as empty state.
18. As a tmux user, I want a distinct tmux access error state, so that I can fix binary path, socket, or server problems directly.
19. As a tmux user, I want a debug snapshot of the current tmux state, so that stale UI bugs can be reported with useful evidence.
20. As a tmux user, I want refresh and preview behavior to reuse existing tmux commands, so that Tmux Kit does not require tmux plugins or config changes.
21. As a tmux user, I want session mutations to keep using stable tmux IDs, so that fuzzy tmux target matching cannot affect the wrong session or pane.
22. As a tmux user, I want the app to stay local-only and telemetry-free, so that it remains a clean control surface over my existing tmux.
23. As a tmux user, I want the menu-bar experience to stay compact, so that extra management features do not crowd out fast switching.
24. As a tmux user, I want the Dashboard to carry richer inspection features, so that deeper management lives in the larger surface.
25. As a maintainer, I want these features to use existing AppState/TmuxService seams, so that implementation remains small and testable.
26. As a maintainer, I want behavior tests around refresh, pin ordering, and preview failure states, so that regressions are caught without brittle view tests.
27. As a maintainer, I want no new third-party dependency for this work, so that the app remains simple to build and ship.
28. As a maintainer, I want the implementation to stay aligned with native macOS UI conventions, so that Tmux Kit feels like a polished local utility.

Implementation Decisions

• Use the existing state owner as the main integration point for session refresh, pin ordering, preview requests, and status reporting.
• Keep lightweight polling and lifecycle refresh as the default synchronization model. Do not introduce tmux control mode for this PRD.
• Store pinned sessions by session name for persistence across app restarts and across recreation of common project sessions. Stable tmux IDs remain the targeting mechanism for live mutations.
• Add pin/unpin actions to session context menus and surface pinned sessions ahead of recent sessions in compact menu surfaces.
• Reuse existing tmux capture behavior for preview content rather than creating a new terminal rendering path.
• Preview the active pane of the selected session by default; fall back to the first pane if no active pane is known.
• Keep preview refresh intentionally modest: refresh on selection/open and manual refresh, not continuous streaming.
• Distinguish state categories in the product model: loading, empty, tmux unavailable, tmux command error, stale or last-known state.
• Keep the menu-bar popover glanceable: pinned/important sessions and status live there; richer previews live in the Dashboard unless a compact preview proves useful.
• Add a debug snapshot action only if it can be built from existing state and tmux read commands. It should be copyable text, not a new logging subsystem.
• Preserve local-only behavior: no telemetry, no network dependency, no tmux plugin installation, no automatic tmux config edits.
• Continue using stable tmux IDs for live operations; avoid fuzzy name targeting for mutations.
• Follow native macOS visual patterns and existing design tokens for status, loading, empty, and error UI.

Testing Decisions

• Test external behavior at the highest practical seam: the shared app state and tmux service boundary, with tmux command output faked or represented by existing parser fixtures.
• Avoid testing private implementation details such as exact timers. Test observable outcomes: queued refreshes run, sessions reorder correctly, empty/error states are distinct, previews return expected text or fallback messages.
• Add or extend pure parser/model tests where new status or pin ordering logic can be tested without UI.
• Add focused tests for pinned session ordering: pinned sessions first, recents preserved inside groups, unknown/deleted pinned names ignored.
• Add tests for preview selection: active pane preferred, first pane fallback, no-pane fallback handled.
• Add tests for refresh coalescing: a refresh requested during an active refresh should result in one follow-up refresh rather than being dropped.
• Use existing Core tests as prior art for parser/model behavior.
• Use build verification for SwiftUI/AppKit integration, since the repo currently relies on project build scripts for app-level validation.
• Manual verification should include: create a new tmux session while the app is running, open menu-bar popover, open Dashboard, pin a session, preview a pane, kill a session, wake/foreground refresh if practical.

Out of Scope

• Do not implement tmux control mode event streaming.
• Do not build a full terminal emulator or live terminal renderer.
• Do not add cloud sync, telemetry, accounts, or network services.
• Do not add tmux plugins or automatically edit tmux configuration.
• Do not add a complex groups/template system in the first implementation.
• Do not add multi-terminal AppleScript attachment support beyond the app's existing Ghostty-focused behavior.
• Do not redesign the Dashboard or menu-bar popover layout broadly.
• Do not replace the existing stable-ID targeting model.

Further Notes

Reference projects:

• devload/TmuxBar demonstrates session management, previews, favorites/groups, hotkeys, templates, and configurable auto-refresh in a native macOS tmux manager.
• daxliar/tmux-bar demonstrates a very small menu-bar/Touch Bar utility with aggressive timer refresh, clearing stale UI when tmux is not active, and careful tmux targeting notes.

The useful shared lesson is not to copy their architecture wholesale. The useful lesson is to keep the synchronization model simple, refresh at user-visible moments, make stale/empty/error states explicit, and add small high-leverage management affordances for real tmux work.