fix: prevent frozen output from transient tmux errors (#572)

Previously, any non-timeout error from tmux display-message or
has-session would cause the capture loop to treat it as "session
doesn't exist", setting running=false and stopping all output updates.

Now only definitive "session gone" errors cause this behavior:
- "error connecting to" - socket doesn't exist
- "can't find session:" - session not found
- "no server running" - tmux server not running
- "executable file not found" - tmux not installed

All other errors (broken pipe, signal killed, generic exit status)
are assumed to be transient, and the capture loop continues retrying.

Also fixed checkSessionExists to use CombinedOutput() instead of Run()
to properly capture stderr for error message detection.

Author: Iron-Ham

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Frozen Output from Transient Tmux Errors** - Fixed a critical bug where tmux sessions would appear frozen (no output updates, input not showing) due to transient tmux errors being misinterpreted as "session doesn't exist". Previously, any non-timeout error from tmux `display-message` or `has-session` commands would cause the capture loop to think the session had ended, setting `running = false` and stopping all output updates. Now, only definitive "session gone" errors (socket doesn't exist, session not found, no server running, tmux not installed) are treated as terminal—all other errors (broken pipe, signal killed, generic exit status) are assumed to be transient and the capture loop continues retrying. Also fixed `checkSessionExists` to properly capture stderr using `CombinedOutput()` for accurate error message detection.
+
 ## [0.12.6] - 2026-01-22
 
 ### Fixed

internal/instance/manager.go

@@ -824,20 +824,53 @@ func (m *Manager) getSessionStatus(sessionName string) sessionStatus {
 	cmd := m.tmuxCmdCtx(ctx, "display-message", "-t", sessionName, "-p", "#{history_size}|#{window_bell_flag}")
 	output, err := cmd.Output()
 	if err != nil {
+		m.mu.RLock()
+		logger := m.logger
+		m.mu.RUnlock()
+
 		// Check if this was a timeout - session may still exist
 		if ctx.Err() == context.DeadlineExceeded {
-			m.mu.RLock()
-			logger := m.logger
-			m.mu.RUnlock()
 			if logger != nil {
 				logger.Warn("tmux display-message timed out, will retry next tick",
 					"session_name", sessionName)
 			}
 			return sessionStatus{historySize: -1, bellActive: false, sessionExists: true}
 		}
 
-		// Any non-timeout error means session doesn't exist or can't be verified
-		return sessionStatus{historySize: -1, bellActive: false, sessionExists: false}
+		// Check if this is a definitive "session doesn't exist" error.
+		// Only treat session as non-existent for specific error patterns:
+		// - "error connecting to" - socket doesn't exist
+		// - "can't find session:" - session not found
+		// - "no server running" - tmux server not running
+		// - "executable file not found" - tmux not installed
+		// For all other errors (transient failures, pipe errors, etc.),
+		// assume the session still exists and retry on next tick.
+		errStr := err.Error()
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			// Include stderr in the error check
+			errStr = string(exitErr.Stderr)
+		}
+		sessionGone := strings.Contains(errStr, "error connecting to") ||
+			strings.Contains(errStr, "can't find session:") ||
+			strings.Contains(errStr, "no server running") ||
+			strings.Contains(errStr, "executable file not found")
+
+		if sessionGone {
+			if logger != nil {
+				logger.Debug("tmux session confirmed not found",
+					"session_name", sessionName,
+					"error", errStr)
+			}
+			return sessionStatus{historySize: -1, bellActive: false, sessionExists: false}
+		}
+
+		// For other errors (transient), assume session exists and retry
+		if logger != nil {
+			logger.Warn("tmux display-message failed with transient error, will retry",
+				"session_name", sessionName,
+				"error", errStr)
+		}
+		return sessionStatus{historySize: -1, bellActive: false, sessionExists: true}
 	}
 
 	// Parse the response using the extracted helper
@@ -881,7 +914,8 @@ func (m *Manager) checkSessionExists(sessionName string) bool {
 	defer cancel()
 
 	cmd := m.tmuxCmdCtx(ctx, "has-session", "-t", sessionName)
-	err := cmd.Run()
+	// Use CombinedOutput to capture stderr which contains the error message
+	output, err := cmd.CombinedOutput()
 
 	// If timeout, assume session still exists (retry on next heartbeat)
 	if ctx.Err() == context.DeadlineExceeded {
@@ -896,9 +930,43 @@ func (m *Manager) checkSessionExists(sessionName string) bool {
 	}
 
 	if err != nil {
-		// Any error means session doesn't exist or can't be verified
-		// This is consistent with TmuxSessionExists() which uses `cmd.Run() == nil`
-		return false
+		m.mu.RLock()
+		logger := m.logger
+		m.mu.RUnlock()
+
+		// Check if this is a definitive "session doesn't exist" error.
+		// Only return false for specific error patterns:
+		// - "error connecting to" - socket doesn't exist
+		// - "can't find session:" - session not found
+		// - "no server running" - tmux server not running
+		// - "executable file not found" - tmux not installed
+		// For transient errors, assume the session still exists.
+		// Note: With CombinedOutput, error messages are in the output bytes, not ExitError.Stderr
+		errStr := string(output)
+		if errStr == "" {
+			errStr = err.Error()
+		}
+		sessionGone := strings.Contains(errStr, "error connecting to") ||
+			strings.Contains(errStr, "can't find session:") ||
+			strings.Contains(errStr, "no server running") ||
+			strings.Contains(errStr, "executable file not found")
+
+		if sessionGone {
+			if logger != nil {
+				logger.Debug("tmux session confirmed not found during heartbeat",
+					"session_name", sessionName,
+					"error", errStr)
+			}
+			return false
+		}
+
+		// For transient errors, assume session exists and retry
+		if logger != nil {
+			logger.Warn("tmux has-session failed with transient error, assuming session exists",
+				"session_name", sessionName,
+				"error", errStr)
+		}
+		return true
 	}
 
 	return true

internal/instance/manager_test.go

@@ -558,6 +558,77 @@ func TestManager_CheckSessionExists_NoSession(t *testing.T) {
 	}
 }
 
+// TestSessionGoneErrorPatterns documents which tmux error messages indicate
+// that a session is definitively gone vs transient errors that should be retried.
+// This test verifies our understanding of tmux error messages.
+func TestSessionGoneErrorPatterns(t *testing.T) {
+	// These error patterns indicate the session is definitively gone
+	sessionGonePatterns := []struct {
+		name     string
+		errorMsg string
+	}{
+		{
+			name:     "socket doesn't exist",
+			errorMsg: "error connecting to /tmp/tmux-501/claudio-test (No such file or directory)",
+		},
+		{
+			name:     "session not found",
+			errorMsg: "can't find session: test-session",
+		},
+		{
+			name:     "no server running on socket",
+			errorMsg: "no server running on /tmp/tmux-501/claudio-test",
+		},
+		{
+			name:     "tmux not installed",
+			errorMsg: `exec: "tmux": executable file not found in $PATH`,
+		},
+	}
+
+	for _, tt := range sessionGonePatterns {
+		t.Run(tt.name, func(t *testing.T) {
+			sessionGone := strings.Contains(tt.errorMsg, "error connecting to") ||
+				strings.Contains(tt.errorMsg, "can't find session:") ||
+				strings.Contains(tt.errorMsg, "no server running") ||
+				strings.Contains(tt.errorMsg, "executable file not found")
+			if !sessionGone {
+				t.Errorf("expected %q to be recognized as session-gone error", tt.errorMsg)
+			}
+		})
+	}
+
+	// These errors should NOT indicate the session is gone (transient errors)
+	transientPatterns := []struct {
+		name     string
+		errorMsg string
+	}{
+		{
+			name:     "generic exit status",
+			errorMsg: "exit status 1",
+		},
+		{
+			name:     "broken pipe",
+			errorMsg: "write: broken pipe",
+		},
+		{
+			name:     "signal killed",
+			errorMsg: "signal: killed",
+		},
+	}
+
+	for _, tt := range transientPatterns {
+		t.Run("transient/"+tt.name, func(t *testing.T) {
+			sessionGone := strings.Contains(tt.errorMsg, "error connecting to") ||
+				strings.Contains(tt.errorMsg, "can't find session:") ||
+				strings.Contains(tt.errorMsg, "no server running") ||
+				strings.Contains(tt.errorMsg, "executable file not found")
+			if sessionGone {
+				t.Errorf("expected %q to NOT be recognized as session-gone error", tt.errorMsg)
+			}
+		})
+	}
+}
+
 func TestListClaudioTmuxSessions_NoTmuxServer(t *testing.T) {
 	// This test may return nil or an empty list depending on whether tmux is running
 	// The important thing is it should not error in a way that causes a panic