Tmux Integration

/**
 * State-first Tmux Session Manager
 * 
 * Architecture:
 * 1. QUERY: Get actual tmux pane state (source of truth)
 * 2. DECIDE: Pure function determines actions based on state
 * 3. EXECUTE: Execute actions with verification
 * 4. UPDATE: Update internal cache only after tmux confirms success
 * 
 * The internal `sessions` Map is just a cache for sessionId<->paneId mapping.
 * The REAL source of truth is always queried from tmux.
 */
export class TmuxSessionManager {
  // ...
}

export class TmuxSessionManager {
  // Session tracking
  private sessions = new Map<string, TrackedSession>()
  private pendingSessions = new Set<string>()
  
  // Deferred session queue (when at capacity)
  private deferredSessions = new Map<string, DeferredSession>()
  private deferredQueue: string[] = []

  // Create pane for session
  async handleSessionCreated(event: SessionCreatedEvent): Promise<void>
  
  // Close pane when session ends
  async handleSessionDeleted(sessionId: string): Promise<void>
  
  // Check if tmux is enabled
  private isEnabled(): boolean
}

interface TmuxConfig {
  enabled: boolean
  layout: "vertical" | "horizontal" | "grid"
  main_pane_size: number      // Percentage (e.g., 60)
  main_pane_min_width: number // Characters (default: 100)
  agent_pane_min_width: number // Characters (default: 52)
}

export function decideSpawnActions(
  windowState: WindowState,
  sessionMappings: SessionMapping[],
  capacityConfig: CapacityConfig
): SpawnDecision

export function decideCloseAction(
  sessionId: string,
  sessionMappings: SessionMapping[]
): CloseAction | null

type SpawnDecision = 
  | { type: "spawn"; targetPaneId: string }
  | { type: "replace"; targetPaneId: string; victimSessionId: string }
  | { type: "defer"; reason: string }
  | { type: "skip"; reason: string }

export async function executeActions(
  actions: PaneAction[],
  serverUrl: string,
  client: OpencodeClient
): Promise<ExecutionResult[]>

export async function executeAction(
  action: PaneAction,
  serverUrl: string,
  client: OpencodeClient
): Promise<ExecutionResult>

type PaneAction =
  | { type: "spawn"; sessionId: string; title: string; targetPaneId: string }
  | { type: "close"; paneId: string }
  | { type: "replace"; sessionId: string; title: string; targetPaneId: string; victimSessionId: string }

export function calculateCapacity(
  windowState: WindowState,
  capacityConfig: CapacityConfig
): {
  canSplit: boolean
  reason?: string
  availableSpace?: { width: number; height: number }
}

┌─────────────┬────────┐
│             │ Agent 1│
│    Main     ├────────┤
│    Pane     │ Agent 2│
│             ├────────┤
│             │ Agent 3│
└─────────────┴────────┘

{
  "tmux": {
    "layout": "vertical",
    "main_pane_size": 60  // 60% width for main pane
  }
}

┌──────────────────────┐
│      Main Pane       │
├──────────────────────┤
│ Agent 1 │ Agent 2    │
└──────────────────────┘

{
  "tmux": {
    "layout": "horizontal",
    "main_pane_size": 50  // 50% height for main pane
  }
}

┌─────────┬─────┬─────┐
│         │ Ag1 │ Ag2 │
│  Main   ├─────┼─────┤
│         │ Ag3 │ Ag4 │
└─────────┴─────┴─────┘

{
  "tmux": {
    "layout": "grid",
    "main_pane_size": 55,
    "agent_pane_min_width": 52
  }
}

// src/features/tmux-subagent/session-created-handler.ts
await tmuxManager.handleSessionCreated({
  type: "session.created",
  properties: {
    info: {
      id: "session-123",
      parentID: "parent-456",
      title: "Task: Build feature"
    }
  }
})

# Executed command
tmux split-window -t <target-pane-id> -h \
  "cd <working-dir> && opencode-url <server-url> <session-id>"

const DEFERRED_SESSION_TTL_MS = 5 * 60 * 1000  // 5 minutes
const MAX_DEFERRED_QUEUE_SIZE = 20

export class TmuxPollingManager {
  private pollingInterval?: ReturnType<typeof setInterval>
  
  startPolling(): void {
    this.pollingInterval = setInterval(
      () => this.pollAllSessions(),
      POLL_INTERVAL_BACKGROUND_MS  // 3000ms
    )
  }
  
  private async pollAllSessions(): Promise<void> {
    // Check each tracked session's pane still exists
    // If pane missing → close session
  }
}

const POLL_INTERVAL_BACKGROUND_MS = 3000        // 3s background health check
const SESSION_READY_POLL_INTERVAL_MS = 100      // 100ms session ready wait
const SESSION_READY_TIMEOUT_MS = 10000          // 10s session ready timeout

{
  "tmux": {
    "enabled": true,
    "layout": "vertical",
    "main_pane_size": 60,
    "main_pane_min_width": 100,
    "agent_pane_min_width": 52
  }
}

{
  "tmux": {
    "enabled": false
  }
}

// Detects interactive tool usage
if (toolName === "Bash" && isInteractiveCommand(args.command)) {
  // Spawn in dedicated tmux pane
  await tmuxManager.spawnInteractiveSession(sessionId, command)
}