Documentation
¶
Index ¶
- Constants
- Variables
- func Binary() string
- func CleanupSessions(cmdExec executor.Executor) error
- func CleanupSessionsOnServer(cmdExec executor.Executor, serverSocket string) error
- func CreateKeepaliveSession(serverSocket string) error
- func EnsureServerRunning(serverSocket string) error
- func IsServerDown(serverSocket string) bool
- func ListAllSessions(serverSocket string) (map[string]bool, error)
- func NewTmuxSessionWithCleanup(name string, program string) (*TmuxSession, CleanupFunc)
- func NewTmuxSessionWithPrefixAndCleanup(name string, program string, prefix string) (*TmuxSession, CleanupFunc)
- func NewTmuxSessionWithServerSocketAndCleanup(name string, program string, prefix string, serverSocket string) (*TmuxSession, CleanupFunc)
- func RecordZombieProcess(pid int, sessionName string, warnFn func(string, ...any))
- func RegisterForkPressureAlert(fn AlertFunc)
- func SetExitEmpty(serverSocket string, enabled bool) error
- func SetServerRecoveryCallback(fn func())
- func StartForkPressureLogger(ctx context.Context, interval time.Duration, logFn func(string, ...any))
- func StartZombieReaper(ctx context.Context, interval time.Duration, logFn func(string, ...any))
- func StartZombieWatcher(ctx context.Context, interval time.Duration, warnFn func(string, ...any))
- func StopServerRegistry(socket string)
- func ToStaplerSquadTmuxName(str string) string
- type AlertFunc
- type BannerFilter
- type CleanupFunc
- type ForkPressureLevel
- type ForkPressureStats
- type MockCmdExec
- type PaneExitSubscriber
- type Pty
- type PtyFactory
- type SessionExistenceChecker
- type SessionLister
- type TmuxServerRegistry
- func (r *TmuxServerRegistry) IsHealthy() bool
- func (r *TmuxServerRegistry) ListSessions() map[string]bool
- func (r *TmuxServerRegistry) SessionExists(name string) bool
- func (r *TmuxServerRegistry) Start(ctx context.Context) error
- func (r *TmuxServerRegistry) Stop()
- func (r *TmuxServerRegistry) SubscribePaneExit(ctx context.Context, sessionName string) <-chan struct{}
- type TmuxSession
- func NewTmuxSession(name string, program string) *TmuxSession
- func NewTmuxSessionFromExisting(exactSessionName string) *TmuxSession
- func NewTmuxSessionWithDeps(name string, program string, ptyFactory PtyFactory, cmdExec executor.Executor) *TmuxSession
- func NewTmuxSessionWithPrefix(name string, program string, prefix string) *TmuxSession
- func NewTmuxSessionWithServerSocket(name string, program string, prefix string, serverSocket string, ...) *TmuxSession
- func (t *TmuxSession) Attach() (chan struct{}, error)
- func (t *TmuxSession) AttachToExisting() error
- func (t *TmuxSession) CapturePaneContent() (string, error)
- func (t *TmuxSession) CapturePaneContentRaw() (string, error)
- func (t *TmuxSession) CapturePaneContentWithOptions(start, end string) (string, error)
- func (t *TmuxSession) Close() error
- func (t *TmuxSession) Detach()
- func (t *TmuxSession) DetachSafely() error
- func (t *TmuxSession) DoesSessionExist() bool
- func (t *TmuxSession) DoesSessionExistNoCache() bool
- func (t *TmuxSession) FilterBanners(content string) (filteredContent string, bannersRemoved int)
- func (t *TmuxSession) GetCursorPosition() (x, y int, err error)
- func (t *TmuxSession) GetPTY() (*os.File, error)
- func (t *TmuxSession) GetPaneCurrentPath() (string, error)
- func (t *TmuxSession) GetPaneDimensions() (width, height int, err error)
- func (t *TmuxSession) GetPanePID() (int32, error)
- func (t *TmuxSession) GetSanitizedName() string
- func (t *TmuxSession) HasMeaningfulContent(content string) bool
- func (t *TmuxSession) HasUpdated() (updated bool, hasPrompt bool, content string)
- func (t *TmuxSession) RefreshClient() error
- func (t *TmuxSession) ResetExitOnce()
- func (t *TmuxSession) Restore() error
- func (t *TmuxSession) RestoreWithWorkDir(workDir string) error
- func (t *TmuxSession) SendKeys(keys string) (int, error)
- func (t *TmuxSession) SetDetachedSize(width, height int) error
- func (t *TmuxSession) SetOnExitCallback(fn func(reason string))
- func (t *TmuxSession) SetWindowSize(cols, rows int) error
- func (t *TmuxSession) Start(workDir string) error
- func (t *TmuxSession) StartControlMode() error
- func (t *TmuxSession) StartWithCleanup(workDir string) (CleanupFunc, error)
- func (t *TmuxSession) StopControlMode() error
- func (t *TmuxSession) SubscribeToControlModeUpdates() (string, chan []byte)
- func (t *TmuxSession) TapDAndEnter() error
- func (t *TmuxSession) TapEnter() error
- func (t *TmuxSession) UnsubscribeFromControlModeUpdates(subscriberID string)
- type TmuxSessionOption
- type TmuxStatePort
- type ZombieInfo
Constants ¶
const LegacyTmuxPrefix = "claudesquad_"
const ProgramAider = "aider"
const ProgramClaude = "claude"
const ProgramGemini = "gemini"
const TmuxPrefix = "staplersquad_"
Variables ¶
var ( // ErrControlModeNotRunning is returned when sendCMCommand is called but control mode is not active. ErrControlModeNotRunning = errors.New("control mode not running") // ErrControlModeStopped is sent to all in-flight commands when the control mode process exits. ErrControlModeStopped = errors.New("control mode stopped") )
ErrRegistryUnavailable is returned when the registry is not healthy and cannot serve a request that requires the registry to be up.
var ErrServerDown = errors.New("tmux server not running")
ErrServerDown is returned by ListAllSessions when the tmux server is not running. Callers should treat this as "no sessions are alive" without attempting recovery.
Functions ¶
func Binary ¶ added in v1.21.0
func Binary() string
Binary returns the tmux executable path. TMUX_BIN env var overrides the default "tmux" — set it to use a specific binary (e.g. TMUX_BIN=$(pwd)/bin/tmux go test or the pinned submodule build).
To bundle tmux directly into the stapler-squad binary instead, build with:
go build -tags embed_tmux .
after running: make build-tmux-embed
func CleanupSessions ¶
CleanupSessions kills all tmux sessions that start with "session-" on the default server
func CleanupSessionsOnServer ¶
CleanupSessionsOnServer kills all tmux sessions that start with "session-" on a specific server serverSocket: socket name for server isolation, empty string for default server
func CreateKeepaliveSession ¶ added in v1.1.0
CreateKeepaliveSession creates a hidden tmux session that keeps the server alive. The session runs an idle shell and is intentionally never cleaned up by stapler-squad. As long as this session exists, the tmux server cannot exit due to having no sessions.
func EnsureServerRunning ¶ added in v1.1.0
EnsureServerRunning starts the tmux server if it is not already running. Uses exec.Command directly so it always runs regardless of circuit breaker state.
func IsServerDown ¶ added in v1.15.0
IsServerDown returns true if the tmux server is not running for the given socket. Returns false if the server state cannot be determined (treats unknown as up to avoid false-positive zombie recovery suppression).
func ListAllSessions ¶ added in v1.15.0
ListAllSessions returns the set of all currently live tmux session names. Uses serverSocket for isolation if non-empty (same -L flag semantics as TmuxSession). Does NOT go through the per-session existence cache - intended for bulk reconciliation. Returns ErrServerDown when the tmux server is not running.
func NewTmuxSessionWithCleanup ¶
func NewTmuxSessionWithCleanup(name string, program string) (*TmuxSession, CleanupFunc)
NewTmuxSessionWithCleanup creates a new TmuxSession and returns it along with a cleanup function. Usage: session, cleanup := NewTmuxSessionWithCleanup(name, program); defer cleanup()
func NewTmuxSessionWithPrefixAndCleanup ¶
func NewTmuxSessionWithPrefixAndCleanup(name string, program string, prefix string) (*TmuxSession, CleanupFunc)
NewTmuxSessionWithPrefixAndCleanup creates a new TmuxSession with custom prefix and cleanup function. Usage: session, cleanup := NewTmuxSessionWithPrefixAndCleanup(name, program, prefix); defer cleanup()
func NewTmuxSessionWithServerSocketAndCleanup ¶
func NewTmuxSessionWithServerSocketAndCleanup(name string, program string, prefix string, serverSocket string) (*TmuxSession, CleanupFunc)
NewTmuxSessionWithServerSocketAndCleanup creates a TmuxSession with server isolation and cleanup. Usage: session, cleanup := NewTmuxSessionWithServerSocketAndCleanup(name, program, prefix, socket); defer cleanup()
func RecordZombieProcess ¶ added in v1.24.0
RecordZombieProcess records detection of a zombie child process (Z state in ps). sessionName identifies which tmux session spawned the zombie.
func RegisterForkPressureAlert ¶ added in v1.24.0
func RegisterForkPressureAlert(fn AlertFunc)
RegisterForkPressureAlert registers fn to be called when fork pressure crosses a threshold. Safe to call from multiple goroutines before any subprocess spawning begins.
func SetExitEmpty ¶ added in v1.1.0
SetExitEmpty sets the tmux server-level exit-empty option. When enabled=false, the server stays alive even when all sessions are closed. Requires the server to already be running.
func SetServerRecoveryCallback ¶ added in v1.1.0
func SetServerRecoveryCallback(fn func())
SetServerRecoveryCallback registers a function called after successful server recovery. Thread-safe: the callback executes outside the recoveryMu lock, in a goroutine.
func StartForkPressureLogger ¶ added in v1.24.0
func StartForkPressureLogger(ctx context.Context, interval time.Duration, logFn func(string, ...any))
StartForkPressureLogger starts a background goroutine that logs fork pressure stats periodically.
func StartZombieReaper ¶ added in v1.24.0
StartZombieReaper starts a background goroutine that periodically reaps zombie child processes by draining Wait4(-1, WNOHANG).
This complements StartZombieWatcher: the watcher detects and alerts; the reaper actually cleans up. A zombie (Z state) by definition has no outstanding Wait4 caller—if cmd.Wait() had been called, the zombie would already be gone—so the WNOHANG wildcard wait is safe to issue without racing active Cmd goroutines.
Recommended interval: 60s (half the watcher period is plenty; slower means fewer interference opportunities with in-flight cmd.Wait calls).
func StartZombieWatcher ¶ added in v1.24.0
StartZombieWatcher starts a background goroutine that periodically scans for zombie processes and records them via RecordZombieProcess when found. ctx controls its lifetime. interval is how often to scan (recommended: 30s).
func StopServerRegistry ¶ added in v1.20.0
func StopServerRegistry(socket string)
StopServerRegistry stops and removes the registry for the given socket. Safe to call even if no registry was ever created for the socket. After this call, GetServerRegistry(socket) will create a fresh registry. Intended for test cleanup to prevent reconnectLoop from restarting a tmux server after it has been killed.
func ToStaplerSquadTmuxName ¶
ToStaplerSquadTmuxName converts a string to a valid tmux session name with the default prefix
Types ¶
type AlertFunc ¶ added in v1.24.0
type AlertFunc func(level ForkPressureLevel, stats ForkPressureStats)
AlertFunc is called when fork pressure crosses a threshold.
type BannerFilter ¶
type BannerFilter struct {
// contains filtered or unexported fields
}
BannerFilter detects and filters tmux status line banners from terminal output
func NewBannerFilter ¶
func NewBannerFilter() *BannerFilter
NewBannerFilter creates a new banner filter with default tmux status patterns
func (*BannerFilter) FilterBanners ¶
func (bf *BannerFilter) FilterBanners(lines []string) ([]string, int)
FilterBanners removes tmux status banners from a slice of lines Returns the filtered lines and a count of how many banners were removed
func (*BannerFilter) FilterBannersFromText ¶
func (bf *BannerFilter) FilterBannersFromText(text string) (string, int)
FilterBannersFromText takes a multi-line string and removes banner lines Returns the filtered text and a count of banners removed
func (*BannerFilter) HasMeaningfulContent ¶
func (bf *BannerFilter) HasMeaningfulContent(text string) bool
HasMeaningfulContent returns true if the text has content beyond just banners The last line may be a tmux status bar, but only exclude it if it matches status bar patterns
func (*BannerFilter) IsBanner ¶
func (bf *BannerFilter) IsBanner(line string) bool
IsBanner returns true if the given line appears to be a tmux status banner
type CleanupFunc ¶
type CleanupFunc func() error
CleanupFunc represents a cleanup function that should be deferred
type ForkPressureLevel ¶ added in v1.24.0
type ForkPressureLevel int
ForkPressureLevel describes the current subprocess pressure state.
const ( ForkPressureOK ForkPressureLevel = iota ForkPressureWarning // spawn rate elevated ForkPressureCritical // spawn failures detected )
func (ForkPressureLevel) String ¶ added in v1.24.0
func (l ForkPressureLevel) String() string
type ForkPressureStats ¶ added in v1.24.0
type ForkPressureStats struct {
TotalSpawns int64
TotalFailures int64
TotalZombies int64
SpawnsInWindow int64
FailuresInWindow int64
ZombiesInWindow int64
WindowDuration time.Duration
Level ForkPressureLevel
LastAlertAt time.Time
}
ForkPressureStats is a point-in-time snapshot of fork pressure metrics.
func ForkPressureSnapshot ¶ added in v1.24.0
func ForkPressureSnapshot() ForkPressureStats
ForkPressureSnapshot returns a point-in-time snapshot of fork pressure metrics.
type MockCmdExec ¶
type MockCmdExec struct {
RunFunc func(cmd *exec.Cmd) error
OutputFunc func(cmd *exec.Cmd) ([]byte, error)
CombinedOutputFunc func(cmd *exec.Cmd) ([]byte, error)
}
MockCmdExec provides mock functionality for executor.Executor interface
func (MockCmdExec) CombinedOutput ¶
func (m MockCmdExec) CombinedOutput(cmd *exec.Cmd) ([]byte, error)
type PaneExitSubscriber ¶ added in v1.18.0
type PaneExitSubscriber interface {
SubscribePaneExit(ctx context.Context, sessionName string) <-chan struct{}
}
PaneExitSubscriber delivers a channel that is closed when the named pane exits. Caller selects on the returned channel alongside ctx.Done(). Cancelling ctx unregisters the subscription; channel is closed immediately.
type Pty ¶
type Pty struct{}
Pty starts a "real" pseudo-terminal (PTY) using the creack/pty package.
type PtyFactory ¶
func MakePtyFactory ¶
func MakePtyFactory() PtyFactory
type SessionExistenceChecker ¶ added in v1.18.0
SessionExistenceChecker answers "is session X alive right now?" Used by TmuxSession.DoesSessionExist to avoid exec.Command forks.
type SessionLister ¶ added in v1.18.0
SessionLister returns a snapshot of all live session names. Used by PTYDiscovery and reconciliation loops.
type TmuxServerRegistry ¶ added in v1.18.0
type TmuxServerRegistry struct {
// contains filtered or unexported fields
}
TmuxServerRegistry maintains a single tmux control-mode connection to a tmux server and pushes session-lifecycle events into an in-memory map. Callers query the map directly instead of forking tmux subprocesses.
func GetServerRegistry ¶ added in v1.18.0
func GetServerRegistry(socket string) *TmuxServerRegistry
GetServerRegistry returns the singleton TmuxServerRegistry for the given socket. Creates and starts the registry on first call for each socket. Never call from init().
func NewTmuxServerRegistry ¶ added in v1.18.0
func NewTmuxServerRegistry(serverSocket string) *TmuxServerRegistry
NewTmuxServerRegistry creates a new registry for the given server socket. Call Start(ctx) to begin listening for events.
func (*TmuxServerRegistry) IsHealthy ¶ added in v1.18.0
func (r *TmuxServerRegistry) IsHealthy() bool
IsHealthy implements SessionExistenceChecker and SessionLister.
func (*TmuxServerRegistry) ListSessions ¶ added in v1.18.0
func (r *TmuxServerRegistry) ListSessions() map[string]bool
ListSessions implements SessionLister. Returns a copy of the live sessions map.
func (*TmuxServerRegistry) SessionExists ¶ added in v1.18.0
func (r *TmuxServerRegistry) SessionExists(name string) bool
SessionExists implements SessionExistenceChecker.
func (*TmuxServerRegistry) Start ¶ added in v1.18.0
func (r *TmuxServerRegistry) Start(ctx context.Context) error
Start launches the control-mode process and begins processing events. It bootstraps the session map from list-sessions before marking the registry healthy. The returned error is non-nil only when the initial setup fails in a way that makes a retry impossible.
func (*TmuxServerRegistry) Stop ¶ added in v1.18.0
func (r *TmuxServerRegistry) Stop()
Stop shuts down the registry and closes all pending subscriber channels.
func (*TmuxServerRegistry) SubscribePaneExit ¶ added in v1.18.0
func (r *TmuxServerRegistry) SubscribePaneExit(ctx context.Context, sessionName string) <-chan struct{}
SubscribePaneExit implements PaneExitSubscriber. The returned channel is closed when the named session/pane exits or when ctx is cancelled.
type TmuxSession ¶
type TmuxSession struct {
// contains filtered or unexported fields
}
TmuxSession represents a managed tmux session
func NewTmuxSession ¶
func NewTmuxSession(name string, program string) *TmuxSession
NewTmuxSession creates a new TmuxSession with the given name and program. The executor is wrapped with a CircuitBreakerExecutor for resilience.
func NewTmuxSessionFromExisting ¶
func NewTmuxSessionFromExisting(exactSessionName string) *TmuxSession
NewTmuxSessionFromExisting creates a TmuxSession that wraps an existing tmux session by its exact name. Unlike other constructors, this does NOT add any prefix to the session name - it uses the name exactly as provided. This is used for external sessions discovered via mux socket monitoring that already have tmux sessions.
The session must already exist in tmux. Call AttachToExisting() after creation to establish the PTY connection.
func NewTmuxSessionWithDeps ¶
func NewTmuxSessionWithDeps(name string, program string, ptyFactory PtyFactory, cmdExec executor.Executor) *TmuxSession
NewTmuxSessionWithDeps creates a new TmuxSession with provided dependencies for testing. WithRegistry(nil) is passed so DoesSessionExist() uses cmdExec (the mock) instead of the global TmuxServerRegistry, which connects to real tmux and would bypass the mock executor.
func NewTmuxSessionWithPrefix ¶
func NewTmuxSessionWithPrefix(name string, program string, prefix string) *TmuxSession
NewTmuxSessionWithPrefix creates a new TmuxSession with a custom prefix for process isolation. The executor is wrapped with a CircuitBreakerExecutor for resilience.
func NewTmuxSessionWithServerSocket ¶
func NewTmuxSessionWithServerSocket(name string, program string, prefix string, serverSocket string, opts ...TmuxSessionOption) *TmuxSession
NewTmuxSessionWithServerSocket creates a new TmuxSession with complete server isolation. This uses the tmux -L flag to create a completely separate tmux server, providing true isolation from other tmux sessions. Use this for testing or when you need complete separation from production tmux sessions.
serverSocket: unique socket name (e.g., "test", "teatest_123", "isolated") prefix: session name prefix (e.g., "staplersquad_test_")
func (*TmuxSession) Attach ¶
func (t *TmuxSession) Attach() (chan struct{}, error)
func (*TmuxSession) AttachToExisting ¶
func (t *TmuxSession) AttachToExisting() error
AttachToExisting connects to an already-running tmux session and establishes the PTY connection. This is similar to RestoreWithWorkDir but assumes the session definitely exists. Returns an error if the session doesn't exist or PTY connection fails.
func (*TmuxSession) CapturePaneContent ¶
func (t *TmuxSession) CapturePaneContent() (string, error)
CapturePaneContent captures the content of the tmux pane. When STAPLER_SQUAD_CM_COMMANDS=true and control mode is running, the query is sent over the control mode stdin pipe (zero new subprocesses); otherwise falls back to subprocess.
func (*TmuxSession) CapturePaneContentRaw ¶
func (t *TmuxSession) CapturePaneContentRaw() (string, error)
CapturePaneContentRaw captures the pane content with ANSI codes preserved and WITHOUT joining wrapped lines. This is essential for hybrid streaming where we need to preserve exact cursor positioning. The -J flag (join wrapped lines) strips cursor positioning codes, breaking TUI rendering.
func (*TmuxSession) CapturePaneContentWithOptions ¶
func (t *TmuxSession) CapturePaneContentWithOptions(start, end string) (string, error)
CapturePaneContentWithOptions captures the pane content with additional options. start and end specify the starting and ending line numbers (use "-" for the start/end of history).
func (*TmuxSession) Close ¶
func (t *TmuxSession) Close() error
Close terminates the tmux session and cleans up resources
func (*TmuxSession) Detach ¶
func (t *TmuxSession) Detach()
Detach disconnects from the current tmux session. It panics if detaching fails. At the moment, there's no way to recover from a failed detach.
func (*TmuxSession) DetachSafely ¶
func (t *TmuxSession) DetachSafely() error
DetachSafely disconnects from the current tmux session without panicking
func (*TmuxSession) DoesSessionExist ¶
func (t *TmuxSession) DoesSessionExist() bool
func (*TmuxSession) DoesSessionExistNoCache ¶
func (t *TmuxSession) DoesSessionExistNoCache() bool
DoesSessionExistNoCache checks if session exists WITHOUT using cache. This is used for critical validation before session creation to ensure we have the most up-to-date information about session existence.
func (*TmuxSession) FilterBanners ¶
func (t *TmuxSession) FilterBanners(content string) (filteredContent string, bannersRemoved int)
FilterBanners removes tmux status banners from terminal output. This is useful for processing terminal output while excluding tmux status lines.
func (*TmuxSession) GetCursorPosition ¶
func (t *TmuxSession) GetCursorPosition() (x, y int, err error)
GetCursorPosition returns the current cursor position in the tmux pane. Returns cursor X (column) and Y (row) coordinates, both 0-based.
func (*TmuxSession) GetPTY ¶
func (t *TmuxSession) GetPTY() (*os.File, error)
GetPTY returns the PTY file descriptor for reading terminal output. This provides direct access to the PTY master for terminal streaming. Returns an error if the PTY is not initialized.
func (*TmuxSession) GetPaneCurrentPath ¶
func (t *TmuxSession) GetPaneCurrentPath() (string, error)
GetPaneCurrentPath returns the current working directory of the tmux pane. This is used by CaptureCurrentState to persist cwd before shutdown for cold restore.
func (*TmuxSession) GetPaneDimensions ¶
func (t *TmuxSession) GetPaneDimensions() (width, height int, err error)
GetPaneDimensions returns the current dimensions of the tmux pane. Returns width (columns) and height (rows).
When STAPLER_SQUAD_CM_COMMANDS=true and control mode is running, the query is sent over the existing control mode stdin pipe (zero new subprocesses). Otherwise it falls back to the original subprocess path.
func (*TmuxSession) GetPanePID ¶
func (t *TmuxSession) GetPanePID() (int32, error)
GetPanePID returns the PID of the foreground process in the pane. This is used by HistoryLinker to correlate open files with session records.
func (*TmuxSession) GetSanitizedName ¶ added in v1.15.0
func (t *TmuxSession) GetSanitizedName() string
GetSanitizedName returns the tmux session name as it appears in `tmux list-sessions`. Used for bulk reconciliation against ListAllSessions output.
func (*TmuxSession) HasMeaningfulContent ¶
func (t *TmuxSession) HasMeaningfulContent(content string) bool
HasMeaningfulContent checks if the terminal output contains meaningful content (excluding tmux status banners). This is used to determine if the session has produced actual output versus just tmux status line updates.
func (*TmuxSession) HasUpdated ¶
func (t *TmuxSession) HasUpdated() (updated bool, hasPrompt bool, content string)
HasUpdated checks if the tmux pane content has changed since the last tick. It also returns true if the tmux pane has a prompt for aider or claude code.
func (*TmuxSession) RefreshClient ¶
func (t *TmuxSession) RefreshClient() error
RefreshClient sends a refresh signal to the tmux client, forcing the process running inside to redraw at current dimensions. This is critical after resizing to update cursor positions and line wrapping.
func (*TmuxSession) ResetExitOnce ¶ added in v1.15.0
func (t *TmuxSession) ResetExitOnce()
ResetExitOnce resets the exit callback so it can fire again after a session restart. Also clears intentionalStop so the next StopControlMode() correctly guards the callback. Call this before reusing a TmuxSession object for a restarted session.
func (*TmuxSession) Restore ¶
func (t *TmuxSession) Restore() error
Restore attaches to an existing session and restores the window size
func (*TmuxSession) RestoreWithWorkDir ¶
func (t *TmuxSession) RestoreWithWorkDir(workDir string) error
func (*TmuxSession) SetDetachedSize ¶
func (t *TmuxSession) SetDetachedSize(width, height int) error
SetDetachedSize set the width and height of the session while detached. This makes the tmux output conform to the specified shape.
func (*TmuxSession) SetOnExitCallback ¶ added in v1.15.0
func (t *TmuxSession) SetOnExitCallback(fn func(reason string))
SetOnExitCallback registers a function called when the session exits unexpectedly. The callback fires at most once per TmuxSession lifetime (guarded by sync.Once). It is NOT called when StopControlMode() is the cause of the exit. The callback must not be called while the owning Instance's stateMutex is held.
func (*TmuxSession) SetWindowSize ¶
func (t *TmuxSession) SetWindowSize(cols, rows int) error
SetWindowSize allows external callers (like web UI) to set terminal dimensions. This is particularly useful for web terminal integration where the browser controls the size. This method executes the resize immediately by calling both PTY and tmux resize commands.
func (*TmuxSession) Start ¶
func (t *TmuxSession) Start(workDir string) error
Start creates and starts a new tmux session, then attaches to it. Program is the command to run in the session (ex. claude). workdir is the git worktree directory.
func (*TmuxSession) StartControlMode ¶
func (t *TmuxSession) StartControlMode() error
StartControlMode begins streaming terminal output via tmux control mode (-C flag). This is the proper way to get real-time terminal output from tmux, replacing pipe-pane + FIFO. Control mode provides structured notifications (%output, %session-changed, etc.) via stdout.
Benefits over pipe-pane: - No FIFO complexity or EOF issues - Direct protocol communication with tmux - Structured, parseable output format - Real-time notifications (no polling) - Native tmux feature (not a hack)
func (*TmuxSession) StartWithCleanup ¶
func (t *TmuxSession) StartWithCleanup(workDir string) (CleanupFunc, error)
StartWithCleanup creates and starts a new tmux session and returns a cleanup function. Usage: cleanup, err := session.StartWithCleanup(workDir); if err == nil { defer cleanup() }
func (*TmuxSession) StopControlMode ¶
func (t *TmuxSession) StopControlMode() error
StopControlMode stops the control mode streaming and cleans up resources.
func (*TmuxSession) SubscribeToControlModeUpdates ¶
func (t *TmuxSession) SubscribeToControlModeUpdates() (string, chan []byte)
SubscribeToControlModeUpdates registers a new subscriber for real-time terminal output. Returns a subscriber ID and a channel that receives terminal output bytes. The channel has a buffer of 100 messages to handle burst traffic.
func (*TmuxSession) TapDAndEnter ¶
func (t *TmuxSession) TapDAndEnter() error
TapDAndEnter sends 'D' followed by an enter keystroke to the tmux pane.
func (*TmuxSession) TapEnter ¶
func (t *TmuxSession) TapEnter() error
TapEnter sends an enter keystroke to the tmux pane.
func (*TmuxSession) UnsubscribeFromControlModeUpdates ¶
func (t *TmuxSession) UnsubscribeFromControlModeUpdates(subscriberID string)
UnsubscribeFromControlModeUpdates removes a subscriber and closes its channel.
type TmuxSessionOption ¶ added in v1.18.0
type TmuxSessionOption func(*TmuxSession)
TmuxSessionOption is a functional option for TmuxSession construction.
func WithRegistry ¶ added in v1.18.0
func WithRegistry(r SessionExistenceChecker) TmuxSessionOption
WithRegistry injects a SessionExistenceChecker; used in tests to avoid the global GetServerRegistry accessor. Passing nil suppresses the automatic GetServerRegistry call so no reconnect loop is started.
type TmuxStatePort ¶ added in v1.18.0
type TmuxStatePort interface {
SessionExistenceChecker
SessionLister
PaneExitSubscriber
}
TmuxStatePort is the full registry interface.
type ZombieInfo ¶ added in v1.24.0
ZombieInfo describes a detected zombie process.
func ScanZombies ¶ added in v1.24.0
func ScanZombies() ([]ZombieInfo, error)
ScanZombies returns all zombie processes (state "Z") owned by the current user. Uses `ps` to avoid any additional subprocess overhead beyond a single ps call.